java - 什么是 Javadoc 摘要片段？

Question

我正在努力遵守 Java Style Guide正如 Error Prone 所建议的.
栏目 7.2 The summary fragment声明如下:

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.

这是我想知道的:

究竟什么是摘要片段 ?据说每个 Javadoc 块都以它开头并且它是文本，但是是否有更多的文档可以让我阅读以更好地理解它？

为什么是摘要片段非常重要 ?据说它出现在类和方法索引中，但我不确定我是否理解这意味着什么或为什么它很重要。我最好的猜测是，这是一种标记类及其成员的方式，这样可以更容易地搜索它们。

我在哪里查找和阅读 摘要片段？我正在使用 IntelliJ IDEA，所以我知道如何通过检查访问代码中的类和成员的 Javadoc，但是有没有办法列出所有可用的摘要片段？

Answer 1

您的前两个问题已得到解答 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.

我在哪里可以找到和阅读摘要片段？

Method Summary是一个表，由三列(在某些版本中，合并为两列)组成:“修饰符和类型”、“方法”和“描述”。它简要描述了方法的功能，即 - 选择 API;HashMap 只是为了演示示例。

Index是一个网页，索引特定 Java 构建的整个 API。

“方法摘要”和“索引”都是 Java 文档的一部分。