gh-121834: Improve `complex` C-API docs (#121835)

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>

1 files changed, 22 insertions, 9 deletions

diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index 5a04748..67d0c5f 100644
--- 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,11 +110,13 @@ 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)
@@ -121,7 +127,9 @@ Complex Numbers as Python Objects
    :meth:`~object.__complex__` 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 call :c:func:`PyFloat_AsDouble` and
-   returns its result.  Upon failure, this method returns ``-1.0``, so one
+   returns its result.
+
+   Upon failure, this method returns ``-1.0`` with an exception set, so one
    should call :c:func:`PyErr_Occurred` to check for errors.
 
    .. versionchanged:: 3.13
@@ -135,8 +143,10 @@ Complex Numbers as Python Objects
    :meth:`~object.__complex__` 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 call :c:func:`PyFloat_AsDouble` and
-   returns ``0.0`` on success.  Upon failure, this method returns ``-1.0``, so
-   one should call :c:func:`PyErr_Occurred` to check for errors.
+   returns ``0.0`` on success.
+
+   Upon failure, this method returns ``-1.0`` with an exception set, so one
+   should call :c:func:`PyErr_Occurred` to check for errors.
 
    .. versionchanged:: 3.13
       Use :meth:`~object.__complex__` if available.
@@ -149,8 +159,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.