bpo-38557: Improve documentation for list and tuple C API. (GH-16925)

2 files changed, 18 insertions, 12 deletions

diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst
index dc90266..646f29d 100644
--- a/Doc/c-api/list.rst
+++ b/Doc/c-api/list.rst
@@ -71,8 +71,9 @@ List Objects
 
 .. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
 
-   Set the item at index *index* in list to *item*.  Return ``0`` on success
-   or ``-1`` on failure.
+   Set the item at index *index* in list to *item*.  Return ``0`` on success.
+   If *index* is out of bounds, return ``-1`` and set an :exc:`IndexError`
+   exception.
 
    .. note::
 
@@ -111,8 +112,7 @@ List Objects
 
    Return a list of the objects in *list* containing the objects *between* *low*
    and *high*.  Return *NULL* and set an exception if unsuccessful.  Analogous
-   to ``list[low:high]``.  Negative indices, as when slicing from Python, are not
-   supported.
+   to ``list[low:high]``.  Indexing from the end of the list is not supported.
 
 
 .. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
@@ -120,8 +120,8 @@ List Objects
    Set the slice of *list* between *low* and *high* to the contents of
    *itemlist*.  Analogous to ``list[low:high] = itemlist``. The *itemlist* may
    be *NULL*, indicating the assignment of an empty list (slice deletion).
-   Return ``0`` on success, ``-1`` on failure.  Negative indices, as when
-   slicing from Python, are not supported.
+   Return ``0`` on success, ``-1`` on failure.  Indexing from the end of the
+   list is not supported.
 
 
 .. c:function:: int PyList_Sort(PyObject *list)
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 259ec4f..a0d53e2 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -57,7 +57,7 @@ Tuple Objects
 .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
 
    Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
-   out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
+   out of bounds, return *NULL* and set an :exc:`IndexError` exception.
 
 
 .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
@@ -67,18 +67,21 @@ Tuple Objects
 
 .. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
 
-   Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
-   as a new tuple.
+   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 list is not supported.
 
 
 .. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
 
    Insert a reference to object *o* at position *pos* of the tuple pointed to by
-   *p*. Return ``0`` on success.
+   *p*.  Return ``0`` on success.  If *pos* is out of bounds, return ``-1``
+   and set an :exc:`IndexError` exception.
 
    .. note::
 
-      This function "steals" a reference to *o*.
+      This function "steals" a reference to *o* and discards a reference to
+      an item already in the tuple at the affected position.
 
 
 .. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
@@ -88,7 +91,10 @@ Tuple Objects
 
    .. note::
 
-      This function "steals" a reference to *o*.
+      This macro "steals" a reference to *o*, and, unlike
+      :c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that
+      is being replaced; any reference in the tuple at position *pos* will be
+      leaked.
 
 
 .. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)