Better document `brockman.sh` and `test_brockman.sh` code

[mattjmcnaughton]

Issue
I could have documented certain aspects of the brockman source code more thoroughly (i.e. I'm worried that some of the bash-isms which make sense now will be confusing in a couple of months).

Implementation
Document each method in the source code, in addition to any "gotchas".