什么是 Javadoc 摘要片段？

Question

我正在尝试按照Error Prone 的建议遵守Java Style Guide。

7.2 The summary fragment 部分声明如下：

每个 Javadoc 块都以一个简短的摘要片段开头。这个片段非常重要：它是文本中唯一出现在某些上下文（例如类和方法索引）中的部分。

这是一个片段——一个名词短语或动词短语，而不是一个完整的句子。它不以 A {@code Foo} is a... 开头，或者 This method returns...，也不是像 Save the record. 这样形成完整的祈使句。但是，片段大写并带有标点，就好像它是一个完整的句子。

这是我想知道的：

• 究竟什么是摘要片段？据说每个 Javadoc 块都以它开头并且它是文本，但是否有更多文档可供我阅读以更好地理解它？
• 为什么摘要片段非常重要？据说它出现在类和方法索引中，但我不确定我理解这意味着什么或为什么它很重要。我最好的猜测是，这是一种标记类及其成员的方式，这样更容易搜索它们。
• 我在哪里可以找到并阅读摘要片段？我正在使用 IntelliJ IDEA，所以我知道如何通过检查访问代码中的类和成员的 Javadoc，但是有没有办法列出所有可用的摘要片段？

Answer 1

您的前两个问题已回答here：

• 究竟什么是摘要片段？

每个文档注释的第一句应该是一个摘要句，包含对 API 项的简洁而完整的描述。这意味着每个成员、类、接口或包描述的第一句。

• 为什么摘要片段非常重要？

Javadoc 工具将第一句复制到适当的成员、类/接口或包摘要中。这使得写出清晰、信息丰富、可以独立存在的初始句子变得很重要。

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

  • Method Summary 是一个表，由三列（在某些版本中，合并为两列）组成：“修饰符和类型”、“方法”和“描述”。它简要描述了方法的功能，即 - API；_{选择 HashMap 只是为了演示示例。}
  • Index 是一个网页，索引特定 Java 构建的整个 API。

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