search

python / cpython

The Python programming language
https://www.python.org
Other
62.28k stars 29.92k forks source link

Some C struct members are not marked up in docs #97909

Open encukou opened 1 year ago

encukou commented 1 year ago

The members of PyMemberDef aren't marked up as members, so they can't be linked to individually.

Linked PRs

encukou commented 1 year ago

Reserving for a student. Everyone else, please don't start on this issue this week.

You will want to click “Show Source” on the page linked in the first comment. That will take you to the place you need to edit on GitHub.

You will also want to read the Devguide, for info like how to build the documentation with your changes: https://devguide.python.org/documentation/start-documenting/

An example of how members should be documented is in PyType_Spec: https://docs.python.org/3/c-api/type.html#c.PyType_Spec

Johnny11502 commented 1 year ago

@encukou I would like to work on this issue. Thanks for the hint!

Johnny11502 commented 1 year ago

@encukou Just to let you know, I did not forget about this issue and I have just been a bit busy at work this week. I will try and submit my PR tonight or tomorrow.

Johnny11502 commented 1 year ago

@encukou I am a bit confused about what needs to be marked up as a member under PyMemberDef. I looked at PyType_Spec and saw how PyType_Spec.name and the members that follow were documented but I do not see what would need it for this issue. Would you please be able to specify the lines or text that needs to be corrected.

encukou commented 1 year ago

The members (fields) are name, type, offset, etc. Currently they're defined in a table, so they don't show up when searching the docs for PyMemberDef.name (and when writing the docs, can't be linked using :c:member`PyMemberDef.name`). The table should be converted to entries for the individual members.

Johnny11502 commented 1 year ago

Got it, thanks!

encukou commented 1 year ago

PyGetSetDef is in the same situation, let's use this issue for that as well.

Johnny11502 commented 1 year ago

@encukou I can update the members of PyGetSetDef as well since it would pretty much be the same if you don't mind.

encukou commented 1 year ago

Sounds good, thanks!

encukou commented 1 year ago

Please do not convert the T_* macros (T_SHORT etc.), though. I'm making bigger changes in that area.

encukou commented 1 year ago

PyMethodDef could use the same treatment.

ramvikrams commented 1 year ago

i'll do that

hugovk commented 1 month ago

Triage: can this be closed?