STY: index_tricks: Improve comments and documentation strings

5 files changed, 63 insertions, 32 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 487ffef00..1a55b6bc7 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -4349,17 +4349,16 @@ add_newdoc('numpy.lib._compiled_base', 'ravel_coords',
     coords : tuple of array_like
         A tuple of integer arrays, one array for each dimension.
     dims : tuple of ints
-        The shape of an array into which indices from `coords` are for.
+        The shape of array into which the indices from ``coords`` apply.
     mode : {'raise', 'wrap', 'clip'}, optional
-        Specifies how out-of-bounds indices will behave.  Can specify
-        either one mode or a tuple of modes, with length matching that
-        of ``dims``.
+        Specifies how out-of-bounds indices are handled.  Can specify
+        either one mode or a tuple of modes, one mode per index.
 
         * 'raise' -- raise an error (default)
         * 'wrap' -- wrap around
         * 'clip' -- clip to the range
 
-        Note that in 'clip' mode, a negative index which would normally
+        In 'clip' mode, a negative index which would normally
         wrap will clip to 0 instead.
     order : {'C', 'F'}, optional
         Determines whether the coords should be viewed as indexing in
@@ -4368,13 +4367,17 @@ add_newdoc('numpy.lib._compiled_base', 'ravel_coords',
     Returns
     -------
     raveled_indices : ndarray
-        This is a new array with the same shape as the broadcast shape
-        of the arrays in ``coords``.
+        An array of indices into the flattened version of an array
+        of dimensions ``dims``.
 
     See Also
     --------
     unravel_index
 
+    Notes
+    -----
+    .. versionadded:: 1.6.0
+
     Examples
     --------
     >>> arr = np.array([[3,6,6],[4,5,1]])
@@ -4401,19 +4404,20 @@ add_newdoc('numpy.lib._compiled_base', 'unravel_index',
     Parameters
     ----------
     indices : array_like
-        An integer type array whose elements are indices for a
-        flattened array with shape `dims`.
+        An integer array whose elements are indices into the flattened
+        version of an array of dimensions ``dims``. Before version 1.6.0,
+        this function accepted just one index value.
     dims : tuple of ints
-        The shape of an array into which flattened indices from
-        ``indices`` are for.
+        The shape of the array to use for unravelling ``indices``.
     order : {'C', 'F'}, optional
+        .. versionadded:: 1.6.0
         Determines whether the indices should be viewed as indexing in
         C (row-major) order or FORTRAN (column-major) order.
 
     Returns
     -------
     unraveled_coords : tuple of ndarray
-        Each array in the tuple is the same shape as the input ``indices``
+        Each array in the tuple has the same shape as the ``indices``
         array.
 
     See Also
diff --git a/numpy/core/src/multiarray/ctors.c b/numpy/core/src/multiarray/ctors.c
index 010a1acb4..71bb75e6c 100644
--- a/numpy/core/src/multiarray/ctors.c
+++ b/numpy/core/src/multiarray/ctors.c
@@ -3726,4 +3726,3 @@ _array_fill_strides(npy_intp *strides, npy_intp *dims, int nd, size_t itemsize,
     }
     return itemsize;
 }
-
diff --git a/numpy/core/src/multiarray/multiarraymodule.c b/numpy/core/src/multiarray/multiarraymodule.c
index 507cd398c..b87baeef7 100644
--- a/numpy/core/src/multiarray/multiarraymodule.c
+++ b/numpy/core/src/multiarray/multiarraymodule.c
@@ -1313,43 +1313,51 @@ PyArray_ClipmodeConverter(PyObject *object, NPY_CLIPMODE *val)
 
 /*NUMPY_API
  * Convert an object to an array of n NPY_CLIPMODE values.
+ * This is intended to be used in functions where a different mode
+ * could be applied to each axis, like in ravel_coords.
  */
 NPY_NO_EXPORT int
-PyArray_ConvertClipmodeSequence(PyObject *object, NPY_CLIPMODE *vals, int n)
+PyArray_ConvertClipmodeSequence(PyObject *object, NPY_CLIPMODE *modes, int n)
 {
     int i;
     /* Get the clip mode(s) */
-    if(object && (PyTuple_Check(object) || PyList_Check(object))) {
+    if (object && (PyTuple_Check(object) || PyList_Check(object))) {
         if (PySequence_Size(object) != n) {
             PyErr_Format(PyExc_ValueError,
                     "list of clipmodes has wrong length (%d instead of %d)",
                     (int)PySequence_Size(object), n);
             return PY_FAIL;
         }
+
         for (i = 0; i < n; ++i) {
             PyObject *item = PySequence_GetItem(object, i);
             if(item == NULL) {
                 return PY_FAIL;
             }
-            if(PyArray_ClipmodeConverter(item, &vals[i]) != PY_SUCCEED) {
+
+            if(PyArray_ClipmodeConverter(item, &modes[i]) != PY_SUCCEED) {
                 Py_DECREF(item);
                 return PY_FAIL;
             }
+
             Py_DECREF(item);
         }
-    } else if(PyArray_ClipmodeConverter(object, &vals[0]) == PY_SUCCEED) {
-        for(i = 1; i < n; ++i) {
-            vals[i] = vals[0];
+    }
+    else if (PyArray_ClipmodeConverter(object, &modes[0]) == PY_SUCCEED) {
+        for (i = 1; i < n; ++i) {
+            modes[i] = modes[0];
         }
-    } else {
+    }
+    else {
         return PY_FAIL;
     }
     return PY_SUCCEED;
 }
 
 /*
- * compare the field dictionary for two types
- * return 1 if the same or 0 if not
+ * Compare the field dictionaries for two types.
+ *
+ * Return 1 if the contents are the same, 0 if not.
  */
 static int
 _equivalent_fields(PyObject *field1, PyObject *field2) {
diff --git a/numpy/core/src/multiarray/new_iterator.c.src b/numpy/core/src/multiarray/new_iterator.c.src
index 931cb0339..1208e5d3c 100644
--- a/numpy/core/src/multiarray/new_iterator.c.src
+++ b/numpy/core/src/multiarray/new_iterator.c.src
@@ -2316,9 +2316,16 @@ NpyIter_GetIterIndexRange(NpyIter *iter,
 }
 
 /*NUMPY_API
- * Gets the broadcast shape if coords are enabled, otherwise
- * gets the shape of the iteration as Fortran-order (fastest-changing
- * coordinate first)
+ * Gets the broadcast shape if coords are being tracked by the iterator,
+ * otherwise gets the shape of the iteration as Fortran-order
+ * (fastest-changing coordinate first).
+ *
+ * The reason Fortran-order is returned when coords
+ * are not enabled is that this is providing a direct view into how
+ * the iterator traverses the n-dimensional space. The iterator organizes
+ * its memory from fastest coordinate to slowest coordinate, and when
+ * coords are enabled, it uses a permutation to recover the original
+ * order.
  *
  * Returns NPY_SUCCEED or NPY_FAIL.
  */
@@ -2361,15 +2368,15 @@ NpyIter_GetShape(NpyIter *iter, npy_intp *outshape)
 }
 
 /*NUMPY_API
- * Builds a set of strides which are compatible with the iteration order
- * for data packed contiguously, but not necessarily C or Fortran.
- * The strides this produces are equivalent to the strides for an
- * automatically allocated output created without an op_axes parameter,
- * and should be used together with NpyIter_GetShape and NpyIter_GetNDim.
+ * Builds a set of strides which are the same as the strides of an
+ * output array created using the NPY_ITER_ALLOCATE flag, where NULL
+ * was passed for op_axes.  This is for data packed contiguously,
+ * but not necessarily in C or Fortran order. This should be used
+ * together with NpyIter_GetShape and NpyIter_GetNDim.
  *
  * A use case for this function is to match the shape and layout of
  * the iterator and tack on one or more dimensions.  For example,
- * if you want to generate a vector per input value for a numerical gradient,
+ * in order to generate a vector per input value for a numerical gradient,
  * you pass in ndim*itemsize for itemsize, then add another dimension to
  * the end with size ndim and stride itemsize.  To do the Hessian matrix,
  * you do the same thing but add two dimensions, or take advantage of
@@ -2403,7 +2410,7 @@ NpyIter_CreateCompatibleStrides(NpyIter *iter,
                 "if coordinates are being tracked");
         return NPY_FAIL;
     }
-    
+
     axisdata = NIT_AXISDATA(iter);
     sizeof_axisdata = NIT_AXISDATA_SIZEOF(itflags, ndim, niter);
 
diff --git a/numpy/lib/src/_compiled_base.c b/numpy/lib/src/_compiled_base.c
index a7a736254..bca2426e6 100644
--- a/numpy/lib/src/_compiled_base.c
+++ b/numpy/lib/src/_compiled_base.c
@@ -565,6 +565,14 @@ fail:
     return NULL;
 }
 
+/*
+ * Converts a Python sequence into 'count' PyArrayObjects
+ *
+ * seq       - Input Python object, usually a tuple but any sequence works.
+ * op        - Where the arrays are placed.
+ * count     - How many arrays there should be (errors if it doesn't match).
+ * paramname - The name of the parameter that produced 'seq'.
+ */
 static int sequence_to_arrays(PyObject *seq,
                                 PyArrayObject **op, int count,
                                 char *paramname)
@@ -604,6 +612,7 @@ static int sequence_to_arrays(PyObject *seq,
     return 0;
 }
 
+/* Inner loop for unravel_index */
 static int
 ravel_coords_loop(int ravel_ndim, npy_intp *ravel_dims,
                         npy_intp *ravel_strides,
@@ -665,6 +674,7 @@ ravel_coords_loop(int ravel_ndim, npy_intp *ravel_dims,
     return NPY_SUCCEED;
 }
 
+/* ravel_coords implementation - see add_newdocs.py */
 static PyObject *
 arr_ravel_coords(PyObject *self, PyObject *args, PyObject *kwds)
 {
@@ -802,6 +812,7 @@ fail:
     return NULL;
 }
 
+/* C-order inner loop for unravel_index */
 static int
 unravel_index_loop_corder(int unravel_ndim, npy_intp *unravel_dims,
                         npy_intp unravel_size, npy_intp count,
@@ -829,6 +840,7 @@ unravel_index_loop_corder(int unravel_ndim, npy_intp *unravel_dims,
     return NPY_SUCCEED;
 }
 
+/* Fortran-order inner loop for unravel_index */
 static int
 unravel_index_loop_forder(int unravel_ndim, npy_intp *unravel_dims,
                         npy_intp unravel_size, npy_intp count,
@@ -855,6 +867,7 @@ unravel_index_loop_forder(int unravel_ndim, npy_intp *unravel_dims,
     return NPY_SUCCEED;
 }
 
+/* unravel_index implementation - see add_newdocs.py */
 static PyObject *
 arr_unravel_index(PyObject *self, PyObject *args, PyObject *kwds)
 {