Skip to content

Commit 17aada0

Browse files
[3.11] gh-107091: Fix some uses of :attr: role (GH-107318) (GH-107331)
Fix also formatting of PyMethodDef members. (cherry picked from commit d363eb5)
1 parent 00b65da commit 17aada0

File tree

9 files changed

+64
-58
lines changed

9 files changed

+64
-58
lines changed

Doc/c-api/import.rst

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -283,23 +283,25 @@ Importing Modules
283283
284284
.. c:struct:: _inittab
285285
286-
Structure describing a single entry in the list of built-in modules. Each of
287-
these structures gives the name and initialization function for a module built
288-
into the interpreter. The name is an ASCII encoded string. Programs which
286+
Structure describing a single entry in the list of built-in modules.
287+
Programs which
289288
embed Python may use an array of these structures in conjunction with
290289
:c:func:`PyImport_ExtendInittab` to provide additional built-in modules.
291-
The structure is defined in :file:`Include/import.h` as::
290+
The structure consists of two members:
292291
293-
struct _inittab {
294-
const char *name; /* ASCII encoded string */
295-
PyObject* (*initfunc)(void);
296-
};
292+
.. c:member:: const char *name
293+
294+
The module name, as an ASCII encoded string.
295+
296+
.. c: member:: PyObject* (*initfunc)(void)
297+
298+
Initialization function for a module built into the interpreter.
297299
298300
299301
.. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
300302
301303
Add a collection of modules to the table of built-in modules. The *newtab*
302-
array must end with a sentinel entry which contains ``NULL`` for the :attr:`name`
304+
array must end with a sentinel entry which contains ``NULL`` for the :c:member:`~_inittab.name`
303305
field; failure to provide the sentinel value can result in a memory fault.
304306
Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
305307
extend the internal table. In the event of failure, no modules are added to the

Doc/c-api/init.rst

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -914,8 +914,11 @@ code, or when embedding the Python interpreter:
914914
.. c:type:: PyThreadState
915915
916916
This data structure represents the state of a single thread. The only public
917-
data member is :attr:`interp` (:c:expr:`PyInterpreterState *`), which points to
918-
this thread's interpreter state.
917+
data member is:
918+
919+
.. c:member:: PyInterpreterState *interp
920+
921+
This thread's interpreter state.
919922
920923
921924
.. c:function:: void PyEval_InitThreads()

Doc/c-api/structures.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ the definition of all other Python objects.
3434

3535
.. c:type:: PyVarObject
3636
37-
This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
37+
This is an extension of :c:type:`PyObject` that adds the :c:member:`~PyVarObject.ob_size`
3838
field. This is only used for objects that have some notion of *length*.
3939
This type does not often appear in the Python/C API.
4040
Access to the members must be done by using the macros
@@ -171,7 +171,7 @@ the definition of all other Python objects.
171171
.. c:macro:: PyVarObject_HEAD_INIT(type, size)
172172
173173
This is a macro which expands to initialization values for a new
174-
:c:type:`PyVarObject` type, including the :attr:`ob_size` field.
174+
:c:type:`PyVarObject` type, including the :c:member:`~PyVarObject.ob_size` field.
175175
This macro expands to::
176176
177177
_PyObject_EXTRA_INIT
@@ -247,21 +247,21 @@ Implementing functions and methods
247247
Structure used to describe a method of an extension type. This structure has
248248
four fields:
249249
250-
.. c:member:: const char* ml_name
250+
.. c:member:: const char *ml_name
251251
252-
name of the method
252+
Name of the method.
253253
254254
.. c:member:: PyCFunction ml_meth
255255
256-
pointer to the C implementation
256+
Pointer to the C implementation.
257257
258258
.. c:member:: int ml_flags
259259
260-
flags bits indicating how the call should be constructed
260+
Flags bits indicating how the call should be constructed.
261261
262-
.. c:member:: const char* ml_doc
262+
.. c:member:: const char *ml_doc
263263
264-
points to the contents of the docstring
264+
Points to the contents of the docstring.
265265
266266
The :c:member:`~PyMethodDef.ml_meth` is a C function pointer.
267267
The functions may be of different

Doc/c-api/tuple.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,8 @@ type.
164164
165165
Describes a field of a struct sequence. As a struct sequence is modeled as a
166166
tuple, all fields are typed as :c:expr:`PyObject*`. The index in the
167-
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
167+
:c:member:`~PyStructSequence_Desc.fields` array of
168+
the :c:type:`PyStructSequence_Desc` determines which
168169
field of the struct sequence is described.
169170
170171
+-----------+------------------+-----------------------------------------+

Doc/c-api/typeobj.rst

Lines changed: 32 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -483,17 +483,17 @@ PyObject Slots
483483
--------------
484484

485485
The type object structure extends the :c:type:`PyVarObject` structure. The
486-
:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
486+
:c:member:`~PyVarObject.ob_size` field is used for dynamic types (created by :func:`type_new`,
487487
usually called from a class statement). Note that :c:data:`PyType_Type` (the
488488
metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e.
489-
type objects) *must* have the :attr:`ob_size` field.
489+
type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
490490

491491

492492
.. c:member:: Py_ssize_t PyObject.ob_refcnt
493493
494494
This is the type object's reference count, initialized to ``1`` by the
495495
``PyObject_HEAD_INIT`` macro. Note that for :ref:`statically allocated type
496-
objects <static-types>`, the type's instances (objects whose :attr:`ob_type`
496+
objects <static-types>`, the type's instances (objects whose :c:member:`~PyObject.ob_type`
497497
points back to the type) do *not* count as references. But for
498498
:ref:`dynamically allocated type objects <heap-types>`, the instances *do*
499499
count as references.
@@ -517,8 +517,8 @@ type objects) *must* have the :attr:`ob_size` field.
517517
Foo_Type.ob_type = &PyType_Type;
518518

519519
This should be done before any instances of the type are created.
520-
:c:func:`PyType_Ready` checks if :attr:`ob_type` is ``NULL``, and if so,
521-
initializes it to the :attr:`ob_type` field of the base class.
520+
:c:func:`PyType_Ready` checks if :c:member:`~PyObject.ob_type` is ``NULL``, and if so,
521+
initializes it to the :c:member:`~PyObject.ob_type` field of the base class.
522522
:c:func:`PyType_Ready` will not change this field if it is non-zero.
523523

524524
**Inheritance:**
@@ -617,20 +617,20 @@ and :c:data:`PyType_Type` effectively act as defaults.)
617617
instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`.
618618

619619
For a type with variable-length instances, the instances must have an
620-
:attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
620+
:c:member:`~PyVarObject.ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
621621
times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of
622-
N is typically stored in the instance's :attr:`ob_size` field. There are
623-
exceptions: for example, ints use a negative :attr:`ob_size` to indicate a
622+
N is typically stored in the instance's :c:member:`~PyVarObject.ob_size` field. There are
623+
exceptions: for example, ints use a negative :c:member:`~PyVarObject.ob_size` to indicate a
624624
negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
625-
:attr:`ob_size` field in the instance layout doesn't mean that the instance
625+
:c:member:`~PyVarObject.ob_size` field in the instance layout doesn't mean that the instance
626626
structure is variable-length (for example, the structure for the list type has
627-
fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
627+
fixed-length instances, yet those instances have a meaningful :c:member:`~PyVarObject.ob_size`
628628
field).
629629

630630
The basic size includes the fields in the instance declared by the macro
631631
:c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to
632-
declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
633-
:attr:`_ob_next` fields if they are present. This means that the only correct
632+
declare the instance struct) and this in turn includes the :c:member:`~PyObject._ob_prev` and
633+
:c:member:`~PyObject._ob_next` fields if they are present. This means that the only correct
634634
way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the
635635
``sizeof`` operator on the struct used to declare the instance layout.
636636
The basic size does not include the GC header size.
@@ -762,7 +762,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
762762

763763
**Inheritance:**
764764

765-
Group: :attr:`tp_getattr`, :attr:`tp_getattro`
765+
Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject.tp_getattro`
766766

767767
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype
768768
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
@@ -779,7 +779,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
779779

780780
**Inheritance:**
781781

782-
Group: :attr:`tp_setattr`, :attr:`tp_setattro`
782+
Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject.tp_setattro`
783783

784784
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype
785785
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
@@ -881,7 +881,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
881881
normal return value; when an error occurs during the computation of the hash
882882
value, the function should set an exception and return ``-1``.
883883

884-
When this field is not set (*and* :attr:`tp_richcompare` is not set),
884+
When this field is not set (*and* :c:member:`~PyTypeObject.tp_richcompare` is not set),
885885
an attempt to take the hash of the object raises :exc:`TypeError`.
886886
This is the same as setting it to :c:func:`PyObject_HashNotImplemented`.
887887

@@ -895,7 +895,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
895895

896896
**Inheritance:**
897897

898-
Group: :attr:`tp_hash`, :attr:`tp_richcompare`
898+
Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject.tp_richcompare`
899899

900900
This field is inherited by subtypes together with
901901
:c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of
@@ -954,7 +954,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
954954

955955
**Inheritance:**
956956

957-
Group: :attr:`tp_getattr`, :attr:`tp_getattro`
957+
Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject.tp_getattro`
958958

959959
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype
960960
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
@@ -980,7 +980,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
980980

981981
**Inheritance:**
982982

983-
Group: :attr:`tp_setattr`, :attr:`tp_setattro`
983+
Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject.tp_setattro`
984984

985985
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype
986986
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
@@ -1046,7 +1046,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
10461046
10471047
This bit is set when the type object itself is allocated on the heap, for
10481048
example, types created dynamically using :c:func:`PyType_FromSpec`. In this
1049-
case, the :attr:`ob_type` field of its instances is considered a reference to
1049+
case, the :c:member:`~PyObject.ob_type` field of its instances is considered a reference to
10501050
the type, and the type object is INCREF'ed when a new instance is created, and
10511051
DECREF'ed when an instance is destroyed (this does not apply to instances of
10521052
subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
@@ -1099,13 +1099,13 @@ and :c:data:`PyType_Type` effectively act as defaults.)
10991099

11001100
**Inheritance:**
11011101

1102-
Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
1102+
Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
11031103

11041104
The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited
1105-
together with the :attr:`tp_traverse` and :attr:`tp_clear`
1105+
together with the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear`
11061106
fields, i.e. if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is
1107-
clear in the subtype and the :attr:`tp_traverse` and
1108-
:attr:`tp_clear` fields in the subtype exist and have ``NULL``
1107+
clear in the subtype and the :c:member:`~PyTypeObject.tp_traverse` and
1108+
:c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have ``NULL``
11091109
values.
11101110

11111111

@@ -1357,7 +1357,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
13571357

13581358
**Inheritance:**
13591359

1360-
Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
1360+
Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
13611361

13621362
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the
13631363
:c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
@@ -1424,7 +1424,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
14241424

14251425
**Inheritance:**
14261426

1427-
Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
1427+
Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
14281428

14291429
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the
14301430
:c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
@@ -1483,7 +1483,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
14831483

14841484
**Inheritance:**
14851485

1486-
Group: :attr:`tp_hash`, :attr:`tp_richcompare`
1486+
Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject.tp_richcompare`
14871487

14881488
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`:
14891489
a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when
@@ -1492,9 +1492,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
14921492

14931493
**Default:**
14941494

1495-
:c:data:`PyBaseObject_Type` provides a :attr:`tp_richcompare`
1495+
:c:data:`PyBaseObject_Type` provides a :c:member:`~PyTypeObject.tp_richcompare`
14961496
implementation, which may be inherited. However, if only
1497-
:attr:`tp_hash` is defined, not even the inherited function is used
1497+
:c:member:`~PyTypeObject.tp_hash` is defined, not even the inherited function is used
14981498
and instances of the type will not be able to participate in any
14991499
comparisons.
15001500

@@ -2288,9 +2288,9 @@ Sequence Object Structures
22882288
This slot must be filled for the :c:func:`PySequence_Check`
22892289
function to return ``1``, it can be ``NULL`` otherwise.
22902290

2291-
Negative indexes are handled as follows: if the :attr:`sq_length` slot is
2291+
Negative indexes are handled as follows: if the :c:member:`~PySequenceMethods.sq_length` slot is
22922292
filled, it is called and the sequence length is used to compute a positive
2293-
index which is passed to :attr:`sq_item`. If :attr:`sq_length` is ``NULL``,
2293+
index which is passed to :c:member:`~PySequenceMethods.sq_item`. If :c:member:`!sq_length` is ``NULL``,
22942294
the index is passed as is to the function.
22952295

22962296
.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
@@ -2500,8 +2500,8 @@ Slot Type typedefs
25002500
The purpose of this function is to separate memory allocation from memory
25012501
initialization. It should return a pointer to a block of memory of adequate
25022502
length for the instance, suitably aligned, and initialized to zeros, but with
2503-
:attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If
2504-
the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field
2503+
:c:member:`~PyObject.ob_refcnt` set to ``1`` and :c:member:`~PyObject.ob_type` set to the type argument. If
2504+
the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :c:member:`~PyVarObject.ob_size` field
25052505
should be initialized to *nitems* and the length of the allocated memory block
25062506
should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
25072507
``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block

Doc/c-api/veryhigh.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,7 @@ the same library that the Python runtime is using.
345345
executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from
346346
__future__ import`` can modify *flags*.
347347
348-
Whenever ``PyCompilerFlags *flags`` is ``NULL``, :attr:`cf_flags` is treated as
348+
Whenever ``PyCompilerFlags *flags`` is ``NULL``, :c:member:`~PyCompilerFlags.cf_flags` is treated as
349349
equal to ``0``, and any modification due to ``from __future__ import`` is
350350
discarded.
351351
@@ -359,7 +359,7 @@ the same library that the Python runtime is using.
359359
initialized to ``PY_MINOR_VERSION``.
360360
361361
The field is ignored by default, it is used if and only if
362-
``PyCF_ONLY_AST`` flag is set in *cf_flags*.
362+
``PyCF_ONLY_AST`` flag is set in :c:member:`~PyCompilerFlags.cf_flags`.
363363
364364
.. versionchanged:: 3.8
365365
Added *cf_feature_version* field.

Doc/extending/newtypes.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -270,7 +270,7 @@ structure::
270270
One entry should be defined for each method provided by the type; no entries are
271271
needed for methods inherited from a base type. One additional entry is needed
272272
at the end; it is a sentinel that marks the end of the array. The
273-
:attr:`ml_name` field of the sentinel must be ``NULL``.
273+
:c:member:`~PyMethodDef.ml_name` field of the sentinel must be ``NULL``.
274274

275275
The second table is used to define attributes which map directly to data stored
276276
in the instance. A variety of primitive C types are supported, and access may

Doc/extending/newtypes_tutorial.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -176,8 +176,8 @@ Everything else in the file should be familiar, except for some code in
176176
if (PyType_Ready(&CustomType) < 0)
177177
return;
178178

179-
This initializes the :class:`Custom` type, filling in a number of members
180-
to the appropriate default values, including :attr:`ob_type` that we initially
179+
This initializes the :class:`!Custom` type, filling in a number of members
180+
to the appropriate default values, including :c:member:`~PyObject.ob_type` that we initially
181181
set to ``NULL``. ::
182182

183183
Py_INCREF(&CustomType);

Doc/whatsnew/2.5.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -954,7 +954,7 @@ The return value must be either a Python integer or long integer. The
954954
interpreter will check that the type returned is correct, and raises a
955955
:exc:`TypeError` if this requirement isn't met.
956956

957-
A corresponding :attr:`nb_index` slot was added to the C-level
957+
A corresponding :c:member:`~PyNumberMethods.nb_index` slot was added to the C-level
958958
:c:type:`PyNumberMethods` structure to let C extensions implement this protocol.
959959
``PyNumber_Index(obj)`` can be used in extension code to call the
960960
:meth:`__index__` function and retrieve its result.

0 commit comments

Comments
 (0)