DOC: Docstring Redesign to fix the problem of unexpected keyword arg (issue10888)
Fixed issue #10888 

@jreback  Is this one ok to merge? 
 needs tests
 So this is simply a DOC problem where users use the wrong parameters specified in Documentation but they don't belong to those methods. I've fixed the documentation so users won't get confused again. I don't think unit tests are needed for this PR. 
 can you post before-after of the doc-strings
 Apart from the few comments, looks good!
 @jreback @jorisvandenbossche Thanks! They look better now! 
 @jreback Thanks. Anything else I should change before I add a new burden to Travis?
 thanks!
