bpo-43774: Enhance debug build documentation (GH-25712)
* Add also references to --with-trace-refs option.
* Move _ob_next and _ob_prev at the end, since they don't exist by
default and are related to debug.
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 1223059..2d85d30 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -749,34 +749,12 @@
not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is enabled
in the Unix build, compiler optimization is disabled.
-In addition to the reference count debugging described below, the following
-extra checks are performed:
+In addition to the reference count debugging described below, extra checks are
+performed, see :ref:`Python Debug Build <debug-build>`.
-* Extra checks are added to the object allocator.
-
-* Extra checks are added to the parser and compiler.
-
-* Downcasts from wide types to narrow types are checked for loss of information.
-
-* A number of assertions are added to the dictionary and set implementations.
- In addition, the set object acquires a :meth:`test_c_api` method.
-
-* Sanity checks of the input arguments are added to frame creation.
-
-* The storage for ints is initialized with a known invalid pattern to catch
- reference to uninitialized digits.
-
-* Low-level tracing and extra exception checking are added to the runtime
- virtual machine.
-
-* Extra checks are added to the memory arena implementation.
-
-* Extra debugging is added to the thread module.
-
-There may be additional checks not mentioned here.
-
-Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, a
-circular doubly linked list of active objects is maintained by adding two extra
+Defining :c:macro:`Py_TRACE_REFS` enables reference tracing
+(see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
+When defined, a circular doubly linked list of active objects is maintained by adding two extra
fields to every :c:type:`PyObject`. Total allocations are tracked as well. Upon
exit, all existing references are printed. (In interactive mode this happens
after every statement run by the interpreter.)
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 2af3b9a..85f0262 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -482,27 +482,6 @@
type objects) *must* have the :attr:`ob_size` field.
-.. c:member:: PyObject* PyObject._ob_next
- PyObject* PyObject._ob_prev
-
- These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
-
- Their initialization to ``NULL`` is taken care of by the
- ``PyObject_HEAD_INIT`` macro. For :ref:`statically allocated objects
- <static-types>`, these fields always remain ``NULL``. For :ref:`dynamically
- allocated objects <heap-types>`, these two fields are used to link the
- object into a doubly-linked list of *all* live objects on the heap.
-
- This could be used for various debugging purposes; currently the only uses
- are the :func:`sys.getobjects` function and to print the objects that are
- still alive at the end of a run when the environment variable
- :envvar:`PYTHONDUMPREFS` is set.
-
- **Inheritance:**
-
- These fields are not inherited by subtypes.
-
-
.. c:member:: Py_ssize_t PyObject.ob_refcnt
This is the type object's reference count, initialized to ``1`` by the
@@ -540,6 +519,28 @@
This field is inherited by subtypes.
+.. c:member:: PyObject* PyObject._ob_next
+ PyObject* PyObject._ob_prev
+
+ These fields are only present when the macro ``Py_TRACE_REFS`` is defined
+ (see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
+
+ Their initialization to ``NULL`` is taken care of by the
+ ``PyObject_HEAD_INIT`` macro. For :ref:`statically allocated objects
+ <static-types>`, these fields always remain ``NULL``. For :ref:`dynamically
+ allocated objects <heap-types>`, these two fields are used to link the
+ object into a doubly-linked list of *all* live objects on the heap.
+
+ This could be used for various debugging purposes; currently the only uses
+ are the :func:`sys.getobjects` function and to print the objects that are
+ still alive at the end of a run when the environment variable
+ :envvar:`PYTHONDUMPREFS` is set.
+
+ **Inheritance:**
+
+ These fields are not inherited by subtypes.
+
+
PyVarObject Slots
-----------------