Merge pull request #18339 from melissawm/matmul_docs

DOC: Discussion on the @ operator and the matrix class

4 files changed, 22 insertions, 6 deletions

diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst
index 3a4ed2168..92c271f6b 100644
--- a/doc/source/reference/arrays.classes.rst
+++ b/doc/source/reference/arrays.classes.rst
@@ -330,6 +330,8 @@ NumPy provides several hooks that classes can customize:
    returned by :func:`__array__`. This practice will return ``TypeError``.
 
 
+.. _matrix-objects:
+
 Matrix objects
 ==============
 
diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst
index 191367058..f2204752d 100644
--- a/doc/source/reference/arrays.ndarray.rst
+++ b/doc/source/reference/arrays.ndarray.rst
@@ -567,10 +567,8 @@ Matrix Multiplication:
 .. note::
 
    Matrix operators ``@`` and ``@=`` were introduced in Python 3.5
-   following PEP465. NumPy 1.10.0 has a preliminary implementation of ``@``
-   for testing purposes. Further documentation can be found in the
-   :func:`matmul` documentation.
-
+   following :pep:`465`, and the ``@`` operator has been introduced in NumPy
+   1.10.0. Further information can be found in the :func:`matmul` documentation.
 
 Special methods
 ===============
diff --git a/doc/source/reference/routines.linalg.rst b/doc/source/reference/routines.linalg.rst
index 86e168b26..76b7ab82c 100644
--- a/doc/source/reference/routines.linalg.rst
+++ b/doc/source/reference/routines.linalg.rst
@@ -30,10 +30,26 @@ flexible broadcasting options.  For example, `numpy.linalg.solve` can handle
 "stacked" arrays, while `scipy.linalg.solve` accepts only a single square
 array as its first argument.
 
+.. note::
+
+   The term *matrix* as it is used on this page indicates a 2d `numpy.array`
+   object, and *not* a `numpy.matrix` object. The latter is no longer
+   recommended, even for linear algebra. See
+   :ref:`the matrix object documentation<matrix-objects>` for
+   more information.
+
+The ``@`` operator
+------------------
+
+Introduced in NumPy 1.10.0, the ``@`` operator is preferable to
+other methods when computing the matrix product between 2d arrays. The
+:func:`numpy.matmul` function implements the ``@`` operator.
+
 .. currentmodule:: numpy
 
 Matrix and vector products
 --------------------------
+
 .. autosummary::
    :toctree: generated/
 
diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py
index 04181fbc2..2f75cb41f 100644
--- a/numpy/core/code_generators/ufunc_docstrings.py
+++ b/numpy/core/code_generators/ufunc_docstrings.py
@@ -2808,8 +2808,8 @@ add_newdoc('numpy.core.umath', 'matmul',
       (9, 5, 7, 3)
       >>> # n is 7, k is 4, m is 3
 
-    The matmul function implements the semantics of the `@` operator introduced
-    in Python 3.5 following PEP465.
+    The matmul function implements the semantics of the ``@`` operator introduced
+    in Python 3.5 following :pep:`465`.
 
     Examples
     --------