什么是 Javadoc 摘要片段？

Question

我正在尝试遵守Error Prone建议的Java 样式指南。

\n

第 7.2 节摘要片段说明如下：

\n

\n

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

\n

\n

\n

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

\n

\n

这是我想知道的：

\n

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

\n

Answer 1

您的前两个问题在这里得到解答：

• 摘要片段到底是什么？

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

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

Javadoc 工具将第一句话复制到适当的成员、类/接口或包摘要中。因此，写出清晰、信息丰富且独立的首句非常重要。

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

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

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