[3.8] bpo-38600: Change the mark up of NULL in the C API documentation. (GH-16950) (GH-16999)

Replace all *NULL* with ``NULL``.
(cherry picked from commit 25fc088)

Author: serhiy-storchaka

Doc/c-api/arg.rst

@@ -50,7 +50,7 @@ Unless otherwise stated, buffers are not NUL-terminated.
 
 Some formats require a read-only :term:`bytes-like object`, and set a
 pointer instead of a buffer structure.  They work by checking that
-the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is *NULL*,
+the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is ``NULL``,
 which disallows mutable objects such as :class:`bytearray`.
 
 .. note::
@@ -99,15 +99,15 @@ which disallows mutable objects such as :class:`bytearray`.
 
 ``z`` (:class:`str` or ``None``) [const char \*]
    Like ``s``, but the Python object may also be ``None``, in which case the C
-   pointer is set to *NULL*.
+   pointer is set to ``NULL``.
 
 ``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]
    Like ``s*``, but the Python object may also be ``None``, in which case the
-   ``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*.
+   ``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``.
 
 ``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int]
    Like ``s#``, but the Python object may also be ``None``, in which case the C
-   pointer is set to *NULL*.
+   pointer is set to ``NULL``.
 
 ``y`` (read-only :term:`bytes-like object`) [const char \*]
    This format converts a bytes-like object to a C pointer to a character
@@ -166,15 +166,15 @@ which disallows mutable objects such as :class:`bytearray`.
 
 ``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
    Like ``u``, but the Python object may also be ``None``, in which case the
-   :c:type:`Py_UNICODE` pointer is set to *NULL*.
+   :c:type:`Py_UNICODE` pointer is set to ``NULL``.
 
    .. deprecated-removed:: 3.3 4.0
       Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
       :c:func:`PyUnicode_AsWideCharString`.
 
 ``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int]
    Like ``u#``, but the Python object may also be ``None``, in which case the
-   :c:type:`Py_UNICODE` pointer is set to *NULL*.
+   :c:type:`Py_UNICODE` pointer is set to ``NULL``.
 
    .. deprecated-removed:: 3.3 4.0
       Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@@ -197,7 +197,7 @@ which disallows mutable objects such as :class:`bytearray`.
 
    This format requires two arguments.  The first is only used as input, and
    must be a :c:type:`const char\*` which points to the name of an encoding as a
-   NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
+   NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
    An exception is raised if the named encoding is not known to Python.  The
    second argument must be a :c:type:`char\*\*`; the value of the pointer it
    references will be set to a buffer with the contents of the argument text.
@@ -220,7 +220,7 @@ which disallows mutable objects such as :class:`bytearray`.
 
    It requires three arguments.  The first is only used as input, and must be a
    :c:type:`const char\*` which points to the name of an encoding as a
-   NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
+   NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
    An exception is raised if the named encoding is not known to Python.  The
    second argument must be a :c:type:`char\*\*`; the value of the pointer it
    references will be set to a buffer with the contents of the argument text.
@@ -230,12 +230,12 @@ which disallows mutable objects such as :class:`bytearray`.
 
    There are two modes of operation:
 
-   If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
+   If *\*buffer* points a ``NULL`` pointer, the function will allocate a buffer of
    the needed size, copy the encoded data into this buffer and set *\*buffer* to
    reference the newly allocated storage.  The caller is responsible for calling
    :c:func:`PyMem_Free` to free the allocated buffer after usage.
 
-   If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
+   If *\*buffer* points to a non-``NULL`` pointer (an already allocated buffer),
    :c:func:`PyArg_ParseTuple` will use this location as the buffer and interpret the
    initial value of *\*buffer_length* as the buffer size.  It will then copy the
    encoded data into the buffer and NUL-terminate it.  If the buffer is not large
@@ -317,7 +317,7 @@ Other objects
 ``O`` (object) [PyObject \*]
    Store a Python object (without any conversion) in a C object pointer.  The C
    program thus receives the actual object that was passed.  The object's reference
-   count is not increased.  The pointer stored is not *NULL*.
+   count is not increased.  The pointer stored is not ``NULL``.
 
 ``O!`` (object) [*typeobject*, PyObject \*]
    Store a Python object in a C object pointer.  This is similar to ``O``, but
@@ -437,7 +437,7 @@ API Functions
 
    Parse the parameters of a function that takes both positional and keyword
    parameters into local variables.  The *keywords* argument is a
-   *NULL*-terminated array of keyword parameter names.  Empty names denote
+   ``NULL``-terminated array of keyword parameter names.  Empty names denote
    :ref:`positional-only parameters <positional-only_parameter>`.
    Returns true on success; on failure, it returns false and raises the
    appropriate exception.
@@ -520,8 +520,8 @@ Building values
 
    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
-   the value or *NULL* in the case of an error; an exception will be raised if
-   *NULL* is returned.
+   the value or ``NULL`` in the case of an error; an exception will be raised if
+   ``NULL`` is returned.
 
    :c:func:`Py_BuildValue` does not always build a tuple.  It builds a tuple only if
    its format string contains two or more format units.  If the format string is
@@ -547,20 +547,20 @@ Building values
 
    ``s`` (:class:`str` or ``None``) [const char \*]
       Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
-      encoding. If the C string pointer is *NULL*, ``None`` is used.
+      encoding. If the C string pointer is ``NULL``, ``None`` is used.
 
    ``s#`` (:class:`str` or ``None``) [const char \*, int]
       Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
-      encoding. If the C string pointer is *NULL*, the length is ignored and
+      encoding. If the C string pointer is ``NULL``, the length is ignored and
       ``None`` is returned.
 
    ``y`` (:class:`bytes`) [const char \*]
       This converts a C string to a Python :class:`bytes` object.  If the C
-      string pointer is *NULL*, ``None`` is returned.
+      string pointer is ``NULL``, ``None`` is returned.
 
    ``y#`` (:class:`bytes`) [const char \*, int]
       This converts a C string and its lengths to a Python object.  If the C
-      string pointer is *NULL*, ``None`` is returned.
+      string pointer is ``NULL``, ``None`` is returned.
 
    ``z`` (:class:`str` or ``None``) [const char \*]
       Same as ``s``.
@@ -570,12 +570,12 @@ Building values
 
    ``u`` (:class:`str`) [const wchar_t \*]
       Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
-      data to a Python Unicode object.  If the Unicode buffer pointer is *NULL*,
+      data to a Python Unicode object.  If the Unicode buffer pointer is ``NULL``,
       ``None`` is returned.
 
    ``u#`` (:class:`str`) [const wchar_t \*, int]
       Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
-      Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
+      Unicode object.   If the Unicode buffer pointer is ``NULL``, the length is ignored
       and ``None`` is returned.
 
    ``U`` (:class:`str` or ``None``) [const char \*]
@@ -636,9 +636,9 @@ Building values
 
    ``O`` (object) [PyObject \*]
       Pass a Python object untouched (except for its reference count, which is
-      incremented by one).  If the object passed in is a *NULL* pointer, it is assumed
+      incremented by one).  If the object passed in is a ``NULL`` pointer, it is assumed
       that this was caused because the call producing the argument found an error and
-      set an exception. Therefore, :c:func:`Py_BuildValue` will return *NULL* but won't
+      set an exception. Therefore, :c:func:`Py_BuildValue` will return ``NULL`` but won't
       raise an exception.  If no exception has been raised yet, :exc:`SystemError` is
       set.
 
@@ -653,7 +653,7 @@ Building values
    ``O&`` (object) [*converter*, *anything*]
       Convert *anything* to a Python object through a *converter* function.  The
       function is called with *anything* (which should be compatible with :c:type:`void
-      \*`) as its argument and should return a "new" Python object, or *NULL* if an
+      \*`) as its argument and should return a "new" Python object, or ``NULL`` if an
       error occurred.
 
    ``(items)`` (:class:`tuple`) [*matching-items*]
@@ -668,7 +668,7 @@ Building values
       respectively.
 
    If there is an error in the format string, the :exc:`SystemError` exception is
-   set and *NULL* returned.
+   set and ``NULL`` returned.
 
 .. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
 

Doc/c-api/buffer.rst

@@ -102,13 +102,13 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
    .. c:member:: void \*obj
 
       A new reference to the exporting object. The reference is owned by
-      the consumer and automatically decremented and set to *NULL* by
+      the consumer and automatically decremented and set to ``NULL`` by
       :c:func:`PyBuffer_Release`. The field is the equivalent of the return
       value of any standard C-API function.
 
       As a special case, for *temporary* buffers that are wrapped by
       :c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
-      this field is *NULL*. In general, exporting objects MUST NOT
+      this field is ``NULL``. In general, exporting objects MUST NOT
       use this scheme.
 
    .. c:member:: Py_ssize_t len
@@ -134,21 +134,21 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
 
       Important exception: If a consumer requests a buffer without the
       :c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will
-      be set to  *NULL*,  but :c:member:`~Py_buffer.itemsize` still has
+      be set to  ``NULL``,  but :c:member:`~Py_buffer.itemsize` still has
       the value for the original format.
 
       If :c:member:`~Py_buffer.shape` is present, the equality
       ``product(shape) * itemsize == len`` still holds and the consumer
       can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.
 
-      If :c:member:`~Py_buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE`
+      If :c:member:`~Py_buffer.shape` is ``NULL`` as a result of a :c:macro:`PyBUF_SIMPLE`
       or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
       :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
 
    .. c:member:: const char \*format
 
       A *NUL* terminated string in :mod:`struct` module style syntax describing
-      the contents of a single item. If this is *NULL*, ``"B"`` (unsigned bytes)
+      the contents of a single item. If this is ``NULL``, ``"B"`` (unsigned bytes)
       is assumed.
 
       This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
@@ -158,7 +158,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
       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
       a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
-      and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
+      and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``.
 
       The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
       to 64. Exporters MUST respect this limit, consumers of multi-dimensional
@@ -248,7 +248,7 @@ readonly, format
    .. c:macro:: PyBUF_FORMAT
 
       Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
-      be filled in correctly. Otherwise, this field MUST be *NULL*.
+      be filled in correctly. Otherwise, this field MUST be ``NULL``.
 
 
 :c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section.
@@ -349,9 +349,9 @@ The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.
 
 If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
 interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
-both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are *NULL*.
+both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are ``NULL``.
 
-If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as
+If :c:member:`~Py_buffer.strides` is ``NULL``, the array is interpreted as
 a standard n-dimensional C-array. Otherwise, the consumer must access an
 n-dimensional array as follows:
 
@@ -438,7 +438,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
+   :c:data:`PyExc_BufferError`, set :c:member:`view->obj` to ``NULL`` and
    return ``-1``.
 
    On success, fill in *view*, set :c:member:`view->obj` to a new reference
@@ -516,7 +516,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/bytearray.rst

@@ -48,7 +48,7 @@ Direct API functions
 .. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
 
    Create a new bytearray object from *string* and its length, *len*.  On
-   failure, *NULL* is returned.
+   failure, ``NULL`` is returned.
 
 
 .. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
@@ -58,13 +58,13 @@ Direct API functions
 
 .. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
 
-   Return the size of *bytearray* after checking for a *NULL* pointer.
+   Return the size of *bytearray* after checking for a ``NULL`` pointer.
 
 
 .. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
 
    Return the contents of *bytearray* as a char array after checking for a
-   *NULL* pointer.  The returned array always has an extra
+   ``NULL`` pointer.  The returned array always has an extra
    null byte appended.
 
 

Doc/c-api/bytes.rst

@@ -37,14 +37,14 @@ called with a non-bytes parameter.
 .. c:function:: PyObject* PyBytes_FromString(const char *v)
 
    Return a new bytes object with a copy of the string *v* as value on success,
-   and *NULL* on failure.  The parameter *v* must not be *NULL*; it will not be
+   and ``NULL`` on failure.  The parameter *v* must not be ``NULL``; it will not be
    checked.
 
 
 .. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
 
    Return a new bytes object with a copy of the string *v* as value and length
-   *len* on success, and *NULL* on failure.  If *v* is *NULL*, the contents of
+   *len* on success, and ``NULL`` on failure.  If *v* is ``NULL``, the contents of
    the bytes object are uninitialized.
 
 
@@ -145,7 +145,7 @@ called with a non-bytes parameter.
    whether there are any other null bytes.  The data must not be
    modified in any way, unless the object was just created using
    ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
-   *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL*
+   *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns ``NULL``
    and raises :exc:`TypeError`.
 
 
@@ -159,7 +159,7 @@ called with a non-bytes parameter.
    Return the null-terminated contents of the object *obj*
    through the output variables *buffer* and *length*.
 
-   If *length* is *NULL*, the bytes object
+   If *length* is ``NULL``, the bytes object
    may not contain embedded null bytes;
    if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
 
@@ -181,7 +181,7 @@ called with a non-bytes parameter.
    appended to *bytes*; the caller will own the new reference.  The reference to
    the old value of *bytes* will be stolen.  If the new object cannot be
    created, the old reference to *bytes* will still be discarded and the value
-   of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
+   of *\*bytes* will be set to ``NULL``; the appropriate exception will be set.
 
 
 .. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
@@ -201,5 +201,5 @@ called with a non-bytes parameter.
    desired.  On success, *\*bytes* holds the resized bytes object and ``0`` is
    returned; the address in *\*bytes* may differ from its input value.  If the
    reallocation fails, the original bytes object at *\*bytes* is deallocated,
-   *\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is
+   *\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
    returned.