I'm now carefully reading through the "extending" documentation pages. This issue will record various problems I find on the way, with the intention of fixing them eventually.

extending.html has a reference to "Demo/embed/demo.c" which no longer exists in the source distribution

"A PyObject is not a very magnificent object - it just contains the refcount and a pointer to the object’s “type object”."

Too chatty and should be replaced by a more pragmatic explanation, or shortened.

"in this case, nothing more than every Python object contains"

There's a grammar error lurking somewhere in there...

This is not strictly in the extending doc, but linked from it:

http://docs.python.org/dev/c-api/type.html#PyType_GenericNew

The PyType_GenericNew API function is not documented

"Let’s expend "

Typo

"The new method calls the tp_alloc slot to allocate memory"

tp_alloc needs formatting here, similarly to the way it's done in other places

"but in this cased"

Typo

[this and the past couple of comments refer to the newtypes.html doc]

Noddy_name in the full code listing (included from noddy2.c) is different from the Noddy_name that is actually explained later

There are some:

"
   XXX Need to ...
"

Paragraphs scattered across the doc. These have no place in the official documentation. For placeholders, an issue can be created that lists all the things that need to be done.

Adding the documentation experts. 

I plan to apply a fix for these soon. If you guys have any objections, let me know.

> "in this case, nothing more than every Python object contains"
> There's a grammar error lurking somewhere in there...

It could be: “nothing more that what every Python object contains”.

Could you post a patch for review?

Patch attached

Thanks for the review. I'm going to do the commit now. Feel free to just fix it if any obvious mistakes remain.

New changeset 6c737eb12c3e by Eli Bendersky in branch 'default':
Some corrections for the Doc/extending documentation. Closes #14129
http://hg.python.org/cpython/rev/6c737eb12c3e