DOC: Update docs.

Update docs for boolean array indexing and nonzero order.
Add links to row-major and column-major terms where they appear.

Closes #3177

1 files changed, 27 insertions, 22 deletions

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 5f96b1d61..b6a28ec9b 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1370,8 +1370,7 @@ def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):
 
 
 def ravel(a, order='C'):
-    """
-    Return a flattened array.
+    """Return a flattened array.
 
     A 1-D array, containing the elements of the input, is returned.  A copy is
     made only if needed.
@@ -1386,18 +1385,21 @@ def ravel(a, order='C'):
         Input array.  The elements in `a` are read in the order specified by
         `order`, and packed as a 1-D array.
     order : {'C','F', 'A', 'K'}, optional
-        The elements of `a` are read using this index order. 'C' means to
-        index the elements in C-like order, with the last axis index changing
-        fastest, back to the first axis index changing slowest.   'F' means to
-        index the elements in Fortran-like index order, with the first index
-        changing fastest, and the last index changing slowest. Note that the
-        'C' and 'F' options take no account of the memory layout of the
-        underlying array, and only refer to the order of axis indexing.
-        'A' means to read the elements in Fortran-like index order if `a` is
-        Fortran *contiguous* in memory, C-like order otherwise.  'K' means to
-        read the elements in the order they occur in memory, except for
-        reversing the data when strides are negative.  By default, 'C' index
-        order is used.
+
+        The elements of `a` are read using this index order. 'C' means
+        to index the elements in row-major, C-style order,
+        with the last axis index changing fastest, back to the first
+        axis index changing slowest.  'F' means to index the elements
+        in column-major, Fortran-style order, with the
+        first index changing fastest, and the last index changing
+        slowest. Note that the 'C' and 'F' options take no account of
+        the memory layout of the underlying array, and only refer to
+        the order of axis indexing.  'A' means to read the elements in
+        Fortran-like index order if `a` is Fortran *contiguous* in
+        memory, C-like order otherwise.  'K' means to read the
+        elements in the order they occur in memory, except for
+        reversing the data when strides are negative.  By default, 'C'
+        index order is used.
 
     Returns
     -------
@@ -1415,11 +1417,12 @@ def ravel(a, order='C'):
 
     Notes
     -----
-    In C-like (row-major) order, in two dimensions, the row index varies the
-    slowest, and the column index the quickest.  This can be generalized to
-    multiple dimensions, where row-major order implies that the index along the
-    first axis varies slowest, and the index along the last quickest.  The
-    opposite holds for Fortran-like, or column-major, index ordering.
+    In row-major, C-style order, in two dimensions, the row index
+    varies the slowest, and the column index the quickest.  This can
+    be generalized to multiple dimensions, where row-major order
+    implies that the index along the first axis varies slowest, and
+    the index along the last quickest.  The opposite holds for
+    column-major, Fortran-style index ordering.
 
     Examples
     --------
@@ -1473,9 +1476,11 @@ def nonzero(a):
     """
     Return the indices of the elements that are non-zero.
 
-    Returns a tuple of arrays, one for each dimension of `a`, containing
-    the indices of the non-zero elements in that dimension. The
-    corresponding non-zero values can be obtained with::
+    Returns a tuple of arrays, one for each dimension of `a`,
+    containing the indices of the non-zero elements in that
+    dimension. The values in `a` are always tested and returned in
+    row-major, C-style order. The corresponding non-zero
+    values can be obtained with::
 
         a[nonzero(a)]