some minor code cleanups from tobgu's review
Docstrings, with doctests!