DOC: add PeriodIndex.asfreq docstring

Author: TomAugspurger

pandas/tseries/period.py

@@ -355,6 +355,36 @@ def freqstr(self):
         return self.freq
 
     def asfreq(self, freq=None, how='E'):
+        """
+        Convert the PeriodIndex to the specified frequency `freq`.
+
+        Parameters
+        ==========
+
+        freq: str; a frequency
+        how: str; {'E', 'S'}
+            'E', 'END', or 'FINISH' for end,
+            'S', 'START', or 'BEGIN' for start.
+
+        Returns
+        =======
+        new: PeriodIndex with the new frequency
+
+        Examples
+        ========
+
+        >>> pidx = pd.datejjk
+        >>> pidx.asfreq('M')
+        <class 'pandas.tseries.period.PeriodIndex'>
+        [2010-12, ..., 2015-12]
+        Length: 6, Freq: M
+
+        >>> pidx.asfreq('M', how='S')
+        Out[3]:
+        <class 'pandas.tseries.period.PeriodIndex'>
+        [2010-01, ..., 2015-01]
+        Length: 6, Freq: M
+        """
         how = _validate_end_alias(how)
 
         freq = frequencies.get_standard_freq(freq)