Clarify which "identifiers" in the C API are macros
Ninguém assumiu esta issue ainda.
- Linguagem predominante
- Python
- Estrelas
- 77.2k
- Forks
- 36k
- Merge médio
- 1d 9h
- PRs com merge (30d)
- 558
Descrição
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).
Guia de contribuição
Primeiros passos
- Leia a issue inteira e depois o guia de contribuição do projeto.
- Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
- Faça um fork do repositório e trabalhe em uma branch.
- Abra um pull request que referencie o número da issue.
Direção de pesquisa
Comece pelo Python/C API Reference Manual e compare as entradas documentadas de PyImport_ImportModuleEx e PyImport_ImportModuleLevel. Inspecione import.h para confirmar a distinção entre as macros e, em seguida, identifique como as anotações de valor de retorno existentes são produzidas. O trabalho estará concluído quando as macros C estiverem visivelmente marcadas na documentação da API sem classificar incorretamente as funções C.
Escrita pelo modelo de indexação a partir do texto da issue.
Avaliação
- Stack de tecnologia
- c, python
- Domínio
- documentation
- Tipo de issue
- Documentação
- Dificuldade
- 4/5
- Tempo estimado
- 3-5 dias
- Status de atividade
- Estagnada
- Clareza
- Razoavelmente clara
- Facilidade para iniciantes
- 45/100