JavaDoc 入门指南 | Baeldung中文网

1. 概述

优秀的 API 文档是软件项目成功的关键因素之一。幸运的是，所有现代 JDK 版本都提供了 Javadoc 工具，可以从源代码注释中自动生成 API 文档。

前置条件：

JDK 1.4（推荐使用 JDK 7+ 以获得最新版 Maven Javadoc 插件支持）
已将 JDK /bin 目录添加到系统 PATH 环境变量
（可选）带内置工具的 IDE

2. Javadoc 注释

2.1. 注释结构

Javadoc 注释结构与普通多行注释非常相似，但关键区别在于开头的额外星号：

// 这是单行注释

/*
 * 这是普通多行注释
 */

/**
 * 这是 Javadoc 注释
 */

Javadoc 注释可包含 HTML 标签，例如：

/**
 * <p>支持HTML段落标签</p>
 * <a href="https://example.com">外部链接</a>
 */

2.2. 注释格式

Javadoc 注释可放在任何需要文档化的类、方法或字段上方。这些注释通常包含两部分：

描述部分（说明注释对象的作用）
独立块标签（以 @ 开头），用于描述特定元数据

常用块标签包括：

@author 作者信息
@param 参数说明
@return 返回值说明
@see 参考链接
@since 起始版本
@deprecated 废弃说明

完整标签列表可参考 Oracle 官方指南

2.3. 类级别注释

类级 Javadoc 注释示例：

/**
 * Hero 是我们使用的主要实体类...
 * 
 * 详见 {@link com.baeldung.javadoc.Person} 类
 * @author 美国队长
 * 
 */
public class SuperHero extends Person {
    // 字段和方法
}

关键点：

独立标签（如 @author）必须单独成行
内联标签（如 {@link}）可出现在任意位置，用花括号包裹
{@link} 提供源代码引用的行内链接

2.4. 字段级别注释

字段注释通常无需块标签：

/**
 * 英雄的公开名称（广为人知）
 */
private String heroName;

⚠️ 私有字段默认不会生成文档，除非显式使用 -private 选项

2.5. 方法级别注释

方法注释可包含多种块标签：

/**
 * <p>这是方法的简单描述...
 * <a href="http://www.supermanisthegreatest.com">超人！</a>
 * </p>
 * @param incomingDamage 传入的伤害值
 * @return 英雄受击后的剩余生命值
 * @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
 * @since 1.0
 */
public int successfullyAttacked(int incomingDamage) {
    // 处理逻辑
    return 0;
}

常用方法标签说明： | 标签 | 用途 | 示例 | |------|------|------| | @param | 描述参数 | @param damage 伤害值 | | @return | 描述返回值 | @return 剩余生命值 | | @throws | 说明异常情况 | @throws IOException 文件读取失败 | | @since | 起始版本 | @since 1.0 | | @deprecated | 废弃说明 | @deprecated 使用新方法替代 |

3. 生成 Javadoc

3.1. 命令行工具

Javadoc 命令行工具功能强大但稍显复杂。直接运行 javadoc 会报错并提示所需参数。

基本用法：

user@baeldung:~$ javadoc -d doc src\*

参数说明：

-d doc：指定输出目录为 doc
src\*：指定源码路径（多个包需全部列出）

💡 推荐使用 IDE 的内置功能生成文档，更简单高效

3.2. Maven 插件

通过 Maven Javadoc 插件生成文档：

pom.xml 配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.6.2</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
                <!-- 自定义标签配置 -->
            </tags>
        </plugin>
    </plugins>
</build>

生成命令：

user@baeldung:~$ mvn javadoc:javadoc

文档将生成在 target/site/apidocs 目录。

生成效果预览：

类概览页面： overview

方法详情页面： ss javadoc

3.3. 自定义标签

命令行添加自定义标签：

user@baeldung:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

参数格式：-tag <标签名>:<位置>:<标题>

使用自定义标签：

/**
 * 示例注释...
 * @location 纽约
 * @returns 返回值说明
 */

Maven 插件配置自定义标签：

<tags>
    <tag>
        <name>location</name>
        <placement>a</placement>
        <head>Notable Places:</head>
    </tag> 
</tags>

✅ 推荐使用 Maven 配置，避免每次执行时重复指定

4. 总结

本文介绍了 Javadoc 的基础用法和文档生成方法：

掌握注释结构和标签用法
通过命令行或 Maven 生成文档
支持自定义标签扩展功能

最佳实践建议：

优先使用 IDE 内置工具生成文档
Maven 项目推荐使用 maven-javadoc-plugin
保持注释简洁，避免过度使用 HTML

完整代码示例请参考 GitHub 仓库

Persistence

REST

Security