Documentation cleanup

I decided to launch an effort to clean up the documentation. The end goal would be to have a doc that's sufficiently clean that we can require subsequent pull requests to maintain (or even better, improve) that level of quality.

Before dispatching tasks, I went through most of the codebase and made sure every class and method had at least a minimal

    """
    .. todo::
    
        WRITEME
    """

docstring so that
* it's easy to evaluate the work that remains to be done
* there's an acknowledgement these classes/methods exist in the online doc, which might encourage people to re-
  use code in the library

This is what this pull request is about.