Java 基础 12：JavaDoc 生成文档学习笔记

JavaDoc：MathUtil 生成文档详解

Java 基础 12：JavaDoc 生成文档学习笔记

一、JavaDoc 概述

1. 核心作用

JavaDoc 是 Sun 公司提供的自动生成 API 文档 的工具，通过解析 Java 源代码中的文档注释（/ \ /）*，生成标准化的 HTML 格式帮助文档，方便开发者查阅类、方法、变量的功能和使用方式，是团队协作、开源项目的必备规范。

2. 文档注释与普通注释的区别

注释类型	语法格式	解析方式	作用场景
文档注释	`/****/`	可被 JavaDoc 工具解析	注释类、方法、常量，用于生成 API 文档
多行注释	`/* */`	仅编译器忽略，不可被解析	注释代码块，仅开发人员阅读
单行注释	`//`	仅编译器忽略，不可被解析	注释单行代码，仅开发人员阅读

3. 适用范围

文档注释只能写在类、方法、成员变量、常量的上方，不能写在代码块内部，用于描述整体功能和使用说明。

二、JavaDoc 的核心标签

JavaDoc 通过标签规范注释内容，标签以@开头，按固定格式书写，工具会自动解析并分类展示，核心标签分为通用标签 和方法专属标签，标签需写在文档注释内，换行书写更规范。

1. 通用标签（类 / 方法 / 变量均可使用）

@author：标注作者名，多个作者用,分隔（如@author 狂神 @author Java）
@version：标注版本号（如@version 1.0）
@since：标注该类 / 方法适用的 JDK 版本（如@since JDK1.8）
@description：标注详细描述（可省略，直接写注释内容即为描述）

2. 方法专属标签

@param：标注方法的参数，格式@param 参数名参数说明，多个参数写多个
@return：标注方法的返回值，无返回值（void）的方法不写
@throws/@exception：标注方法抛出的异常，两者用法一致，格式@throws 异常类异常说明

3. 标签使用规范

标签后需加空格，再写内容，格式统一保证文档整洁；
方法的@param需与参数列表一一对应，顺序一致；
标签可按@author→@version→@since→@param→@return的顺序书写。

三、文档注释的书写规范

1. 类的文档注释

写在class关键字上方，描述类的功能、设计思路、适用场景，搭配通用标签使用。

语法格式

php 复制代码

/**
 * 类的详细描述：描述该类的核心功能、设计用途
 * @author 作者名
 * @version 版本号
 * @since 适用JDK版本
 */
public class 类名 {
    // 类的内容
}

2. 成员变量 / 常量的文档注释

写在变量定义上方，描述变量的含义、取值范围、使用说明。

语法格式

arduino 复制代码

/**
 * 变量的详细描述：如表示用户年龄，取值范围0-150
 */
private int age;

/**
 * 常量的详细描述：如表示圆周率，固定值3.1415926
 */
public static final double PI = 3.1415926;

3. 方法的文档注释

写在方法定义上方，描述方法的功能、参数含义、返回值说明、异常情况，搭配方法专属标签使用，是 JavaDoc 的核心注释部分。

语法格式

java 复制代码

/**
 * 方法的详细描述：如实现两个整数的求和功能
 * @param a 第一个求和的整数
 * @param b 第二个求和的整数
 * @return 两个整数的和
 * @since JDK1.8
 */
public int add(int a, int b) {
    return a + b;
}

4. 完整代码示例（含所有注释）

php 复制代码

/**
 * 数学工具类：提供基础的数学运算方法（加法、减法）
 * @author 狂神
 * @version 1.0
 * @since JDK1.8
 */
public class MathUtil {
    /**
     * 表示默认的运算精度，保留2位小数
     */
    public static final int SCALE = 2;

    /**
     * 两个整数的加法运算
     * @param num1 第一个参与加法的整数
     * @param num2 第二个参与加法的整数
     * @return 两个整数相加的结果
     */
    public int add(int num1, int num2) {
        return num1 + num2;
    }

    /**
     * 两个整数的减法运算
     * @param num1 被减数
     * @param num2 减数
     * @return 两个整数相减的结果
     * @throws ArithmeticException 当减数为0时抛出（示例）
     */
    public int sub(int num1, int num2) {
        if (num2 == 0) {
            throw new ArithmeticException("减数不能为0");
        }
        return num1 - num2;
    }
}

四、生成 JavaDoc 文档的两种方式

方式 1：使用 cmd 命令行生成（基础通用，无 IDE 限制）

核心命令

复制代码

javadoc -encoding UTF-8 -charset UTF-8 源代码文件名.java

参数说明

-encoding UTF-8：指定源代码的编码格式，解决中文注释乱码；
-charset UTF-8：指定生成文档的编码格式，保证网页端中文正常显示；

执行步骤

打开 cmd，进入 Java 源代码所在的文件夹（使用cd 文件夹路径命令）；
输入上述核心命令，回车执行；
执行完成后，文件夹内会生成多个 HTML 文件，index.html是文档首页，双击打开即可查看。

示例

bash 复制代码

# 生成MathUtil.java的API文档，解决中文乱码
javadoc -encoding UTF-8 -charset UTF-8 MathUtil.java

方式 2：使用 IDEA 工具生成（可视化操作，更便捷）

执行步骤

打开 IDEA，选中需要生成文档的类 / 包（包可生成整个包的文档）；
点击顶部菜单栏Tools → Generate JavaDoc，打开生成窗口；
配置核心参数：
1. Output directory：选择文档的生成路径（如桌面，方便查找）；
2. Other command line arguments ：输入-encoding UTF-8 -charset UTF-8，解决中文乱码；
3. Locale ：可填zh_CN，设置文档为中文显示；
点击OK，IDEA 自动执行生成，完成后打开生成路径，双击index.html查看文档。

五、生成的 API 文档解读

生成的 HTML 文档为标准化结构，核心板块如下，可快速查阅信息：

类信息区：展示类的名称、作者、版本、JDK 版本、类的详细描述；
常量 / 变量区：展示所有带文档注释的成员变量、常量，含变量描述；
方法区 ：展示所有带文档注释的方法，按方法名分类，每个方法展示参数、返回值、异常、方法描述；
导航栏：右侧可快速定位到指定方法 / 变量，顶部可切换包、类，方便多类文档查阅；
详情区：点击方法名，可查看方法的完整注释和使用说明，与源代码中的文档注释一一对应。

六、JavaDoc 开发规范与注意事项

注释语言 ：统一使用中文（国内开发）或英文（开源项目），不可混写，保证团队可读性；
注释准确性：注释需与代码逻辑一致，代码修改后同步更新注释，避免 "注释与代码不符"；
中文乱码解决 ：生成文档时必须加编码参数 （-encoding UTF-8 -charset UTF-8），否则中文注释会显示为乱码；
标签完整性 ：方法的@param和@return需完整，无遗漏，参数说明要简洁明了（如@param a 第一个求和整数，而非仅写@param a 整数）；
注释简洁性：避免冗余注释，仅写核心功能和使用说明，代码本身能体现的逻辑无需重复注释；
包级注释 ：如需为整个包生成注释，可在包下创建package-info.java文件，在该文件中写包的文档注释，JavaDoc 会自动解析；
私有成员 ：默认情况下，JavaDoc 不会解析private修饰的类、方法、变量，如需解析，可在命令行 / IDEA 中添加-private参数。

七、package-info.java 包注释（拓展）

作用

为整个包添加统一的描述，生成的 API 文档中会展示包的注释，方便开发者了解整个包的功能，适用于多类组成的工具包 / 业务包。

书写格式（package-info.java）

java 复制代码

/**
 * 数学运算工具包：提供所有基础的数学运算方法，包括加减乘除、取模、开方等
 * @author 狂神
 * @version 1.0
 * @since JDK1.8
 */
package com.kuang.math; // 包名与实际一致

生成说明

创建该文件后，与其他 Java 类一起生成 JavaDoc 文档，文档中会单独展示包的注释信息，提升文档的完整性。

Java 基础 12：JavaDoc 生成文档 学习笔记