Merge pull request #13946 from eric-wieser/add_newdoc_docs

DOC: Add a numpy-doc docstring to add_newdoc

1 files changed, 33 insertions, 11 deletions

diff --git a/numpy/core/function_base.py b/numpy/core/function_base.py
index c1067299d..0dd6ee420 100644
--- a/numpy/core/function_base.py
+++ b/numpy/core/function_base.py
@@ -440,18 +440,29 @@ def _add_docstring(obj, doc):
 
 def add_newdoc(place, obj, doc):
     """
-    Adds documentation to obj which is in module place.
+    Add documentation to an existing object, typically one defined in C
 
-    If doc is a string add it to obj as a docstring
+    The purpose is to allow easier editing of the docstrings without requiring
+    a re-compile. This exists primarily for internal use within numpy itself.
 
-    If doc is a tuple, then the first element is interpreted as
-       an attribute of obj and the second as the docstring
-          (method, docstring)
+    Parameters
+    ----------
+    place : str
+        The absolute name of the module to import from
+    obj : str
+        The name of the object to add documentation to, typically a class or
+        function name
+    doc : {str, Tuple[str, str], List[Tuple[str, str]]}
+        If a string, the documentation to apply to `obj`
 
-    If doc is a list, then each element of the list should be a
-       sequence of length two --> [(method1, docstring1),
-       (method2, docstring2), ...]
+        If a tuple, then the first element is interpreted as an attribute of
+        `obj` and the second as the docstring to apply - ``(method, docstring)``
 
+        If a list, then each element of the list should be a tuple of length
+        two - ``[(method1, docstring1), (method2, docstring2), ...]``
+
+    Notes
+    -----
     This routine never raises an error if the docstring can't be written, but
     will raise an error if the object being documented does not exist.
 
@@ -459,12 +470,23 @@ def add_newdoc(place, obj, doc):
     in new-style classes or built-in functions. Because this
     routine never raises an error the caller must check manually
     that the docstrings were changed.
+
+    Since this function grabs the ``char *`` from a c-level str object and puts
+    it into the ``tp_doc`` slot of the type of `obj`, it violates a number of
+    C-API best-practices, by:
+
+    - modifying a `PyTypeObject` after calling `PyType_Ready`
+    - calling `Py_INCREF` on the str and losing the reference, so the str
+      will never be released
+
+    If possible it should be avoided.
     """
     new = getattr(__import__(place, globals(), {}, [obj]), obj)
     if isinstance(doc, str):
         _add_docstring(new, doc.strip())
     elif isinstance(doc, tuple):
-        _add_docstring(getattr(new, doc[0]), doc[1].strip())
+        attr, docstring = doc
+        _add_docstring(getattr(new, attr), docstring.strip())
     elif isinstance(doc, list):
-        for val in doc:
-            _add_docstring(getattr(new, val[0]), val[1].strip())
+        for attr, docstring in doc:
+            _add_docstring(getattr(new, attr), docstring.strip())