Corrections for the "extending" doc

[786d3f11-b763-4414-a03f-abc264e0b72d]

BPO	14129
Nosy	@birkenfeld, @ezio-melotti, @merwok
Files	issue_14129.1.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = created_at = labels = ['easy', 'docs'] title = 'Corrections for the "extending" doc' updated_at = user = 'https://bugs.python.org/elibendersky' ``` bugs.python.org fields: ```python activity = actor = 'python-dev' assignee = 'eli.bendersky' closed = True closed_date = closer = 'python-dev' components = ['Documentation'] creation = creator = 'eli.bendersky' dependencies = [] files = ['24663'] hgrepos = [] issue_num = 14129 keywords = ['patch', 'easy'] message_count = 15.0 messages = ['154325', '154326', '154341', '154342', '154344', '154346', '154347', '154348', '154349', '154419', '154434', '154441', '154480', '154492', '154494'] nosy_count = 6.0 nosy_names = ['georg.brandl', 'ezio.melotti', 'eric.araujo', 'eli.bendersky', 'docs@python', 'python-dev'] pr_nums = [] priority = 'low' resolution = 'fixed' stage = 'resolved' status = 'closed' superseder = None type = None url = 'https://bugs.python.org/issue14129' versions = ['Python 3.3'] ```

[786d3f11-b763-4414-a03f-abc264e0b72d]

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.

[786d3f11-b763-4414-a03f-abc264e0b72d]

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

[786d3f11-b763-4414-a03f-abc264e0b72d]

"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.

[786d3f11-b763-4414-a03f-abc264e0b72d]

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

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

[786d3f11-b763-4414-a03f-abc264e0b72d]

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

[786d3f11-b763-4414-a03f-abc264e0b72d]

"Let’s expend "

Typo

[786d3f11-b763-4414-a03f-abc264e0b72d]

"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

[786d3f11-b763-4414-a03f-abc264e0b72d]

"but in this cased"

Typo

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

[786d3f11-b763-4414-a03f-abc264e0b72d]

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

[786d3f11-b763-4414-a03f-abc264e0b72d]

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.

[786d3f11-b763-4414-a03f-abc264e0b72d]

Adding the documentation experts.

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

[merwok]

"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?

[786d3f11-b763-4414-a03f-abc264e0b72d]

Patch attached

[786d3f11-b763-4414-a03f-abc264e0b72d]

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

[1762cc99-3127-4a62-9baf-30c3d0f51ef7]

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