[Python-Dev] C API doc question

[Georg Brandl]

Am 03.09.2010 13:44, schrieb 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.

Thanks, I will handle that at some point; I intended to overhaul the
refcounting extension anyway, and add data for the missing functions.

Georg


-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.