Merge pull request #18253 from rgommers/doc-novalue

DOC: improve description of `_NoValue`

1 files changed, 14 insertions, 2 deletions

diff --git a/numpy/_globals.py b/numpy/_globals.py
index 9f44c7729..4a8c266d3 100644
--- a/numpy/_globals.py
+++ b/numpy/_globals.py
@@ -58,8 +58,20 @@ class _NoValueType:
     """Special keyword value.
 
     The instance of this class may be used as the default value assigned to a
-    deprecated keyword in order to check if it has been given a user defined
-    value.
+    keyword if no other obvious default (e.g., `None`) is suitable,
+
+    Common reasons for using this keyword are:
+
+    - A new keyword is added to a function, and that function forwards its
+      inputs to another function or method which can be defined outside of
+      NumPy. For example, ``np.std(x)`` calls ``x.std``, so when a ``keepdims``
+      keyword was added that could only be forwarded if the user explicitly
+      specified ``keepdims``; downstream array libraries may not have added
+      the same keyword, so adding ``x.std(..., keepdims=keepdims)``
+      unconditionally could have broken previously working code.
+    - A keyword is being deprecated, and a deprecation warning must only be
+      emitted when the keyword is used.
+
     """
     __instance = None
     def __new__(cls):