7 Javadoc

7.1 格式化

7.1.1 一般形式

Javadoc 块的基本格式如下例所示：

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

… 或单行示例：

/** An especially short bit of Javadoc. */

基本形式始终是可以接受的。当整个 Javadoc 块（包括注释标记）可以放在一行上时，可以使用单行形式。注意，这仅在没有块标签（如 @param）时适用。

7.1.2 段落

段落之间以及块标签组（如果存在）之前，有一个空行——即仅包含对齐的前导星号（*）的行。除第一段外，每段在第一个单词之前紧跟 <p>，其后没有空格。其他块级元素的 HTML 标签，如 <ul> 或 <table>，不在前面加 <p>。

7.1.3 块标签

使用的任何标准”块标签”按以下顺序出现：@param、@return、@throws、@deprecated，且这四种类型不允许有空描述。当块标签无法放在一行上时，续行从 @ 的位置缩进四个（或更多）空格。

7.2 摘要片段

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

这是一个片段——一个名词短语或动词短语，而不是完整的句子。它不以 A {@code Foo} is a... 或 This method returns... 开头，也不构成完整的祈使句，如 Save the record.。然而，该片段的大写和标点符号就像完整的句子一样。

**提示：**一个常见的错误是将简单的 Javadoc 写成 /** @return the customer ID */ 的形式。这是不正确的，应改为 /** Returns the customer ID. */ 或 /** {@return the customer ID} */。

7.3 Javadoc 的使用场景

至少，每个可见的类、成员或记录组件都应有 Javadoc，下文列出的少数例外情况除外。如果顶层类是 public，则它是可见的；如果成员是 public 或 protected 且其所在类是可见的，则该成员是可见的；如果记录组件所在的记录是可见的，则该组件是可见的。

其他 Javadoc 内容也可以出现，如第 7.3.4 节非必需的 Javadoc 所述。

7.3.1 例外：自解释的成员

对于”简单、明显”的成员和记录组件（如 getFoo() 方法），如果确实没有其他值得说的内容，只是”the foo”，则 Javadoc 是可选的。

**重要提示：**不应以此例外为由省略典型读者可能需要知道的相关信息。例如，对于名为 canonicalName 的记录组件，如果典型读者可能不知道”canonical name”是什么意思，就不要省略其文档（理由是它只会说 @param canonicalName the canonical name）！

7.3.2 例外：覆盖方法

覆盖超类方法的方法并不总是需要 Javadoc。

7.3.4 非必需的 Javadoc

其他类、成员和记录组件根据需要或意愿编写 Javadoc。

每当需要使用实现注释来定义类或成员的总体用途或行为时，该注释应改为 Javadoc（使用 /**）。

非必需的 Javadoc 不严格要求遵循第 7.1.1、7.1.2、7.1.3 和 7.2 节的格式化规则，但当然推荐遵循。