[WIP] Fix doc signature mismatch

Fixes #2062 

- [ ] Make all docstrings match with signatures ( 8 left )
- [ ] Cross check and scavenge #2084 for reviews / improvised docstrings etc...
- [ ] Add Joel's script as a test

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... 
but you removed the leading underscore which is part of the attribute name. If you leave the leading underscore in and remove the backticks, sphinx will interpret this as a reference, throw an error, and not render it.