6

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?
1
  • Look at the "Method Summary" section here. It's the brief method description on the rightmost column. Commented Feb 18, 2021 at 11:19

1 Answer 1

5

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.

1
  • Thanks for the information, this explains where the summary is being used - in the Javadoc summary sections to give readers clear and concise information. However, I am still interested in what method and class indexes are. The documentation you linked says that "Javadoc automatically places it in the method summary table (and index).", what does index refer?
    – Matthew
    Commented Feb 19, 2021 at 11:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.