JavaDoc的最佳实践

文章目录

- 一、JavaDoc 使用说明
- - 1.1 什么是 JavaDoc
  - 1.2 文档注释结构
  - 1.3 常见的 Javadoc 标签
- 二、文档最佳实践
- - 2.1 注释原则
  - 2.2 实际案例
- 参考资料

一、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;}
}