DOC: Update ndarray.shape property documention.

[ci skip]

1 files changed, 14 insertions, 10 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index f81f6cb72..fd6fe277f 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -2926,14 +2926,13 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('shape',
     """
     Tuple of array dimensions.
 
-    As with `numpy.reshape`, one shape dimension can be -1. In this case, the value is
-    inferred from the length of the array and remaining dimensions.
-    Notes
-    -----
-    May be used to "reshape" the array, as long as this would not
-    require a change in the total number of elements
-    Using `numpy.reshape` or `ndarray.reshape` should always be preferred.
-    Setting the shape directly is not really a safe thing to do.
+    The shape property is usually used to get the current shape of an array,
+    but may also be used to reshape the array in-place by assigning a tuple of
+    array dimensions to it.  As with `numpy.reshape`, one of the new shape
+    dimensions can be -1, in which case its value is inferred from the size of
+    the array and the remaining dimensions. Reshaping an array in-place will
+    fail if a copy is required.
+
     Examples
     --------
     >>> x = np.array([1, 2, 3, 4])
@@ -2951,10 +2950,15 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('shape',
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
     ValueError: total size of new array must be unchanged
+    >>> np.zeros((4,2))[::2].shape = (-1,)
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    AttributeError: incompatible shape for a non-contiguous array
+
     See Also
     --------
-    numpy.reshape : equivalent function
-    ndarray.reshape : equivalent function
+    numpy.reshape : similar function
+    ndarray.reshape : similar method
 
     """))