[WIP] Fix doc signature mismatch

Fixes #2062 

- [ ] Make all docstrings match with signatures ( 75 / 80 )
- [ ] Cross check and scavenge #2084 for reviews / improvised docstrings etc...
- [ ] Add Joel's script as a test
- [ ] Consistently remove `optional` across all docstrings and specify the `default` value directly...

I'll refrain from force pushing over this commit to allow review comments to be visible... ( I'll squash those commits later on )

@jnothman @amueller @NelleV Kindly take a look... 
In any case, I think trying to fix up the raft of optional/defaults should probably not be in this PR except where you happen to have done things along the way.

Consistency PRs provide marginal benefit for great cost. They're not easy to review, they often create as much argument than they resolve, and they touch lots of files leading to lots of PRs requiring rebase.

That contrasts with the primary goal of the PR which is to fix up actual shortcomings (not inconsistencies) of the documentation.