Add code documentation and provide use cases.

[jamesiarmes]

While we have documentation for the project, the code documentation is sorely lacking. We should add doc blocks to the code, at a minimum for public methods but ideally for all methods. One such example is https://github.com/acquia/moonshot/blob/master/lib/moonshot/build_mechanism/version_proxy.rb, which only has a class comment that provides no use cases for when this mechanism should be used (it does, however, include a typo).