Javadoc的注释方式

一、Javadoc 的基本语法

注释格式：

/**
 * 描述信息（概述该元素的功能）
 *
 * @标签名 说明内容
 */

• 使用 /** 开始，*/ 结束。
• 描述信息通常放在顶部，用来简述该元素的作用。
• 可选的 @标签 用于补充更详细的信息。

位置：

• 类/接口前：描述类的用途和设计意图。
• 方法前：描述方法的功能、参数、返回值和异常。
• 字段前：描述字段的用途。
• 构造函数前：描述构造器的作用。

---

二、Javadoc 常用的标签

以下是 Javadoc 支持的主要标签及其用途：

1. @param

描述方法的参数。

格式：

@param 参数名 描述信息

示例：

/**
 * 设置用户名称
 *
 * @param username 用户名称
 */
public void setUsername(String username) {
    this.username = username;
}

2. @return

描述方法的返回值。

格式：

@return 返回值描述

示例：

/**
 * 获取用户名称
 *
 * @return 用户名称
 */
public String getUsername() {
    return username;
}

3. @throws 或 @exception

描述方法可能抛出的异常。

格式：

@throws 异常类 描述信息

@throws 异常类 描述信息

示例：

/**
 * 根据用户 ID 获取用户
 *
 * @param userId 用户 ID
 * @return 用户信息
 * @throws UserNotFoundException 如果用户不存在
 */
public User getUserById(String userId) throws UserNotFoundException {
    // 实现代码
}

4. @see

提供相关链接，用于引用类、方法或文档。

格式：

@see 完整类名#方法名 描述信息

示例：

/**
 * 处理用户登录
 *
 * @see com.example.UserService#login(String, String) 详细登录逻辑
 */
public void loginUser() {
    // 实现代码
}

5. @deprecated

标记方法或类已废弃，建议开发者避免使用。

格式：

@deprecated 描述信息

示例：

/**
 * 获取用户年龄
 *
 * @return 用户年龄
 * @deprecated 请使用 {@link #getUserAge()} 代替
 */
public int getAge() {
    return age;
}

6. @since

表示从哪个版本开始引入。

格式：

@since 版本号

示例：

/**
 * 获取用户地址
 *
 * @return 用户地址
 * @since 1.2
 */
public String getAddress() {
    return address;
}

7. {@link}

嵌入式链接，用于引用类或方法。

格式：

{@link 完整类名#方法名 描述信息}

示例：

/**
 * 计算两个数的和
 *
 * @param a 第一个数
 * @param b 第二个数
 * @return 两数之和
 * @see Math#addExact(int, int)
 */
public int sum(int a, int b) {
    return a + b;
}

8. @author

标注类或接口的作者。

格式：

@author 作者姓名

示例：

/**
 * 用户管理服务
 *
 * @author John Doe
 */
public class UserService {
    // 实现代码
}

9. @version

标注类的版本号。

格式：

@version 版本号

示例：

/**
 * 用户管理服务
 *
 * @author John Doe
 * @version 1.0
 */
public class UserService {
    // 实现代码
}

10. {@code}

用于嵌入代码片段，常用于描述参数或示例。

格式：

{@code 代码内容}

示例：

/**
 * 计算阶乘
 *
 * 示例代码：
 * {@code factorial(5) = 120}
 *
 * @param n 非负整数
 * @return 阶乘值
 */
public int factorial(int n) {
    return n == 0 ? 1 : n * factorial(n - 1);
}

---

三、Javadoc 生成 HTML 文档

生成工具：

• 使用 JDK 提供的 javadoc 命令。
• 格式：

javadoc [选项] [源文件]

常用选项：

• -d：指定生成文档的输出目录。
• -author：在文档中包含 @author 信息。
• -version：在文档中包含 @version 信息。

示例：

javadoc -d ./docs -author -version MyClass.java

• 将 MyClass.java 的 Javadoc 生成到 ./docs 目录中。

---

四、Javadoc 在IDEA中的使用

快捷键自动生成

• 方法位置输入/**，然后按回车
• 自动生成标准Javadoc模板
• 模板包括@param、@return、@throws等标签
• 光标会自动停留在注释中，方便快速编辑

---

五、Javadoc 的优点

• 自动生成文档：方便生成标准化的 API 文档。
• 提升代码可读性：详细的注释帮助开发者理解代码逻辑。
• 开发工具支持：主流 IDE（如 IntelliJ IDEA、Eclipse）都能解析并显示 Javadoc 注释。
• 团队协作效率：对复杂功能进行清晰说明，降低沟通成本。