DOC: rewrite docstrings / fix whitespace

Rewrite some docstrings, clean out some extra and trailing whitespace.