On Fri, Sep 3, 2010 at 9:19 PM, Amaury Forgeot d'Arc <amaur...@gmail.com> wrote: > 2010/9/3 Nick Coghlan <ncogh...@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 | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
