From 310bf2c28e4f5b795366c034cbac0097868baa5a Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 26 Jul 2023 22:58:05 +0300 Subject: [PATCH] gh-107298: Docs: add targets for some :c:member: and :c:macro: references Add targets for PyStructSequence_Desc and PyStructSequence_Field members and macros like Py_EQ. Fix target for Py_RETURN_RICHCOMPARE. --- Doc/c-api/tuple.rst | 50 +++++++++++++++++++++---------------------- Doc/c-api/typeobj.rst | 32 ++++++++++++++------------- Doc/tools/.nitignore | 1 - 3 files changed, 42 insertions(+), 41 deletions(-) diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index 2277a39c959067..43c59bccaea6a7 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -147,39 +147,39 @@ type. Contains the meta information of a struct sequence type to create. - +-------------------+------------------------------+--------------------------------------+ - | Field | C Type | Meaning | - +===================+==============================+======================================+ - | ``name`` | ``const char *`` | name of the struct sequence type | - +-------------------+------------------------------+--------------------------------------+ - | ``doc`` | ``const char *`` | pointer to docstring for the type | - | | | or ``NULL`` to omit | - +-------------------+------------------------------+--------------------------------------+ - | ``fields`` | ``PyStructSequence_Field *`` | pointer to ``NULL``-terminated array | - | | | with field names of the new type | - +-------------------+------------------------------+--------------------------------------+ - | ``n_in_sequence`` | ``int`` | number of fields visible to the | - | | | Python side (if used as tuple) | - +-------------------+------------------------------+--------------------------------------+ + .. c:member:: const char *name + + name of the struct sequence type + + .. c:member:: const char *doc + + pointer to docstring for the type or ``NULL`` to omit + + .. c:member:: PyStructSequence_Field *fields + + pointer to ``NULL``-terminated array with field names of the new type + + .. c:member:: int n_in_sequence + + number of fields visible to the Python side (if used as tuple) .. c:type:: PyStructSequence_Field Describes a field of a struct sequence. As a struct sequence is modeled as a tuple, all fields are typed as :c:expr:`PyObject*`. The index in the - :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which + :c:member:`~PyStructSequence_Desc.fields` array of + the :c:type:`PyStructSequence_Desc` determines which field of the struct sequence is described. - +-----------+------------------+-----------------------------------------+ - | Field | C Type | Meaning | - +===========+==================+=========================================+ - | ``name`` | ``const char *`` | name for the field or ``NULL`` to end | - | | | the list of named fields, set to | - | | | :c:data:`PyStructSequence_UnnamedField` | - | | | to leave unnamed | - +-----------+------------------+-----------------------------------------+ - | ``doc`` | ``const char *`` | field docstring or ``NULL`` to omit | - +-----------+------------------+-----------------------------------------+ + .. c:member:: const char *name + + name for the field or ``NULL`` to end the list of named fields, + set to :c:data:`PyStructSequence_UnnamedField` to leave unnamed + + .. c:member:: const char *doc + + field docstring or ``NULL`` to omit .. c:var:: const char * const PyStructSequence_UnnamedField diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 2b21a349ccc4c8..b5f51b6299839e 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1513,21 +1513,23 @@ and :c:data:`PyType_Type` effectively act as defaults.) The following constants are defined to be used as the third argument for :c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`: - +------------------+------------+ - | Constant | Comparison | - +==================+============+ - | :c:macro:`Py_LT` | ``<`` | - +------------------+------------+ - | :c:macro:`Py_LE` | ``<=`` | - +------------------+------------+ - | :c:macro:`Py_EQ` | ``==`` | - +------------------+------------+ - | :c:macro:`Py_NE` | ``!=`` | - +------------------+------------+ - | :c:macro:`Py_GT` | ``>`` | - +------------------+------------+ - | :c:macro:`Py_GE` | ``>=`` | - +------------------+------------+ + .. c:namespace:: NULL + + +--------------------+------------+ + | Constant | Comparison | + +====================+============+ + | .. c:macro:: Py_LT | ``<`` | + +--------------------+------------+ + | .. c:macro:: Py_LE | ``<=`` | + +--------------------+------------+ + | .. c:macro:: Py_EQ | ``==`` | + +--------------------+------------+ + | .. c:macro:: Py_NE | ``!=`` | + +--------------------+------------+ + | .. c:macro:: Py_GT | ``>`` | + +--------------------+------------+ + | .. c:macro:: Py_GE | ``>=`` | + +--------------------+------------+ The following macro is defined to ease writing rich comparison functions: diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 2a10db5f3fff89..399feff4cb5fed 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -32,7 +32,6 @@ Doc/c-api/set.rst Doc/c-api/stable.rst Doc/c-api/structures.rst Doc/c-api/sys.rst -Doc/c-api/tuple.rst Doc/c-api/type.rst Doc/c-api/typehints.rst Doc/c-api/typeobj.rst