From 05eb9678d8c4fd2cf6ba90d6d9f765401c1a495a Mon Sep 17 00:00:00 2001
From: Tom Augspurger <tom.w.augspurger@gmail.com>
Date: Sat, 2 May 2015 10:03:07 -0500
Subject: [PATCH] DOC: add docstring for PeriodIndex.asfreq

---
 pandas/tseries/period.py | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/pandas/tseries/period.py b/pandas/tseries/period.py
index a4b754f5a6bbd..010d6dfb42f63 100644
--- a/pandas/tseries/period.py
+++ b/pandas/tseries/period.py
@@ -355,6 +355,44 @@ 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.
+            Whether the elements should be aligned to the end
+            or start within pa period. January 31st ('END') vs.
+            Janury 1st ('START') for example.
+
+        Returns
+        -------
+
+        new : PeriodIndex with the new frequency
+
+        Examples
+        --------
+        >>> pidx = pd.period_range('2010-01-01', '2015-01-01', freq='A')
+        >>> pidx
+        <class 'pandas.tseries.period.PeriodIndex'>
+        [2010, ..., 2015]
+        Length: 6, Freq: A-DEC
+
+        >>> pidx.asfreq('M')
+        <class 'pandas.tseries.period.PeriodIndex'>
+        [2010-12, ..., 2015-12]
+        Length: 6, Freq: M
+
+        >>> pidx.asfreq('M', how='S')
+        <class 'pandas.tseries.period.PeriodIndex'>
+        [2010-01, ..., 2015-01]
+        Length: 6, Freq: M
+        """
         how = _validate_end_alias(how)
 
         freq = frequencies.get_standard_freq(freq)