gh-128813: cleanup C-API docs for PyComplexObject (GH-137579)

* move non-deprecated API up
* make a dedicated section for deprecated low-leved API

diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index a1fd27ad0acd2e8353064e3f99153bec3dcfb541..aa91b85d07fc7e0fd7c382be53c9f225be95589a 100644 (file)
--- a/Doc/c-api/complex.rst
+++ b/Doc/c-api/complex.rst
@@ -3,116 +3,10 @@
 .. _complexobjects:
 
 Complex Number Objects
-----------------------
+======================
 
 .. index:: pair: object; complex number
 
-Python's complex number objects are implemented as two distinct types when
-viewed from the C API:  one is the Python object exposed to Python programs, and
-the other is a C structure which represents the actual complex number value.
-The API provides functions for working with both.
-
-
-Complex Numbers as C Structures
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Note that the functions which accept these structures as parameters and return
-them as results do so *by value* rather than dereferencing them through
-pointers.  This is consistent throughout the API.
-
-
-.. c:type:: Py_complex
-
-   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.
-
-   .. c:member:: double real
-                 double imag
-
-   The structure is defined as::
-
-      typedef struct {
-          double real;
-          double imag;
-      } Py_complex;
-
-
-.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
-
-   Return the sum of two complex numbers, using the C :c:type:`Py_complex`
-   representation.
-
-   .. deprecated:: 3.15
-      This function is :term:`soft deprecated`.
-
-
-.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
-
-   Return the difference between two complex numbers, using the C
-   :c:type:`Py_complex` representation.
-
-   .. deprecated:: 3.15
-      This function is :term:`soft deprecated`.
-
-
-.. c:function:: Py_complex _Py_c_neg(Py_complex num)
-
-   Return the negation of the complex number *num*, using the C
-   :c:type:`Py_complex` representation.
-
-   .. deprecated:: 3.15
-      This function is :term:`soft deprecated`.
-
-
-.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
-
-   Return the product of two complex numbers, using the C :c:type:`Py_complex`
-   representation.
-
-   .. deprecated:: 3.15
-      This function is :term:`soft deprecated`.
-
-
-.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
-
-   Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
-   representation.
-
-   If *divisor* is null, this method returns zero and sets
-   :c:data:`errno` to :c:macro:`!EDOM`.
-
-   .. deprecated:: 3.15
-      This function is :term:`soft deprecated`.
-
-
-.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
-
-   Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
-   representation.
-
-   If *num* is null and *exp* is not a positive real number,
-   this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
-
-   Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
-
-   .. deprecated:: 3.15
-      This function is :term:`soft deprecated`.
-
-
-.. c:function:: double _Py_c_abs(Py_complex num)
-
-   Return the absolute value of the complex number *num*.
-
-   Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
-
-   .. deprecated:: 3.15
-      This function is :term:`soft deprecated`.
-
-
-Complex Numbers as Python Objects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
 
 .. c:type:: PyComplexObject
 
@@ -147,12 +41,6 @@ Complex Numbers as Python Objects
    :c:type:`PyComplexObject`.  This function always succeeds.
 
 
-.. 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*.
@@ -191,6 +79,29 @@ Complex Numbers as Python Objects
    .. versionchanged:: 3.13
       Use :meth:`~object.__complex__` if available.
 
+
+.. c:type:: Py_complex
+
+   This C structure defines export format for a Python complex
+   number object.
+
+   .. c:member:: double real
+                 double imag
+
+   The structure is defined as::
+
+      typedef struct {
+          double real;
+          double imag;
+      } Py_complex;
+
+
+.. 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:: Py_complex PyComplex_AsCComplex(PyObject *op)
 
    Return the :c:type:`Py_complex` value of the complex number *op*.
@@ -207,3 +118,82 @@ Complex Numbers as Python Objects
 
    .. versionchanged:: 3.8
       Use :meth:`~object.__index__` if available.
+
+
+Complex Numbers as C Structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The API also provides functions for working with complex numbers, using the
+:c:type:`Py_complex` representation.  Note that the functions which accept
+these structures as parameters and return them as results do so *by value*
+rather than dereferencing them through pointers.
+
+Please note, that these functions are :term:`soft deprecated` since Python
+3.15.  Avoid using this API in a new code to do complex arithmetic: either use
+the `Number Protocol <number>`_ API or use native complex types, like
+:c:expr:`double complex`.
+
+
+.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
+
+   Return the sum of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+   .. deprecated:: 3.15
+
+
+.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
+
+   Return the difference between two complex numbers, using the C
+   :c:type:`Py_complex` representation.
+
+   .. deprecated:: 3.15
+
+
+.. c:function:: Py_complex _Py_c_neg(Py_complex num)
+
+   Return the negation of the complex number *num*, using the C
+   :c:type:`Py_complex` representation.
+
+   .. deprecated:: 3.15
+
+
+.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
+
+   Return the product of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+   .. deprecated:: 3.15
+
+
+.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
+
+   Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+   If *divisor* is null, this method returns zero and sets
+   :c:data:`errno` to :c:macro:`!EDOM`.
+
+   .. deprecated:: 3.15
+
+
+.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
+
+   Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
+   representation.
+
+   If *num* is null and *exp* is not a positive real number,
+   this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
+
+   Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
+
+   .. deprecated:: 3.15
+
+
+.. c:function:: double _Py_c_abs(Py_complex num)
+
+   Return the absolute value of the complex number *num*.
+
+   Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
+
+   .. deprecated:: 3.15