From 94b1a121ebadef5b65f8ff2494333fc26378fe69 Mon Sep 17 00:00:00 2001
From: tp <terji78@yaho.com>
Date: Mon, 13 Nov 2017 20:10:33 +0000
Subject: [PATCH] updated (Series/DataFrame).combine doc strings

---
 pandas/core/frame.py  | 17 ++++++++++++++++-
 pandas/core/series.py | 15 +++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index f3137c1edf2af..a7f8049a53af8 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -4029,6 +4029,8 @@ def combine(self, other, func, fill_value=None, overwrite=True):
         ----------
         other : DataFrame
         func : function
+            Function that takes two series as inputs and return a Series or a
+            scalar
         fill_value : scalar value
         overwrite : boolean, default True
             If True then overwrite values for common keys in the calling frame
@@ -4036,8 +4038,21 @@ def combine(self, other, func, fill_value=None, overwrite=True):
         Returns
         -------
         result : DataFrame
-        """
 
+        Examples
+        --------
+        >>> df1 = DataFrame({'A': [0, 0], 'B': [4, 4]})
+        >>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
+        >>> df1.combine(df2, lambda s1, s2: s1 if s1.sum() < s2.sum() else s2)
+           A  B
+        0  0  3
+        1  0  3
+
+        See Also
+        --------
+        DataFrame.combine_first : Combine two DataFrame objects and default to
+            non-null values in frame calling the method
+        """
         other_idxlen = len(other.index)  # save for compare
 
         this, other = self.align(other, copy=False)
diff --git a/pandas/core/series.py b/pandas/core/series.py
index c9a72bb688270..1cac35d58d888 100644
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -1731,11 +1731,26 @@ def combine(self, other, func, fill_value=np.nan):
         ----------
         other : Series or scalar value
         func : function
+            Function that takes two scalars as inputs and return a scalar
         fill_value : scalar value
 
         Returns
         -------
         result : Series
+
+        Examples
+        --------
+        >>> s1 = Series([1, 2])
+        >>> s2 = Series([0, 3])
+        >>> s1.combine(s2, lambda x1, x2: x1 if x1 < x2 else x2)
+        0    0
+        1    2
+        dtype: int64
+
+        See Also
+        --------
+        Series.combine_first : Combine Series values, choosing the calling
+            Series's values first
         """
         if isinstance(other, Series):
             new_index = self.index.union(other.index)