ENH pandas-dev#3715: add documentation

pandas/core/generic.py

@@ -3990,6 +3990,10 @@ def asfreq(self, freq, method=None, how=None, normalize=False,
 
         Optionally provide filling method to pad/backfill missing values.
 
+        Returns the original data conformed to a new index with the specified
+        frequency. ``resample`` is more appropriate if an operation, such as
+        summarization, is necessary to represent the data at the new frequency.
+
         Parameters
         ----------
         freq : DateOffset object, or string
@@ -4005,7 +4009,8 @@ def asfreq(self, freq, method=None, how=None, normalize=False,
         normalize : bool, default False
             Whether to reset output index to midnight
         fill_value: scalar, optional
-            value to use for missing values, applied during upsampling
+            Value to use for missing values, applied during upsampling (note
+            this does not fill NaNs that already were present).
 
             .. version added:: 0.20.0
 
@@ -4052,6 +4057,18 @@ def asfreq(self, freq, method=None, how=None, normalize=False,
         2000-01-01 00:02:30    9.0
         2000-01-01 00:03:00    3.0
 
+        Upsample again, providing a ``method``.
+
+        >>> df.asfreq(freq='30S', method='bfill')
+                               s
+        2000-01-01 00:00:00    0.0
+        2000-01-01 00:00:30    NaN
+        2000-01-01 00:01:00    NaN
+        2000-01-01 00:01:30    2.0
+        2000-01-01 00:02:00    2.0
+        2000-01-01 00:02:30    3.0
+        2000-01-01 00:03:00    3.0
+
         Notes
         -----
         To learn more about the frequency strings, please see `this link