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

javadoc - generate HTML pages of API documentation from Java source files

1. javadoc 简介

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

2. 基本用法

2.1 编写带 javadoc 注释的 Java 类

java 复制代码

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

2.2 生成文档

在命令行输入：

powershell 复制代码

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：标记已废弃

示例：

java 复制代码

/**
 * 计算两个整数的和。
 * @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 注释

示例：

java 复制代码

/**
 * 用法示例：{@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 文档，让代码更易于维护和分享！