Skip to content

Commit

Permalink
[3.11] gh-93738: Documentation C syntax (Function glob patterns -> li…
Browse files Browse the repository at this point in the history
…teral markup) (GH-97774) (#97910)

(cherry picked from commit 0e72606)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
  • Loading branch information
3 people authored and pablogsal committed Oct 22, 2022
1 parent c5d6009 commit 6ff98f7
Show file tree
Hide file tree
Showing 7 changed files with 21 additions and 21 deletions.
8 changes: 4 additions & 4 deletions Doc/c-api/arg.rst
Original file line number Diff line number Diff line change
Expand Up @@ -335,7 +335,7 @@ Other objects
status = converter(object, address);

where *object* is the Python object to be converted and *address* is the
:c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` function.
:c:type:`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.
Expand Down Expand Up @@ -409,9 +409,9 @@ what is specified for the corresponding format unit in that case.

For the conversion to succeed, the *arg* object must match the format
and the format must be exhausted. On success, the
:c:func:`PyArg_Parse\*` functions return true, otherwise they return
``PyArg_Parse*`` functions return true, otherwise they return
false and raise an appropriate exception. When the
:c:func:`PyArg_Parse\*` functions fail due to conversion failure in one
``PyArg_Parse*`` functions fail due to conversion failure in one
of the format units, the variables at the addresses corresponding to that
and the following format units are left untouched.

Expand Down Expand Up @@ -518,7 +518,7 @@ Building values
.. c:function:: PyObject* Py_BuildValue(const char *format, ...)
Create a new value based on a format string similar to those accepted by the
:c:func:`PyArg_Parse\*` family of functions and a sequence of values. Returns
``PyArg_Parse*`` family of functions and a sequence of values. Returns
the value or ``NULL`` in the case of an error; an exception will be raised if
``NULL`` is returned.
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/exceptions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ there is a global indicator (per thread) of the last error that occurred. Most
C API functions don't clear this on success, but will set it to indicate the
cause of the error on failure. Most C API functions also return an error
indicator, usually ``NULL`` if they are supposed to return a pointer, or ``-1``
if they return an integer (exception: the :c:func:`PyArg_\*` functions
if they return an integer (exception: the ``PyArg_*`` functions
return ``1`` for success and ``0`` for failure).

Concretely, the error indicator consists of three object pointers: the
Expand Down Expand Up @@ -370,7 +370,7 @@ Querying the error indicator
.. c:function:: PyObject* PyErr_Occurred()
Test whether the error indicator is set. If set, return the exception *type*
(the first argument to the last call to one of the :c:func:`PyErr_Set\*`
(the first argument to the last call to one of the ``PyErr_Set*``
functions or to :c:func:`PyErr_Restore`). If not set, return ``NULL``. You do not
own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
it.
Expand Down
6 changes: 3 additions & 3 deletions Doc/c-api/init.rst
Original file line number Diff line number Diff line change
Expand Up @@ -847,11 +847,11 @@ from a C thread is::
/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);
Note that the :c:func:`PyGILState_\*` functions assume there is only one global
Note that the ``PyGILState_*`` functions assume there is only one global
interpreter (created automatically by :c:func:`Py_Initialize`). Python
supports the creation of additional interpreters (using
:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the
:c:func:`PyGILState_\*` API is unsupported.
``PyGILState_*`` API is unsupported.
.. _fork-and-threads:
Expand Down Expand Up @@ -1478,7 +1478,7 @@ operations executed by such objects may affect the wrong (sub-)interpreter's
dictionary of loaded modules. It is equally important to avoid sharing
objects from which the above are reachable.
Also note that combining this functionality with :c:func:`PyGILState_\*` APIs
Also note that combining this functionality with ``PyGILState_*`` APIs
is delicate, because these APIs assume a bijection between Python thread states
and OS-level threads, an assumption broken by the presence of sub-interpreters.
It is highly recommended that you don't switch sub-interpreters between a pair
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/module.rst
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ Module Objects
If *module* is not a module object (or a subtype of a module object),
:exc:`SystemError` is raised and ``NULL`` is returned.
It is recommended extensions use other :c:func:`PyModule_\*` and
:c:func:`PyObject_\*` functions rather than directly manipulate a module's
It is recommended extensions use other ``PyModule_*`` and
``PyObject_*`` functions rather than directly manipulate a module's
:attr:`~object.__dict__`.
Expand Down
8 changes: 4 additions & 4 deletions Doc/c-api/typeobj.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ Type Objects

Perhaps one of the most important structures of the Python object system is the
structure that defines a new type: the :c:type:`PyTypeObject` structure. Type
objects can be handled using any of the :c:func:`PyObject_\*` or
:c:func:`PyType_\*` functions, but do not offer much that's interesting to most
objects can be handled using any of the ``PyObject_*`` or
``PyType_*`` functions, but do not offer much that's interesting to most
Python applications. These objects are fundamental to how objects behave, so
they are very important to the interpreter itself and to any extension module
that implements new types.
Expand Down Expand Up @@ -1484,8 +1484,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
If the instances of this type are weakly referenceable, this field is greater
than zero and contains the offset in the instance structure of the weak
reference list head (ignoring the GC header, if present); this offset is used by
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
instance structure needs to include a field of type :c:type:`PyObject*` which is
:c:func:`PyObject_ClearWeakRefs` and the ``PyWeakref_*`` functions. The
instance structure needs to include a field of type :c:expr:`PyObject*` which is
initialized to ``NULL``.

Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
Expand Down
6 changes: 3 additions & 3 deletions Doc/extending/extending.rst
Original file line number Diff line number Diff line change
Expand Up @@ -157,16 +157,16 @@ since you should be able to tell from the return value.

When a function *f* that calls another function *g* detects that the latter
fails, *f* should itself return an error value (usually ``NULL`` or ``-1``). It
should *not* call one of the :c:func:`PyErr_\*` functions --- one has already
should *not* call one of the ``PyErr_*`` functions --- one has already
been called by *g*. *f*'s caller is then supposed to also return an error
indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so on
indication to *its* caller, again *without* calling ``PyErr_*``, and so on
--- the most detailed cause of the error was already reported by the function
that first detected it. Once the error reaches the Python interpreter's main
loop, this aborts the currently executing Python code and tries to find an
exception handler specified by the Python programmer.

(There are situations where a module can actually give a more detailed error
message by calling another :c:func:`PyErr_\*` function, and in such cases it is
message by calling another ``PyErr_*`` function, and in such cases it is
fine to do so. As a general rule, however, this is not necessary, and can cause
information about the cause of the error to be lost: most operations can fail
for a variety of reasons.)
Expand Down
6 changes: 3 additions & 3 deletions Doc/whatsnew/2.5.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2270,9 +2270,9 @@ code:
earlier section :ref:`pep-353` for a discussion of this change.

* C API: The obmalloc changes mean that you must be careful to not mix usage
of the :c:func:`PyMem_\*` and :c:func:`PyObject_\*` families of functions. Memory
allocated with one family's :c:func:`\*_Malloc` must be freed with the
corresponding family's :c:func:`\*_Free` function.
of the ``PyMem_*`` and ``PyObject_*`` families of functions. Memory
allocated with one family's ``*_Malloc`` must be freed with the
corresponding family's ``*_Free`` function.

.. ======================================================================
Expand Down

0 comments on commit 6ff98f7

Please sign in to comment.