Merge pull request #17464 from takanori-pskq/i13114-add-entries

DOC: Add some entries for C types and macros

2 files changed, 112 insertions, 75 deletions

diff --git a/doc/source/reference/c-api/types-and-structures.rst b/doc/source/reference/c-api/types-and-structures.rst
index cc961df3a..59361fd62 100644
--- a/doc/source/reference/c-api/types-and-structures.rst
+++ b/doc/source/reference/c-api/types-and-structures.rst
@@ -357,27 +357,25 @@ PyArrayDescr_Type and PyArray_Descr
     useful as the data-type descriptor for a field in another
     data-type descriptor. The fields member should be ``NULL`` if this
     is non- ``NULL`` (the fields member of the base descriptor can be
-    non- ``NULL`` however). The :c:type:`PyArray_ArrayDescr` structure is
-    defined using
+    non- ``NULL`` however).
 
-    .. code-block:: c
-
-       typedef struct {
-           PyArray_Descr *base;
-           PyObject *shape;
-       } PyArray_ArrayDescr;
+    .. c:type:: PyArray_ArrayDescr
 
-    The elements of this structure are:
+        .. code-block:: c
 
-    .. c:member:: PyArray_Descr *PyArray_ArrayDescr.base
+           typedef struct {
+               PyArray_Descr *base;
+               PyObject *shape;
+           } PyArray_ArrayDescr;
 
-        The data-type-descriptor object of the base-type.
+        .. c:member:: PyArray_Descr *PyArray_ArrayDescr.base
 
-    .. c:member:: PyObject *PyArray_ArrayDescr.shape
+            The data-type-descriptor object of the base-type.
 
-        The shape (always C-style contiguous) of the sub-array as a Python
-        tuple.
+        .. c:member:: PyObject *PyArray_ArrayDescr.shape
 
+            The shape (always C-style contiguous) of the sub-array as a Python
+            tuple.
 
 .. c:member:: PyObject *PyArray_Descr.fields
 
@@ -961,9 +959,14 @@ PyUFunc_Type and PyUFuncObject
 
        For each distinct core dimension, a set of ``UFUNC_CORE_DIM*`` flags
 
-       - :c:data:`UFUNC_CORE_DIM_CAN_IGNORE` if the dim name ends in ``?``
-       - :c:data:`UFUNC_CORE_DIM_SIZE_INFERRED` if the dim size will be
-         determined from the operands and not from a :ref:`frozen <frozen>` signature
+       .. c:macro:: UFUNC_CORE_DIM_CAN_IGNORE
+
+           if the dim name ends in ``?``
+
+       .. c:macro:: UFUNC_CORE_DIM_SIZE_INFERRED
+
+           if the dim size will be determined from the operands
+           and not from a :ref:`frozen <frozen>` signature
 
 PyArrayIter_Type and PyArrayIterObject
 --------------------------------------
@@ -1433,7 +1436,7 @@ for completeness and assistance in understanding the code.
    Advanced indexing is handled with this Python type. It is simply a
    loose wrapper around the C-structure containing the variables
    needed for advanced array indexing. The associated C-structure,
-   :c:type:`PyArrayMapIterObject`, is useful if you are trying to
+   ``PyArrayMapIterObject``, is useful if you are trying to
    understand the advanced-index mapping code. It is defined in the
    ``arrayobject.h`` header. This type is not exposed to Python and
    could be replaced with a C-structure. As a Python type it takes
diff --git a/doc/source/reference/c-api/ufunc.rst b/doc/source/reference/c-api/ufunc.rst
index 50963c81f..1b9b68642 100644
--- a/doc/source/reference/c-api/ufunc.rst
+++ b/doc/source/reference/c-api/ufunc.rst
@@ -12,12 +12,39 @@ Constants
 
 .. c:var:: UFUNC_ERR_{HANDLER}
 
-    ``{HANDLER}`` can be **IGNORE**, **WARN**, **RAISE**, or **CALL**
+    .. c:macro:: UFUNC_ERR_IGNORE
+
+    .. c:macro:: UFUNC_ERR_WARN
+
+    .. c:macro:: UFUNC_ERR_RAISE
+
+    .. c:macro:: UFUNC_ERR_CALL
 
 .. c:var:: UFUNC_{THING}_{ERR}
 
-    ``{THING}`` can be **MASK**, **SHIFT**, or **FPE**, and ``{ERR}`` can
-    be **DIVIDEBYZERO**, **OVERFLOW**, **UNDERFLOW**, and **INVALID**.
+    .. c:macro:: UFUNC_MASK_DIVIDEBYZERO
+
+    .. c:macro:: UFUNC_MASK_OVERFLOW
+
+    .. c:macro:: UFUNC_MASK_UNDERFLOW
+
+    .. c:macro:: UFUNC_MASK_INVALID
+
+    .. c:macro:: UFUNC_SHIFT_DIVIDEBYZERO
+
+    .. c:macro:: UFUNC_SHIFT_OVERFLOW
+
+    .. c:macro:: UFUNC_SHIFT_UNDERFLOW
+
+    .. c:macro:: UFUNC_SHIFT_INVALID
+
+    .. c:macro:: UFUNC_FPE_DIVIDEBYZERO
+
+    .. c:macro:: UFUNC_FPE_OVERFLOW
+
+    .. c:macro:: UFUNC_FPE_UNDERFLOW
+
+    .. c:macro:: UFUNC_FPE_INVALID
 
 .. c:var:: PyUFunc_{VALUE}
 
@@ -50,6 +77,66 @@ Macros
     was released (because loop->obj was not true).
 
 
+Types
+-----
+
+.. c:type:: PyUFuncGenericFunction
+
+    pointers to functions that actually implement the underlying
+    (element-by-element) function :math:`N` times with the following
+    signature:
+
+    .. c:function:: void loopfunc(
+            char** args, npy_intp const *dimensions, npy_intp const *steps, void* data)
+
+        *args*
+
+            An array of pointers to the actual data for the input and output
+            arrays. The input arguments are given first followed by the output
+            arguments.
+
+        *dimensions*
+
+            A pointer to the size of the dimension over which this function is
+            looping.
+
+        *steps*
+
+            A pointer to the number of bytes to jump to get to the
+            next element in this dimension for each of the input and
+            output arguments.
+
+        *data*
+
+            Arbitrary data (extra arguments, function names, *etc.* )
+            that can be stored with the ufunc and will be passed in
+            when it is called.
+
+        This is an example of a func specialized for addition of doubles
+        returning doubles.
+
+        .. code-block:: c
+
+            static void
+            double_add(char **args,
+                       npy_intp const *dimensions,
+                       npy_intp const *steps,
+                       void *extra)
+            {
+                npy_intp i;
+                npy_intp is1 = steps[0], is2 = steps[1];
+                npy_intp os = steps[2], n = dimensions[0];
+                char *i1 = args[0], *i2 = args[1], *op = args[2];
+                for (i = 0; i < n; i++) {
+                    *((double *)op) = *((double *)i1) +
+                                      *((double *)i2);
+                    i1 += is1;
+                    i2 += is2;
+                    op += os;
+                 }
+            }
+
+
 Functions
 ---------
 
@@ -71,60 +158,7 @@ Functions
 
     :param func:
         Must to an array of length *ntypes* containing
-        :c:type:`PyUFuncGenericFunction` items. These items are pointers to
-        functions that actually implement the underlying
-        (element-by-element) function :math:`N` times with the following
-        signature:
-
-        .. c:function:: void loopfunc(
-                char** args, npy_intp const *dimensions, npy_intp const *steps, void* data)
-
-            *args*
-
-                An array of pointers to the actual data for the input and output
-                arrays. The input arguments are given first followed by the output
-                arguments.
-
-            *dimensions*
-
-                A pointer to the size of the dimension over which this function is
-                looping.
-
-            *steps*
-
-                A pointer to the number of bytes to jump to get to the
-                next element in this dimension for each of the input and
-                output arguments.
-
-            *data*
-
-                Arbitrary data (extra arguments, function names, *etc.* )
-                that can be stored with the ufunc and will be passed in
-                when it is called.
-
-            This is an example of a func specialized for addition of doubles
-            returning doubles.
-
-            .. code-block:: c
-
-                static void
-                double_add(char **args,
-                           npy_intp const *dimensions,
-                           npy_intp const *steps,
-                           void *extra)
-                {
-                    npy_intp i;
-                    npy_intp is1 = steps[0], is2 = steps[1];
-                    npy_intp os = steps[2], n = dimensions[0];
-                    char *i1 = args[0], *i2 = args[1], *op = args[2];
-                    for (i = 0; i < n; i++) {
-                        *((double *)op) = *((double *)i1) +
-                                          *((double *)i2);
-                        i1 += is1;
-                        i2 += is2;
-                        op += os;
-                     }
-                }
+        :c:type:`PyUFuncGenericFunction` items.
 
     :param data:
         Should be ``NULL`` or a pointer to an array of size *ntypes*