clearer examples and PEP8, linting fixes

Author: tm9k1

pandas/core/series.py

@@ -2281,47 +2281,61 @@ def _binop(self, other, func, level=None, fill_value=None):
 
     def combine(self, other, func, fill_value=None):
         """
-        Combine the Series with a `Series` or `Scalar` according to `func`.
+        Combine the Series with a Series or Scalar according to `func`.
 
         Perform elementwise binary operation on two Series using given function
-        with optional fill value when an index is missing from one Series or
-        the other.
+        with optional `fill_value` when an index is missing from the Series or
+        the other value.
 
         Parameters
         ----------
-        other : Series or scalar value
+        other : Series or Scalar
             The value(s) to be combined with the `Series`.
-        func : function
-            Function that takes two scalars as inputs and return a scalar.
-        fill_value : scalar value
+        func : Function
+            `function` that takes two Scalars as inputs and returns a `bool`.
+        fill_value : Scalar
             The optional value to assume when an index
             is missing from one Series or the other,
             The default specifies to use the appropriate NaN value for
             the underlying dtype of the Series.
 
         Returns
         -------
-        result : the combined `Series` object
+        A Series object.
 
         Examples
         --------
-        >>> s1 = pd.Series([1, 2])
-        >>> s2 = pd.Series([0, 3, 4])
+        >>> import pandas as pd
+        >>> s1 = pd.Series([1,2])
+        >>> s2 = pd.Series([0,3])
         >>> s1.combine(s2, lambda x1, x2: x1 if x1 < x2 else x2)
         0    0
         1    2
+        dtype: int64
+
+        >>> s2 = pd.Series([0,3,4])
+        >>> s1.combine(s2, lambda x1, x2: x1 if x1 > x2 else x2)
+        0    1
+        1    3
         2    4
         dtype: int64
-        >>> s1.combine(s2, lambda x1, x2: x1 if x1 > x2 else x2,fill_value=787)
+
+        When fill_value is given:-
+
+        >>> s1.combine(s2, lambda x1, x2: x1 if x1 > x2 else x2,
+        ...             fill_value = 787)
         0      1
         1      3
         2    787
         dtype: int64
 
+        If `func` doesn't get a value from either of the two Series,
+        fill_value` is used.
+
         See Also
         --------
         Series.combine_first : Combine Series values, choosing the calling
-            Series's values first.
+                                Series' values first
         """
         if fill_value is None:
             fill_value = na_value_for_dtype(self.dtype, compat=False)