Java 23：JavaDoc 重大升级，支持Markdown文档注释

Java 23 带来的JEP 467（Markdown文档注释）彻底改变了传统 JavaDoc 的编写方式。通过引入 Markdown 语法，开发者不仅能更高效地编写文档，还能显著提升代码注释的可读性与维护性。本文将结合JDK 23实战案例，深入解析这一特性的核心价值与使用方法。

背景信息

JavaDoc自Java 1.1版本引入以来，一直采用基于HTML的文档注释格式，结合@标签（如@param、@return）提供结构化信息。然而，随着技术文档编写工具的演进，Markdown已成为开发者广泛使用的标准格式，其简洁语法和易读性显著提升了文档维护效率。

过去，开发者常需手动编写HTML与JavaDoc标签的混合代码，导致文档可读性降低且维护成本高。例如，格式复杂的参数列表或代码示例需要嵌套HTML标签，增加了编写负担。此外，第三方工具（如Asciidoctor、DocFX）虽支持Markdown，但需额外配置或插件，导致Java生态中文档工具碎片化。

为应对这些问题，Java社区长期呼吁将Markdown原生支持纳入JavaDoc。JEP 467的提出经历了多次草案迭代，最终在Java 23中落地，标志着Java官方文档体系向现代标记语言的正式兼容，进一步简化开发流程并提升协作效率。

简化与兼容并存

JEP 467的核心目标可概括为三点：

• 简化文档编写：用轻量级Markdown替代复杂的HTML标签，降低学习成本。
• 增强可读性：注释更贴近自然语言，减少格式噪音。
• 兼容性保障：保留对传统JavaDoc标签（如@param、@return）和HTML的支持，确保老代码平滑迁移。

例如，以下对比展示了同一方法注释在Markdown与HTML下的差异：

传统JavaDoc

/**
 * 计算两个数的乘积。
 * <p>
 * 示例：{@code multiply(2, 3) == 6}
 * @param a 第一个数
 * @param b 第二个数
 * @return 乘积结果
 */
public int multiply(int a, int b) { return a * b; }

Markdown注释（JDK 23）

/// 计算两个数的乘积。  
/// 示例：`multiply(2, 3) == 6`  
///  
/// @param a 第一个数  
/// @param b 第二个数  
/// @return 乘积结果  
public int multiply(int a, int b) { return a * b; }

Markdown与JavaDoc的融合

JEP 467重新定义了注释格式，并扩展了Markdown支持：

• 注释块标记

使用///替代/**... */，每行注释以///开头，支持多行书写。

• 基础Markdown语法

  • 段落：空行分隔，无需<p>标签。
  • 代码块：使用单反引号（```）或三个反引号（`````）包裹。
  • 加粗/斜体：支持**和*。
  • 列表：无序列表（-）、有序列表（1.）和嵌套列表均可用。

• 链接与引用

  • 内链：[类名](类路径)替代{@link 类路径}。
  • 外链：[链接文本](URL)。
  • 引用：> 引用内容。

• 特殊处理

传统JavaDoc标签（如@since、@author）需保留，但内容部分可用Markdown增强。

实战示例

以下示例展示了如何在JDK 23中编写Markdown注释。

1. 准备 JDK 23 环境。

从 Oracle 网站下载 JDK 23 安装包，并进行安装配置。

[root@el7 ~]# java -version
java version "23.0.2" 2025-01-21
Java(TM) SE Runtime Environment (build 23.0.2+7-58)
Java HotSpot(TM) 64-Bit Server VM (build 23.0.2+7-58, mixed mode, sharing)

2. 编写带JavaDoc注释的Java类。

package com.example;

import java.util.List;

/**
 * 计算数学工具类
 * @author Shawn Yan
 * @version 1.0
 * @since Java 23
 */
public class MathUtils {
  
  /** 
   * 计算斐波那契数列的第n项
   * @param n 项数（必须大于0）
   * @return 第n项的值
   * @throws IllegalArgumentException 如果n小于等于0
   */
  public int fibonacci(int n) {
    if (n <= 0) {
      throw new IllegalArgumentException("n must be > 0");
    }
    // 实现代码...
	return 0;
  }
  
  /** 
   * 计算列表中所有元素的平均值
   * @param nums 数值列表
   * @return 平均值（若列表为空则返回0）
   */
  public double average(List<Integer> nums) {
    // 实现代码...
	return 0;
  }
}

3. 编译Java文件

确保Java文件已正确编译，生成.class文件。

[root@el7 ~]# javac MathUtils.java
[root@el7 ~]# ls MathUtils.*
MathUtils.class  MathUtils.java

4. 使用Javadoc生成文档

在命令行中运行以下命令（假设当前目录包含MathUtils.class文件）：

javadoc -d docs -encoding UTF-8 -charset UTF-8 MathUtils.java

参数说明：

• -d docs：指定生成的文档输出到docs目录。
• -encoding UTF-8 -charset UTF-8：确保中文等字符不乱码。
• MathUtils.java：指定要生成文档的源文件。

5. 查看生成的文档

在docs目录下会生成HTML文件，打开index.html即可查看API文档。

6. 将上述代码中的注释修改为 Markdown 格式。

package com.example;

import java.util.List;

///
/// **计算数学工具类**
/// @author Shawn Yan
/// @version 1.1
/// @since Java 23
/// 演示Markdown语法支持：  
/// - **代码块**：
///   ```  
///   System.out.println("Hello, Markdown!");
///   ```
///
public class MathUtils {
  
  ///  
  /// 计算斐波那契数列的第n项
  /// @param n 项数（必须大于0）
  /// @return 第n项的值
  /// @throws IllegalArgumentException 如果n小于等于0
  /// 
  public int fibonacci(int n) {
    if (n <= 0) {
      throw new IllegalArgumentException("n must be > 0");
    }
    // 实现代码...
	return 0;
  }
  
  /** 
   * 计算列表中所有元素的平均值
   * @param nums 数值列表
   * @return 平均值（若列表为空则返回0）
   */
  public double average(List<Integer> nums) {
    // 实现代码...
	return 0;
  }
}

7. 再次生成文档。

[root@el7 ~]# vi MathUtils.java
[root@el7 ~]# javac MathUtils.java
[root@el7 ~]# ls MathUtils.*
MathUtils.class  MathUtils.java
[root@el7 ~]# javadoc -d docs -encoding UTF-8 -charset UTF-8 MathUtils.java
Loading source file MathUtils.java...
Constructing Javadoc information...
Creating destination directory: "docs/"
Building index for all the packages and classes...
Standard Doclet version 23.0.2+7-58
Building tree for all the packages and classes...
Generating docs/com/example/MathUtils.html...
MathUtils.java:21: warning: use of default constructor, which does not provide a comment
public class MathUtils {
       ^
Generating docs/com/example/package-summary.html...
Generating docs/com/example/package-tree.html...
Generating docs/overview-tree.html...
Generating docs/allclasses-index.html...
Building index for all classes...
Generating docs/allpackages-index.html...
Generating docs/index-all.html...
Generating docs/search.html...
Generating docs/index.html...
Generating docs/help-doc.html...
1 warning

8. 查看生成的文档。

注意事项

1. 兼容性

   • 传统标签与Markdown在 JDK 23 支持混合使用。
   • 复杂HTML（如自定义样式）可能无法完全转换，建议逐步迁移。

2. 工具支持

   • IDE集成：IntelliJ IDEA、VS Code Java插件已支持Markdown注释语法高亮与实时预览。
   • 文档生成：Javadoc需升级至JDK 23版本，或使用第三方工具支持Markdown输出。

总结

JEP 467 不仅是语法层面的改进，更是Java对开发者习惯的深度适配。通过Markdown注释，JavaDoc终于摆脱了“写文档的痛苦”，让代码与文档真正成为开发者的“第二语言”。使用Markdown格式编写文档，可减少格式调试时间，团队协作更高效。

Have a nice day ~ ☕

🌻 往期精彩 ▼

• 错过一个亿，MySQL免费认证页面下架了
• MySQL 30 周年庆！MySQL 8.4 认证免费考！这次是认真的。。。
• 卷疯了！众数据库厂商的征文汇
• TiDB社区&墨天轮 | 专栏征文大赛全面开启，期待您分享TiDB业务实战和运维开发那些事儿
• 「合集」三年 50 篇，TiDB 干货全收录
• 「合集」MySQL 8.x 系列文章汇总
• TiDB 新朋友 DBdoctor
• Oracle 数据库全面升级为 23ai
• 广东的崖山，中国的崖山数据库
• TiDB v8 发版！超硬核 v8 引擎！
• 几张图带你了解 TiDB 架构演进
• 一文带你了解 KING BASE 金仓数据库
• 全球 Oracle ACE 社区突破 500 位成员
• 如何选择适合的 MySQL Connector/J 版本
• 即将告别 PG 12，建议升级到 PG 16.3 版本
• G-Star Landscape 2.0 重磅发布，助力开源生态再升级
• 【一文讲透（番外篇）】如何编译安装KWDB v2.0.4数据库
• TiDB x DeepSeek 打造更好用的国产知识库问答系统解决方案

– / END / –

👉 这里可以找到我

• 微信公众号：@少安事务所 #少安事务所
• ITPUB：@少安事务所
• TiDB 专栏：@ShawnYan
• PGFans: @严少安
• 墨天轮：@严少安

👉 这里有得聊

如果对国产基础软件（操作系统、数据库、中间件）感兴趣，可以加群一起聊聊。
关注微信公众号：少安事务所，后台回复[群]，即可看到入口。

如果这篇文章为你带来了灵感或启发，请帮忙『三连』吧，感谢！ღ( ´･ᴗ･` )~