Issue #25701: Document C API functions that both set and delete objects
Also document that the separate functions that delete objects are preferred;
using PyObject_SetAttr(), _SetAttrString(), and PySequence_SetItem() to
delete is deprecated.
diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst
index 5960db9..f1825f0 100644
--- a/Doc/c-api/sequence.rst
+++ b/Doc/c-api/sequence.rst
@@ -62,10 +62,14 @@
.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
- Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This
+ Assign object *v* to the *i*\ th element of *o*. Raise an exception
+ and return ``-1`` on failure; return ``0`` on success. This
is the equivalent of the Python statement ``o[i] = v``. This function *does
not* steal a reference to *v*.
+ If *v* is *NULL*, the element is deleted, however this feature is
+ deprecated in favour of using :c:func:`PySequence_DelItem`.
+
.. c:function:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)