MAINT: formatting, remove version, rework flags

2 files changed, 21 insertions, 16 deletions

diff --git a/doc/source/reference/c-api.generalized-ufuncs.rst b/doc/source/reference/c-api.generalized-ufuncs.rst
index dce198013..b59f077ad 100644
--- a/doc/source/reference/c-api.generalized-ufuncs.rst
+++ b/doc/source/reference/c-api.generalized-ufuncs.rst
@@ -149,11 +149,13 @@ Notes:
 Here are some examples of signatures:
 
 +-------------+----------------------------+-----------------------------------+
-| add         | ``(),()->()``              |                                   |
+| name        | signature                  | common usage                      |
++=============+============================+===================================+
+| add         | ``(),()->()``              | binary ufunc                      |
 +-------------+----------------------------+-----------------------------------+
-| sum1d       | ``(i)->()``                |                                   |
+| sum1d       | ``(i)->()``                | reduction                         |
 +-------------+----------------------------+-----------------------------------+
-| inner1d     | ``(i),(i)->()``            |                                   |
+| inner1d     | ``(i),(i)->()``            | vector-vector multiplication      |
 +-------------+----------------------------+-----------------------------------+
 | matmat      | ``(m,n),(n,p)->(m,p)``     | matrix multiplication             |
 +-------------+----------------------------+-----------------------------------+
@@ -167,10 +169,15 @@ Here are some examples of signatures:
 |             |                            | outer over the second to last,    |
 |             |                            | and loop/broadcast over the rest. |
 +-------------+----------------------------+-----------------------------------+
-| cross1d     | ``(3),(3)->(3)``           | cross product where the last      |
-|             |                            | dimension must be 3               |
+|  cross1d    | ``(3),(3)->(3)``           | cross product where the last      |
+|             |                            | dimension is frozen and must be 3 |
 +-------------+----------------------------+-----------------------------------+
 
+.. _frozen:
+
+The last is an instance of freezing a core dimension and can be used to
+improve ufunc performance
+
 C-API for implementing Elementary Functions
 -------------------------------------------
 
diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst
index 51818142a..0766f5a3f 100644
--- a/doc/source/reference/c-api.types-and-structures.rst
+++ b/doc/source/reference/c-api.types-and-structures.rst
@@ -734,8 +734,8 @@ PyUFunc_Type
           npy_uint32 *op_flags;
           npy_uint32 *iter_flags;
           /* new in API version 0x0000000D */
-          npy_intp *core_dim_sizes; 
-          npy_intp *core_dim_flags; 
+          npy_intp *core_dim_sizes;
+          npy_intp *core_dim_flags;
 
       } PyUFuncObject;
 
@@ -796,11 +796,9 @@ PyUFunc_Type
        specifies how many different 1-d loops (of the builtin data
        types) are available.
 
-   .. c:member:: int PyUFuncObject.version
+   .. c:member:: int PyUFuncObject.reserved1
 
-       The ``NPY_API_VERSION`` used during the call to
-       :c:func:`PyUFunc_FromFuncAndDataAndSignature`. If less than
-        0x0000000D, ``core_dim_sizes`` and ``core_dim_flags`` will be ignored.
+       Unused.
 
    .. c:member:: char *PyUFuncObject.name
 
@@ -901,15 +899,15 @@ PyUFunc_Type
    .. c:member:: npy_intp *PyUFuncObject.core_dim_sizes
 
        For each distinct core dimension, the possible
-       "frozen" size (``-1`` if not frozen)
+       :ref:`frozen <frozen>` size (``-1`` if not frozen)
 
    .. c:member:: npy_uint32 *PyUFuncObject.core_dim_flags
 
-       For each distinct core dimension, a set of flags ``OR`` ed together:
+       For each distinct core dimension, a set of ``UFUNC_CORE_DIM*`` flags
 
-       - :c:data:`UFUNC_CORE_CAN_IGNORE` if the dim name ends in ``?``
-       - :c:data:`UFUNC_CORE_DIM_SIZE_UNSET` if the dim size will be
-         determined by the operands (not frozen)
+       - :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
 
 PyArrayIter_Type
 ----------------