classification
Title: PyCodec C API is not documented in reST
Type: Stage: needs patch
Components: Documentation Versions: Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amaury.forgeotdarc, belopolsky, docs@python, eli.bendersky, ezio.melotti, georg.brandl, lemburg, loewis, vstinner
Priority: normal Keywords: easy, patch

Created on 2010-11-17 00:08 by belopolsky, last changed 2010-11-20 13:45 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
issue10439.1.patch eli.bendersky, 2010-11-20 12:26
issue10439.2.patch eli.bendersky, 2010-11-20 13:18
issue10439.3.patch eli.bendersky, 2010-11-20 13:22
Messages (11)
msg121329 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-11-17 00:08
Python Codec Registry and support functions are well documented in codecs.h header file.  It should be easy to convert that to reST.
msg121603 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-20 10:42
I will write a codecs.rst for this. Any suggestion of where in c-api/index.html it should be linked?
msg121606 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-20 10:51
Please call it codec.rst.  It is probably best placed under "utilities".
msg121613 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-20 11:27
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*"?
msg121614 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-20 11:31
Yes, apparently the parameter was (intended to be) called "error" at some point.  Can you put the correction in your patch?
msg121620 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-20 12:26
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
msg121629 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2010-11-20 13:02
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.
msg121632 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-20 13:18
Amaury,

Thanks for the review & comments.
I'm attaching a fixed patch.
msg121633 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-20 13:18
Please also keep to 3-space indentation in directives.
msg121636 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-20 13:22
Georg,
Thanks. Submitting fixed patch with 3-space indentation in directives.
msg121640 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-20 13:45
Reviewed and applied in r86562.  Thanks!
History
Date User Action Args
2010-11-20 13:45:29georg.brandlsetstatus: open -> closed
resolution: fixed
messages: + msg121640
2010-11-20 13:22:53eli.benderskysetfiles: + issue10439.3.patch

messages: + msg121636
2010-11-20 13:18:53georg.brandlsetmessages: + msg121633
2010-11-20 13:18:06eli.benderskysetfiles: + issue10439.2.patch

messages: + msg121632
2010-11-20 13:02:03amaury.forgeotdarcsetnosy: + amaury.forgeotdarc
messages: + msg121629
2010-11-20 12:26:55eli.benderskysetfiles: + issue10439.1.patch
keywords: + patch
messages: + msg121620
2010-11-20 11:31:10georg.brandlsetmessages: + msg121614
2010-11-20 11:27:09eli.benderskysetmessages: + msg121613
2010-11-20 10:51:10georg.brandlsetnosy: + georg.brandl
messages: + msg121606
2010-11-20 10:42:57eli.benderskysetnosy: + eli.bendersky
messages: + msg121603
2010-11-17 01:04:27ezio.melottisetnosy: + ezio.melotti
2010-11-17 00:08:55belopolskycreate