Editing javadoc comments

Many changes to the javadoc comments, filling in blanks, making comments
more accurate & precise, making formatting more consistent, etc.