DOC: testing: Mention the handling of nan in the assert_equal docstring.

1 files changed, 10 insertions, 0 deletions

diff --git a/numpy/testing/_private/utils.py b/numpy/testing/_private/utils.py
index c22348103..b6ec768d3 100644
--- a/numpy/testing/_private/utils.py
+++ b/numpy/testing/_private/utils.py
@@ -301,6 +301,11 @@ def assert_equal(actual, desired, err_msg='', verbose=True):
     check that all elements of these objects are equal. An exception is raised
     at the first conflicting values.
 
+    This function handles NaN comparisons as if NaN was a "normal" number.
+    That is, no assertion is raised if both objects have NaNs in the same
+    positions.  This is in contrast to the IEEE standard on NaNs, which says
+    that NaN compared to anything must return False.
+
     Parameters
     ----------
     actual : array_like
@@ -328,6 +333,11 @@ def assert_equal(actual, desired, err_msg='', verbose=True):
      ACTUAL: 5
      DESIRED: 6
 
+    The following comparison does not raise an exception.  There are NaNs
+    in the inputs, but they are in the same positions.
+
+    >>> np.testing.assert_equal(np.array([1.0, 2.0, np.nan]), [1, 2, np.nan])
+
     """
     __tracebackhide__ = True  # Hide traceback for py.test
     if isinstance(desired, dict):