Merge pull request #9920 from xuhdev/dot-doc

DOC: dot: Add explanation in case `b` has only 1 dimension.

1 files changed, 15 insertions, 5 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index eba532735..6982bf689 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -1928,12 +1928,22 @@ add_newdoc('numpy.core', 'dot',
     """
     dot(a, b, out=None)
 
-    Dot product of two arrays.
+    Dot product of two arrays. Specifically,
+
+    - If both `a` and `b` are 1-D arrays, it is inner product of vectors
+      (without complex conjugation).
+
+    - If both `a` and `b` are 2-D arrays, it is matrix multiplication,
+      but using :func:`matmul` or ``a @ b`` is preferred.
+
+    - If either `a` or `b` is 0-D (scalar), it is equivalent to :func:`multiply`
+      and using ``numpy.multiply(a, b)`` or ``a * b`` is preferred.
+
+    - If `a` is an N-D array and `b` is a 1-D array, it is a sum product over
+      the last axis of `a` and `b`.
 
-    For 2-D arrays it is equivalent to matrix multiplication, and for 1-D
-    arrays to inner product of vectors (without complex conjugation). For
-    N dimensions it is a sum product over the last axis of `a` and
-    the second-to-last of `b`::
+    - If `a` is an N-D array and `b` is an M-D array (where ``M>=2``), it is a
+      sum product over the last axis of `a` and the second-to-last axis of `b`::
 
         dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m])