Issue python#28496: Mark up constants 0, 1 and -1 that denote return values or

special input values as literal text.

Author: serhiy-storchaka

Doc/c-api/arg.rst

@@ -338,7 +338,7 @@ Other objects
 ``p`` (:class:`bool`) [int]
    Tests the value passed in for truth (a boolean **p**\ redicate) and converts
    the result to its equivalent C true/false integer value.
-   Sets the int to 1 if the expression was true and 0 if it was false.
+   Sets the int to ``1`` if the expression was true and ``0`` if it was false.
    This accepts any valid Python value.  See :ref:`truth` for more
    information about how Python tests values for truth.
 

Doc/c-api/buffer.rst

@@ -156,7 +156,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
    .. c:member:: int ndim
 
       The number of dimensions the memory represents as an n-dimensional array.
-      If it is 0, :c:member:`~Py_buffer.buf` points to a single item representing
+      If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing
       a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
       and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
 
@@ -427,7 +427,7 @@ Buffer-related functions
 
 .. c:function:: int PyObject_CheckBuffer(PyObject *obj)
 
-   Return 1 if *obj* supports the buffer interface otherwise 0.  When 1 is
+   Return ``1`` if *obj* supports the buffer interface otherwise ``0``.  When ``1`` is
    returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
    succeed.
 
@@ -437,7 +437,7 @@ Buffer-related functions
    Send a request to *exporter* to fill in *view* as specified by  *flags*.
    If the exporter cannot provide a buffer of the exact type, it MUST raise
    :c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
-   return -1.
+   return ``-1``.
 
    On success, fill in *view*, set :c:member:`view->obj` to a new reference
    to *exporter* and return 0. In the case of chained buffer providers
@@ -468,9 +468,9 @@ Buffer-related functions
 
 .. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
 
-   Return 1 if the memory defined by the *view* is C-style (*order* is
+   Return ``1`` if the memory defined by the *view* is C-style (*order* is
    ``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
-   (*order* is ``'A'``).  Return 0 otherwise.
+   (*order* is ``'A'``).  Return ``0`` otherwise.
 
 
 .. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)
@@ -492,7 +492,7 @@ Buffer-related functions
 
    On success, set :c:member:`view->obj` to a new reference to *exporter* and
    return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
-   :c:member:`view->obj` to *NULL* and return -1;
+   :c:member:`view->obj` to *NULL* and return ``-1``;
 
    If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
    *exporter* MUST be set to the exporting object and *flags* must be passed

Doc/c-api/capsule.rst

@@ -120,31 +120,31 @@ Refer to :ref:`using-capsules` for more information on using these objects.
    guaranteed to succeed.
 
    Return a nonzero value if the object is valid and matches the name passed in.
-   Return 0 otherwise.  This function will not fail.
+   Return ``0`` otherwise.  This function will not fail.
 
 .. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
 
    Set the context pointer inside *capsule* to *context*.
 
-   Return 0 on success.  Return nonzero and set an exception on failure.
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
 
 .. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
 
    Set the destructor inside *capsule* to *destructor*.
 
-   Return 0 on success.  Return nonzero and set an exception on failure.
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
 
 .. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
 
    Set the name inside *capsule* to *name*.  If non-*NULL*, the name must
    outlive the capsule.  If the previous *name* stored in the capsule was not
    *NULL*, no attempt is made to free it.
 
-   Return 0 on success.  Return nonzero and set an exception on failure.
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
 
 .. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
 
    Set the void pointer inside *capsule* to *pointer*.  The pointer may not be
    *NULL*.
 
-   Return 0 on success.  Return nonzero and set an exception on failure.
+   Return ``0`` on success.  Return nonzero and set an exception on failure.

Doc/c-api/import.rst

@@ -185,10 +185,10 @@ Importing Modules
 
    Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` file).
    The magic number should be present in the first four bytes of the bytecode
-   file, in little-endian byte order. Returns -1 on error.
+   file, in little-endian byte order. Returns ``-1`` on error.
 
    .. versionchanged:: 3.3
-      Return value of -1 upon failure.
+      Return value of ``-1`` upon failure.
 
 
 .. c:function:: const char * PyImport_GetMagicTag()

Doc/c-api/init.rst

@@ -44,8 +44,8 @@ Initializing and finalizing the interpreter
 
 .. c:function:: void Py_InitializeEx(int initsigs)
 
-   This function works like :c:func:`Py_Initialize` if *initsigs* is 1. If
-   *initsigs* is 0, it skips initialization registration of signal handlers, which
+   This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If
+   *initsigs* is ``0``, it skips initialization registration of signal handlers, which
    might be useful when Python is embedded.
 
 
@@ -123,7 +123,7 @@ Process-wide parameters
    If :c:func:`Py_FinalizeEx` is called, this function will need to be called
    again in order to affect subsequent calls to :c:func:`Py_Initialize`.
 
-   Returns 0 if successful, a nonzero value on error (e.g. calling after the
+   Returns ``0`` if successful, a nonzero value on error (e.g. calling after the
    interpreter has already been initialized).
 
    .. versionadded:: 3.4
@@ -358,7 +358,7 @@ Process-wide parameters
    - If the name of an existing script is passed in ``argv[0]``, the absolute
      path of the directory where the script is located is prepended to
      :data:`sys.path`.
-   - Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point
+   - Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
      to an existing file name), an empty string is prepended to
      :data:`sys.path`, which is the same as prepending the current working
      directory (``"."``).
@@ -368,7 +368,7 @@ Process-wide parameters
 
    .. note::
       It is recommended that applications embedding the Python interpreter
-      for purposes other than executing a single script pass 0 as *updatepath*,
+      for purposes other than executing a single script pass ``0`` as *updatepath*,
       and update :data:`sys.path` themselves if desired.
       See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
 
@@ -380,14 +380,14 @@ Process-wide parameters
 
    .. versionadded:: 3.1.3
 
-   .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
+   .. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
       check w/ Guido.
 
 
 .. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
 
    This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
-   to 1 unless the :program:`python` interpreter was started with the
+   to ``1`` unless the :program:`python` interpreter was started with the
    :option:`-I`.
 
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
@@ -727,10 +727,10 @@ with sub-interpreters:
 
 .. c:function:: int PyGILState_Check()
 
-   Return 1 if the current thread is holding the GIL and 0 otherwise.
+   Return ``1`` if the current thread is holding the GIL and ``0`` otherwise.
    This function can be called from any thread at any time.
    Only if it has had its Python thread state initialized and currently is
-   holding the GIL will it return 1.
+   holding the GIL will it return ``1``.
    This is mainly a helper/diagnostic function.  It can be useful
    for example in callback contexts or memory allocation functions when
    knowing that the GIL is locked can allow the caller to perform sensitive
@@ -1000,8 +1000,8 @@ pointer and a void pointer argument.
    .. index:: single: Py_AddPendingCall()
 
    Schedule a function to be called from the main interpreter thread.  On
-   success, 0 is returned and *func* is queued for being called in the
-   main thread.  On failure, -1 is returned without setting any exception.
+   success, ``0`` is returned and *func* is queued for being called in the
+   main thread.  On failure, ``-1`` is returned without setting any exception.
 
    When successfully queued, *func* will be *eventually* called from the
    main interpreter thread with the argument *arg*.  It will be called
@@ -1012,7 +1012,7 @@ pointer and a void pointer argument.
    * with the main thread holding the :term:`global interpreter lock`
      (*func* can therefore use the full C API).
 
-   *func* must return 0 on success, or -1 on failure with an exception
+   *func* must return ``0`` on success, or ``-1`` on failure with an exception
    set.  *func* won't be interrupted to perform another asynchronous
    notification recursively, but it can still be interrupted to switch
    threads if the global interpreter lock is released.

Doc/c-api/long.rst

@@ -232,7 +232,7 @@ All integers are implemented as "long" integer objects of arbitrary size.
    method (if present) to convert it to a :c:type:`PyLongObject`.
 
    If the value of *obj* is out of range for an :c:type:`unsigned long`,
-   return the reduction of that value modulo :const:`ULONG_MAX + 1`.
+   return the reduction of that value modulo ``ULONG_MAX + 1``.
 
 
 .. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
@@ -242,7 +242,7 @@ All integers are implemented as "long" integer objects of arbitrary size.
    method (if present) to convert it to a :c:type:`PyLongObject`.
 
    If the value of *obj* is out of range for an :c:type:`unsigned long long`,
-   return the reduction of that value modulo :const:`PY_ULLONG_MAX + 1`.
+   return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
 
 
 .. c:function:: double PyLong_AsDouble(PyObject *pylong)

Doc/c-api/number.rst

@@ -266,7 +266,7 @@ Number Protocol
 .. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
 
    Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
-   integer.  If the call fails, an exception is raised and -1 is returned.
+   integer.  If the call fails, an exception is raised and ``-1`` is returned.
 
    If *o* can be converted to a Python int but the attempt to
    convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the

Doc/c-api/set.rst

@@ -114,7 +114,7 @@ or :class:`frozenset` or instances of their subtypes.
 
 .. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
 
-   Return 1 if found, 0 if not found, and -1 if an error is encountered.  Unlike
+   Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered.  Unlike
    the Python :meth:`__contains__` method, this function does not automatically
    convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
    the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
@@ -125,8 +125,8 @@ or :class:`frozenset` or instances of their subtypes.
 
    Add *key* to a :class:`set` instance.  Also works with :class:`frozenset`
    instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
-   of brand new frozensets before they are exposed to other code).  Return 0 on
-   success or -1 on failure. Raise a :exc:`TypeError` if the *key* is
+   of brand new frozensets before they are exposed to other code).  Return ``0`` on
+   success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is
    unhashable. Raise a :exc:`MemoryError` if there is no room to grow.  Raise a
    :exc:`SystemError` if *set* is not an instance of :class:`set` or its
    subtype.
@@ -138,7 +138,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
 
 .. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
 
-   Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
+   Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
    error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
    :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~set.discard`
    method, this function does not automatically convert unhashable sets into

Doc/c-api/slice.rst

@@ -32,9 +32,9 @@ Slice Objects
    assuming a sequence of length *length*. Treats indices greater than
    *length* as errors.
 
-   Returns 0 on success and -1 on error with no exception set (unless one of
+   Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
    the indices was not :const:`None` and failed to be converted to an integer,
-   in which case -1 is returned with an exception set).
+   in which case ``-1`` is returned with an exception set).
 
    You probably do not want to use this function.
 
@@ -51,7 +51,7 @@ Slice Objects
    of bounds indices are clipped in a manner consistent with the handling of
    normal slices.
 
-   Returns 0 on success and -1 on error with exception set.
+   Returns ``0`` on success and ``-1`` on error with exception set.
 
    .. versionchanged:: 3.2
       The parameter type for the *slice* parameter was ``PySliceObject*``

Doc/c-api/structures.rst

@@ -291,7 +291,7 @@ definition with the same method name.
    handles use of the :keyword:`del` statement on that attribute more correctly
    than :c:macro:`T_OBJECT`.
 
-   :attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for
+   :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
    read-only access.  Using :c:macro:`T_STRING` for :attr:`type` implies
    :c:macro:`READONLY`.  Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
    members can be deleted.  (They are set to *NULL*).