CAS-1238 Javadoc improvements inspired by @apetro.
CAS-1238 Respond to @apetro code review.