DOC: add PeriodIndex.asfreq docstring
Part of https://github.com/pydata/pandas/issues/6384

I guess PeriodIndex don't show up in the API docs at all. Not sure if I'll get to any more.

@jorisvandenbossche thanks. Should be good now I think
 @TomAugspurger added some more .. :-)
 @TomAugspurger can you update?
 @jreback done. Merge when you're ready.
 @TomAugspurger I think you forgot to add your changes
 Seems to be good now.
 I realize after we merge index-repr prob need to fix s bunch of doc strings :(
 e.g. will be.

```
In [1]: pidx = pd.period_range('2010-01-01', '2015-01-01', freq='A')

In [2]: pidx
Out[2]: PeriodIndex(['2010', '2011', '2012', '2013', '2014', '2015'], dtype='int64', freq='A-DEC')

In [3]: pidx.asfreq('M')
Out[3]: PeriodIndex(['2010-12', '2011-12', '2012-12', '2013-12', '2014-12', '2015-12'], dtype='int64', freq='M')

In [4]: pidx.asfreq('M', how='S')
Out[4]: PeriodIndex(['2010-01', '2011-01', '2012-01', '2013-01', '2014-01', '2015-01'], dtype='int64', freq='M')
```
 Indeed. A search for `<class 'pandas.tseries.period.PeriodIndex'>` and alike can help there maybe. I will open an issue for that. -> #10094
