DOC: updated (Series/DataFrame).combine_first doc strings (pandas-dev#18266)

Author: topper-123

pandas/core/frame.py

@@ -4125,16 +4125,24 @@ def combine_first(self, other):
         ----------
         other : DataFrame
 
+        Returns
+        -------
+        combined : DataFrame
+
         Examples
         --------
-        a's values prioritized, use values from b to fill holes:
-
-        >>> a.combine_first(b)
+        df1's values prioritized, use values from df2 to fill holes:
 
+        >>> df1 = pd.DataFrame([[1, np.nan]])
+        >>> df2 = pd.DataFrame([[3, 4]])
+        >>> df1.combine_first(df2)
+           0    1
+        0  1  4.0
 
-        Returns
-        -------
-        combined : DataFrame
+        See Also
+        --------
+        DataFrame.combine : Perform series-wise operation on two DataFrames
+            using a given function
         """
         import pandas.core.computation.expressions as expressions
 

pandas/core/series.py

@@ -1764,7 +1764,21 @@ def combine_first(self, other):
 
         Returns
         -------
-        y : Series
+        combined : Series
+
+        Examples
+        --------
+        >>> s1 = pd.Series([1, np.nan])
+        >>> s2 = pd.Series([3, 4])
+        >>> s1.combine_first(s2)
+        0    1.0
+        1    4.0
+        dtype: float64
+
+        See Also
+        --------
+        Series.combine : Perform elementwise operation on two Series
+            using a given function
         """
         new_index = self.index.union(other.index)
         this = self.reindex(new_index, copy=False)