[3.12] gh-107298: Document PyMODINIT_FUNC macro (GH-109236) (#109947)

gh-107298: Document PyMODINIT_FUNC macro (GH-109236)

Document PyMODINIT_FUNC macro.

Remove links to PyAPI_FUNC() and PyAPI_DATA() macros since they are
not documented. These macros should only be used to define the Python
C API. They should not be used outside Python code base.
(cherry picked from commit d7a27e527d7e669d2e45cff80ad725978226477c)

Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 4a6cb7ab3b8381cdcc2e5287eea0de42b96f5efe..26c0168dbbb18cd0b6ea9f79296b61a44b76f9b7 100644 (file)
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -105,6 +105,30 @@ defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
 Others of a more general utility are defined here.  This is not necessarily a
 complete listing.
 
+.. c:macro:: PyMODINIT_FUNC
+
+   Declare an extension module ``PyInit`` initialization function. The function
+   return type is :c:expr:`PyObject*`. The macro declares any special linkage
+   declarations required by the platform, and for C++ declares the function as
+   ``extern "C"``.
+
+   The initialization function must be named :samp:`PyInit_{name}`, where
+   *name* is the name of the module, and should be the only non-\ ``static``
+   item defined in the module file. Example::
+
+       static struct PyModuleDef spam_module = {
+           PyModuleDef_HEAD_INIT,
+           .m_name = "spam",
+           ...
+       };
+
+       PyMODINIT_FUNC
+       PyInit_spam(void)
+       {
+           return PyModule_Create(&spam_module);
+       }
+
+
 .. c:macro:: Py_ABS(x)
 
    Return the absolute value of ``x``.

diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index d9d52945bcdbe2be4627c58565b9079000d0d272..6fe06381d16841938c5ab38e011b2c2423464ea8 100644 (file)
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -769,8 +769,8 @@ Example on Linux x86-64::
 At the beginning of the files, C extensions are built as built-in modules.
 Extensions defined after the ``*shared*`` marker are built as dynamic libraries.
 
-The :c:macro:`PyAPI_FUNC()`, :c:macro:`PyAPI_DATA()` and
-:c:macro:`PyMODINIT_FUNC` macros of :file:`Include/pyport.h` are defined
+The :c:macro:`!PyAPI_FUNC()`, :c:macro:`!PyAPI_DATA()` and
+:c:macro:`PyMODINIT_FUNC` macros of :file:`Include/exports.h` are defined
 differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined:
 
 * Use ``Py_EXPORTED_SYMBOL`` if the ``Py_BUILD_CORE_MODULE`` is defined

diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst
index c06fd9582627e2f61073c6fe50a6e348b9d0bcdb..0442c9fdd08ce3dd48d0ca9e269d23e0fa7bf78a 100644 (file)
--- a/Doc/whatsnew/2.3.rst
+++ b/Doc/whatsnew/2.3.rst
@@ -1889,7 +1889,7 @@ Changes to Python's build process and to the C API include:
 * The :c:macro:`!DL_EXPORT` and :c:macro:`!DL_IMPORT` macros are now deprecated.
   Initialization functions for Python extension modules should now be declared
   using the new macro :c:macro:`PyMODINIT_FUNC`, while the Python core will
-  generally use the :c:macro:`PyAPI_FUNC` and :c:macro:`PyAPI_DATA` macros.
+  generally use the :c:macro:`!PyAPI_FUNC` and :c:macro:`!PyAPI_DATA` macros.
 
 * The interpreter can be compiled without any docstrings for the built-in
   functions and modules by supplying :option:`!--without-doc-strings` to the