improve test documentation

Added some docstrings and comments as highlighted by discussion in #29.