Extend docstrings of dunder methods, so autodoc table looks reasonable.

Author: rgommers

spec/API_specification/dataframe_api/dataframe_object.py

@@ -165,6 +165,8 @@ def set_column(self, label: str, value: Column) -> DataFrame:
 
     def __eq__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Compare for equality.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -180,6 +182,8 @@ def __eq__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __ne__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Compare for non-equality.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -195,6 +199,8 @@ def __ne__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __ge__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Compare for "greater than or equal to" `other`.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -210,6 +216,8 @@ def __ge__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __gt__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Compare for "greater than" `other`.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -225,6 +233,8 @@ def __gt__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __le__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Compare for "less than or equal to" `other`.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -240,6 +250,8 @@ def __le__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __lt__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Compare for "less than" `other`.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -255,6 +267,8 @@ def __lt__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __add__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Add `other` dataframe or scalar to this dataframe.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -270,6 +284,8 @@ def __add__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __sub__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Subtract `other` dataframe or scalar from this dataframe.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -285,6 +301,8 @@ def __sub__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __mul__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Multiply  `other` dataframe or scalar with this dataframe.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -300,6 +318,8 @@ def __mul__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __truediv__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Divide  this dataframe by `other` dataframe or scalar. True division, returns floats.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -315,6 +335,8 @@ def __truediv__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __floordiv__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Floor-divide (returns integers) this dataframe by `other` dataframe or scalar.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -330,6 +352,8 @@ def __floordiv__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __pow__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Raise this dataframe to the power of `other`.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -345,6 +369,8 @@ def __pow__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __mod__(self, other: DataFrame | "Scalar") -> DataFrame:
         """
+        Return modulus of this dataframe by `other` (`%` operator).
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -360,6 +386,8 @@ def __mod__(self, other: DataFrame | "Scalar") -> DataFrame:
 
     def __divmod__(self, other: DataFrame | "Scalar") -> tuple[DataFrame, DataFrame]:
         """
+        Return quotient and remainder of integer division. See `divmod` builtin function.
+
         Parameters
         ----------
         other : DataFrame or Scalar
@@ -369,8 +397,7 @@ def __divmod__(self, other: DataFrame | "Scalar") -> tuple[DataFrame, DataFrame]
 
         Returns
         -------
-        DataFrame
-        DataFrame
+        A tuple of two DataFrame's
         """
         ...
 

spec/API_specification/dataframe_object.rst

@@ -59,6 +59,11 @@ an array object supporting the following Python arithmetic operators.
 
 Arithmetic operators should be defined for a dataframe having real-valued data types.
 
+.. note::
+
+   TODO: figure out whether we want to add ``__neg__`` and ``__pos__``, those
+   are the two missing arithmetic operators.
+
 
 Comparison Operators
 ~~~~~~~~~~~~~~~~~~~~