gh-101944: Clarify PyModule_AddObjectRef() documentation (#129433)

diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index f82a050ab75de0aaa253f42aa7e5ac3dc503ed07..f71089370152ce61bae8e2ce756f0b181a4957a8 100644 (file)
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -523,9 +523,6 @@ state:
 
    On success, return ``0``. On error, raise an exception and return ``-1``.
 
-   Return ``-1`` if *value* is ``NULL``. It must be called with an exception
-   raised in this case.
-
    Example usage::
 
        static int
@@ -540,6 +537,10 @@ state:
            return res;
         }
 
+   To be convenient, the function accepts ``NULL`` *value* with an exception
+   set. In this case, return ``-1`` and just leave the raised exception
+   unchanged.
+
    The example can also be written without checking explicitly if *obj* is
    ``NULL``::