Improve C-API doc for PyTypeObject

[ericsnowcurrently]

BPO	17045
Nosy	@ezio-melotti, @ericsnowcurrently, @berkerpeksag, @serhiy-storchaka, @csabella
PRs	bpo-17045: Improve C-API doc for PyTypeObject. #7413
Files	typeobj-doc.diff

^{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:

assignee = None
closed_at = <Date 2018-06-14.21:47:00.962>
created_at = <Date 2013-01-27.00:11:25.039>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'Improve C-API doc for PyTypeObject'
updated_at = <Date 2018-06-14.21:47:00.961>
user = 'https://github.com/ericsnowcurrently'

bugs.python.org fields:

activity = <Date 2018-06-14.21:47:00.961>
actor = 'eric.snow'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-06-14.21:47:00.962>
closer = 'eric.snow'
components = ['Documentation']
creation = <Date 2013-01-27.00:11:25.039>
creator = 'eric.snow'
dependencies = []
files = ['28865']
hgrepos = []
issue_num = 17045
keywords = ['patch']
message_count = 8.0
messages = ['180723', '180733', '318541', '318659', '318722', '318741', '319474', '319558']
nosy_count = 6.0
nosy_names = ['ezio.melotti', 'docs@python', 'eric.snow', 'berker.peksag', 'serhiy.storchaka', 'cheryl.sabella']
pr_nums = ['7413']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue17045'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[ericsnowcurrently]

http://docs.python.org/dev/c-api/typeobj.html

I found the the documentation for PyTypeObject to be somewhat harder to use than it need be. In the end I distilled the info down for my own use. I'm comfortable with what I came up with, so I'd like to at least add a condensed version of one or two of the tables I made to the top of the doc, with the slot names linking to each description as it currently exists. Attached is a patch.

(I also plan on reformatting the doc source so the lines wrap better--70 columns or so.)

As well, I have a couple open questions that I'll address separately:

• should tp_del be added?
• inheritance of tp_flags...

[ericsnowcurrently]

Here's an updated patch after feedback. Thanks Ezio!

[serhiy-storchaka]

Do you mind to create a PR Eric?

[ericsnowcurrently]

I'll definitely take a look. It might not be until Friday though.

[ericsnowcurrently]

I found some time to at least get the patch to apply cleanly to master and to make a PR. :)

[csabella]

This isn't directly related to this change, but I wanted to point out bpo-23869 since you seem to understand the topic enough to respond to that ticket.

Thanks!

[ericsnowcurrently]

@cheryl, thanks for pointing that out. I'll take a look.

[ericsnowcurrently]

New changeset 9e7c921 by Eric Snow in branch 'master':
bpo-17045: Improve C-API doc for PyTypeObject. (gh-7413)
9e7c921