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

pandas/core/resample.py

@@ -418,23 +418,80 @@ def pad(self, limit=None):
 
     def nearest(self, limit=None):
         """
-        Fill values with nearest neighbor starting from center
+        Resample by using the nearest value.
+
+        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
+        limit : int, optional
+            Limit of how many values to fill.
 
             .. versionadded:: 0.21.0
 
         Returns
         -------
-        an upsampled Series
+        Series or DataFrame
+            An upsampled Series or DataFrame with ``NaN`` values filled with
+            their nearest value.
 
         See Also
         --------
-        Series.fillna
-        DataFrame.fillna
+        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
+        --------
+        >>> 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
+
+        Limit the number of upsampled values imputed by the nearest:
+
+        >>> 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
         """
         return self._upsample('nearest', limit=limit)