Beefed up commentary.

(as I was writing a blog post about this for work, I saw opportunities to
enhance the comments and docstrings.)