A big spring clean of the docstrings (sure long time coming!)
* Fix typos,
* rewrite clumsy explanations,
* omit unnecessary and misleading parts,
* remove awkward and "smart" language,
* use consistent here-doc formatting across small and big docstrings
(isolate quote mark triplets on own line.)