DOC: Further clarification of order argument in np.array.

Attempt to clarify the sometimes convoluted behavior of the various
order options 'K', 'A', 'C', 'F'.

1 files changed, 34 insertions, 24 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 269c17adf..46601b8ef 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -654,32 +654,36 @@ add_newdoc('numpy.core.multiarray', 'array',
     Parameters
     ----------
     object : array_like
-        An array, any object exposing the array interface, an
-        object whose __array__ method returns an array, or any
-        (nested) sequence.
+        An array, any object exposing the array interface, an object whose
+        __array__ method returns an array, or any (nested) sequence.
     dtype : data-type, optional
-        The desired data-type for the array.  If not given, then
-        the type will be determined as the minimum type required
-        to hold the objects in the sequence.  This argument can only
-        be used to 'upcast' the array.  For downcasting, use the
-        .astype(t) method.
+        The desired data-type for the array.  If not given, then the type will
+        be determined as the minimum type required to hold the objects in the
+        sequence.  This argument can only be used to 'upcast' the array.  For
+        downcasting, use the .astype(t) method.
     copy : bool, optional
-        If true (default), then the object is copied.  Otherwise, a copy
-        will only be made if __array__ returns a copy, if obj is a
-        nested sequence, or if a copy is needed to satisfy any of the other
-        requirements (`dtype`, `order`, etc.).
-    order : {'C', 'F', 'A', 'K'}, optional, default 'K'
-        Specify the order of the array.  If order is 'C', then the array
-        will be in C-contiguous order (last-index varies the fastest).
-        If order is 'F', then the returned array will be in
-        Fortran-contiguous order (first-index varies the fastest).
-        If ``copy=False``, and order is set to 'A' or 'K', nothing
-        is ensured about the memory layout of the output array.
-        If ``copy=True`` and
-            - Order is 'A', then the order of the output is C
-              unless the input is fortran-ordered.
-            - Order is 'K', then the memory layout of the returned array is
-              kept as close as possible to the original array.
+        If true (default), then the object is copied.  Otherwise, a copy will
+        only be made if __array__ returns a copy, if obj is a nested sequence,
+        or if a copy is needed to satisfy any of the other requirements
+        (`dtype`, `order`, etc.).
+    order : {'K', 'A', 'C', 'F'}, optional
+        Specify the memory layout of the array. If object is not an array, the
+        newly created array will be in C order (row major) unless 'F' is
+        specified, in which case it will be in Fortran order (column major).
+        If object is an array the following holds.
+
+        ===== ========= ===================================================
+        order  no copy                     copy=True
+        ===== ========= ===================================================
+        'K'   unchanged F & C order preserved, otherwise most similar order
+        'A'   unchanged F order if input is F and not C, otherwise C order
+        'C'   C order   C order
+        'F'   F order   F order
+        ===== ========= ===================================================
+
+        When ``copy=False`` and a copy is made for other reasons, the result is
+        the same as if ``copy=True``, with some exceptions for `A`, see the
+        Notes section. The default order is 'K'.
     subok : bool, optional
         If True, then sub-classes will be passed-through, otherwise
         the returned array will be forced to be a base-class array (default).
@@ -697,6 +701,12 @@ add_newdoc('numpy.core.multiarray', 'array',
     --------
     empty, empty_like, zeros, zeros_like, ones, ones_like, full, full_like
 
+    Notes
+    -----
+    When order is 'A' and `object` is an array in neither 'C' nor 'F' order,
+    and a copy is forced by a change in dtype, then the order of the result is
+    not necessarily 'C' as expected. This is likely a bug.
+
     Examples
     --------
     >>> np.array([1, 2, 3])