Parent issue: #19807

Coverage table

First Sentence

Chapter link

Content

Image

Text

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) {
...

Guidelines

This chapter is covered by SummaryJavadocCheck. Proposal: