在 Java 中，文档注释（Javadoc）是用 /** ... */ 包围的特殊注释，用于生成官方 API 文档。以下是关键用法和规范（中文说明）：

一、基本语法

/**
 * 类/方法/字段的说明
 * 
 * @标签 参数说明
 */

二、核心标签

三、完整示例

1. 类注释

/**
 * 表示一个用户实体类
 * 
 * <p>包含用户基本信息和账户状态管理功能</p>
 *
 * @author 张三
 * @version 1.2
 * @since 2020-03-15
 */
public class User {
    // ...
}

2. 方法注释

/**
 * 根据ID查询用户
 * 
 * <p><b>注意：</b>如果ID不存在将返回 null</p>
 *
 * @param id 用户ID（必须大于0）
 * @return 用户对象或 null
 * @throws SQLException 数据库连接失败时抛出
 * @see UserDAO#findById(int)
 */
public User getUserById(int id) throws SQLException {
    // ...
}

3. 字段注释

/**
 * 用户状态码：
 * <ul>
 *   <li>0 = 未激活</li>
 *   <li>1 = 正常</li>
 *   <li>2 = 冻结</li>
 * </ul>
 */
private int statusCode;

四、排版规范

1. 首行摘要：第一句作为概要描述（会出现在索引列表）
2. HTML 标签：支持 <p>, <ul>, <b>, <i> 等基础标签
3. 空行分隔：用空白行分隔不同逻辑段落（Javadoc 会保留换行）

五、生成文档命令

javadoc -d docs -encoding UTF-8 -charset UTF-8 MyClass.java

生成的 HTML 文档会保存在 docs/ 目录

六、最佳实践

1. 公共 API 必须写文档注释
2. 避免空洞描述（如“这是一个方法”）
3. 用 {@code} 代替 <code> 防止 HTML 注入
4. 过时方法用 @deprecated 明确替代方案

? 提示：IDE（如 IntelliJ IDEA/Eclipse）可通过 /** + Enter 自动生成模板