DOC: reduce warnings and cleanup redundant c-api documentation

1 files changed, 62 insertions, 3 deletions

diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst
index 8c2554a9e..391acf1cb 100644
--- a/doc/source/reference/c-api.ufunc.rst
+++ b/doc/source/reference/c-api.ufunc.rst
@@ -85,12 +85,61 @@ Functions
         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.
+        (element-by-element) function :math:`N` times with the following
+        signature:
+
+        .. c:function:: void loopfunc( \
+                char** args, npy_intp* dimensions, npy_intp* 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 *dimensions, npy_intp *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;
+                     }
+                }
 
     :param data:
         Should be ``NULL`` or a pointer to an array of size *ntypes*
         . This array may contain arbitrary extra-data to be passed to
-        the corresponding 1-d loop function in the func array.
+        the corresponding loop function in the func array.
 
     :param types:
        Length ``(nin + nout) * ntypes`` array of ``char`` encoding the
@@ -102,6 +151,9 @@ Functions
        be ``(char[]) {5, 5, 0, 7, 7, 0}`` since ``NPY_INT32`` is 5,
        ``NPY_INT64`` is 7, and ``NPY_BOOL`` is 0.
 
+       The bit-width names can also be used (e.g. :c:data:`NPY_INT32`,
+       :c:data:`NPY_COMPLEX128` ) if desired.
+
        :ref:`ufuncs.casting` will be used at runtime to find the first
        ``func`` callable by the input/output provided.
 
@@ -114,8 +166,15 @@ Functions
     :param nout:
         The number of outputs
 
+    :param identity:
+
+        Either :c:data:`PyUFunc_One`, :c:data:`PyUFunc_Zero`,
+        :c:data:`PyUFunc_None`. This specifies what should be returned when
+        an empty array is passed to the reduce method of the ufunc.
+
     :param name:
-        The name for the ufunc.  Specifying a name of 'add' or
+        The name for the ufunc as a ``NULL`` terminated string.
+        Specifying a name of 'add' or
         'multiply' enables a special behavior for  integer-typed
         reductions when no dtype is given.  If the input type is an
         integer (or boolean) data type smaller than the size of the