Clarify which "identifiers" in the C API are macros
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 36k
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 558
Description
Documentation
The "Python/C API Reference Manual" is an excellent resource but could be even better
if C macros were marked as such.
For a programmer that writes directly in C it doesn't matter which identifiers are real C functions
and which are C macros. However, when Python is used through libpython only the
C functions are available. This is the case for languages embedding Python through ffilib.
As an example: Consider the C macro PyImport_ImportModuleEx and the C function PyImport_ImportModuleLevel. They are documented in a way that makes it impossible
to guess that one is a C macro.
PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
A look in "Python.c" (or friends import.h here) will reveal that PyImport_ImportModuleEx is a C macro.
But it would be a quality of life-improvement, if a simple "C Macro" were added below the
signature of C macros.
This "C macro" annotation could have the same style as the "Return value is a new reference" annotation.
(maybe with a different color).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Python/C API Reference Manual and compare the documented PyImport_ImportModuleEx and PyImport_ImportModuleLevel entries. Inspect import.h to confirm the macro distinction, then identify how the existing return-value annotations are produced. Done means C macros in the API documentation are visibly marked without mislabeling C functions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100