javajavadocerrorprone

What is a Javadoc summary fragment?


I am trying to adhere to Java Style Guide as suggested by Error Prone.

Section 7.2 The summary fragment states the following:

Each Javadoc block begins with a brief summary fragment. This fragment is very important: it is the only part of the text that appears in certain contexts such as class and method indexes.

This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does not begin with A {@code Foo} is a..., or This method returns..., nor does it form a complete imperative sentence like Save the record.. However, the fragment is capitalized and punctuated as if it were a complete sentence.

Here is what I would like to know:


Solution

  • Your first two questions are answered here:

    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.

    Both, "Method Summary" and "Index", are part of the Java doc.