[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... 
I would like to remove the "optional" when ever possible. I don't see any benefit if saying something is optional and not providing a default value.