Updated reference docs for DeprecationWarning

2 files changed, 14 insertions, 3 deletions

diff --git a/doc/source/reference/arrays.indexing.rst b/doc/source/reference/arrays.indexing.rst
index 8da4ecca7..bc12c5d0e 100644
--- a/doc/source/reference/arrays.indexing.rst
+++ b/doc/source/reference/arrays.indexing.rst
@@ -335,6 +335,16 @@ sub-array) but of data type ``x.dtype['field-name']`` and contains
 only the part of the data in the specified field. Also record array
 scalars can be "indexed" this way.
 
+Indexing into a record array can also be done with a list of field names,
+*e.g.* ``x[['field-name1','field-name2']]``. Currently this returns a new
+array containing a copy of the values in the fields specified in the list.
+As of NumPy 1.7, returning a copy is being deprecated in favor of returning
+a view. A copy will continue to be returned for now, but a DeprecationWarning
+will be issued when writing to the copy. If you depend on the current
+behavior, then we suggest copying the returned array explicitly, i.e. use
+x[['field-name1','field-name2']].copy(). This will work with both past and
+future versions of NumPy.
+
 If the accessed field is a sub-array, the dimensions of the sub-array
 are appended to the shape of the result.
 
diff --git a/numpy/core/src/multiarray/arrayobject.c b/numpy/core/src/multiarray/arrayobject.c
index 4a219e70e..f0e9e36a5 100644
--- a/numpy/core/src/multiarray/arrayobject.c
+++ b/numpy/core/src/multiarray/arrayobject.c
@@ -694,10 +694,11 @@ array_might_be_written(PyArrayObject *obj)
 {
     const char *msg =
         "Numpy has detected that you (may be) writing to an array returned\n"
-        "by numpy.diagonal or by selecting multiple fields in a structured\n"
+        "by numpy.diagonal or by selecting multiple fields in a record\n"
         "array. This code will likely break in the next numpy release --\n"
-        "see numpy.diagonal or structured array docs for details. The quick\n"
-        "fix is to make an explicit copy (e.g., do arr.diagonal().copy()).";
+        "see numpy.diagonal or arrays.indexing reference docs for details.\n"
+        "The quick fix is to make an explicit copy (e.g., do\n"
+        "arr.diagonal().copy() or arr[['f0','f1']].copy()).";
     if (PyArray_FLAGS(obj) & NPY_ARRAY_WARN_ON_WRITE) {
         if (DEPRECATE_FUTUREWARNING(msg) < 0) {
             return -1;