PyObject_HEAD's documentation in py3k (http://docs.python.org/dev/py3k/c-api/structures.html#PyObject_HEAD) uses the same content used in the python 2.x's docs which is wrong, as there were some API changes.

PyObject_HEAD is actually defined as

#define PyObject_HEAD PyObject ob_base;

with PyObject defined as

typedef struct _object {
    _PyObject_HEAD_EXTRA
    Py_ssize_t ob_refcnt;
    struct _typeobject *ob_type;
} PyObject;

(The PyTRACE_REFS discussion is still valid, though.)

Additionally, it'd be nice to mention that the Py_REFCNT(ob) and Py_TYPE(ob) macros should be used to access the PyObject members.

Additionally, I prefer move the discussion of Py_TRACE_REFS under the documentation of PyObject: http://docs.python.org/dev/py3k/c-api/structures.html?highlight=pyobject_head#PyObject, since they'are connected directly. The doc of PyObject_HEAD should only saying like "expands to a PyObject variable".