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

Replace all *NULL* with ``NULL``.

4 files changed, 57 insertions, 57 deletions

diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
index 483bc852f6..5f5abdf9c1 100644
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -196,7 +196,7 @@ function is then made with::
 
    pValue = PyObject_CallObject(pFunc, pArgs);
 
-Upon return of the function, ``pValue`` is either *NULL* or it contains a
+Upon return of the function, ``pValue`` is either ``NULL`` or it contains a
 reference to the return value of the function.  Be sure to release the reference
 after examining the value.
 
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index 5b4ea8220e..7986ea1e15 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -117,7 +117,7 @@ store the converted values.  More about this later.
 type and its components have been stored in the variables whose addresses are
 passed.  It returns false (zero) if an invalid argument list was passed.  In the
 latter case it also raises an appropriate exception so the calling function can
-return *NULL* immediately (as we saw in the example).
+return ``NULL`` immediately (as we saw in the example).
 
 
 .. _extending-errors:
@@ -127,8 +127,8 @@ Intermezzo: Errors and Exceptions
 
 An important convention throughout the Python interpreter is the following: when
 a function fails, it should set an exception condition and return an error value
-(usually a *NULL* pointer).  Exceptions are stored in a static global variable
-inside the interpreter; if this variable is *NULL* no exception has occurred.  A
+(usually a ``NULL`` pointer).  Exceptions are stored in a static global variable
+inside the interpreter; if this variable is ``NULL`` no exception has occurred.  A
 second global variable stores the "associated value" of the exception (the
 second argument to :keyword:`raise`).  A third variable contains the stack
 traceback in case the error originated in Python code.  These three variables
@@ -152,13 +152,13 @@ its associated value.  You don't need to :c:func:`Py_INCREF` the objects passed
 to any of these functions.
 
 You can test non-destructively whether an exception has been set with
-:c:func:`PyErr_Occurred`.  This returns the current exception object, or *NULL*
+:c:func:`PyErr_Occurred`.  This returns the current exception object, or ``NULL``
 if no exception has occurred.  You normally don't need to call
 :c:func:`PyErr_Occurred` to see whether an error occurred in a function call,
 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
+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
 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
@@ -234,7 +234,7 @@ with an exception object::
 
 Note that the Python name for the exception object is :exc:`spam.error`.  The
 :c:func:`PyErr_NewException` function may create a class with the base class
-being :exc:`Exception` (unless another class is passed in instead of *NULL*),
+being :exc:`Exception` (unless another class is passed in instead of ``NULL``),
 described in :ref:`bltin-exceptions`.
 
 Note also that the :c:data:`SpamError` variable retains a reference to the newly
@@ -278,7 +278,7 @@ statement::
    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
 
-It returns *NULL* (the error indicator for functions returning object pointers)
+It returns ``NULL`` (the error indicator for functions returning object pointers)
 if an error is detected in the argument list, relying on the exception set by
 :c:func:`PyArg_ParseTuple`.  Otherwise the string value of the argument has been
 copied to the local variable :c:data:`command`.  This is a pointer assignment and
@@ -308,7 +308,7 @@ macro)::
    return Py_None;
 
 :c:data:`Py_None` is the C name for the special Python object ``None``.  It is a
-genuine Python object rather than a *NULL* pointer, which means "error" in most
+genuine Python object rather than a ``NULL`` pointer, which means "error" in most
 contexts, as we have seen.
 
 
@@ -376,7 +376,7 @@ inserts built-in function objects into the newly created module based upon the
 table (an array of :c:type:`PyMethodDef` structures) found in the module definition.
 :c:func:`PyModule_Create` returns a pointer to the module object
 that it creates.  It may abort with a fatal error for
-certain errors, or return *NULL* if the module could not be initialized
+certain errors, or return ``NULL`` if the module could not be initialized
 satisfactorily. The init function must return the module object to its caller,
 so that it then gets inserted into ``sys.modules``.
 
@@ -526,8 +526,8 @@ This function must be registered with the interpreter using the
 :ref:`parsetuple`.
 
 The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement the
-reference count of an object and are safe in the presence of *NULL* pointers
-(but note that *temp* will not be  *NULL* in this context).  More info on them
+reference count of an object and are safe in the presence of ``NULL`` pointers
+(but note that *temp* will not be  ``NULL`` in this context).  More info on them
 in section :ref:`refcounts`.
 
 .. index:: single: PyObject_CallObject()
@@ -566,7 +566,7 @@ somehow :c:func:`Py_DECREF` the result, even (especially!) if you are not
 interested in its value.
 
 Before you do this, however, it is important to check that the return value
-isn't *NULL*.  If it is, the Python function terminated by raising an exception.
+isn't ``NULL``.  If it is, the Python function terminated by raising an exception.
 If the C code that called :c:func:`PyObject_CallObject` is called from Python, it
 should now return an error indication to its Python caller, so the interpreter
 can print a stack trace, or the calling Python code can handle the exception.
@@ -723,7 +723,7 @@ The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::
 The *arg* and *format* parameters are identical to those of the
 :c:func:`PyArg_ParseTuple` function.  The *kwdict* parameter is the dictionary of
 keywords received as the third parameter from the Python runtime.  The *kwlist*
-parameter is a *NULL*-terminated list of strings which identify the parameters;
+parameter is a ``NULL``-terminated list of strings which identify the parameters;
 the names are matched with the type information from *format* from left to
 right.  On success, :c:func:`PyArg_ParseTupleAndKeywords` returns true, otherwise
 it returns false and raises an appropriate exception.
@@ -1084,32 +1084,32 @@ NULL Pointers
 -------------
 
 In general, functions that take object references as arguments do not expect you
-to pass them *NULL* pointers, and will dump core (or cause later core dumps) if
-you do so.  Functions that return object references generally return *NULL* only
-to indicate that an exception occurred.  The reason for not testing for *NULL*
+to pass them ``NULL`` pointers, and will dump core (or cause later core dumps) if
+you do so.  Functions that return object references generally return ``NULL`` only
+to indicate that an exception occurred.  The reason for not testing for ``NULL``
 arguments is that functions often pass the objects they receive on to other
-function --- if each function were to test for *NULL*, there would be a lot of
+function --- if each function were to test for ``NULL``, there would be a lot of
 redundant tests and the code would run more slowly.
 
-It is better to test for *NULL* only at the "source:" when a pointer that may be
-*NULL* is received, for example, from :c:func:`malloc` or from a function that
+It is better to test for ``NULL`` only at the "source:" when a pointer that may be
+``NULL`` is received, for example, from :c:func:`malloc` or from a function that
 may raise an exception.
 
-The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for *NULL*
+The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for ``NULL``
 pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF`
 do.
 
 The macros for checking for a particular object type (``Pytype_Check()``) don't
-check for *NULL* pointers --- again, there is much code that calls several of
+check for ``NULL`` pointers --- again, there is much code that calls several of
 these in a row to test an object against various different expected types, and
-this would generate redundant tests.  There are no variants with *NULL*
+this would generate redundant tests.  There are no variants with ``NULL``
 checking.
 
 The C function calling mechanism guarantees that the argument list passed to C
-functions (``args`` in the examples) is never *NULL* --- in fact it guarantees
+functions (``args`` in the examples) is never ``NULL`` --- in fact it guarantees
 that it is always a tuple [#]_.
 
-It is a severe error to ever let a *NULL* pointer "escape" to the Python user.
+It is a severe error to ever let a ``NULL`` pointer "escape" to the Python user.
 
 .. Frank Stajano:
    A pedagogically buggy example, along the lines of the previous listing, would
@@ -1184,7 +1184,7 @@ different ways between the module providing the code and the client modules.
 
 Whichever method you choose, it's important to name your Capsules properly.
 The function :c:func:`PyCapsule_New` takes a name parameter
-(:c:type:`const char \*`); you're permitted to pass in a *NULL* name, but
+(:c:type:`const char \*`); you're permitted to pass in a ``NULL`` name, but
 we strongly encourage you to specify a name.  Properly named Capsules provide
 a degree of runtime type-safety; there is no feasible way to tell one unnamed
 Capsule from another.
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index 7e0b18d629..d9023709fd 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -191,7 +191,7 @@ For every object which can support attributes, the corresponding type must
 provide the functions that control how the attributes are resolved.  There needs
 to be a function which can retrieve attributes (if any are defined), and another
 to set attributes (if setting attributes is allowed).  Removing an attribute is
-a special case, for which the new value passed to the handler is *NULL*.
+a special case, for which the new value passed to the handler is ``NULL``.
 
 Python supports two pairs of attribute handlers; a type that supports attributes
 only needs to implement the functions for one pair.  The difference is that one
@@ -233,9 +233,9 @@ attributes, when the values are computed, or how relevant data is stored.
 When :c:func:`PyType_Ready` is called, it uses three tables referenced by the
 type object to create :term:`descriptor`\s which are placed in the dictionary of the
 type object.  Each descriptor controls access to one attribute of the instance
-object.  Each of the tables is optional; if all three are *NULL*, instances of
+object.  Each of the tables is optional; if all three are ``NULL``, instances of
 the type will only have attributes that are inherited from their base type, and
-should leave the :c:member:`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields *NULL* as
+should leave the :c:member:`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields ``NULL`` as
 well, allowing the base type to handle attributes.
 
 The tables are declared as three fields of the type object::
@@ -244,7 +244,7 @@ The tables are declared as three fields of the type object::
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
 
-If :c:member:`~PyTypeObject.tp_methods` is not *NULL*, it must refer to an array of
+If :c:member:`~PyTypeObject.tp_methods` is not ``NULL``, it must refer to an array of
 :c:type:`PyMethodDef` structures.  Each entry in the table is an instance of this
 structure::
 
@@ -258,7 +258,7 @@ structure::
 One entry should be defined for each method provided by the type; no entries are
 needed for methods inherited from a base type.  One additional entry is needed
 at the end; it is a sentinel that marks the end of the array.  The
-:attr:`ml_name` field of the sentinel must be *NULL*.
+:attr:`ml_name` field of the sentinel must be ``NULL``.
 
 The second table is used to define attributes which map directly to data stored
 in the instance.  A variety of primitive C types are supported, and access may
@@ -307,7 +307,7 @@ application can use the introspection API to retrieve the descriptor from the
 class object, and get the doc string using its :attr:`__doc__` attribute.
 
 As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :attr:`name` value
-of *NULL* is required.
+of ``NULL`` is required.
 
 .. XXX Descriptors need to be explained in more detail somewhere, but not here.
 
@@ -352,9 +352,9 @@ Here is an example::
 
 The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`__setattr__` or
 :meth:`__delattr__` method of a class instance would be called.  When an
-attribute should be deleted, the third parameter will be *NULL*.  Here is an
+attribute should be deleted, the third parameter will be ``NULL``.  Here is an
 example that simply raises an exception; if this were really all you wanted, the
-:c:member:`~PyTypeObject.tp_setattr` handler should be set to *NULL*. ::
+:c:member:`~PyTypeObject.tp_setattr` handler should be set to ``NULL``. ::
 
    static int
    newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
@@ -380,7 +380,7 @@ where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, ``Py_GT``,
 ``Py_LT`` or ``Py_GT``.  It should compare the two objects with respect to the
 specified operator and return ``Py_True`` or ``Py_False`` if the comparison is
 successful, ``Py_NotImplemented`` to indicate that comparison is not
-implemented and the other object's comparison method should be tried, or *NULL*
+implemented and the other object's comparison method should be tried, or ``NULL``
 if an exception was set.
 
 Here is a sample implementation, for a datatype that is considered equal if the
@@ -427,7 +427,7 @@ from the type implementation, the older protocols have been defined as optional
 blocks of handlers referenced by the type object.  For newer protocols there are
 additional slots in the main type object, with a flag bit being set to indicate
 that the slots are present and should be checked by the interpreter.  (The flag
-bit does not indicate that the slot values are non-*NULL*. The flag may be set
+bit does not indicate that the slot values are non-``NULL``. The flag may be set
 to indicate the presence of a slot, but a slot may still be unfilled.) ::
 
    PyNumberMethods   *tp_as_number;
@@ -478,9 +478,9 @@ This function takes three arguments:
    :c:func:`PyArg_ParseTuple` to extract the arguments.
 
 #. *kwds* is a dictionary of keyword arguments that were passed. If this is
-   non-*NULL* and you support keyword arguments, use
+   non-``NULL`` and you support keyword arguments, use
    :c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments.  If you
-   do not want to support keyword arguments and this is non-*NULL*, raise a
+   do not want to support keyword arguments and this is non-``NULL``, raise a
    :exc:`TypeError` with a message saying that keyword arguments are not supported.
 
 Here is a toy ``tp_call`` implementation::
@@ -512,7 +512,7 @@ Here is a toy ``tp_call`` implementation::
 These functions provide support for the iterator protocol.  Both handlers
 take exactly one parameter, the instance for which they are being called,
 and return a new reference.  In the case of an error, they should set an
-exception and return *NULL*.  :c:member:`~PyTypeObject.tp_iter` corresponds
+exception and return ``NULL``.  :c:member:`~PyTypeObject.tp_iter` corresponds
 to the Python :meth:`__iter__` method, while :c:member:`~PyTypeObject.tp_iternext`
 corresponds to the Python :meth:`~iterator.__next__` method.
 
@@ -534,11 +534,11 @@ and :c:member:`~PyTypeObject.tp_iternext`.  An iterator's
 to the iterator.  Its :c:member:`~PyTypeObject.tp_iternext` handler should
 return a new reference to the next object in the iteration, if there is one.
 If the iteration has reached the end, :c:member:`~PyTypeObject.tp_iternext`
-may return *NULL* without setting an exception, or it may set
-:exc:`StopIteration` *in addition* to returning *NULL*; avoiding
+may return ``NULL`` without setting an exception, or it may set
+:exc:`StopIteration` *in addition* to returning ``NULL``; avoiding
 the exception can yield slightly better performance.  If an actual error
 occurs, :c:member:`~PyTypeObject.tp_iternext` should always set an exception
-and return *NULL*.
+and return ``NULL``.
 
 
 .. _weakref-support:
@@ -557,7 +557,7 @@ For an object to be weakly referencable, the extension type must do two things:
 
 #. Include a :c:type:`PyObject\*` field in the C object structure dedicated to
    the weak reference mechanism.  The object's constructor should leave it
-   *NULL* (which is automatic when using the default
+   ``NULL`` (which is automatic when using the default
    :c:member:`~PyTypeObject.tp_alloc`).
 
 #. Set the :c:member:`~PyTypeObject.tp_weaklistoffset` type member
@@ -582,7 +582,7 @@ And the corresponding member in the statically-declared type object::
 
 The only further addition is that ``tp_dealloc`` needs to clear any weak
 references (by calling :c:func:`PyObject_ClearWeakRefs`) if the field is
-non-*NULL*::
+non-``NULL``::
 
    static void
    Trivial_dealloc(TrivialObject *self)
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index b2c819c858..0eb6ffd026 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -177,7 +177,7 @@ Everything else in the file should be familiar, except for some code in
 
 This initializes the :class:`Custom` type, filling in a number of members
 to the appropriate default values, including :attr:`ob_type` that we initially
-set to *NULL*. ::
+set to ``NULL``. ::
 
    Py_INCREF(&CustomType);
    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
@@ -275,7 +275,7 @@ which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::
 
 This method first clears the reference counts of the two Python attributes.
 :c:func:`Py_XDECREF` correctly handles the case where its argument is
-*NULL* (which might happen here if ``tp_new`` failed midway).  It then
+``NULL`` (which might happen here if ``tp_new`` failed midway).  It then
 calls the :c:member:`~PyTypeObject.tp_free` member of the object's type
 (computed by ``Py_TYPE(self)``) to free the object's memory.  Note that
 the object's type might not be :class:`CustomType`, because the object may
@@ -321,7 +321,7 @@ objects of the type.  It is exposed in Python as the :meth:`__new__` method.
 It is not required to define a ``tp_new`` member, and indeed many extension
 types will simply reuse :c:func:`PyType_GenericNew` as done in the first
 version of the ``Custom`` type above.  In this case, we use the ``tp_new``
-handler to initialize the ``first`` and ``last`` attributes to non-*NULL*
+handler to initialize the ``first`` and ``last`` attributes to non-``NULL``
 default values.
 
 ``tp_new`` is passed the type being instantiated (not necessarily ``CustomType``,
@@ -341,7 +341,7 @@ slot to allocate memory::
    self = (CustomObject *) type->tp_alloc(type, 0);
 
 Since memory allocation may fail, we must check the :c:member:`~PyTypeObject.tp_alloc`
-result against *NULL* before proceeding.
+result against ``NULL`` before proceeding.
 
 .. note::
    We didn't fill the :c:member:`~PyTypeObject.tp_alloc` slot ourselves. Rather
@@ -455,9 +455,9 @@ below for details.
 A disadvantage of this approach is that it doesn't provide a way to restrict the
 types of objects that can be assigned to the Python attributes.  We expect the
 first and last names to be strings, but any Python objects can be assigned.
-Further, the attributes can be deleted, setting the C pointers to *NULL*.  Even
-though we can make sure the members are initialized to non-*NULL* values, the
-members can be set to *NULL* if the attributes are deleted.
+Further, the attributes can be deleted, setting the C pointers to ``NULL``.  Even
+though we can make sure the members are initialized to non-``NULL`` values, the
+members can be set to ``NULL`` if the attributes are deleted.
 
 We define a single method, :meth:`Custom.name()`, that outputs the objects name as the
 concatenation of the first and last names. ::
@@ -489,8 +489,8 @@ equivalent to the Python method:
        return "%s %s" % (self.first, self.last)
 
 Note that we have to check for the possibility that our :attr:`first` and
-:attr:`last` members are *NULL*.  This is because they can be deleted, in which
-case they are set to *NULL*.  It would be better to prevent deletion of these
+:attr:`last` members are ``NULL``.  This is because they can be deleted, in which
+case they are set to ``NULL``.  It would be better to prevent deletion of these
 attributes and to restrict the attribute values to be strings.  We'll see how to
 do that in the next section.
 
@@ -584,7 +584,7 @@ could, for example, be used to allow a single set of getter and setter functions
 that decide the attribute to get or set based on data in the closure.)
 
 The setter function is passed the :class:`Custom` object, the new value, and the
-closure.  The new value may be *NULL*, in which case the attribute is being
+closure.  The new value may be ``NULL``, in which case the attribute is being
 deleted.  In our setter, we raise an error if the attribute is deleted or if its
 new value is not a string.
 
@@ -603,7 +603,7 @@ and register it in the :c:member:`~PyTypeObject.tp_getset` slot::
    .tp_getset = Custom_getsetters,
 
 The last item in a :c:type:`PyGetSetDef` structure is the "closure" mentioned
-above.  In this case, we aren't using a closure, so we just pass *NULL*.
+above.  In this case, we aren't using a closure, so we just pass ``NULL``.
 
 We also remove the member definitions for these attributes::
 
@@ -643,7 +643,7 @@ allow strings [#]_ to be passed::
    }
 
 With these changes, we can assure that the ``first`` and ``last`` members are
-never *NULL* so we can remove checks for *NULL* values in almost all cases.
+never ``NULL`` so we can remove checks for ``NULL`` values in almost all cases.
 This means that most of the :c:func:`Py_XDECREF` calls can be converted to
 :c:func:`Py_DECREF` calls.  The only place we can't change these calls is in
 the ``tp_dealloc`` implementation, where there is the possibility that the
@@ -749,7 +749,7 @@ participate in cycles::
 Notice the use of the :c:func:`Py_CLEAR` macro.  It is the recommended and safe
 way to clear data attributes of arbitrary types while decrementing
 their reference counts.  If you were to call :c:func:`Py_XDECREF` instead
-on the attribute before setting it to *NULL*, there is a possibility
+on the attribute before setting it to ``NULL``, there is a possibility
 that the attribute's destructor would call back into code that reads the
 attribute again (*especially* if there is a reference cycle).