[Python-Dev] C API doc question

[Nick Coghlan]

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:
>>
>> PyUnicode_FromUnicode
>> PyUnicode_FromStringAndSize
>> PyUnicode_FromString
>> PyUnicode_FromFormat
>> PyUnicode_FromFormatV
>> PyUnicode_FromEncodedObject
>> PyUnicode_FromObject
>>
>> 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
>> be).
>>
>> 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
>> missing?
>
> This information is in the file:
>    Doc/data/refcounts.dat
> 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
PyString->PyUnicode rename).

>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.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia