gh-123254: Improve `tuple` C API docs with more info about errors (#123255)

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 52668d16b74436866123cf0e961fa06c62e59c92..7a8a6134282ade28a174723877a0b3f8a146c97e 100644 (file)
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -33,12 +33,14 @@ Tuple Objects
 
 .. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
 
-   Return a new tuple object of size *len*, or ``NULL`` on failure.
+   Return a new tuple object of size *len*,
+   or ``NULL`` with an exception set on failure.
 
 
 .. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
 
-   Return a new tuple object of size *n*, or ``NULL`` on failure. The tuple values
+   Return a new tuple object of size *n*,
+   or ``NULL`` with an exception set on failure. The tuple values
    are initialized to the subsequent *n* C arguments pointing to Python objects.
    ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
 
@@ -46,12 +48,12 @@ Tuple Objects
 .. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
 
    Take a pointer to a tuple object, and return the size of that tuple.
+   On error, return ``-1`` and with an exception set.
 
 
 .. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
 
-   Return the size of the tuple *p*, which must be non-``NULL`` and point to a tuple;
-   no error checking is performed.
+   Like :c:func:`PyTuple_Size`, but without error checking.
 
 
 .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
@@ -74,8 +76,10 @@ Tuple Objects
 .. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
 
    Return the slice of the tuple pointed to by *p* between *low* and *high*,
-   or ``NULL`` on failure.  This is the equivalent of the Python expression
-   ``p[low:high]``.  Indexing from the end of the tuple is not supported.
+   or ``NULL`` with an exception set on failure.
+
+   This is the equivalent of the Python expression ``p[low:high]``.
+   Indexing from the end of the tuple is not supported.
 
 
 .. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
@@ -141,6 +145,8 @@ type.
    Create a new struct sequence type from the data in *desc*, described below. Instances
    of the resulting type can be created with :c:func:`PyStructSequence_New`.
 
+   Return ``NULL`` with an exception set on failure.
+
 
 .. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
 
@@ -149,8 +155,8 @@ type.
 
 .. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
 
-   The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
-   failure.
+   Like :c:func:`PyStructSequence_InitType`, but returns ``0`` on success
+   and ``-1`` with an exception set on failure.
 
    .. versionadded:: 3.4
 
@@ -207,6 +213,8 @@ type.
    Creates an instance of *type*, which must have been created with
    :c:func:`PyStructSequence_NewType`.
 
+   Return ``NULL`` with an exception set on failure.
+
 
 .. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)