gh-123254: Improve tuple CAPI docs with more info about errors

Doc/c-api/tuple.rst

@@ -33,25 +33,28 @@ 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)``.
 
 
 .. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
 
    Take a pointer to a tuple object, and return the size of that tuple.
+   or ``-1`` and set a :exc:`SystemError` exception if *op* is not a tuple.
 
 
 .. 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.
+   Return the size of the tuple *op*, which must be non-``NULL``
+   and point to a tuple; no error checking is performed.
 
 
 .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
@@ -74,8 +77,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 +146,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`.
 
+   Returns ``NULL`` with an exception set on failure.
+
 
 .. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
 
@@ -149,8 +156,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.
+   The same as ``PyStructSequence_InitType``, but returns ``0`` on success
+   and ``-1`` with an exception set on failure.
 
    .. versionadded:: 3.4
 
@@ -207,6 +214,8 @@ type.
    Creates an instance of *type*, which must have been created with
    :c:func:`PyStructSequence_NewType`.
 
+   Returns ``NULL`` with an exception set on failure.
+
 
 .. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)