DOC: a few touchups
Comments in https://github.com/pydata/pandas/pull/11660#issuecomment-158427446

@jorisvandenbossche 
@jreback 

I think we're ok to merge.

looks good (for a follow-up, you should also use a space before the `:` in the Parameters section)
 @TomAugspurger ready on this?
