命令格式怎么写才正确？

javadoc 是 Java 开发工具包（JDK）自带的文档生成工具，用于将源代码中的注释转换为 HTML 格式的 API 文档（如 Java 官方文档），它通过解析 格式的注释标签（如 @param、@return），自动生成结构化的技术文档，便于团队协作和代码维护,以下详解其使用方法。

javadoc [选项] [包名|源文件名...]

• 包名：如 com.example.util，会对该包下所有类生成文档。
• 源文件名：如 MyClass.java，可指定单个或多个文件（空格分隔）。

示例 1：为单个类生成文档

javadoc MyClass.java

生成 index.html 及关联文件到当前目录。

示例 2：为整个包生成文档

javadoc -d ./docs com.example.utils

• -d ./docs：指定输出目录为当前文件夹下的 docs 子目录。
• com.example.utils：包名（需确保该包路径在 CLASSPATH 中）。

核心选项详解

注释标签规范（关键 E-A-T 实践）

在源代码中使用 Javadoc 标准标签，确保生成文档的专业性：

/**
 * 计算两数之和（方法功能描述）。
 * 
 * @param a 第一个加数（必须为整数）
 * @param b 第二个加数
 * @return 两数之和（int 类型）
 * @throws IllegalArgumentException 参数为负数时抛出
 * @see com.example.Calculator#subtract(int, int) 关联方法
 * @since 1.0
 * @author 开发者姓名
 */
public int add(int a, int b) {
    if (a < 0 || b < 0) {
        throw new IllegalArgumentException("参数不能为负");
    }
    return a + b;
}

高级用法

生成私有成员文档

javadoc -private -d ./docs com.example.model

• -private：包含 private 修饰的成员（默认仅生成 public 和 protected）。

自定义标签（如 @apiNote）

创建标签描述文件 tags.txt：

@apiNote 描述  API 注意事项

运行命令：

javadoc -tag apiNote:a:"API Note:" -d ./docs MyClass.java

生成文档链接到 JDK 官方 API

javadoc -link https://docs.oracle.com/javase/8/docs/api/ -d ./docs com.example.utils

• -link：添加指向外部文档的链接（如 JDK 标准库）。

完整示例

项目结构：

src/
  └── main/
      └── java/
          └── com/
              └── example/
                  ├── MathUtil.java
                  └── StringUtil.java

生成命令：

javadoc \
  -d ./api-docs \                          # 输出目录
  -sourcepath src/main/java \              # 源码路径
  -encoding UTF-8 \                        # 编码格式
  -windowtitle "工具库 API" \              # 窗口标题
  -doctitle "<h2>核心工具库文档</h2>" \    # 首页标题
  -version -author \                       # 包含版本和作者
  -link https://docs.oracle.com/javase/8/docs/api/ \  # 链接到 JDK
  com.example                              # 包名

常见问题

1. 中文乱码：

   • 确保源文件编码与 -encoding 一致（如 -encoding UTF-8）。
   • 若控制台乱码，调整终端编码（Windows 用 chcp 65001 切 UTF-8）。

2. 错误：未找到包或类

   • 检查 -sourcepath 路径是否正确，或通过 -classpath 添加依赖。

3. 如何忽略警告？

   • 使用 -quiet 隐藏非致命警告（不推荐，应优先修复注释问题）。

掌握 javadoc 能显著提升代码可维护性，建议：

1. 为所有公开类和方法添加规范注释。
2. 在 CI/CD 流程中集成自动文档生成（如 Maven 的 mvn javadoc:javadoc）。
3. 定期检查生成的文档，确保与代码同步更新。

引用说明基于 Oracle 官方文档 Javadoc 工具使用指南 及 Java 编码实践总结，遵循 JDK 8+ 标准语法。