undocumented api functions
Every so often, when writing C extensions, or embedding Python, I encounter api functions which seem to be useful, but they are undocumented. I brought the Doc/tools/undoc_symbols.py script up to date - this uses ctags to find function declarations, macro definitions and typedefs, then looks through the .tex files whether they are mentioned or not. Currently, for CVS head, it finds 239 undocumented function prototypes. Probably most of them should better stay undocumented and unused by extension writers, but several are really useful like these random picks: PySys_SetPath PyGILState_* PyOS_snprintf First I thought I write docs for some of them myself and submit patches or check them in directly, but maybe a more organized way would be better. So, as an experiment, I set up a wiki page for that. <http://starship.python.net/crew/theller/moin.cgi/Documenting_25CorePythonApi...> Maybe the page should be moved to the python.org wiki, but I'd like to hear any comments before. Thanks, Thomas
Thomas> First I thought I write docs for some of them myself and submit Thomas> patches or check them in directly, but maybe a more organized Thomas> way would be better. So, as an experiment, I set up a wiki page Thomas> for that. Thomas> <http://starship.python.net/crew/theller/moin.cgi/Documenting_25CorePythonApi...> Thomas> Maybe the page should be moved to the python.org wiki, but I'd Thomas> like to hear any comments before. This worked pretty well for the tutorial glossary. I started up a wiki page, gathered a bunch of contributions then filtered the submissions into what is in the current glossary. (I must admit that Raymond Hettinger was a major contributor. I actually did very little.) Skip
"Thomas Heller" <theller@python.net> wrote in message news:y8mwtu2r.fsf@python.net...
Every so often, when writing C extensions, or embedding Python, I encounter api functions which seem to be useful, but they are undocumented. I brought the Doc/tools/undoc_symbols.py script up to date - this uses ctags to find function declarations, macro definitions and typedefs, then looks through the .tex files whether they are mentioned or not.
Currently, for CVS head, it finds 239 undocumented function prototypes. Probably most of them should better stay undocumented and unused by extension writers,
Perhaps these could be tagged, if they are not now, in a way, such as /* NOT API */, that both readers and your script could recognize. TJR
participants (3)
-
Skip Montanaro
-
Terry Reedy
-
Thomas Heller