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?