1 files changed, 35 insertions, 6 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 26711f177..b6ace230f 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -1,10 +1,14 @@
-# This is only meant to add docs to objects defined in C-extension modules.
-# The purpose is to allow easier editing of the docstrings without
-# requiring a re-compile.
+"""
+This is only meant to add docs to objects defined in C-extension modules.
+The purpose is to allow easier editing of the docstrings without
+requiring a re-compile.
 
-# NOTE: Many of the methods of ndarray have corresponding functions.
-#       If you update these docstrings, please keep also the ones in
-#       core/fromnumeric.py, core/defmatrix.py up-to-date.
+NOTE: Many of the methods of ndarray have corresponding functions.
+      If you update these docstrings, please keep also the ones in
+      core/fromnumeric.py, core/defmatrix.py up-to-date.
+
+"""
+from __future__ import division
 
 from numpy.lib import add_newdoc
 
@@ -4460,6 +4464,15 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('view',
     (same shape, dtype, etc.)  This does not cause a reinterpretation of the
     memory.
 
+    For ``a.view(some_dtype)``, if ``some_dtype`` has a different number of
+    bytes per entry than the previous dtype (for example, converting a
+    regular array to a structured array), then the behavior of the view
+    cannot be predicted just from the superficial appearance of ``a`` (shown
+    by ``print(a)``). It also depends on exactly how ``a`` is stored in
+    memory. Therefore if ``a`` is C-ordered versus fortran-ordered, versus
+    defined as a slice or transpose, etc., the view may give different
+    results.
+
 
     Examples
     --------
@@ -4501,6 +4514,22 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('view',
     >>> z[0]
     (9, 10)
 
+    Views that change the dtype size (bytes per entry) should normally be
+    avoided on arrays defined by slices, transposes, fortran-ordering, etc.:
+
+    >>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
+    >>> y = x[:, 0:2]
+    >>> y
+    array([[1, 2],
+           [4, 5]], dtype=int16)
+    >>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    ValueError: new type not compatible with array.
+    >>> z = y.copy()
+    >>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
+    array([[(1, 2)],
+           [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])
     """))