bpo-40838: document `getdoc`, `getmodule`, `getsourcefile` in `inspect` returns ...

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit b86d783a4eff96306f315acf9a6f1aca85d47fc3)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 575b3088900e1389d5f2a5431a65c3dad764ff94..154d0f5dab0cd1201c76fcf0d015f7cc02a19ed6 100644 (file)
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -512,6 +512,7 @@ Retrieving source code
    If the documentation string for an object is not provided and the object is
    a class, a method, a property or a descriptor, retrieve the documentation
    string from the inheritance hierarchy.
+   Return ``None`` if the documentation string is invalid or missing.
 
    .. versionchanged:: 3.5
       Documentation strings are now inherited if not overridden.
@@ -535,12 +536,14 @@ Retrieving source code
 
 .. function:: getmodule(object)
 
-   Try to guess which module an object was defined in.
+   Try to guess which module an object was defined in. Return ``None``
+   if the module cannot be determined.
 
 
 .. function:: getsourcefile(object)
 
-   Return the name of the Python source file in which an object was defined.  This
+   Return the name of the Python source file in which an object was defined
+   or ``None`` if no way can be identified to get the source.  This
    will fail with a :exc:`TypeError` if the object is a built-in module, class, or
    function.
 

diff --git a/Misc/NEWS.d/next/Documentation/2022-01-13-16-03-15.bpo-40838.k3NVCf.rst b/Misc/NEWS.d/next/Documentation/2022-01-13-16-03-15.bpo-40838.k3NVCf.rst
new file mode 100644 (file)
index 0000000..0f071ab
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-01-13-16-03-15.bpo-40838.k3NVCf.rst
@@ -0,0 +1,2 @@
+Document that :func:`inspect.getdoc`, :func:`inspect.getmodule`, and
+:func:`inspect.getsourcefile` might return ``None``.