[3.12] gh-121834: Improve complex C-API docs (GH-121835) (#121897)

sobolevn · skirpichev · encukou · web-flow · commit 6a19d22a190b · 2024-07-17T07:30:18.000Z
* [3.12] gh-121834: Improve `complex` C-API docs (GH-121835) (cherry picked from commit 72dccd6) Co-authored-by: sobolevn <mail@sobolevn.me> Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
@@ -25,12 +25,16 @@ pointers.  This is consistent throughout the API.
 
    The C structure which corresponds to the value portion of a Python complex
    number object.  Most of the functions for dealing with complex number objects
-   use structures of this type as input or output values, as appropriate.  It is
-   defined as::
+   use structures of this type as input or output values, as appropriate.
+
+   .. c:member:: double real
+                 double imag
+
+   The structure is defined as::
 
       typedef struct {
-         double real;
-         double imag;
+          double real;
+          double imag;
       } Py_complex;
 
 
@@ -106,17 +110,22 @@ Complex Numbers as Python Objects
 .. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
 
    Create a new Python complex number object from a C :c:type:`Py_complex` value.
+   Return ``NULL`` with an exception set on error.
 
 
 .. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
 
    Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
+   Return ``NULL`` with an exception set on error.
 
 
 .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
 
    Return the real part of *op* as a C :c:expr:`double`.
 
+   Upon failure, this method returns ``-1.0`` with an exception set, so one
+   should call :c:func:`PyErr_Occurred` to check for errors.
+
 
 .. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
 
@@ -131,8 +140,11 @@ Complex Numbers as Python Objects
    method, this method will first be called to convert *op* to a Python complex
    number object.  If :meth:`!__complex__` is not defined then it falls back to
    :meth:`~object.__float__`.  If :meth:`!__float__` is not defined then it falls back
-   to :meth:`~object.__index__`.  Upon failure, this method returns ``-1.0`` as a real
-   value.
+   to :meth:`~object.__index__`.
+
+   Upon failure, this method returns :c:type:`Py_complex`
+   with :c:member:`~Py_complex.real` set to ``-1.0`` and with an exception set, so one
+   should call :c:func:`PyErr_Occurred` to check for errors.
 
    .. versionchanged:: 3.8
       Use :meth:`~object.__index__` if available.
