Document the PyArray_Diagonal transition scheme.

1 files changed, 5 insertions, 2 deletions

diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
index 2b518aeae..eab8f867a 100644
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -223,12 +223,15 @@ def diag(v, k=0):
     """
     Extract a diagonal or construct a diagonal array.
 
-    As of NumPy 1.7, extracting a diagonal always returns a view into `v`.
+    See the more detailed documentation for ``numpy.diagonal`` if you use this
+    function to extract a diagonal and wish to write to the resulting array;
+    whether it returns a copy or a view depends on what version of numpy you
+    are using.
 
     Parameters
     ----------
     v : array_like
-        If `v` is a 2-D array, return a view of its `k`-th diagonal.
+        If `v` is a 2-D array, return a copy of its `k`-th diagonal.
         If `v` is a 1-D array, return a 2-D array with `v` on the `k`-th
         diagonal.
     k : int, optional