[Python-Dev] C API doc question
ncoghlan at gmail.com
Fri Sep 3 13:44:51 CEST 2010
On Fri, Sep 3, 2010 at 9:19 PM, Amaury Forgeot d'Arc <amauryfa at gmail.com> wrote:
> 2010/9/3 Nick Coghlan <ncoghlan at gmail.com>:
>> Due to the Unicode API discussion, I happened to be looking at the C
>> API docs at http://docs.python.org/dev/c-api/unicode.html#plain-py-unicode
>> and noticed that out of:
>> only the first and the last two are flagged in the online docs as
>> returning a new reference. The other 4 are not (but probably should
>> However, I can't see anything in the markup which is even causing
>> those "Return value: New reference" markings to appear in the first
>> place, nor any clues in the Documenting Python info. What am I
> This information is in the file:
> There is a extension to sphinx that reads this file and generates
> the annotation in the documentation.
> This file is not very well known, even by core developers...
Nope, never knew it existed until just now :)
Since it does exist, how hard would it be to get the extension to emit
a warning if a C API function isn't listed in that file, or if a
function listed in that file doesn't appear anywhere in the docs?
Currently it appears to default to reporting no effect on references
if a function isn't mentioned, which is potentially misleading (as the
above examples show, this file completely missed out on the
>From a more wish-list point of view, how hard would it be to modify
the extension to support having this markup inline with the function
documentation rather than having it off in a separate file? Or
addressing Skip's comment by allowing "-0" to indicate cases where
item references are stolen?
I created http://bugs.python.org/issue9755 to cover these questions.
Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia
More information about the Python-Dev