(PUP-2093) Improve documentation and test names.

Prior to this commit, there were a number of places where documentation
was missing and test names were insufficiently descriptive.  This commit
adds additional clarity around those places, and makes a couple of code
clarity changes as well.