Add documentation to an existing object, typically one defined in C
The purpose is to allow easier editing of the docstrings without requiring a re-compile. This exists primarily for internal use within numpy itself.
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 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), ...`` warn_on_python : bool If True, the default, emit `UserWarning` if this is used to attach documentation to a pure-python object.
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.
This routine cannot modify read-only docstrings, as appear 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.