[3.11] gh-93738: Documentation C syntax (:c:type:<C type> -> :c:expr:<C type>) (GH-97768) (#97924)

:c:type:`<C type>` -> :c:expr:`<C type>`

Co-authored-by: Łukasz Langa <[email protected]>
(cherry picked from commit 0031e62)

Co-authored-by: Adam Turner <[email protected]>

Author: 2 people

Doc/c-api/arg.rst

@@ -194,10 +194,10 @@ which disallows mutable objects such as :class:`bytearray`.
    It only works for encoded data without embedded NUL bytes.
 
    This format requires two arguments.  The first is only used as input, and
-   must be a :c:type:`const char*` which points to the name of an encoding as a
+   must be a :c:expr:`const char*` which points to the name of an encoding as a
    NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
    An exception is raised if the named encoding is not known to Python.  The
-   second argument must be a :c:type:`char**`; the value of the pointer it
+   second argument must be a :c:expr:`char**`; the value of the pointer it
    references will be set to a buffer with the contents of the argument text.
    The text will be encoded in the encoding specified by the first argument.
 
@@ -217,10 +217,10 @@ which disallows mutable objects such as :class:`bytearray`.
    characters.
 
    It requires three arguments.  The first is only used as input, and must be a
-   :c:type:`const char*` which points to the name of an encoding as a
+   :c:expr:`const char*` which points to the name of an encoding as a
    NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
    An exception is raised if the named encoding is not known to Python.  The
-   second argument must be a :c:type:`char**`; the value of the pointer it
+   second argument must be a :c:expr:`char**`; the value of the pointer it
    references will be set to a buffer with the contents of the argument text.
    The text will be encoded in the encoding specified by the first argument.
    The third argument must be a pointer to an integer; the referenced integer
@@ -252,59 +252,59 @@ Numbers
 
 ``b`` (:class:`int`) [unsigned char]
    Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
-   :c:type:`unsigned char`.
+   :c:expr:`unsigned char`.
 
 ``B`` (:class:`int`) [unsigned char]
    Convert a Python integer to a tiny int without overflow checking, stored in a C
-   :c:type:`unsigned char`.
+   :c:expr:`unsigned char`.
 
 ``h`` (:class:`int`) [short int]
-   Convert a Python integer to a C :c:type:`short int`.
+   Convert a Python integer to a C :c:expr:`short int`.
 
 ``H`` (:class:`int`) [unsigned short int]
-   Convert a Python integer to a C :c:type:`unsigned short int`, without overflow
+   Convert a Python integer to a C :c:expr:`unsigned short int`, without overflow
    checking.
 
 ``i`` (:class:`int`) [int]
-   Convert a Python integer to a plain C :c:type:`int`.
+   Convert a Python integer to a plain C :c:expr:`int`.
 
 ``I`` (:class:`int`) [unsigned int]
-   Convert a Python integer to a C :c:type:`unsigned int`, without overflow
+   Convert a Python integer to a C :c:expr:`unsigned int`, without overflow
    checking.
 
 ``l`` (:class:`int`) [long int]
-   Convert a Python integer to a C :c:type:`long int`.
+   Convert a Python integer to a C :c:expr:`long int`.
 
 ``k`` (:class:`int`) [unsigned long]
-   Convert a Python integer to a C :c:type:`unsigned long` without
+   Convert a Python integer to a C :c:expr:`unsigned long` without
    overflow checking.
 
 ``L`` (:class:`int`) [long long]
-   Convert a Python integer to a C :c:type:`long long`.
+   Convert a Python integer to a C :c:expr:`long long`.
 
 ``K`` (:class:`int`) [unsigned long long]
-   Convert a Python integer to a C :c:type:`unsigned long long`
+   Convert a Python integer to a C :c:expr:`unsigned long long`
    without overflow checking.
 
 ``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
    Convert a Python integer to a C :c:type:`Py_ssize_t`.
 
 ``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
    Convert a Python byte, represented as a :class:`bytes` or
-   :class:`bytearray` object of length 1, to a C :c:type:`char`.
+   :class:`bytearray` object of length 1, to a C :c:expr:`char`.
 
    .. versionchanged:: 3.3
       Allow :class:`bytearray` objects.
 
 ``C`` (:class:`str` of length 1) [int]
    Convert a Python character, represented as a :class:`str` object of
-   length 1, to a C :c:type:`int`.
+   length 1, to a C :c:expr:`int`.
 
 ``f`` (:class:`float`) [float]
-   Convert a Python floating point number to a C :c:type:`float`.
+   Convert a Python floating point number to a C :c:expr:`float`.
 
 ``d`` (:class:`float`) [double]
-   Convert a Python floating point number to a C :c:type:`double`.
+   Convert a Python floating point number to a C :c:expr:`double`.
 
 ``D`` (:class:`complex`) [Py_complex]
    Convert a Python complex number to a C :c:type:`Py_complex` structure.
@@ -329,13 +329,13 @@ Other objects
 ``O&`` (object) [*converter*, *anything*]
    Convert a Python object to a C variable through a *converter* function.  This
    takes two arguments: the first is a function, the second is the address of a C
-   variable (of arbitrary type), converted to :c:type:`void *`.  The *converter*
+   variable (of arbitrary type), converted to :c:expr:`void *`.  The *converter*
    function in turn is called as follows::
 
       status = converter(object, address);
 
    where *object* is the Python object to be converted and *address* is the
-   :c:type:`void*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
+   :c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` function.
    The returned *status* should be ``1`` for a successful conversion and ``0`` if
    the conversion has failed.  When the conversion fails, the *converter* function
    should raise an exception and leave the content of *address* unmodified.
@@ -568,7 +568,7 @@ Building values
       Same as ``s#``.
 
    ``u`` (:class:`str`) [const wchar_t \*]
-      Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
+      Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
       data to a Python Unicode object.  If the Unicode buffer pointer is ``NULL``,
       ``None`` is returned.
 
@@ -584,51 +584,51 @@ Building values
       Same as ``s#``.
 
    ``i`` (:class:`int`) [int]
-      Convert a plain C :c:type:`int` to a Python integer object.
+      Convert a plain C :c:expr:`int` to a Python integer object.
 
    ``b`` (:class:`int`) [char]
-      Convert a plain C :c:type:`char` to a Python integer object.
+      Convert a plain C :c:expr:`char` to a Python integer object.
 
    ``h`` (:class:`int`) [short int]
-      Convert a plain C :c:type:`short int` to a Python integer object.
+      Convert a plain C :c:expr:`short int` to a Python integer object.
 
    ``l`` (:class:`int`) [long int]
-      Convert a C :c:type:`long int` to a Python integer object.
+      Convert a C :c:expr:`long int` to a Python integer object.
 
    ``B`` (:class:`int`) [unsigned char]
-      Convert a C :c:type:`unsigned char` to a Python integer object.
+      Convert a C :c:expr:`unsigned char` to a Python integer object.
 
    ``H`` (:class:`int`) [unsigned short int]
-      Convert a C :c:type:`unsigned short int` to a Python integer object.
+      Convert a C :c:expr:`unsigned short int` to a Python integer object.
 
    ``I`` (:class:`int`) [unsigned int]
-      Convert a C :c:type:`unsigned int` to a Python integer object.
+      Convert a C :c:expr:`unsigned int` to a Python integer object.
 
    ``k`` (:class:`int`) [unsigned long]
-      Convert a C :c:type:`unsigned long` to a Python integer object.
+      Convert a C :c:expr:`unsigned long` to a Python integer object.
 
    ``L`` (:class:`int`) [long long]
-      Convert a C :c:type:`long long` to a Python integer object.
+      Convert a C :c:expr:`long long` to a Python integer object.
 
    ``K`` (:class:`int`) [unsigned long long]
-      Convert a C :c:type:`unsigned long long` to a Python integer object.
+      Convert a C :c:expr:`unsigned long long` to a Python integer object.
 
    ``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
       Convert a C :c:type:`Py_ssize_t` to a Python integer.
 
    ``c`` (:class:`bytes` of length 1) [char]
-      Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of
+      Convert a C :c:expr:`int` representing a byte to a Python :class:`bytes` object of
       length 1.
 
    ``C`` (:class:`str` of length 1) [int]
-      Convert a C :c:type:`int` representing a character to Python :class:`str`
+      Convert a C :c:expr:`int` representing a character to Python :class:`str`
       object of length 1.
 
    ``d`` (:class:`float`) [double]
-      Convert a C :c:type:`double` to a Python floating point number.
+      Convert a C :c:expr:`double` to a Python floating point number.
 
    ``f`` (:class:`float`) [float]
-      Convert a C :c:type:`float` to a Python floating point number.
+      Convert a C :c:expr:`float` to a Python floating point number.
 
    ``D`` (:class:`complex`) [Py_complex \*]
       Convert a C :c:type:`Py_complex` structure to a Python complex number.
@@ -651,7 +651,7 @@ Building values
 
    ``O&`` (object) [*converter*, *anything*]
       Convert *anything* to a Python object through a *converter* function.  The
-      function is called with *anything* (which should be compatible with :c:type:`void*`)
+      function is called with *anything* (which should be compatible with :c:expr:`void*`)
       as its argument and should return a "new" Python object, or ``NULL`` if an
       error occurred.
 

Doc/c-api/capsule.rst

@@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
 .. c:type:: PyCapsule
 
    This subtype of :c:type:`PyObject` represents an opaque value, useful for C
-   extension modules who need to pass an opaque value (as a :c:type:`void*`
+   extension modules who need to pass an opaque value (as a :c:expr:`void*`
    pointer) through Python code to other C code.  It is often used to make a C
    function pointer defined in one module available to other modules, so the
    regular import mechanism can be used to access C APIs defined in dynamically

Doc/c-api/complex.rst

@@ -115,12 +115,12 @@ Complex Numbers as Python Objects
 
 .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
 
-   Return the real part of *op* as a C :c:type:`double`.
+   Return the real part of *op* as a C :c:expr:`double`.
 
 
 .. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
 
-   Return the imaginary part of *op* as a C :c:type:`double`.
+   Return the imaginary part of *op* as a C :c:expr:`double`.
 
 
 .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)

Doc/c-api/conversion.rst

@@ -49,7 +49,7 @@ The following functions provide locale-independent string to number conversions.
 
 .. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
 
-   Convert a string ``s`` to a :c:type:`double`, raising a Python
+   Convert a string ``s`` to a :c:expr:`double`, raising a Python
    exception on failure.  The set of accepted strings corresponds to
    the set of strings accepted by Python's :func:`float` constructor,
    except that ``s`` must not have leading or trailing whitespace.
@@ -83,7 +83,7 @@ The following functions provide locale-independent string to number conversions.
 
 .. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
 
-   Convert a :c:type:`double` *val* to a string using supplied
+   Convert a :c:expr:`double` *val* to a string using supplied
    *format_code*, *precision*, and *flags*.
 
    *format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,

Doc/c-api/dict.rst

@@ -73,7 +73,7 @@ Dictionary Objects
    .. index:: single: PyUnicode_FromString()
 
    Insert *val* into the dictionary *p* using *key* as a key. *key* should
-   be a :c:type:`const char*`.  The key object is created using
+   be a :c:expr:`const char*`.  The key object is created using
    ``PyUnicode_FromString(key)``.  Return ``0`` on success or ``-1`` on
    failure.  This function *does not* steal a reference to *val*.
 
@@ -118,7 +118,7 @@ Dictionary Objects
 .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
 
    This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
-   :c:type:`const char*`, rather than a :c:type:`PyObject*`.
+   :c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
 
    Note that exceptions which occur while calling :meth:`__hash__` and
    :meth:`__eq__` methods and creating a temporary string object

Doc/c-api/file.rst

@@ -38,7 +38,7 @@ the :mod:`io` APIs instead.
 
 .. c:function:: int PyObject_AsFileDescriptor(PyObject *p)
 
-   Return the file descriptor associated with *p* as an :c:type:`int`.  If the
+   Return the file descriptor associated with *p* as an :c:expr:`int`.  If the
    object is an integer, its value is returned.  If not, the
    object's :meth:`~io.IOBase.fileno` method is called if it exists; the
    method must return an integer, which is returned as the file descriptor

Doc/c-api/float.rst

@@ -44,7 +44,7 @@ Floating Point Objects
 
 .. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
 
-   Return a C :c:type:`double` representation of the contents of *pyfloat*.  If
+   Return a C :c:expr:`double` representation of the contents of *pyfloat*.  If
    *pyfloat* is not a Python floating point object but has a :meth:`__float__`
    method, this method will first be called to convert *pyfloat* into a float.
    If ``__float__()`` is not defined then it falls back to :meth:`__index__`.
@@ -57,7 +57,7 @@ Floating Point Objects
 
 .. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
 
-   Return a C :c:type:`double` representation of the contents of *pyfloat*, but
+   Return a C :c:expr:`double` representation of the contents of *pyfloat*, but
    without error checking.
 
 
@@ -70,21 +70,21 @@ Floating Point Objects
 
 .. c:function:: double PyFloat_GetMax()
 
-   Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
+   Return the maximum representable finite float *DBL_MAX* as C :c:expr:`double`.
 
 
 .. c:function:: double PyFloat_GetMin()
 
-   Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
+   Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`.
 
 
 Pack and Unpack functions
 =========================
 
 The pack and unpack functions provide an efficient platform-independent way to
 store floating-point values as byte strings. The Pack routines produce a bytes
-string from a C :c:type:`double`, and the Unpack routines produce a C
-:c:type:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the
+string from a C :c:expr:`double`, and the Unpack routines produce a C
+:c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the
 number of bytes in the bytes string.
 
 On platforms that appear to use IEEE 754 formats these functions work by
@@ -107,7 +107,7 @@ Pack functions
 --------------
 
 The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
-:c:type:`int` argument, non-zero if you want the bytes string in little-endian
+:c:expr:`int` argument, non-zero if you want the bytes string in little-endian
 format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you
 want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN`
 constant can be used to use the native endian: it is equal to ``1`` on big
@@ -138,7 +138,7 @@ Unpack functions
 ----------------
 
 The unpack routines read 2, 4 or 8 bytes, starting at *p*.  *le* is an
-:c:type:`int` argument, non-zero if the bytes string is in little-endian format
+:c:expr:`int` argument, non-zero if the bytes string is in little-endian format
 (exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
 (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to
 use the native endian: it is equal to ``1`` on big endian processor, or ``0``