DOC: improve binary operator docs (fixes #10093)

Author: mortada

pandas/core/ops.py

@@ -703,12 +703,31 @@ def _radd_compat(left, right):
 
     return output
 
+_op_descriptions = {'add': 'addition',
+                    'radd': 'addition in the reverse order of operands compared to add',
+                    'sub': 'subtraction',
+                    'rsub': 'subtraction in the reverse order of operands compared to sub',
+                    'mul': 'multiplication',
+                    'rmul': 'multiplication in the reverse order of operands compared to mul',
+                    'mod': 'modulo',
+                    'rmod': 'modulo in the reverse order of operands compared to mod',
+                    'pow': 'exponential power',
+                    'rpow': 'exponential power in the reverse order of operands compared to pow',
+                    'truediv': 'floating division',
+                    'rtruediv': 'floating division in the reverse order of operands compared to truediv',
+                    'floordiv': 'integer division',
+                    'rfloordiv': 'integer division in the reverse order of operands compared to floordiv'}
 
 def _flex_method_SERIES(op, name, str_rep, default_axis=None,
                         fill_zeros=None, **eval_kwargs):
+    desc = name
+    if _op_descriptions.get(name):
+        desc = desc + ' (' + _op_descriptions.get(name) + ')'
+
     doc = """
-    Binary operator %s with support to substitute a fill_value for missing data
-    in one of the inputs
+    Binary operator %s.
+    This supports substituting a fill_value for missing data
+    in one of the inputs.
 
     Parameters
     ----------
@@ -723,7 +742,7 @@ def _flex_method_SERIES(op, name, str_rep, default_axis=None,
     Returns
     -------
     result : Series
-    """ % name
+    """ % desc
 
     @Appender(doc)
     def flex_wrapper(self, other, level=None, fill_value=None, axis=0):
@@ -754,7 +773,8 @@ def flex_wrapper(self, other, level=None, fill_value=None, axis=0):
 
 
 _arith_doc_FRAME = """
-Binary operator %s with support to substitute a fill_value for missing data in
+Binary operator %s.
+This supports substituting a fill_value for missing data in
 one of the inputs
 
 Parameters
@@ -813,7 +833,11 @@ def na_op(x, y):
 
         return result
 
-    @Appender(_arith_doc_FRAME % name)
+    desc = name
+    if _op_descriptions.get(name):
+        desc = desc + ' (' + _op_descriptions.get(name) + ')'
+
+    @Appender(_arith_doc_FRAME % desc)
     def f(self, other, axis=default_axis, level=None, fill_value=None):
         if isinstance(other, pd.DataFrame):    # Another DataFrame
             return self._combine_frame(other, na_op, fill_value, level)

pandas/core/panel.py

@@ -30,6 +30,8 @@
 import pandas.core.nanops as nanops
 import pandas.computation.expressions as expressions
 from pandas import lib
+from pandas.core.ops import _op_descriptions
+
 
 _shared_doc_kwargs = dict(
     axes='items, major_axis, minor_axis',
@@ -1437,7 +1439,7 @@ def _add_aggregate_operations(cls, use_numexpr=True):
 ----------
 other : %s or %s""" % (cls._constructor_sliced.__name__, cls.__name__) + """
 axis : {""" + ', '.join(cls._AXIS_ORDERS) + "}" + """
-Axis to broadcast over
+    Axis to broadcast over
 
 Returns
 -------
@@ -1459,7 +1461,10 @@ def na_op(x, y):
                 result = com._fill_zeros(result, x, y, name, fill_zeros)
                 return result
 
-            @Substitution(name)
+            desc = name
+            if _op_descriptions.get(name):
+                desc = desc + ' (' + _op_descriptions.get(name) + ')'
+            @Substitution(desc)
             @Appender(_agg_doc)
             def f(self, other, axis=0):
                 return self._combine(other, na_op, axis=axis)