[3.12] gh-121533: Improve `PyCell_[Get,Set]` docs: mention the exceptions (GH-121534...

gh-121533: Improve `PyCell_[Get,Set]` docs: mention the exceptions (GH-121534)
(cherry picked from commit 649d5b6d7b04607dd17810ac73e8f16720c6dc78)

Co-authored-by: sobolevn <mail@sobolevn.me>
Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/c-api/cell.rst b/Doc/c-api/cell.rst
index f8cd0344fdd1c0c93eb00b40120e67d61a753169..61eb994c37094604e15563813c2cb7ec470c543c 100644 (file)
--- a/Doc/c-api/cell.rst
+++ b/Doc/c-api/cell.rst
@@ -39,7 +39,8 @@ Cell objects are not likely to be useful elsewhere.
 
 .. c:function:: PyObject* PyCell_Get(PyObject *cell)
 
-   Return the contents of the cell *cell*.
+   Return the contents of the cell *cell*, which can be ``NULL``.
+   If *cell* is not a cell object, returns ``NULL`` with an exception set.
 
 
 .. c:function:: PyObject* PyCell_GET(PyObject *cell)
@@ -52,8 +53,10 @@ Cell objects are not likely to be useful elsewhere.
 
    Set the contents of the cell object *cell* to *value*.  This releases the
    reference to any current content of the cell. *value* may be ``NULL``.  *cell*
-   must be non-``NULL``; if it is not a cell object, ``-1`` will be returned.  On
-   success, ``0`` will be returned.
+   must be non-``NULL``.
+
+   On success, return ``0``.
+   If *cell* is not a cell object, set an exception and return ``-1``.
 
 
 .. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)