DOC: Upgraded Docstring pandas.DataFrame.dot (#23024)

Author: HubertKl

pandas/core/frame.py

@@ -931,16 +931,70 @@ def __len__(self):
 
  def dot(self, other):
  """
- Matrix multiplication with DataFrame or Series objects. Can also be
- called using `self @ other` in Python >= 3.5.
+ Compute the matrix mutiplication between the DataFrame and other.
+
+ This method computes the matrix product between the DataFrame and the
+ values of an other Series, DataFrame or a numpy array.
+
+ It can also be called using ``self @ other`` in Python >= 3.5.
 
  Parameters
  ----------
- other : DataFrame or Series
+ other : Series, DataFrame or array-like
+ The other object to compute the matrix product with.
 
  Returns
  -------
- dot_product : DataFrame or Series
+ Series or DataFrame
+ If other is a Series, return the matrix product between self and
+ other as a Serie. If other is a DataFrame or a numpy.array, return
+ the matrix product of self and other in a DataFrame of a np.array.
+
+ See Also
+ --------
+ Series.dot: Similar method for Series.
+
+ Notes
+ -----
+ The dimensions of DataFrame and other must be compatible in order to
+ compute the matrix multiplication.
+
+ The dot method for Series computes the inner product, instead of the
+ matrix product here.
+
+ Examples
+ --------
+ Here we multiply a DataFrame with a Series.
+
+ >>> df = pd.DataFrame([[0, 1, -2, -1], [1, 1, 1, 1]])
+ >>> s = pd.Series([1, 1, 2, 1])
+ >>> df.dot(s)
+ 0 -4
+ 1 5
+ dtype: int64
+
+ Here we multiply a DataFrame with another DataFrame.
+
+ >>> other = pd.DataFrame([[0, 1], [1, 2], [-1, -1], [2, 0]])
+ >>> df.dot(other)
+ 0 1
+ 0 1 4
+ 1 2 2
+
+ Note that the dot method give the same result as @
+
+ >>> df @ other
+ 0 1
+ 0 1 4
+ 1 2 2
+
+ The dot method works also if other is an np.array.
+
+ >>> arr = np.array([[0, 1], [1, 2], [-1, -1], [2, 0]])
+ >>> df.dot(arr)
+ 0 1
+ 0 1 4
+ 1 2 2
  """
  if isinstance(other, (Series, DataFrame)):
  common = self.columns.union(other.index)