问题描述
我正在努力遵守 Java Style Guide 建议的 Error Prone。
第 7.2 The summary fragment 节声明如下：
每个 Javadoc 块都以一个简短的摘要片段开始。这个片段非常重要：它是文本中唯一出现在某些上下文（例如类和方法索引）中的部分。
这是一个片段——名词短语或动词短语，而不是一个完整的句子。它不以 A {@code Foo} is a... 开头，或者此方法返回...，也不会形成像 Save the record.. 这样完整的祈使句。但是，片段是大写和标点的，好像它是一个完整的句子。
以下是我想知道的：
- 什么是摘要片段？据说每个 Javadoc 块都以它开头，并且是文本，但是否有更多文档可供我阅读以更好地理解它？
- 为什么摘要片段非常重要？据说它出现在类和方法索引中，但我不确定我是否理解这意味着什么或为什么它很重要。我最好的猜测是，这是一种标记类及其成员的方法，这样可以更轻松地搜索它们。
- 在哪里可以找到和阅读摘要片段？我使用的是 IntelliJ IDEA，所以我知道如何通过检查访问代码中的类和成员的 Javadoc，但是有没有办法列出所有可用的摘要片段？
解决方法
您的前两个问题已得到解答here：
- 究竟什么是摘要片段？
每个文档注释的第一句应该是一个摘要句，包含对 API 项的简洁但完整的描述。这意味着每个成员、类、接口或包描述的第一句话。
- 为什么摘要片段非常重要？
Javadoc 工具将第一句话复制到适当的成员、类/接口或包摘要。这使得写出清晰且内容丰富的初始句子很重要。
-
在哪里可以找到和阅读摘要片段？
- Method Summary 是一个表，由三列（在某些版本中，合并为两列）组成：“修饰符和类型”、“方法”和“描述”。它简要描述了方法的功能，即 - API；选择 HashMap 只是为了演示示例。
- Index 是一个网页，索引特定 Java 构建的整个 API。
“方法摘要”和“索引”都是 Java 文档的一部分。