[WIP] Fix doc signature mismatch

Fixes #2062 

This is almost done, but I haven't cross checked with #2084 yet and a few more ( < 8 ) are yet to be done...

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... 
are `optional` and `default` both necessary?