*The first sentence of each doc comment should be a summary
sentence, containing a concise but complete description of the
API item. This means the first sentence of each member, class,
interface or package description. The Javadoc tool copies this
first sentence to the appropriate member, class/interface or package
summary. This makes it important to write crisp and informative
initial sentences that can stand on their own.
*The rest of the description is the explaination and goes
beyond the summary. The best member names are "self-documenting",
meaning they tell you basically what the item does. If the doc
comment merely repeats the member name in sentence form, it is
not providing more information. For example, if method description
uses only the words that appear in the method name, then it is
adding nothing at all to what you could infer. The ideal comment
goes beyond those words and should always reward you with some
bit of information that was not immediately obvious from the name.