[issue14189] Documentation for some C APIs is missing clear specification of the type of reference they return

[Josh Rosenberg]

Josh Rosenberg added the comment:

If any of these actually return borrowed references, I'd consider it a serious documentation bug to not mention it. New reference semantics are the default, and while it's best to call them out, it can be assumed in most cases. Returning borrowed references without a big honking "not a normal function" flag in the docs causes a big problem.

Heck, the lack of such a big warning flag on PyDict_Next (which doesn't return a PyObject, but populates via a double pointer) caused me a major headache recently when I DECREF-ed the resulting objects. Totally my fault (the description says they're borrowed), but I rely on that "Returns: Borrowed Reference" header so much that I made a dumb mistake.

----------
nosy: +josh.rosenberg

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue14189>
_______________________________________