什么是 Javadoc 摘要片段？
What is a Javadoc summary fragment?
我正在努力遵守 Java Style Guide as suggested by 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 块都以它开头并且它是文本，但是我可以阅读更多文档以更好地理解它吗？
- 为什么摘要片段非常重要？据说它出现在 class 和方法索引中，但我不确定我是否理解这意味着什么或为什么它很重要。我最好的猜测是，这是一种标记 [=34=]es 及其成员的方式，这样可以更轻松地搜索它们。
- 在哪里可以找到和阅读摘要片段？我正在使用 IntelliJ IDEA，所以我知道如何通过检查访问代码中的 classes 和成员的 Javadoc，但是有没有办法列出所有可用的摘要片段？
您的前两个问题已得到解答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 是一个 table，由三个（在某些版本中合并为两个）列组成：“修饰符和类型”、“方法”和“描述”。它简要描述了方法的功能，即 - 选择 API;HashMap 只是为了演示示例。
- Index 是一个网页，索引了特定 Java 构建的整个 API。
“方法摘要”和“索引”都是 Java 文档的一部分。
我正在努力遵守 Java Style Guide as suggested by 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 块都以它开头并且它是文本，但是我可以阅读更多文档以更好地理解它吗？
- 为什么摘要片段非常重要？据说它出现在 class 和方法索引中，但我不确定我是否理解这意味着什么或为什么它很重要。我最好的猜测是，这是一种标记 [=34=]es 及其成员的方式，这样可以更轻松地搜索它们。
- 在哪里可以找到和阅读摘要片段？我正在使用 IntelliJ IDEA，所以我知道如何通过检查访问代码中的 classes 和成员的 Javadoc，但是有没有办法列出所有可用的摘要片段？
您的前两个问题已得到解答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 是一个 table，由三个（在某些版本中合并为两个）列组成：“修饰符和类型”、“方法”和“描述”。它简要描述了方法的功能，即 - 选择 API;HashMap 只是为了演示示例。
- Index 是一个网页，索引了特定 Java 构建的整个 API。
“方法摘要”和“索引”都是 Java 文档的一部分。