Tidy up and add comments

This diff does some tidying and adds documentation. There are still some
TODOs, but this is in good enough shape that I can start sharing it, I
think.

Author: ispeters