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,14 @@ 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))
+ if op_name in _op_descriptions:
+ op_desc = _op_descriptions[op_name]
+ doc = _flex_comp_doc_FRAME.format(desc=op_desc['desc'],
+ op_name=op_name)
+ else:
+ doc = "Flexible wrappers to comparison methods"
+
+ @Appender(doc)
  def f(self, other, axis=default_axis, level=None):
 
  other = _align_method_FRAME(self, other, axis)