[3.8] bpo-38600: NULL -> NULL. (GH-17001) (GH-17003)

Also fix some other formatting.
(cherry picked from commit e835b31)

Author: serhiy-storchaka

Doc/c-api/arg.rst

@@ -345,7 +345,7 @@ Other objects
    If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a
    second time if the argument parsing eventually fails, giving the converter a
    chance to release any memory that it had already allocated. In this second
-   call, the *object* parameter will be NULL; *address* will have the same value
+   call, the *object* parameter will be ``NULL``; *address* will have the same value
    as in the original call.
 
    .. versionchanged:: 3.1

Doc/c-api/buffer.rst

@@ -130,7 +130,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
    .. c:member:: Py_ssize_t itemsize
 
       Item size in bytes of a single element. Same as the value of :func:`struct.calcsize`
-      called on non-NULL :c:member:`~Py_buffer.format` values.
+      called on non-``NULL`` :c:member:`~Py_buffer.format` values.
 
       Important exception: If a consumer requests a buffer without the
       :c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will
@@ -199,7 +199,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
       memory block).
 
       If all suboffsets are negative (i.e. no de-referencing is needed), then
-      this field must be NULL (the default value).
+      this field must be ``NULL`` (the default value).
 
       This type of array representation is used by the Python Imaging Library
       (PIL). See `complex arrays`_ for further information how to access elements
@@ -407,7 +407,7 @@ to two ``char x[2][3]`` arrays that can be located anywhere in memory.
 
 
 Here is a function that returns a pointer to the element in an N-D array
-pointed to by an N-dimensional index when there are both non-NULL strides
+pointed to by an N-dimensional index when there are both non-``NULL`` strides
 and suboffsets::
 
    void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
@@ -520,4 +520,4 @@ Buffer-related functions
 
    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
-   unmodified. Otherwise, *exporter* MUST be NULL.
+   unmodified. Otherwise, *exporter* MUST be ``NULL``.

Doc/c-api/conversion.rst

@@ -32,7 +32,7 @@ NULL``.
 
 If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
 avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
-*Py_FatalError*.
+:c:func:`Py_FatalError`.
 
 The return value (*rv*) for these functions should be interpreted as follows:
 
@@ -95,21 +95,21 @@ The following functions provide locale-independent string to number conversions.
    must be 0 and is ignored.  The ``'r'`` format code specifies the
    standard :func:`repr` format.
 
-   *flags* can be zero or more of the values *Py_DTSF_SIGN*,
-   *Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:
+   *flags* can be zero or more of the values ``Py_DTSF_SIGN``,
+   ``Py_DTSF_ADD_DOT_0``, or ``Py_DTSF_ALT``, or-ed together:
 
-   * *Py_DTSF_SIGN* means to always precede the returned string with a sign
+   * ``Py_DTSF_SIGN`` means to always precede the returned string with a sign
      character, even if *val* is non-negative.
 
-   * *Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look
+   * ``Py_DTSF_ADD_DOT_0`` means to ensure that the returned string will not look
      like an integer.
 
-   * *Py_DTSF_ALT* means to apply "alternate" formatting rules.  See the
+   * ``Py_DTSF_ALT`` means to apply "alternate" formatting rules.  See the
      documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
      details.
 
-   If *ptype* is non-NULL, then the value it points to will be set to one of
-   *Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that
+   If *ptype* is non-``NULL``, then the value it points to will be set to one of
+   ``Py_DTST_FINITE``, ``Py_DTST_INFINITE``, or ``Py_DTST_NAN``, signifying that
    *val* is a finite number, an infinite number, or not a number, respectively.
 
    The return value is a pointer to *buffer* with the converted string or

Doc/c-api/coro.rst

@@ -23,7 +23,7 @@ return.
 
 .. c:function:: int PyCoro_CheckExact(PyObject *ob)
 
-   Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be ``NULL``.
+   Return true if *ob*'s type is :c:type:`PyCoro_Type`; *ob* must not be ``NULL``.
 
 
 .. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)

Doc/c-api/exceptions.rst

@@ -19,9 +19,9 @@ return ``1`` for success and ``0`` for failure).
 
 Concretely, the error indicator consists of three object pointers: the
 exception's type, the exception's value, and the traceback object.  Any
-of those pointers can be NULL if non-set (although some combinations are
-forbidden, for example you can't have a non-NULL traceback if the exception
-type is NULL).
+of those pointers can be ``NULL`` if non-set (although some combinations are
+forbidden, for example you can't have a non-``NULL`` traceback if the exception
+type is ``NULL``).
 
 When a function must fail because some function it called failed, it generally
 doesn't set the error indicator; the function it called already set it.  It is
@@ -92,7 +92,7 @@ Raising exceptions
 
 These functions help you set the current thread's error indicator.
 For convenience, some of these functions will always return a
-NULL pointer for use in a ``return`` statement.
+``NULL`` pointer for use in a ``return`` statement.
 
 
 .. c:function:: void PyErr_SetString(PyObject *type, const char *message)

Doc/c-api/function.rst

@@ -42,8 +42,8 @@ There are a few functions specific to Python functions.
 .. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
 
    As :c:func:`PyFunction_New`, but also allows setting the function object's
-   ``__qualname__`` attribute.  *qualname* should be a unicode object or NULL;
-   if NULL, the ``__qualname__`` attribute is set to the same value as its
+   ``__qualname__`` attribute.  *qualname* should be a unicode object or ``NULL``;
+   if ``NULL``, the ``__qualname__`` attribute is set to the same value as its
    ``__name__`` attribute.
 
    .. versionadded:: 3.3
@@ -75,7 +75,7 @@ There are a few functions specific to Python functions.
 .. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
 
    Set the argument default values for the function object *op*. *defaults* must be
-   *Py_None* or a tuple.
+   ``Py_None`` or a tuple.
 
    Raises :exc:`SystemError` and returns ``-1`` on failure.
 
@@ -89,7 +89,7 @@ There are a few functions specific to Python functions.
 .. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
 
    Set the closure associated with the function object *op*. *closure* must be
-   *Py_None* or a tuple of cell objects.
+   ``Py_None`` or a tuple of cell objects.
 
    Raises :exc:`SystemError` and returns ``-1`` on failure.
 
@@ -103,6 +103,6 @@ There are a few functions specific to Python functions.
 .. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
 
    Set the annotations for the function object *op*. *annotations*
-   must be a dictionary or *Py_None*.
+   must be a dictionary or ``Py_None``.
 
    Raises :exc:`SystemError` and returns ``-1`` on failure.

Doc/c-api/gen.rst

@@ -27,7 +27,7 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
 
 .. c:function:: int PyGen_CheckExact(PyObject *ob)
 
-   Return true if *ob*'s type is *PyGen_Type*; *ob* must not be ``NULL``.
+   Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be ``NULL``.
 
 
 .. c:function:: PyObject* PyGen_New(PyFrameObject *frame)

Doc/c-api/import.rst

@@ -207,8 +207,8 @@ Importing Modules
 .. c:function:: PyObject* PyImport_GetModule(PyObject *name)
 
    Return the already imported module with the given name.  If the
-   module has not been imported yet then returns NULL but does not set
-   an error.  Returns NULL and sets an error if the lookup failed.
+   module has not been imported yet then returns ``NULL`` but does not set
+   an error.  Returns ``NULL`` and sets an error if the lookup failed.
 
    .. versionadded:: 3.7
 

Doc/c-api/init.rst

@@ -329,7 +329,7 @@ Process-wide parameters
    It overrides :envvar:`PYTHONIOENCODING` values, and allows embedding code
    to control IO encoding when the environment variable does not work.
 
-   ``encoding`` and/or ``errors`` may be NULL to use
+   *encoding* and/or *errors* may be ``NULL`` to use
    :envvar:`PYTHONIOENCODING` and/or default values (depending on other
    settings).
 

Doc/c-api/init_config.rst

@@ -61,8 +61,8 @@ PyWideStringList
 
    List of ``wchar_t*`` strings.
 
-   If *length* is non-zero, *items* must be non-NULL and all strings must be
-   non-NULL.
+   If *length* is non-zero, *items* must be non-``NULL`` and all strings must be
+   non-``NULL``.
 
    Methods:
 
@@ -608,7 +608,7 @@ PyConfig
 
       :data:`sys.pycache_prefix`: ``.pyc`` cache prefix.
 
-      If NULL, :data:`sys.pycache_prefix` is set to ``None``.
+      If ``NULL``, :data:`sys.pycache_prefix` is set to ``None``.
 
    .. c:member:: int quiet
 

Doc/c-api/marshal.rst

@@ -16,7 +16,7 @@ Numeric values are stored with the least significant byte first.
 The module supports two versions of the data format: version 0 is the
 historical version, version 1 shares interned strings in the file, and upon
 unmarshalling.  Version 2 uses a binary format for floating point numbers.
-*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
+``Py_MARSHAL_VERSION`` indicates the current file format (currently 2).
 
 
 .. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

Doc/c-api/memory.rst

@@ -424,7 +424,7 @@ Customize Memory Allocators
 
    Set the memory block allocator of the specified domain.
 
-   The new allocator must return a distinct non-NULL pointer when requesting
+   The new allocator must return a distinct non-``NULL`` pointer when requesting
    zero bytes.
 
    For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be

Doc/c-api/number.rst

@@ -275,8 +275,8 @@ Number Protocol
    convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
    *exc* argument is the type of exception that will be raised (usually
    :exc:`IndexError` or :exc:`OverflowError`).  If *exc* is ``NULL``, then the
-   exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
-   integer or *PY_SSIZE_T_MAX* for a positive integer.
+   exception is cleared and the value is clipped to ``PY_SSIZE_T_MIN`` for a negative
+   integer or ``PY_SSIZE_T_MAX`` for a positive integer.
 
 
 .. c:function:: int PyIndex_Check(PyObject *o)

Doc/c-api/object.rst

@@ -354,7 +354,7 @@ Object Protocol
    To get actual number of arguments, use
    :c:func:`PyVectorcall_NARGS(nargsf) <PyVectorcall_NARGS>`.
 
-   *kwnames* can be either NULL (no keyword arguments) or a tuple of keyword
+   *kwnames* can be either ``NULL`` (no keyword arguments) or a tuple of keyword
    names. In the latter case, the values of the keyword arguments are stored
    in *args* after the positional arguments.
    The number of keyword arguments does not influence *nargsf*.

Doc/c-api/tuple.rst

@@ -153,7 +153,7 @@ type.
    | ``name``          | ``const char *``             | name of the struct sequence type     |
    +-------------------+------------------------------+--------------------------------------+
    | ``doc``           | ``const char *``             | pointer to docstring for the type    |
-   |                   |                              | or NULL to omit                      |
+   |                   |                              | or ``NULL`` to omit                  |
    +-------------------+------------------------------+--------------------------------------+
    | ``fields``        | ``PyStructSequence_Field *`` | pointer to ``NULL``-terminated array |
    |                   |                              | with field names of the new type     |
@@ -170,16 +170,16 @@ type.
    :attr:`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       |
-   |           |                  | PyStructSequence_UnnamedField to       |
-   |           |                  | leave unnamed                          |
-   +-----------+------------------+----------------------------------------+
-   | ``doc``   | ``const char *`` | field docstring or ``NULL`` to omit    |
-   +-----------+------------------+----------------------------------------+
+   +-----------+------------------+-----------------------------------------+
+   | 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:var:: char* PyStructSequence_UnnamedField

Doc/c-api/type.rst

@@ -181,7 +181,7 @@ The following functions and structs are used to create
       * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
       * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
 
-      The following fields cannot be set using *PyType_Spec* and *PyType_Slot*:
+      The following fields cannot be set using :c:type:`PyType_Spec` and :c:type:`PyType_Slot`:
 
       * :c:member:`~PyTypeObject.tp_dict`
       * :c:member:`~PyTypeObject.tp_mro`

Doc/c-api/typeobj.rst

@@ -740,7 +740,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
    This field is inherited by subtypes together with
    :c:member:`~PyTypeObject.tp_call`: a subtype inherits
    :c:member:`~PyTypeObject.tp_vectorcall_offset` from its base type when
-   the subtype’s :c:member:`~PyTypeObject.tp_call` is NULL.
+   the subtype’s :c:member:`~PyTypeObject.tp_call` is ``NULL``.
 
    Note that `heap types`_ (including subclasses defined in Python) do not
    inherit the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag.
@@ -1180,7 +1180,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
 
       This bit is set on *static* subtypes if ``tp_flags`` is not overridden:
       a subtype inherits ``_Py_TPFLAGS_HAVE_VECTORCALL`` from its base type
-      when the subtype’s :c:member:`~PyTypeObject.tp_call` is NULL
+      when the subtype’s :c:member:`~PyTypeObject.tp_call` is ``NULL``
       and the subtype's ``Py_TPFLAGS_HEAPTYPE`` is not set.
 
       `Heap types`_ do not inherit ``_Py_TPFLAGS_HAVE_VECTORCALL``.
@@ -1955,7 +1955,7 @@ This results in types that are limited relative to types defined in Python:
   :ref:`sub-interpreters <sub-interpreter-support>`, so they should not
   include any subinterpreter-specific state.
 
-Also, since *PyTypeObject* is not part of the :ref:`stable ABI <stable>`,
+Also, since :c:type:`PyTypeObject` is not part of the :ref:`stable ABI <stable>`,
 any extension modules using static types must be compiled for a specific
 Python minor version.
 

Doc/c-api/unicode.rst

@@ -526,9 +526,9 @@ APIs:
    .. note::
       The width formatter unit is number of characters rather than bytes.
       The precision formatter unit is number of bytes for ``"%s"`` and
-      ``"%V"`` (if the ``PyObject*`` argument is NULL), and a number of
+      ``"%V"`` (if the ``PyObject*`` argument is ``NULL``), and a number of
       characters for ``"%A"``, ``"%U"``, ``"%S"``, ``"%R"`` and ``"%V"``
-      (if the ``PyObject*`` argument is not NULL).
+      (if the ``PyObject*`` argument is not ``NULL``).
 
    .. [1] For integer specifiers (d, u, ld, li, lu, lld, lli, llu, zd, zi,
       zu, i, x): the 0-conversion flag has effect even when a precision is given.
@@ -1172,7 +1172,7 @@ These are the UTF-32 codec APIs:
    If byteorder is ``0``, the output string will always start with the Unicode BOM
    mark (U+FEFF). In the other two modes, no BOM mark is prepended.
 
-   If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output
+   If ``Py_UNICODE_WIDE`` is not defined, surrogate pairs will be output
    as a single code point.
 
    Return ``NULL`` if an exception was raised by the codec.
@@ -1246,7 +1246,7 @@ These are the UTF-16 codec APIs:
    If byteorder is ``0``, the output string will always start with the Unicode BOM
    mark (U+FEFF). In the other two modes, no BOM mark is prepended.
 
-   If *Py_UNICODE_WIDE* is defined, a single :c:type:`Py_UNICODE` value may get
+   If ``Py_UNICODE_WIDE`` is defined, a single :c:type:`Py_UNICODE` value may get
    represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE`
    values is interpreted as a UCS-2 character.
 

Doc/c-api/veryhigh.rst

@@ -80,7 +80,7 @@ the same library that the Python runtime is using.
 .. c:function:: int PyRun_SimpleString(const char *command)
 
    This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below,
-   leaving the *PyCompilerFlags\** argument set to NULL.
+   leaving the :c:type:`PyCompilerFlags`\* argument set to ``NULL``.
 
 
 .. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

Doc/extending/extending.rst

@@ -536,7 +536,7 @@ Later, when it is time to call the function, you call the C function
 :c:func:`PyObject_CallObject`.  This function has two arguments, both pointers to
 arbitrary Python objects: the Python function, and the argument list.  The
 argument list must always be a tuple object, whose length is the number of
-arguments.  To call the Python function with no arguments, pass in NULL, or
+arguments.  To call the Python function with no arguments, pass in ``NULL``, or
 an empty tuple; to call it with one argument, pass a singleton tuple.
 :c:func:`Py_BuildValue` returns a tuple when its format string consists of zero
 or more format codes between parentheses.  For example::

Doc/howto/clinic.rst

@@ -1070,7 +1070,7 @@ Currently Argument Clinic supports only a few return converters:
     DecodeFSDefault
 
 None of these take parameters.  For the first three, return -1 to indicate
-error.  For ``DecodeFSDefault``, the return type is ``const char *``; return a NULL
+error.  For ``DecodeFSDefault``, the return type is ``const char *``; return a ``NULL``
 pointer to indicate an error.
 
 (There's also an experimental ``NoneType`` converter, which lets you

Doc/library/ctypes.rst

@@ -152,8 +152,8 @@ the ``time()`` function, which returns system time in seconds since the Unix
 epoch, and the ``GetModuleHandleA()`` function, which returns a win32 module
 handle.
 
-This example calls both functions with a NULL pointer (``None`` should be used
-as the NULL pointer)::
+This example calls both functions with a ``NULL`` pointer (``None`` should be used
+as the ``NULL`` pointer)::
 
    >>> print(libc.time(None))  # doctest: +SKIP
    1150640792
@@ -1110,7 +1110,7 @@ Since ``table`` is a ``pointer`` to the array of ``struct_frozen`` records, we
 can iterate over it, but we just have to make sure that our loop terminates,
 because pointers have no size. Sooner or later it would probably crash with an
 access violation or whatever, so it's better to break out of the loop when we
-hit the NULL entry::
+hit the ``NULL`` entry::
 
    >>> for item in table:
    ...     if item.name is None:

Doc/library/gc.rst

@@ -212,7 +212,7 @@ values but should not rebind them):
    A list of objects which the collector found to be unreachable but could
    not be freed (uncollectable objects).  Starting with Python 3.4, this
    list should be empty most of the time, except when using instances of
-   C extension types with a non-NULL ``tp_del`` slot.
+   C extension types with a non-``NULL`` ``tp_del`` slot.
 
    If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be
    added to this list rather than freed.