[issue10439] PyCodec C API is not documented in reST
New submission from Alexander Belopolsky <belopolsky@users.sourceforge.net>: Python Codec Registry and support functions are well documented in codecs.h header file. It should be easy to convert that to reST. ---------- assignee: docs@python components: Documentation keywords: easy messages: 121329 nosy: belopolsky, docs@python, haypo, lemburg, loewis priority: normal severity: normal stage: needs patch status: open title: PyCodec C API is not documented in reST versions: Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: I will write a codecs.rst for this. Any suggestion of where in c-api/index.html it should be linked? ---------- nosy: +eli.bendersky _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Georg Brandl <georg@python.org> added the comment: Please call it codec.rst. It is probably best placed under "utilities". ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: While preparing a .rst document for this, I ran into a possible inaccuracy in a comment in codecs.h: /* Lookup the error handling callback function registered under the name error. As a special case NULL can be passed, in which case the error handling callback for "strict" will be returned. */ PyAPI_FUNC(PyObject *) PyCodec_LookupError(const char *name); ---- The problem may be with the phrase "under the name error". Shouldn't it be just "under *name*"? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Georg Brandl <georg@python.org> added the comment: Yes, apparently the parameter was (intended to be) called "error" at some point. Can you put the correction in your patch? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Submitting a patch. What was touched: 1. Include/codecs.h - minor inaccuracy and inconsistency in a comment 2. Doc/c-api/codec.rst - new reST documentation file for the codecs.h C API 3. Doc/c-api/utilities.rst - for linking to codec.rst, per Georg's suggestion ---------- keywords: +patch Added file: http://bugs.python.org/file19657/issue10439.1.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Amaury Forgeot d'Arc <amauryfa@gmail.com> added the comment: Thanks for the patch, it looks good, I have 2 remarks though: - "under the name name" could be replaced by "under the given name". - "The *search_function*'s refcount is incremented by this function." This information is not useful to the caller - she just wants to know whether she still owns the reference she had before. Most probably here, the refcount is incremented because the object is stored in a list; the caller still owns the reference to the parameter, like most functions of the API, and there is nothing to say about refcounts here. ---------- nosy: +amaury.forgeotdarc _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Amaury, Thanks for the review & comments. I'm attaching a fixed patch. ---------- Added file: http://bugs.python.org/file19661/issue10439.2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Georg Brandl <georg@python.org> added the comment: Please also keep to 3-space indentation in directives. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Georg, Thanks. Submitting fixed patch with 3-space indentation in directives. ---------- Added file: http://bugs.python.org/file19662/issue10439.3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
Georg Brandl <georg@python.org> added the comment: Reviewed and applied in r86562. Thanks! ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10439> _______________________________________
participants (5)
-
Alexander Belopolsky -
Amaury Forgeot d'Arc
-
Eli Bendersky
-
Ezio Melotti
-
Georg Brandl