DOC: Discussion on the @ operator and the matrix class

1 files changed, 16 insertions, 0 deletions

diff --git a/doc/source/reference/routines.linalg.rst b/doc/source/reference/routines.linalg.rst
index 86e168b26..97bdf3974 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 ``@`` and ``@=`` operators are preferable to
+other methods when computing the matrix product between 2d arrays. The
+:func:`numpy.matmul` function implements the semantics of the ``@`` operator.
+
 .. currentmodule:: numpy
 
 Matrix and vector products
 --------------------------
+
 .. autosummary::
    :toctree: generated/