Search code examples
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:

  • What exactly is a summary fragment? It is stated that every Javadoc block begins with it and that it is text, but is there more documentation somewhere that I might read to get a better understanding about it?
  • Why is the summary fragment very important? It is stated that it appears in class and method indexes, but I am not sure I understand what that means or why it is important. My best guess would be that it is a way to mark classes and it's members in such a way where it would be easier to search them.
  • Where can I find and read the summary fragment? I am using IntelliJ IDEA, so I know how to access Javadoc for classes and members in code via inspection, but is there a way to list all available summary fragments?

Solution

  • Your first two questions are answered here:

    • What exactly is a summary fragment?

    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.

    • Why is the summary fragment very important?

    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.

    • Where can I find and read the summary fragment?

      • Method Summary is a table, consisting of three (in some versions, combined in two) columns: "Modifier and Type", "Method", and a "Description". It briefly describes methods' functionality, i.e. - the API;HashMap was chosen merely for the sake of demonstration example.
      • Index is a web page, indexing entire API of the particular Java build.

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