First Sentence Javadoc

Descriptions

First Sentence
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.

This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag (as defined below). For example, this first sentence ends at "Prof.":

   /**
    * This is a simulation of Prof. Knuth's MIX computer.
    */

However, you can work around this by typing an HTML meta-character such as "&" or "<" immediately after the period, such as:

   /**
    * This is a simulation of Prof. Knuth's MIX computer.
    */

or

   /**
    * This is a simulation of Prof.<!-- --> Knuth's MIX computer.
    */

In particular, write summary sentences that distinguish overloaded methods from each other. For example:

   /** 
    * Class constructor.
    */
   foo() {
     ...
    
   /**
    * Class constructor specifying number of objects to create.
    */
   foo(int n) {
     ...