JDK 工具学习系列（三）：javadoc 命令实用教程

JDK 工具学习系列（三）：javadoc 命令实用教程

1. javadoc 简介

javadoc 是 JDK 自带的文档生成工具，可以根据 Java 源代码中的注释，自动生成结构化、可浏览的 HTML API 文档。它是 Java 项目标准的文档工具。

2. 基本用法

2.1 编写带 javadoc 注释的 Java 类

/**
 * 这是一个演示用的 HelloJavadoc 类。
 * @author YourName
 */
public class HelloJavadoc {
    /**
     * 打印问候信息。
     * @param name 用户名
     */
    public void sayHello(String name) {
        System.out.println("Hello, " + name + "!");
    }
}

2.2 生成文档

在命令行输入：

javadoc -d doc HelloJavadoc.java

• -d doc 表示将文档输出到 doc 目录（没有会自动创建）

2.3 查看文档

用文件管理器打开 doc/index.html，即可浏览自动生成的 API 文档。

3. javadoc 注释语法与常用标签

3.1 基本语法

• 注释以 /** ... */ 包裹，写在类、方法、字段前

3.2 常用标签

• @author：作者
• @version：版本
• @param：方法参数说明
• @return：返回值说明
• @throws 或 @exception：抛出的异常说明
• @see：参考链接
• @since：自哪个版本起有
• @deprecated：标记已废弃

示例：

/**
 * 计算两个整数的和。
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 两数之和
 * @throws IllegalArgumentException 如果参数不合法
 * @see java.lang.Math
 */
public int add(int a, int b) throws IllegalArgumentException {
    return a + b;
}

4. 高级用法

4.1 内联标签

• {@code ...}：代码样式
• {@link ...}：插入链接到类或方法
• {@inheritDoc}：继承父类或接口的 javadoc 注释

示例：

/**
 * 用法示例：{@code Example ex = new Example();}
 * 参考 {@link #add(int, int)}
 */

4.2 支持 HTML 标签

可以在注释中使用 <p>, <ul>, <li>, <pre> 等 HTML 标签美化文档。

5. 常见问题

• 警告：use of default constructor, which does not provide a comment
  说明类没有显式声明构造方法，建议手动添加带注释的构造方法。

6. 参考资料

• Oracle 官方 javadoc 指南

通过本教程，你可以快速上手 javadoc 工具，为你的 Java 项目生成专业的 API 文档，让代码更易于维护和分享！