https://docs.python.org/3/c-api/structures.html#c.PyObject_HEAD says that the macro should be used for creating new types and that it has ob_type. Unfortunately at some point (@61466 perhaps) that definition in object.h was changed. This affects other pages too (at least https://docs.python.org/3/extending/newtypes.html).

I encountered this while checking if a C extension (imposm.parser) could be trivially ported for Python 3. Unfortunately not. I suppose

  self->ob_type

should be replaced with

  Py_TYPE(self)

but that isn't really clear from the docs.

Docs of PyObject_HEAD and friends have already been fixed in 760c5cfacbaa.

https://docs.python.org/3/extending/newtypes.html still needs to be updated to mention ob_base:

    This is what a Noddy object will contain—in this case, nothing more than what every Python object contains—a refcount and a pointer to a type object. These are the fields the PyObject_HEAD macro brings in.

This diff amends the documentation to point out that PyObject_HEAD includes the ob_base field, gives a brief overview of it and points to the PyObject/structures page for more information.

It also changes the semicolon part to a warning for clarity.

Warnings are big red boxes, and we try to only use those for really critical info.  The current text is what we want as far as that goes.

>The current text is what we want as far as that goes.

Roger that, I've reverted the change to make that a warning in the newest diff.

Looks good to me.

There is a patch, and it looks good to me. This should be moved into 'commit review' state.

Changed to commit review.

New changeset 92b468020e07 by Berker Peksag in branch '3.5':
Issue #23710: Update PyObject_HEAD documentation
https://hg.python.org/cpython/rev/92b468020e07

New changeset 26dd6e7f1733 by Berker Peksag in branch 'default':
Issue #23710: Merge from 3.5
https://hg.python.org/cpython/rev/26dd6e7f1733

Thanks for the patch. Committed capidocs.diff-2 with some tweaks.