Add commentary for pull request

Attempt to document some of my thinking in comments. I'm sure this
should be fixed before the pull request goes through.