[Python-checkins] [3.8] bpo-38159: Clarify documentation of PyState_AddModule (GH-16101) (GH-17026)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/1270d2cf1d17bfa581bf2a19f82c8cb43bf793d9
commit: 1270d2cf1d17bfa581bf2a19f82c8cb43bf793d9
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-11-05T05:35:56-08:00
summary:

[3.8] bpo-38159: Clarify documentation of PyState_AddModule (GH-16101) (GH-17026)



This was never intented to be called manually from PyInit_*.

Also, clarify PyState_RemoveModule return value.
(cherry picked from commit 9bc94eca0c69a551f928692364a99e9b67c4a45b)


Co-authored-by: Petr Viktorin <encukou at gmail.com>


https://bugs.python.org/issue38159



Automerge-Triggered-By: @encukou

files:
M Doc/c-api/module.rst

diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 46306b3917cce..57902a9c7f838 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -485,10 +485,21 @@ since multiple such modules can be created from a single definition.
 
    Only effective on modules created using single-phase initialization.
 
+   Python calls ``PyState_AddModule`` automatically after importing a module,
+   so it is unnecessary (but harmless) to call it from module initialization
+   code. An explicit call is needed only if the module's own init code
+   subsequently calls ``PyState_FindModule``.
+   The function is mainly intended for implementing alternative import
+   mechanisms (either by calling it directly, or by referring to its
+   implementation for details of the required state updates).
+
+   Return 0 on success or -1 on failure.
+
    .. 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.
 
    .. versionadded:: 3.3