Adding documentation so that the Javadocs are more useful

No need to change in this CL, but these args should all be lined up - looks like they are 2 spaces too far left. (same below)