DOC: update the pandas.core.resample.Resampler.fillna docstring

pandas/core/resample.py

@@ -624,18 +624,134 @@ def backfill(self, limit=None):
 
     def fillna(self, method, limit=None):
         """
-        Fill missing values
+        Fill the new missing values in the resampled data using different
+        methods.
+
+        In statistics, imputation is the process of replacing missing data with
+        substituted values [1]_. When resampling data, missing values may
+        appear (e.g., when the resampling frequency is higher than the original
+        frequency).
+
+        The backward fill ('bfill') will replace NaN values that appeared in
+        the resampled data with the next value in the original sequence. The
+        forward fill ('ffill'), on the other hand, will replace NaN values
+        that appeared in the resampled data with the previous value in the
+        original sequence. Missing values that existed in the orginal data will
+        not be modified.
 
         Parameters
         ----------
         method : str, method of resampling ('ffill', 'bfill')
+            Method to use for filling holes in resampled data
+                * ffill: use previous valid observation to fill gap (forward
+                  fill).
+                * bfill: use next valid observation to fill gap (backward
+                  fill).
         limit : integer, optional
-            limit of how many values to fill
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        Series, DataFrame
+            An upsampled Series or DataFrame with backward or forwards filled
+            NaN values.
+
+        Examples
+        --------
+
+        Resampling a Series:
+
+        >>> s = pd.Series([1, 2, 3],
+        ...               index=pd.date_range('20180101', periods=3, freq='h'))
+        >>> 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('30min').fillna("bfill")
+        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
+
+        >>> s.resample('15min').fillna("bfill", limit=2)
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:15:00    NaN
+        2018-01-01 00:30:00    2.0
+        2018-01-01 00:45:00    2.0
+        2018-01-01 01:00:00    2.0
+        2018-01-01 01:15:00    NaN
+        2018-01-01 01:30:00    3.0
+        2018-01-01 01:45:00    3.0
+        2018-01-01 02:00:00    3.0
+        Freq: 15T, dtype: float64
+
+        >>> s.resample('30min').fillna("ffill")
+        2018-01-01 00:00:00    1
+        2018-01-01 00:30:00    1
+        2018-01-01 01:00:00    2
+        2018-01-01 01:30:00    2
+        2018-01-01 02:00:00    3
+        Freq: 30T, dtype: int64
+
+        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('30min').fillna("bfill")
+                               a  b
+        2018-01-01 00:00:00  2.0  1
+        2018-01-01 00:30:00  NaN  3
+        2018-01-01 01:00:00  NaN  3
+        2018-01-01 01:30:00  6.0  5
+        2018-01-01 02:00:00  6.0  5
+
+        >>> df.resample('15min').fillna("bfill", limit=2)
+                               a    b
+        2018-01-01 00:00:00  2.0  1.0
+        2018-01-01 00:15:00  NaN  NaN
+        2018-01-01 00:30:00  NaN  3.0
+        2018-01-01 00:45:00  NaN  3.0
+        2018-01-01 01:00:00  NaN  3.0
+        2018-01-01 01:15:00  NaN  NaN
+        2018-01-01 01:30:00  6.0  5.0
+        2018-01-01 01:45:00  6.0  5.0
+        2018-01-01 02:00:00  6.0  5.0
+
+        >>> df.resample('30min').fillna("ffill")
+                              a	b
+        2018-01-01 00:00:00	2.0	1
+        2018-01-01 00:30:00	2.0	1
+        2018-01-01 01:00:00	NaN	3
+        2018-01-01 01:30:00	NaN	3
+        2018-01-01 02:00:00	6.0	5
 
         See Also
         --------
-        Series.fillna
-        DataFrame.fillna
+        backfill : Backward fill NaN values in the resampled data.
+        pad : Forward fill NaN values in the resampled data.
+        bfill : Alias of backfill.
+        ffill: Alias of pad.
+        nearest : Fill NaN values in the resampled data
+            with nearest neighbor starting from center.
+        pandas.Series.fillna : Fill NaN values in the Series using the
+            specified method, which can be 'bfill' and 'ffill'.
+        pandas.DataFrame.fillna : Fill NaN values in the DataFrame using the
+            specified method, which can be 'bfill' and 'ffill'.
+
+        References
+        ----------
+        .. [1] https://en.wikipedia.org/wiki/Imputation_(statistics)
         """
         return self._upsample(method, limit=limit)