Minor cosmetic changes & docs updates

Hi,

I think this is really useful (thanks for sharing!) and so I decided to familiarize myself a bit with it: the best way I figured, was to add a few comments here and there and some minor cosmetic cleanups.

All unit tests pass.