DOC: update the DataFrame.combine and DataFrame.combine_first docstrings
State: closed


Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:
```
################################################################################
##################### Docstring (pandas.DataFrame.combine) #####################
################################################################################

Perform series-wise combine with `other` DataFrame using given `func`.

Combines `self` DataFrame with `other` DataFrame using `func`
to merge columns. The row and column indexes of the resulting
DataFrame will be the union of the two. If `fill_value` is
specified, that value will be filled prior to the call to
`func`. If `overwrite` is `False`, columns in `self` that
do not exist in `other` will be preserved.

Parameters
----------
other : DataFrame
    The DataFrame to merge column-wise.
func : function
    Function that takes two series as inputs and return a Series or a
    scalar, used to merge the two dataframes column by columns.
fill_value : scalar value, default None
    The value to fill NaNs with prior to passing any column to the
    merge func.
overwrite : boolean, default True
    If True, columns in `self` that do not exist in `other` will be
    overwritten with NaNs.

Returns
-------
result : DataFrame

Examples
--------
Combine using a simple function that chooses the smaller column.

>>> from pandas import DataFrame
>>> df1 = DataFrame({'A': [0, 0], 'B': [4, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
>>> take_smaller = lambda s1, s2: s1 if s1.sum() < s2.sum() else s2
>>> df1.combine(df2, take_smaller)
   A  B
0  0  3
1  0  3

Using `fill_value` fills Nones prior to passing the column to the
merge function.

>>> df1 = DataFrame({'A': [0, 0], 'B': [None, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
>>> df1.combine(df2, take_smaller, fill_value=-5)
   A  B
0  0  -5.0
1  0  4.0

However, if the same element in both dataframes is None, that None
is preserved

>>> df1 = DataFrame({'A': [0, 0], 'B': [None, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [None, 3]})
>>> df1.combine(df2, take_smaller, fill_value=-5)
   A  B
0  0  NaN
1  0  3.0

Example that demonstrates the use of `overwrite` and behavior when
the axis differ between the dataframes.

>>> df1 = DataFrame({'A': [0, 0], 'B': [4, 4]})
>>> df2 = DataFrame({'B': [3, 3], 'C': [-10, 1],}, index=[1, 2])
>>> df1.combine(df2, take_smaller)
   A    B    C
0  NaN  NaN  NaN
1  NaN  3.0  -10.0
2  NaN  3.0  1.0

>>> df1.combine(df2, take_smaller, overwrite=False)
   A    B    C
0  0.0  NaN  NaN
1  0.0  3.0  -10.0
2  NaN  3.0  1.0

Demonstrating the preference of the passed in dataframe.

>>> df2 = DataFrame({'B': [3, 3], 'C': [1, 1],}, index=[1, 2])
>>> df2.combine(df1, take_smaller)
   A    B   C
0  0.0  NaN NaN
1  0.0  3.0 NaN
2  NaN  3.0 NaN

>>> df2.combine(df1, take_smaller, overwrite=False)
   A    B   C
0  0.0  NaN NaN
1  0.0  3.0 1.0
2  NaN  3.0 1.0

See Also
--------
DataFrame.combine_first : Combine two DataFrame objects and default to
    non-null values in frame calling the method

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.combine" correct. :)

```

For `DataFrame.combine_first`
```

################################################################################
################## Docstring (pandas.DataFrame.combine_first) ##################
################################################################################

Update null elements with value in the same location in `other`.

Combine two DataFrame objects by filling null values in self DataFrame
with non-null values from other DataFrame. The row and column indexes
of the resulting DataFrame will be the union of the two.

Parameters
----------
other : DataFrame
    Provided DataFrame to use to fill null values.

Returns
-------
combined : DataFrame

Examples
--------

df1's values prioritized, use values from df2 to fill holes:

>>> from pandas import DataFrame
>>> df1 = DataFrame({'A': [None, 0], 'B': [None, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
>>> df1.combine_first(df2)
   A  B
0  1.0  3.0
1  0.0  4.0

Illustrate the behavior when the axis differ between the dataframes.

>>> df1 = DataFrame({'A': [None, 0], 'B': [4, None]})
>>> df2 = DataFrame({'B': [3, 3], 'C': [1, 1],}, index=[1, 2])
>>> df1.combine_first(df2)
   A    B    C
0  NaN  4.0  NaN
1  0.0  3.0  1.0
2  NaN  3.0  1.0

See Also
--------
DataFrame.combine : Perform series-wise operation on two DataFrames
    using a given function

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.combine_first" correct. :)


```


Labels:
name: Docs
name: Missing-data
description: np.nan, pd.NaT, pd.NA, dropna, isnull, interpolate

Comments:
Would to like to give recognition to @qshng who worked on this documentation with me.
The `validate_docstring` output for `DataFrame.combine`
```
################################################################################
##################### Docstring (pandas.DataFrame.combine) #####################
################################################################################

Perform series-wise combine with `other` DataFrame using given `func`.

Combines `self` DataFrame with `other` DataFrame using `func`
to element-wise combine columns. The row and column indexes of the
resulting DataFrame will be the union of the two.

Parameters
----------
other : DataFrame
    The DataFrame to merge column-wise.
func : function
    Function that takes two series as inputs and return a Series or a
    scalar, used to merge the two dataframes column by columns.
fill_value : scalar value, default None
    The value to fill NaNs with prior to passing any column to the
    merge func.
overwrite : boolean, default True
    If True, columns in `self` that do not exist in `other` will be
    overwritten with NaNs.

Returns
-------
result : DataFrame

Examples
--------
Combine using a simple function that chooses the smaller column.

>>> from pandas import DataFrame
>>> import numpy as np
>>> df1 = DataFrame({'A': [0, 0], 'B': [4, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
>>> take_smaller = lambda s1, s2: s1 if s1.sum() < s2.sum() else s2
>>> df1.combine(df2, take_smaller)
   A  B
0  0  3
1  0  3

Example  using a true element-wise combine function.

>>> import numpy as np
>>> df1 = DataFrame({'A': [5, 0], 'B': [2, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
>>> df1.combine(df2, np.minimum)
   A  B
0  1  2
1  0  3

Using `fill_value` fills Nones prior to passing the column to the
merge function.

>>> df1 = DataFrame({'A': [0, 0], 'B': [None, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
>>> df1.combine(df2, take_smaller, fill_value=-5)
   A    B
0  0 -5.0
1  0  4.0

However, if the same element in both dataframes is None, that None
is preserved

>>> df1 = DataFrame({'A': [0, 0], 'B': [None, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [None, 3]})
>>> df1.combine(df2, take_smaller, fill_value=-5)
   A    B
0  0  NaN
1  0  3.0

Example that demonstrates the use of `overwrite` and behavior when
the axis differ between the dataframes.

>>> df1 = DataFrame({'A': [0, 0], 'B': [4, 4]})
>>> df2 = DataFrame({'B': [3, 3], 'C': [-10, 1],}, index=[1, 2])
>>> df1.combine(df2, take_smaller)
     A    B     C
0  NaN  NaN   NaN
1  NaN  3.0 -10.0
2  NaN  3.0   1.0

>>> df1.combine(df2, take_smaller, overwrite=False)
     A    B     C
0  0.0  NaN   NaN
1  0.0  3.0 -10.0
2  NaN  3.0   1.0

Demonstrating the preference of the passed in dataframe.

>>> df2 = DataFrame({'B': [3, 3], 'C': [1, 1],}, index=[1, 2])
>>> df2.combine(df1, take_smaller)
   A    B   C
0  0.0  NaN NaN
1  0.0  3.0 NaN
2  NaN  3.0 NaN

>>> df2.combine(df1, take_smaller, overwrite=False)
     A    B   C
0  0.0  NaN NaN
1  0.0  3.0 1.0
2  NaN  3.0 1.0

See Also
--------
DataFrame.combine_first : Combine two DataFrame objects and default to
    non-null values in frame calling the method

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.combine" correct. :)
```

And for `combine_first`

```
################################################################################
################## Docstring (pandas.DataFrame.combine_first) ##################
################################################################################

Update null elements with value in the same location in `other`.

Combine two DataFrame objects by filling null values in self DataFrame
with non-null values from other DataFrame. The row and column indexes
of the resulting DataFrame will be the union of the two.

Parameters
----------
other : DataFrame
    Provided DataFrame to use to fill null values.

Returns
-------
combined : DataFrame

Examples
--------

df1's values prioritized, use values from df2 to fill holes:

>>> from pandas import DataFrame
>>> df1 = DataFrame({'A': [None, 0], 'B': [None, 4]})
>>> df2 = DataFrame({'A': [1, 1], 'B': [3, 3]})
>>> df1.combine_first(df2)
     A    B
0  1.0  3.0
1  0.0  4.0

Illustrate the behavior when the axis differ between the dataframes.

>>> df1 = DataFrame({'A': [None, 0], 'B': [4, None]})
>>> df2 = DataFrame({'B': [3, 3], 'C': [1, 1],}, index=[1, 2])
>>> df1.combine_first(df2)
     A    B    C
0  NaN  4.0  NaN
1  0.0  3.0  1.0
2  NaN  3.0  1.0

See Also
--------
DataFrame.combine : Perform series-wise operation on two DataFrames
    using a given function

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.combine_first" correct. :)
```
Hello @Michael-J-Ward! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on July 07, 2018 at 19:58 Hours UTC
Thanks @Michael-J-Ward! 

(Travis error was from a prior lint error on master)