DOC: update pandas.core.resample.Resampler.nearest docstring
State: closed

Checklist for the pandas documentation sprint:

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py pandas.core.resample.Resampler.nearest`
- [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 pandas.core.resample.Resampler.nearest`
- [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.core.resample.Resampler.nearest) ##############
################################################################################

Fill the new missing values with their nearest neighbor value, based
on index.

When resampling data, missing values may appear (e.g., when the
resampling frequency is higher than the original frequency).
The nearest fill will replace ``NaN`` values that appeared in
the resampled data with the value from the nearest member of the
sequence, based on the index value.
Missing values that existed in the original data will not be modified.
If `limit` is given, fill only `limit` values in each direction for
each of the original values.

Parameters
----------
limit : integer, optional
    Limit of how many values to fill.

    .. versionadded:: 0.21.0

Returns
-------
Series, DataFrame
    An upsampled Series or DataFrame with ``NaN`` values filled with
    their closest neighbor value.

See Also
--------
backfill: Backward fill the new missing values in the resampled data.
fillna : Fill ``NaN`` values using the specified method, which can be
    'backfill'.
pad : Forward fill ``NaN`` values.
pandas.Series.fillna : Fill ``NaN`` values in the Series using the
    specified method, which can be 'backfill'.
pandas.DataFrame.fillna : Fill ``NaN`` values in the DataFrame using
    the specified method, which can be 'backfill'.

Examples
--------

Resampling a Series:

>>> s = pd.Series([1, 2, 3],
...               index=pd.date_range('20180101', periods=3,
...                                   freq='1h'))
>>> s
2018-01-01 00:00:00    1
2018-01-01 01:00:00    2
2018-01-01 02:00:00    3
Freq: H, dtype: int64

>>> s.resample('20min').nearest()
2018-01-01 00:00:00    1
2018-01-01 00:20:00    1
2018-01-01 00:40:00    2
2018-01-01 01:00:00    2
2018-01-01 01:20:00    2
2018-01-01 01:40:00    3
2018-01-01 02:00:00    3
Freq: 20T, dtype: int64

Resample in the middle:

>>> s.resample('30min').nearest()
2018-01-01 00:00:00    1
2018-01-01 00:30:00    2
2018-01-01 01:00:00    2
2018-01-01 01:30:00    3
2018-01-01 02:00:00    3
Freq: 30T, dtype: int64

Limited fill:

>>> s.resample('10min').nearest(limit=1)
2018-01-01 00:00:00    1.0
2018-01-01 00:10:00    1.0
2018-01-01 00:20:00    NaN
2018-01-01 00:30:00    NaN
2018-01-01 00:40:00    NaN
2018-01-01 00:50:00    2.0
2018-01-01 01:00:00    2.0
2018-01-01 01:10:00    2.0
2018-01-01 01:20:00    NaN
2018-01-01 01:30:00    NaN
2018-01-01 01:40:00    NaN
2018-01-01 01:50:00    3.0
2018-01-01 02:00:00    3.0
Freq: 10T, dtype: float64

Resampling a DataFrame that has missing values:

>>> df = pd.DataFrame({'a': [2, np.nan, 6], 'b': [1, 3, 5]},
...                   index=pd.date_range('20180101', periods=3,
...                                       freq='h'))
>>> df
                       a  b
2018-01-01 00:00:00  2.0  1
2018-01-01 01:00:00  NaN  3
2018-01-01 02:00:00  6.0  5

>>> df.resample('20min').nearest()
                       a  b
2018-01-01 00:00:00  2.0  1
2018-01-01 00:20:00  2.0  1
2018-01-01 00:40:00  NaN  3
2018-01-01 01:00:00  NaN  3
2018-01-01 01:20:00  NaN  3
2018-01-01 01:40:00  6.0  5
2018-01-01 02:00:00  6.0  5

Resampling a DataFrame with shuffled indexes:

>>> df = pd.DataFrame({'a': [2, 6, 4]},
...                   index=pd.date_range('20180101', periods=3,
...                                       freq='h'))
>>> df
                     a
2018-01-01 00:00:00  2
2018-01-01 01:00:00  6
2018-01-01 02:00:00  4

>>> sorted_df = df.sort_values(by=['a'])
>>> sorted_df
                     a
2018-01-01 00:00:00  2
2018-01-01 02:00:00  4
2018-01-01 01:00:00  6

>>> sorted_df.resample('20min').nearest()
                     a
2018-01-01 00:00:00  2
2018-01-01 00:20:00  2
2018-01-01 00:40:00  6
2018-01-01 01:00:00  6
2018-01-01 01:20:00  6
2018-01-01 01:40:00  4
2018-01-01 02:00:00  4

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameter "limit" description should finish with "."
```

The error is caused by `.. versionadded:: 0.21.0`, which has no period in the end.


Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20381?src=pr&el=h1) Report
> Merging [#20381](https://codecov.io/gh/pandas-dev/pandas/pull/20381?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/4f717551b8e49ecd978bb4f5a985d6f6a96d86e9?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20381/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/20381?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20381      +/-   ##
==========================================
+ Coverage   92.22%   92.23%   +<.01%     
==========================================
  Files         161      161              
  Lines       51187    51197      +10     
==========================================
+ Hits        47209    47220      +11     
+ Misses       3978     3977       -1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.61% <ø> (ø)` | :arrow_up: |
| #single | `42.27% <ø> (+0.01%)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20381?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/resample.py](https://codecov.io/gh/pandas-dev/pandas/pull/20381/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzYW1wbGUucHk=) | `96.99% <ø> (ø)` | :arrow_up: |
| [pandas/core/arrays/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/20381/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3RpbWVkZWx0YXMucHk=) | `93.75% <0%> (-0.56%)` | :arrow_down: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20381/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.81% <0%> (ø)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20381/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.87% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/20381/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `90.74% <0%> (+0.12%)` | :arrow_up: |
| [pandas/core/indexes/frozen.py](https://codecov.io/gh/pandas-dev/pandas/pull/20381/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9mcm96ZW4ucHk=) | `92.1% <0%> (+0.43%)` | :arrow_up: |
| [pandas/core/arrays/period.py](https://codecov.io/gh/pandas-dev/pandas/pull/20381/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3BlcmlvZC5weQ==) | `98.08% <0%> (+0.59%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20381?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20381?src=pr&el=footer). Last update [4f71755...3ab559a](https://codecov.io/gh/pandas-dev/pandas/pull/20381?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

@datapythonista 
Hello @thicorfon! Thanks for updating the PR.

 - There are no PEP8 issues in the file [`pandas/core/resample.py`](https://github.com/thicorfon/pandas/blob/14a3b3ae5709423b6f5001f512a2b2a2ed1567f4/pandas/core/resample.py) !


Thanks for another great review @jbrockmendel. Made the changes, I think this should be ready to be merged on green.

For the "same type as caller", we try to use only Python types in the types of the return and parameters. Ideally at some point we can parse those types and detect suspicious things or get statistics. In generic methods, so far we're using `Series or DataFrame`. At a later stage it'd be nice to write the corresponding class, but that requires a bit of thinking on how to do, and will come in a separate PR.
@jreback this should be ready to merge, if you want to have a look
thanks @thicorfon