[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 am not quite sure of my wording here... ( mainly in `norm_diag`, and also in `smallest_coeff` and `largest_coeff` )