From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 2 Apr 2022 20:23:26 +0000 (-0700)
Subject: bpo-47031: Improve documentation for `math.nan` (GH-32170)
X-Git-Tag: v3.9.13~151
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5b80031fb0d2ea14f0d42a33309ce5464c4a6042;p=thirdparty%2FPython%2Fcpython.git

bpo-47031: Improve documentation for `math.nan` (GH-32170)


Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit 182e93c3f57b0c72e765c9896066d32e461c0865)

Co-authored-by: Charlie Zhao <zhaoyu_hit@qq.com>
---

diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index b20e557b5c61..9783e9ef825d 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -622,8 +622,23 @@ Constants
 
 .. data:: nan
 
-   A floating-point "not a number" (NaN) value.  Equivalent to the output of
-   ``float('nan')``.
+   A floating-point "not a number" (NaN) value. Equivalent to the output of
+   ``float('nan')``. Due to the requirements of the `IEEE-754 standard
+   <https://en.wikipedia.org/wiki/IEEE_754>`_, ``math.nan`` and ``float('nan')`` are
+   not considered to equal to any other numeric value, including themselves. To check
+   whether a number is a NaN, use the :func:`isnan` function to test
+   for NaNs instead of ``is`` or ``==``.
+   Example::
+
+      >>> import math
+      >>> math.nan == math.nan
+      False
+      >>> float('nan') == float('nan')
+      False
+      >>> math.isnan(math.nan)
+      True
+      >>> math.isnan(float('nan'))
+      True
 
    .. versionadded:: 3.5