DOC: Document changes to diag, diagonal, ravel in 1.10-notes.rst.

The changes are that they all preserve ndarray subtypes with the
exception of ravel, which still return 1-D arrays for backward
compatibility.

1 files changed, 7 insertions, 5 deletions

diff --git a/doc/release/1.10.0-notes.rst b/doc/release/1.10.0-notes.rst
index 1fdbb84bd..6403283d1 100644
--- a/doc/release/1.10.0-notes.rst
+++ b/doc/release/1.10.0-notes.rst
@@ -41,11 +41,13 @@ NPY_RELAXED_STRIDE_CHECKING is now true by default.
 
 *np.ravel*, *np.diagonal* and *np.diag* now preserve subtypes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There was inconsistent behavior between *x.ravel()* and *np.ravel(x)*, as well
-as between *x.diagonal()* and *np.diagonal(x)*.  For example, if *x* was a
-matrix, then *x.ravel()* returned a matrix, while *np.ravel(x)* returned an
-ndarray.  In the case of matrices, the returned value will have different
-dimensions and that may lead to problems in using the result.
+There was inconsistent behavior between *x.ravel()* and *np.ravel(x)*, as
+well as between *x.diagonal()* and *np.diagonal(x)*, with the methods
+preserving subtypes while the functions did not. This has been fixed and
+the functions now behave like the methods, preserving subtypes except in
+the case of matrices.  Matrices are special cased for backward
+compatibility and still return 1-D arrays as before. If you need to
+preserve the matrix subtype, use the methods instead of the functions.
 
 
 New Features