3

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

第7.2 节摘要片段指出以下内容：

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

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

这是我想知道的：

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

1 回答 1

4

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

  • 究竟什么是摘要片段？

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

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

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

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

    • Method Summary是一个表格，由三列（在某些版本中合并为两列）组成：“Modifier and Type”、“Method”和“Description”。它简要描述了方法的功能，即 - API；选择 HashMap 仅仅是为了演示示例。
    • 索引是一个网页，索引特定 Java 构建的整个 API。

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

于 2021-02-18T11:24:36.170 回答