DOC: Updating operators docstrings

pandas/core/ops.py

@@ -493,28 +493,23 @@ def _get_op_name(op, special):
     # Comparison Operators
     'eq': {'op': '==',
            'desc': 'Equal to',
-           'reverse': None,
-           'df_examples': None},
+           'reverse': None},
     'ne': {'op': '!=',
            'desc': 'Not equal to',
-           'reverse': None,
-           'df_examples': None},
+           'reverse': None},
     'lt': {'op': '<',
            'desc': 'Less than',
-           'reverse': None,
-           'df_examples': None},
+           'reverse': None},
     'le': {'op': '<=',
            'desc': 'Less than or equal to',
-           'reverse': None,
-           'df_examples': None},
+           'reverse': None},
     'gt': {'op': '>',
            'desc': 'Greater than',
-           'reverse': None,
-           'df_examples': None},
+           'reverse': None},
     'ge': {'op': '>=',
            'desc': 'Greater than or equal to',
-           'reverse': None,
-           'df_examples': None}}
+           'reverse': None}
+}
 
 _op_names = list(_op_descriptions.keys())
 for key in _op_names:
@@ -640,6 +635,139 @@ def _get_op_name(op, special):
 DataFrame.{reverse}
 """
 
+_flex_comp_doc_FRAME = """
+{desc} of dataframe and other, element-wise (binary operator `{op_name}`).
+
+Among flexible wrappers (`eq`, `ne`, `le`, `lt`, `ge`, `gt`) to comparison
+operators.
+
+Equivalent to `==`, `=!`, `<=`, `<`, `>=`, `>` with support to choose axis
+(rows or columns) and level for comparison.
+
+Parameters
+----------
+other : scalar, sequence, Series, or DataFrame
+    Any single or multiple element data structure, or list-like object.
+axis :  {{0 or 'index', 1 or 'columns'}}, default 'columns'
+    Whether to compare by the index (0 or 'index') or columns
+    (1 or 'columns').
+level : int or object
+    Broadcast across a level, matching Index values on the passed
+    MultiIndex level.
+
+Returns
+-------
+DataFrame of bool
+    Result of the comparison.
+
+See Also
+--------
+DataFrame.eq : Compare DataFrames for equality elementwise
+DataFrame.ne : Compare DataFrames for inequality elementwise
+DataFrame.le : Compare DataFrames for less than inequality
+    or equality elementwise
+DataFrame.lt : Compare DataFrames for strictly less than
+    inequality elementwise
+DataFrame.ge : Compare DataFrames for greater than inequality
+    or equality elementwise
+DataFrame.gt : Compare DataFrames for strictly greater than
+    inequality elementwise
+
+Notes
+--------
+Mismatched indices will be unioned together.
+`NaN` values are considered different (i.e. `NaN` != `NaN`).
+
+Examples
+--------
+>>> df = pd.DataFrame({{'cost': [250, 150, 100],
+...                    'revenue': [100, 250, 300]}},
+...                    index = ['A', 'B', 'C'])
+>>> df
+   cost  revenue
+A   250      100
+B   150      250
+C   100      300
+
+Compare to a scalar and operator version which return the same
+results.
+
+>>> df == 100
+    cost  revenue
+A  False     True
+B  False    False
+C   True    False
+>>> df.eq(100)
+    cost  revenue
+A  False     True
+B  False    False
+C   True    False
+
+Compare to a list and Series by axis and operator version.
+
+>>> df != [100, 250, 300]
+   cost  revenue
+A  True    False
+B  True    False
+C  True    False
+>>> df.ne([100, 250, 300], axis='index')
+  cost  revenue
+A  True    False
+B  True    False
+C  True    False
+>>> df != pd.Series([100, 250, 300])
+   cost  revenue     0     1     2
+A  True     True  True  True  True
+B  True     True  True  True  True
+C  True     True  True  True  True
+>>> df.ne(pd.Series([100, 250, 300]), axis='columns')
+   cost  revenue     0     1     2
+A  True     True  True  True  True
+B  True     True  True  True  True
+C  True     True  True  True  True
+
+Compare to a DataFrame of different shape.
+
+>>> other = pd.DataFrame({{'revenue': [300, 250, 100, 150]}},
+...                       index = ['A', 'B', 'C', 'D'])
+>>> other
+   revenue
+A      300
+B      250
+C      100
+D      150
+>>> df.gt(other)
+    cost  revenue
+A  False    False
+B  False    False
+C  False     True
+D  False    False
+
+Compare to a MultiIndex by level.
+
+>>> df_multindex = pd.DataFrame({{'cost': [250, 150, 100, 150, 300, 220],
+...                              'revenue': [100, 250, 300, 200, 175, 225]}},
+...                              index = [['Q1', 'Q1', 'Q1', 'Q2', 'Q2', 'Q2'],
+...                                       ['A', 'B', 'C', 'A', 'B' ,'C']])
+>>> df_multindex
+      cost  revenue
+Q1 A   250      100
+   B   150      250
+   C   100      300
+Q2 A   150      200
+   B   300      175
+   C   220      225
+
+>>> df.le(df_multindex, level=1)
+       cost  revenue
+Q1 A   True     True
+   B   True     True
+   C   True     True
+Q2 A  False     True
+   B   True    False
+   C   True    False
+"""
+
 _flex_doc_PANEL = """
 {desc} of series and other, element-wise (binary operator `{op_name}`).
 Equivalent to ``{equiv}``.
@@ -1764,8 +1892,10 @@ def na_op(x, y):
             result = mask_cmp_op(x, y, op, (np.ndarray, ABCSeries))
         return result
 
-    @Appender('Wrapper for flexible comparison methods {name}'
-              .format(name=op_name))
+    doc = _flex_comp_doc_FRAME.format(op_name=op_name,
+                                      desc=_op_descriptions[op_name]['desc'])
+
+    @Appender(doc)
     def f(self, other, axis=default_axis, level=None):
 
         other = _align_method_FRAME(self, other, axis)