JavaDoc的最佳实践

一、JavaDoc 使用说明

1.1 什么是 JavaDoc

JavaDoc 是一款能根据源代码中的文档注释来产生 HTML 格式的 API 文档的工具。
JavaDoc 相关规则如下：

• 文档注释以 /** 开头、以 */ 结尾，并且每行要以星号开头。
• 文档注释覆盖范围包括：类、接口、方法、构造器、成员字段，如果写在其他位置，比如函数内部，被视为无效的文档注释。
• 文档注释支持 HTML 语法和 辅助标签。

1.2 文档注释结构

在类/方法上的文档标注一般分为三段，顺序如下：

• 第一段：概要描述，通常用一句话简要描述该类的作用，以英文句号结束，这句话会被提取并放到索引目录中
• 第二段：详细描述，通常用一段话或者多段话详细描述该类的作用，每段话都以英文句号结束，详细描述中可以使用 html 标签，如<p>，<pre>，<a>，<li>等标签
• 第三段：文档标记，通常用于标注作者、创建时间、参阅类等信息，描述部分和文档标记之间必须空一行

1.3 常见的 Javadoc 标签

具体细节查看 如何生成一套标准的 Java API 文档？ (qq.com)

JavaDoc 注释不仅包含文本描述，还可以包含特定的标签，用于生成结构化的文档。以下是一些常见的 JavaDoc 标签。

标签	用途	示例	注意事项
@author	指明类或接口的作者或组织，可以添加邮箱	@author John Doe	有多少个作者就用多少个该标签
@version	指明类或接口的版本	@version 1.0
@param	描述方法的参数	@param a the first integer<br>@param b the second integer	@param 的参数名之后空两格；写明各参数的 null 行为
@return	描述方法的返回值	@return the sum of a and b	写明返回值的 null 行为
@throws	描述方法可能抛出的异常	@throws ArithmeticException if b is zero	用 if - 句来描述@throws
@exception	描述方法可能抛出的异常	@exception ArithmeticException if b is zero
@see	提供相关的参考信息	@see java.lang.String	必须放在某一行中的最开始
@since	指明自哪个版本开始引入该功能	@since 1.5
@deprecated	指明该方法或类已经过时	@deprecated Use {@link #newMethod()} instead.
{@code}	用于在文档中插入代码片段	{@code String result = toUpperCase("example");}
{@link}	创建指向其他类或方法的链接	@see {@link java.lang.String}	可以放在某一行中的任意位置
{@inheritDoc}	从父类或接口继承文档注释	@inheritDoc
@serial	描述序列化属性	@serial
@serialField	描述序列化字段	@serialField
@serialData	描述 writeObject 方法的序列化数据	@serialData

二、文档最佳实践

2.1 注释原则

具体细节查看 Javadoc 最佳实践 | Coding Husky (ericfu.me)

• 首句中不要使用 @link

• 英文注释，推荐使用使用第三人称来描述。 比如 “Gets the foo”，避免 “Get the foo”

• 段落标记使用 <p> ，不用加 </p> 闭合它

• 用 “this” 指代类的对象。当你想描述这个类的一个实例（对象）的时候，用 “this” 来指代它，比如 “Returns a copy of this foo with the bar value updated”

• 用 if - 句来描述 @throws。比如 “@throws IllegalArgumentException if the file could not be found”。

• 写明各参数和返回值的 null 行为。一个方法是否接受 null、会不会返回 null 对于其他开发者是十分重要的信息。除非是原始类型，@param 和 @return 都应该注明它是否接受或返回 null。以下标准若适用请务必遵循：

  • “not nul” 表明不接受 null，若输入 nul 可能导致异常，例如 NullPointerException
  • “may be null” 表明可以传入 null 参数
  • “null treated as xxx”表明 nu 值等价于某个值
  • "null returns xxx”表明如果输入 null 则一定会返回某个值

2.2 实际案例

/*** This class represents a simple calculator.* <p>* This calculator supports basic arithmetic operations such as addition,* subtraction, multiplication, and division.* </p>* * @author John Doe* @version 1.0* @since 1.0*/
public class Calculator {/*** Adds two integers.* * @param a the first integer,not null* @param b the second integer, not null* @return the sum of a and b*/public int add(int a, int b) {return a + b;}
}

参考资料

如何生成一套标准的 Java API 文档？ (qq.com)

Javadoc Tool Home Page (oracle.com)

How to Write Doc Comments for the Javadoc Tool (oracle.com)

JavaDoc Documentation Comment Specification for the Standard Doclet (JDK 22) (oracle.com)

Javadoc 最佳实践 | Coding Husky (ericfu.me)