A variety of improvements to the javadoc text.
Merge pull request #765 from Netflix/docs

A variety of improvements to the javadoc text.