[3.13] gh-121615: Improve `module.rst` C-API docs with better error descriptions...

gh-121615: Improve `module.rst` C-API docs with better error descriptions (GH-121616)
(cherry picked from commit e6264b44dc7221c713b14dfa0f5929b33d362829)

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

diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 63e3bed67279878bbdfc2e3063d97e35735863b2..ce9d5a0f758b29873eb8ea51b51ee3a44e535954 100644 (file)
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -43,6 +43,8 @@ Module Objects
    to ``None``); the caller is responsible for providing a :attr:`__file__`
    attribute.
 
+   Return ``NULL`` with an exception set on error.
+
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.4
@@ -265,6 +267,8 @@ of the following two module creation functions:
    API version *module_api_version*.  If that version does not match the version
    of the running interpreter, a :exc:`RuntimeWarning` is emitted.
 
+   Return ``NULL`` with an exception set on error.
+
    .. note::
 
       Most uses of this function should be using :c:func:`PyModule_Create`
@@ -461,6 +465,8 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
    If that version does not match the version of the running interpreter,
    a :exc:`RuntimeWarning` is emitted.
 
+   Return ``NULL`` with an exception set on error.
+
    .. note::
 
       Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec`
@@ -601,15 +607,16 @@ state:
 .. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
 
    Add an integer constant to *module* as *name*.  This convenience function can be
-   used from the module's initialization function. Return ``-1`` on error, ``0`` on
-   success.
+   used from the module's initialization function.
+   Return ``-1`` with an exception set on error, ``0`` on success.
 
 
 .. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
 
    Add a string constant to *module* as *name*.  This convenience function can be
    used from the module's initialization function.  The string *value* must be
-   ``NULL``-terminated.  Return ``-1`` on error, ``0`` on success.
+   ``NULL``-terminated.
+   Return ``-1`` with an exception set on error, ``0`` on success.
 
 
 .. c:macro:: PyModule_AddIntMacro(module, macro)
@@ -617,7 +624,7 @@ state:
    Add an int constant to *module*. The name and the value are taken from
    *macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
    constant *AF_INET* with the value of *AF_INET* to *module*.
-   Return ``-1`` on error, ``0`` on success.
+   Return ``-1`` with an exception set on error, ``0`` on success.
 
 
 .. c:macro:: PyModule_AddStringMacro(module, macro)
@@ -630,7 +637,7 @@ state:
    The type object is finalized by calling internally :c:func:`PyType_Ready`.
    The name of the type object is taken from the last component of
    :c:member:`~PyTypeObject.tp_name` after dot.
-   Return ``-1`` on error, ``0`` on success.
+   Return ``-1`` with an exception set on error, ``0`` on success.
 
    .. versionadded:: 3.9
 
@@ -643,7 +650,7 @@ state:
    import machinery assumes the module does not support running without the
    GIL. This function is only available in Python builds configured with
    :option:`--disable-gil`.
-   Return ``-1`` on error, ``0`` on success.
+   Return ``-1`` with an exception set on error, ``0`` on success.
 
    .. versionadded:: 3.13
 
@@ -682,14 +689,14 @@ since multiple such modules can be created from a single definition.
 
    The caller must hold the GIL.
 
-   Return 0 on success or -1 on failure.
+   Return ``-1`` with an exception set on error, ``0`` on success.
 
    .. versionadded:: 3.3
 
 .. c:function:: int PyState_RemoveModule(PyModuleDef *def)
 
    Removes the module object created from *def* from the interpreter state.
-   Return 0 on success or -1 on failure.
+   Return ``-1`` with an exception set on error, ``0`` on success.
 
    The caller must hold the GIL.