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

[Baruch Sterin]

New submission from Baruch Sterin <python at bsterin.com>:

In addition to the description text, most C API functions have a one-line, emphasized specification whether they return a new or a borrowed reference. (e.g. 'Return value: New reference.').

The following API functions are missing that. Some of them, like PyMemoryView_FromBuffer(), have descriptions that are clear, but it would still be nice to have an unambiguous statement like most other API functions have.

The list has been generated automatically, so it might contain some errors.

Doc/c-api/arg.rst:  Py_VaBuildValue
Doc/c-api/buffer.rst:  PyMemoryView_FromBuffer
Doc/c-api/buffer.rst:  PyMemoryView_FromObject
Doc/c-api/buffer.rst:  PyMemoryView_GetContiguous
Doc/c-api/bytearray.rst:  PyByteArray_Concat
Doc/c-api/bytearray.rst:  PyByteArray_FromObject
Doc/c-api/bytearray.rst:  PyByteArray_FromStringAndSize
Doc/c-api/code.rst:  PyCode_New
Doc/c-api/codec.rst:  PyCodec_BackslashReplaceErrors
Doc/c-api/codec.rst:  PyCodec_Decode
Doc/c-api/codec.rst:  PyCodec_Decoder
Doc/c-api/codec.rst:  PyCodec_Encode
Doc/c-api/codec.rst:  PyCodec_Encoder
Doc/c-api/codec.rst:  PyCodec_IgnoreErrors
Doc/c-api/codec.rst:  PyCodec_IncrementalDecoder
Doc/c-api/codec.rst:  PyCodec_IncrementalEncoder
Doc/c-api/codec.rst:  PyCodec_LookupError
Doc/c-api/codec.rst:  PyCodec_ReplaceErrors
Doc/c-api/codec.rst:  PyCodec_StreamReader
Doc/c-api/codec.rst:  PyCodec_StreamWriter
Doc/c-api/codec.rst:  PyCodec_StrictErrors
Doc/c-api/codec.rst:  PyCodec_XMLCharRefReplaceErrors
Doc/c-api/exceptions.rst:  PyUnicodeDecodeError_Create
Doc/c-api/exceptions.rst:  PyUnicodeDecodeError_GetEncoding
Doc/c-api/exceptions.rst:  PyUnicodeDecodeError_GetObject
Doc/c-api/exceptions.rst:  PyUnicodeDecodeError_GetReason
Doc/c-api/exceptions.rst:  PyUnicodeEncodeError_Create
Doc/c-api/exceptions.rst:  PyUnicodeTranslateError_Create
Doc/c-api/float.rst:  PyFloat_GetInfo
Doc/c-api/import.rst:  PyImport_GetImporter
Doc/c-api/import.rst:  PyImport_ImportModuleNoBlock
Doc/c-api/import.rst:  _PyImport_FindExtension
Doc/c-api/import.rst:  _PyImport_FixupExtension
Doc/c-api/init.rst:  PyEval_GetCallStats
Doc/c-api/int.rst:  PyInt_FromSize_t
Doc/c-api/long.rst:  PyLong_FromSize_t
Doc/c-api/long.rst:  PyLong_FromSsize_t
Doc/c-api/number.rst:  PyNumber_Index
Doc/c-api/number.rst:  PyNumber_ToBase
Doc/c-api/object.rst:  PyObject_Bytes
Doc/c-api/object.rst:  PyObject_GenericGetAttr
Doc/c-api/unicode.rst:  PyUnicode_AsUTF32String
Doc/c-api/unicode.rst:  PyUnicode_DecodeMBCSStateful
Doc/c-api/unicode.rst:  PyUnicode_DecodeUTF32
Doc/c-api/unicode.rst:  PyUnicode_DecodeUTF32Stateful
Doc/c-api/unicode.rst:  PyUnicode_DecodeUTF7
Doc/c-api/unicode.rst:  PyUnicode_DecodeUTF7Stateful
Doc/c-api/unicode.rst:  PyUnicode_EncodeUTF32
Doc/c-api/unicode.rst:  PyUnicode_EncodeUTF7
Doc/c-api/veryhigh.rst:  PyEval_EvalCodeEx
Doc/c-api/veryhigh.rst:  PyEval_EvalFrame
Doc/c-api/veryhigh.rst:  PyEval_EvalFrameEx

----------
assignee: docs at python
components: Documentation
messages: 154877
nosy: baruch.sterin, docs at python
priority: normal
severity: normal
status: open
title: Documentation for some C APIs is missing clear specification of the type of reference they return
type: behavior
versions: Python 2.7

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