gh-107298: Document doesn't link to PyAPI_DATA() #109236
Conversation
cbd269f to
553fdd0
Compare
553fdd0 to
5eba491
Compare
Oh right. I fixed my PR:
Please review it again. @hugovk: I added "the" in the added doc ;-) |
5eba491 to
5847580
Compare
Doc/c-api/intro.rst
Outdated
| type is :c:expr:`PyObject*`. The macro should only be used in the Python C | ||
| API. |
There was a problem hiding this comment.
"The macro should only be used in the Python C API." -- I think that it is wrong.
This description is not clear, and does not help. The use of PyMODINIT_FUNC is actually described in Doc/extending/extending.rst:
This structure, in turn, must be passed to the interpreter in the module's
initialization function. The initialization function must be named
:c:func:`!PyInit_name`, where *name* is the name of the module, and should be the
only non-\ ``static`` item defined in the module file::
PyMODINIT_FUNC
PyInit_spam(void)
{
return PyModule_Create(&spammodule);
}
Note that :c:macro:`PyMODINIT_FUNC` declares the function as ``PyObject *`` return type,
declares any special linkage declarations required by the platform, and for C++
declares the function as ``extern "C"``.It would be better if PyMODINIT_FUNC links would refer to that text. Or at least make a reference to it from the declaration in Doc/c-api/intro.rst.
There was a problem hiding this comment.
Ok, I copied this doc to Doc/c-api/intro.rst.
|
@serhiy-storchaka: I completed PyMODINIT_FUNC doc. Would you mind to review my doc change again? |
|
Oops sorry, I tested a Git tool and it messed up my PR :-( I fixed my PR. |
Doc/c-api/intro.rst
Outdated
| declarations required by the platform, and for C++ declares the function as | ||
| ``extern "C"``. | ||
|
|
||
| The initialization function must be named :c:func:`!PyInit_name`, where |
There was a problem hiding this comment.
Maybe write :samp:`PyInit_{name}`? It renders the whole name as a code, but name additionally is in italic, as a variable part.
There was a problem hiding this comment.
I never saw :samp:, let me try.
There was a problem hiding this comment.
|
Merged, thanks for the review @serhiy-storchaka. |
Oh, and thanks @hugovk for the review as well :-) |
|
Thanks @vstinner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11. |
|
Thanks @vstinner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12. |
|
Sorry, @vstinner, I could not cleanly backport this to |
Document PyMODINIT_FUNC macro. Remove links to PyAPI_FUNC() and PyAPI_DATA() macros since they are not documented. These macros should only be used to define the Python C API. They should not be used outside Python code base. (cherry picked from commit d7a27e5) Co-authored-by: Victor Stinner <vstinner@python.org>
|
GH-109947 is a backport of this pull request to the 3.12 branch. |
|
GH-109948 is a backport of this pull request to the 3.11 branch. |
gh-107298: Document PyMODINIT_FUNC macro (#109236) Document PyMODINIT_FUNC macro. Remove links to PyAPI_FUNC() and PyAPI_DATA() macros since they are not documented. These macros should only be used to define the Python C API. They should not be used outside Python code base. (cherry picked from commit d7a27e5)
gh-107298: Document PyMODINIT_FUNC macro (GH-109236) Document PyMODINIT_FUNC macro. Remove links to PyAPI_FUNC() and PyAPI_DATA() macros since they are not documented. These macros should only be used to define the Python C API. They should not be used outside Python code base. (cherry picked from commit d7a27e5) Co-authored-by: Victor Stinner <vstinner@python.org>
Remove links to PyAPI_FUNC() and PyAPI_DATA() macros since they are
not documented. These macros should only be used to define the Python
C API. They should not be used outside Python code base.
Document PyMODINIT_FUNC macro.
📚 Documentation preview 📚: https://cpython-previews--109236.org.readthedocs.build/