[3.11] gh-107298: Fix more Sphinx warnings in the C API doc (GH-107329) (GH-107377)

Declare the following functions as macros, since they are actually
macros. It avoids a warning on "TYPE" or "macro" argument.

* PyMem_New()
* PyMem_Resize()
* PyModule_AddIntMacro()
* PyModule_AddStringMacro()
* PyObject_GC_New()
* PyObject_GC_NewVar()
* PyObject_New()
* PyObject_NewVar()

(cherry picked from commit 8d61a71)

Co-authored-by: Victor Stinner <[email protected]>

Author: serhiy-storchaka

Doc/c-api/allocation.rst

@@ -27,31 +27,34 @@ Allocating Objects on the Heap
    length information for a variable-size object.
 
 
-.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
+.. c:macro:: PyObject_New(TYPE, typeobj)
 
    Allocate a new Python object using the C structure type *TYPE* and the
-   Python type object *type*.  Fields not defined by the Python object header
+   Python type object *typeobj* (``PyTypeObject*``).
+   Fields not defined by the Python object header
    are not initialized; the object's reference count will be one.  The size of
    the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
    the type object.
 
 
-.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+.. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
 
    Allocate a new Python object using the C structure type *TYPE* and the
-   Python type object *type*.  Fields not defined by the Python object header
+   Python type object *typeobj* (``PyTypeObject*``).
+   Fields not defined by the Python object header
    are not initialized.  The allocated memory allows for the *TYPE* structure
-   plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
-   *type*.  This is useful for implementing objects like tuples, which are
+   plus *size* (``Py_ssize_t``) fields of the size
+   given by the :c:member:`~PyTypeObject.tp_itemsize` field of
+   *typeobj*.  This is useful for implementing objects like tuples, which are
    able to determine their size at construction time.  Embedding the array of
    fields into the same allocation decreases the number of allocations,
    improving the memory management efficiency.
 
 
 .. c:function:: void PyObject_Del(void *op)
 
-   Releases memory allocated to an object using :c:func:`PyObject_New` or
-   :c:func:`PyObject_NewVar`.  This is normally called from the
+   Releases memory allocated to an object using :c:macro:`PyObject_New` or
+   :c:macro:`PyObject_NewVar`.  This is normally called from the
    :c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type.  The fields of
    the object should not be accessed after this call as the memory is no
    longer a valid Python object.

Doc/c-api/capsule.rst

@@ -64,7 +64,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
 
    The *name* parameter must compare exactly to the name stored in the capsule.
    If the name stored in the capsule is ``NULL``, the *name* passed in must also
-   be ``NULL``.  Python uses the C function :c:func:`strcmp` to compare capsule
+   be ``NULL``.  Python uses the C function :c:func:`!strcmp` to compare capsule
    names.
 
 

Doc/c-api/complex.rst

@@ -64,7 +64,7 @@ pointers.  This is consistent throughout the API.
    representation.
 
    If *divisor* is null, this method returns zero and sets
-   :c:data:`errno` to :c:macro:`EDOM`.
+   :c:data:`errno` to :c:macro:`!EDOM`.
 
 
 .. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
@@ -73,7 +73,7 @@ pointers.  This is consistent throughout the API.
    representation.
 
    If *num* is null and *exp* is not a positive real number,
-   this method returns zero and sets :c:data:`errno` to :c:macro:`EDOM`.
+   this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
 
 
 Complex Numbers as Python Objects

Doc/c-api/conversion.rst

@@ -119,10 +119,10 @@ The following functions provide locale-independent string to number conversions.
 .. c:function:: int PyOS_stricmp(const char *s1, const char *s2)
 
    Case insensitive comparison of strings. The function works almost
-   identically to :c:func:`strcmp` except that it ignores the case.
+   identically to :c:func:`!strcmp` except that it ignores the case.
 
 
 .. c:function:: int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t  size)
 
    Case insensitive comparison of strings. The function works almost
-   identically to :c:func:`strncmp` except that it ignores the case.
+   identically to :c:func:`!strncmp` except that it ignores the case.

Doc/c-api/exceptions.rst

@@ -78,7 +78,7 @@ Printing and clearing
    This utility function prints a warning message to ``sys.stderr`` when an
    exception has been set but it is impossible for the interpreter to actually
    raise the exception.  It is used, for example, when an exception occurs in an
-   :meth:`__del__` method.
+   :meth:`~object.__del__` method.
 
    The function is called with a single argument *obj* that identifies the context
    in which the unraisable exception occurred. If possible,
@@ -154,7 +154,7 @@ For convenience, some of these functions will always return a
    tuple object whose first item is the integer :c:data:`errno` value and whose
    second item is the corresponding error message (gotten from :c:func:`!strerror`),
    and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the
-   :c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call,
+   :c:data:`errno` value is :c:macro:`!EINTR`, indicating an interrupted system call,
    this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
    leaves it set to that.  The function always returns ``NULL``, so a wrapper
    function around a system call can write ``return PyErr_SetFromErrno(type);``
@@ -166,7 +166,7 @@ For convenience, some of these functions will always return a
    Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
    *filenameObject* is not ``NULL``, it is passed to the constructor of *type* as
    a third parameter.  In the case of :exc:`OSError` exception,
-   this is used to define the :attr:`filename` attribute of the
+   this is used to define the :attr:`!filename` attribute of the
    exception instance.
 
 
@@ -189,12 +189,12 @@ For convenience, some of these functions will always return a
 .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
 
    This is a convenience function to raise :exc:`WindowsError`. If called with
-   *ierr* of ``0``, the error code returned by a call to :c:func:`GetLastError`
-   is used instead.  It calls the Win32 function :c:func:`FormatMessage` to retrieve
-   the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
+   *ierr* of ``0``, the error code returned by a call to :c:func:`!GetLastError`
+   is used instead.  It calls the Win32 function :c:func:`!FormatMessage` to retrieve
+   the Windows description of error code given by *ierr* or :c:func:`!GetLastError`,
    then it constructs a tuple object whose first item is the *ierr* value and whose
    second item is the corresponding error message (gotten from
-   :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
+   :c:func:`!FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
    object)``. This function always returns ``NULL``.
 
    .. availability:: Windows.
@@ -567,7 +567,7 @@ Signal Handling
    be interruptible by user requests (such as by pressing Ctrl-C).
 
    .. note::
-      The default Python signal handler for :c:macro:`SIGINT` raises the
+      The default Python signal handler for :c:macro:`!SIGINT` raises the
       :exc:`KeyboardInterrupt` exception.
 
 
@@ -578,7 +578,7 @@ Signal Handling
       single: SIGINT
       single: KeyboardInterrupt (built-in exception)
 
-   Simulate the effect of a :c:macro:`SIGINT` signal arriving.
+   Simulate the effect of a :c:macro:`!SIGINT` signal arriving.
    This is equivalent to ``PyErr_SetInterruptEx(SIGINT)``.
 
    .. note::

Doc/c-api/gcsupport.rst

@@ -25,8 +25,8 @@ include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
 
 Constructors for container types must conform to two rules:
 
-#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
-   or :c:func:`PyObject_GC_NewVar`.
+#. The memory for the object must be allocated using :c:macro:`PyObject_GC_New`
+   or :c:macro:`PyObject_GC_NewVar`.
 
 #. Once all the fields which may contain references to other containers are
    initialized, it must call :c:func:`PyObject_GC_Track`.
@@ -52,21 +52,21 @@ rules:
       class that implements the garbage collector protocol and the child class
       does *not* include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
 
-.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
+.. c:macro:: PyObject_GC_New(TYPE, typeobj)
 
-   Analogous to :c:func:`PyObject_New` but for container objects with the
+   Analogous to :c:macro:`PyObject_New` but for container objects with the
    :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
 
 
-.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+.. c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)
 
-   Analogous to :c:func:`PyObject_NewVar` but for container objects with the
+   Analogous to :c:macro:`PyObject_NewVar` but for container objects with the
    :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
 
 
 .. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
 
-   Resize an object allocated by :c:func:`PyObject_NewVar`.  Returns the
+   Resize an object allocated by :c:macro:`PyObject_NewVar`.  Returns the
    resized object or ``NULL`` on failure.  *op* must not be tracked by the collector yet.
 
 
@@ -109,8 +109,8 @@ rules:
 
 .. c:function:: void PyObject_GC_Del(void *op)
 
-   Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
-   :c:func:`PyObject_GC_NewVar`.
+   Releases memory allocated to an object using :c:macro:`PyObject_GC_New` or
+   :c:macro:`PyObject_GC_NewVar`.
 
 
 .. c:function:: void PyObject_GC_UnTrack(void *op)

Doc/c-api/import.rst

@@ -135,10 +135,10 @@ Importing Modules
    The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
    not set already, with the appropriate values.  The spec's loader will
    be set to the module's ``__loader__`` (if set) and to an instance of
-   :class:`SourceFileLoader` otherwise.
+   :class:`~importlib.machinery.SourceFileLoader` otherwise.
 
    The module's :attr:`__file__` attribute will be set to the code object's
-   :attr:`co_filename`.  If applicable, :attr:`__cached__` will also
+   :attr:`!co_filename`.  If applicable, :attr:`__cached__` will also
    be set.
 
    This function will reload the module if it was already imported.  See
@@ -214,7 +214,7 @@ Importing Modules
 
 .. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
 
-   Return a finder object for a :data:`sys.path`/:attr:`pkg.__path__` item
+   Return a finder object for a :data:`sys.path`/:attr:`!pkg.__path__` item
    *path*, possibly by fetching it from the :data:`sys.path_importer_cache`
    dict.  If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
    is found that can handle the path item.  Return ``None`` if no hook could;

Doc/c-api/init.rst

@@ -25,7 +25,7 @@ The following functions can be safely called before Python is initialized:
 
   * :c:func:`PyImport_AppendInittab`
   * :c:func:`PyImport_ExtendInittab`
-  * :c:func:`PyInitFrozenExtensions`
+  * :c:func:`!PyInitFrozenExtensions`
   * :c:func:`PyMem_SetAllocator`
   * :c:func:`PyMem_SetupDebugHooks`
   * :c:func:`PyObject_SetArenaAllocator`
@@ -122,7 +122,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
 .. c:var:: int Py_IgnoreEnvironmentFlag
 
-   Ignore all :envvar:`PYTHON*` environment variables, e.g.
+   Ignore all :envvar:`!PYTHON*` environment variables, e.g.
    :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
 
    Set by the :option:`-E` and :option:`-I` options.
@@ -165,7 +165,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 .. c:var:: int Py_LegacyWindowsStdioFlag
 
    If the flag is non-zero, use :class:`io.FileIO` instead of
-   :class:`WindowsConsoleIO` for :mod:`sys` standard streams.
+   :class:`!io._WindowsConsoleIO` for :mod:`sys` standard streams.
 
    Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
    variable is set to a non-empty string.
@@ -292,7 +292,7 @@ Initializing and finalizing the interpreter
    the application.
 
    **Bugs and caveats:** The destruction of modules and objects in modules is done
-   in random order; this may cause destructors (:meth:`__del__` methods) to fail
+   in random order; this may cause destructors (:meth:`~object.__del__` methods) to fail
    when they depend on other objects (even functions) or modules.  Dynamically
    loaded extension modules loaded by Python are not unloaded.  Small amounts of
    memory allocated by the Python interpreter may not be freed (if you find a leak,
@@ -381,7 +381,7 @@ Process-wide parameters
    .. deprecated:: 3.11
 
 
-.. c:function:: wchar* Py_GetProgramName()
+.. c:function:: wchar_t* Py_GetProgramName()
 
    .. index:: single: Py_SetProgramName()
 
@@ -872,7 +872,7 @@ the fork, and releasing them afterwards. In addition, it resets any
 :ref:`lock-objects` in the child. When extending or embedding Python, there
 is no way to inform Python of additional (non-Python) locks that need to be
 acquired before or reset after a fork. OS facilities such as
-:c:func:`pthread_atfork` would need to be used to accomplish the same thing.
+:c:func:`!pthread_atfork` would need to be used to accomplish the same thing.
 Additionally, when extending or embedding Python, calling :c:func:`fork`
 directly rather than through :func:`os.fork` (and returning to or calling
 into Python) may result in a deadlock by one of Python's internal locks
@@ -978,7 +978,7 @@ code, or when embedding the Python interpreter:
    .. note::
       Calling this function from a thread when the runtime is finalizing
       will terminate the thread, even if the thread was not created by Python.
-      You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+      You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
       check if the interpreter is in process of being finalized before calling
       this function to avoid unwanted termination.
 
@@ -1024,7 +1024,7 @@ with sub-interpreters:
    .. note::
       Calling this function from a thread when the runtime is finalizing
       will terminate the thread, even if the thread was not created by Python.
-      You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+      You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
       check if the interpreter is in process of being finalized before calling
       this function to avoid unwanted termination.
 
@@ -1306,7 +1306,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    .. note::
       Calling this function from a thread when the runtime is finalizing
       will terminate the thread, even if the thread was not created by Python.
-      You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+      You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
       check if the interpreter is in process of being finalized before calling
       this function to avoid unwanted termination.
 

Doc/c-api/init_config.rst

@@ -850,7 +850,7 @@ PyConfig
    .. c:member:: int legacy_windows_stdio
 
       If non-zero, use :class:`io.FileIO` instead of
-      :class:`io.WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
+      :class:`!io._WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
       and :data:`sys.stderr`.
 
       Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
@@ -1096,7 +1096,7 @@ PyConfig
 
       Set to ``0`` by the :option:`-S` command line option.
 
-      :data:`sys.flags.no_site` is set to the inverted value of
+      :data:`sys.flags.no_site <sys.flags>` is set to the inverted value of
       :c:member:`~PyConfig.site_import`.
 
       Default: ``1``.

Doc/c-api/memory.rst

@@ -136,7 +136,7 @@ need to be held.
 
 The :ref:`default raw memory allocator <default-memory-allocators>` uses
 the following functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc`
-and :c:func:`free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting
+and :c:func:`!free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting
 zero bytes.
 
 .. versionadded:: 3.4
@@ -264,14 +264,14 @@ The following type-oriented macros are provided for convenience.  Note  that
 *TYPE* refers to any C type.
 
 
-.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
+.. c:macro:: PyMem_New(TYPE, n)
 
    Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
    memory.  Returns a pointer cast to :c:expr:`TYPE*`.  The memory will not have
    been initialized in any way.
 
 
-.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
+.. c:macro:: PyMem_Resize(p, TYPE, n)
 
    Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
    sizeof(TYPE))`` bytes.  Returns a pointer cast to :c:expr:`TYPE*`. On return,
@@ -423,7 +423,7 @@ Customize Memory Allocators
    +----------------------------------------------------------+---------------------------------------+
 
    .. versionchanged:: 3.5
-      The :c:type:`PyMemAllocator` structure was renamed to
+      The :c:type:`!PyMemAllocator` structure was renamed to
       :c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added.
 
 
@@ -627,8 +627,8 @@ with a fixed size of 256 KiB. It falls back to :c:func:`PyMem_RawMalloc` and
 
 The arena allocator uses the following functions:
 
-* :c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows,
-* :c:func:`mmap` and :c:func:`munmap` if available,
+* :c:func:`!VirtualAlloc` and :c:func:`!VirtualFree` on Windows,
+* :c:func:`!mmap` and :c:func:`!munmap` if available,
 * :c:func:`malloc` and :c:func:`free` otherwise.
 
 This allocator is disabled if Python is configured with the
@@ -732,8 +732,8 @@ allocators operating on different heaps. ::
    free(buf1);       /* Fatal -- should be PyMem_Del()  */
 
 In addition to the functions aimed at handling raw memory blocks from the Python
-heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
-:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.
+heap, objects in Python are allocated and released with :c:macro:`PyObject_New`,
+:c:macro:`PyObject_NewVar` and :c:func:`PyObject_Del`.
 
 These will be explained in the next chapter on defining and implementing new
 object types in C.