DOC: update pandas.core.resample.Resampler.nearest docstring (pandas-…

…dev#20381)

pandas/core/resample.py

@@ -418,23 +418,63 @@ 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` method 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 this many 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.
+        pad : Forward fill ``NaN`` values.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2],
+        ...               index=pd.date_range('20180101',
+        ...                                   periods=2,
+        ...                                   freq='1h'))
+        >>> s
+        2018-01-01 00:00:00    1
+        2018-01-01 01:00:00    2
+        Freq: H, dtype: int64
+
+        >>> s.resample('15min').nearest()
+        2018-01-01 00:00:00    1
+        2018-01-01 00:15:00    1
+        2018-01-01 00:30:00    2
+        2018-01-01 00:45:00    2
+        2018-01-01 01:00:00    2
+        Freq: 15T, dtype: int64
+
+        Limit the number of upsampled values imputed by the nearest:
+
+        >>> s.resample('15min').nearest(limit=1)
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:15:00    1.0
+        2018-01-01 00:30:00    NaN
+        2018-01-01 00:45:00    2.0
+        2018-01-01 01:00:00    2.0
+        Freq: 15T, dtype: float64
         """
         return self._upsample('nearest', limit=limit)