issue9014: Properly document PyObject_HEAD and friends post-PEP-3123.

Doc/c-api/structures.rst

@@ -21,53 +21,65 @@ the definition of all other Python objects.
    All object types are extensions of this type.  This is a type which
    contains the information Python needs to treat a pointer to an object as an
    object.  In a normal "release" build, it contains only the object's
-   reference count and a pointer to the corresponding type object.  It
+   reference count and a pointer to the corresponding type object.
-   corresponds to the fields defined by the expansion of the ``PyObject_HEAD``
+   Nothing is actually declared to be a PyObject, but every pointer to a
-   macro.
+   Python object can be cast to a PyObject*.  Access to the members
+   must be done by using the macros :c:macro:`Py_REFCNT` and
+   :c:macro:`Py_TYPE`.
 
 
 .. c:type:: PyVarObject
 
    This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
    field.  This is only used for objects that have some notion of *length*.
-   This type does not often appear in the Python/C API.  It corresponds to the
+   This type does not often appear in the Python/C API.
-   fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro.
+   Access to the members must be done by using the macros
+   :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`.
 
-These macros are used in the definition of :c:type:`PyObject` and
-:c:type:`PyVarObject`:
-
-.. XXX need to document PEP 3123 changes here
 
 .. c:macro:: PyObject_HEAD
 
-   This is a macro which expands to the declarations of the fields of the
+   This is a macro used when declaring new types which represent objects
-   :c:type:`PyObject` type; it is used when declaring new types which represent
+   without a varying length.  The PyObject_HEAD macro expands to::
-   objects without a varying length.  The specific fields it expands to depend
-   on the definition of :c:macro:`Py_TRACE_REFS`.  By default, that macro is
-   not defined, and :c:macro:`PyObject_HEAD` expands to::
 
-      Py_ssize_t ob_refcnt;
+      PyObject ob_base;
-      PyTypeObject *ob_type;
 
-   When :c:macro:`Py_TRACE_REFS` is defined, it expands to::
+   See documentation of :c:type::`PyObject` above.
-
-      PyObject *_ob_next, *_ob_prev;
-      Py_ssize_t ob_refcnt;
-      PyTypeObject *ob_type;
 
 
 .. c:macro:: PyObject_VAR_HEAD
 
-   This is a macro which expands to the declarations of the fields of the
+   This is a macro used when declaring new types which represent objects
-   :c:type:`PyVarObject` type; it is used when declaring new types which
+   with a length that varies from instance to instance.
-   represent objects with a length that varies from instance to instance.
+   The PyObject_VAR_HEAD macro expands to::
-   This macro always expands to::
 
-      PyObject_HEAD
+      PyVarObject ob_base;
-      Py_ssize_t ob_size;
 
-   Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own
+   See documentation of :c:type:`PyVarObject` above.
-   expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`.
+
+
+.. c:macro:: Py_TYPE(o)
+
+   This macro is used to access the `ob_type` member of a Python object.
+   It expands to::
+
+      (((PyObject*)(o))->ob_type)
+
+
+.. c:macro:: Py_REFCNT(o)
+
+   This macro is used to access the `ob_refcnt` member of a Python object.
+   It expands to::
+
+      (((PyObject*)(o))->ob_refcnt)
+
+
+.. c:macro:: Py_SIZE(o)
+
+   This macro is used to access the `ob_size` member of a Python object.
+   It expands to::
+
+      (((PyVarObject*)(o))->ob_size)
 
 
 .. c:macro:: PyObject_HEAD_INIT(type)