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注释。

准备 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)

编写带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;
  }
}

编译Java文件

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

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

使用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：指定要生成文档的源文件。

查看生成的文档

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

将上述代码中的注释修改为 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;
  }
}

再次生成文档。

[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

查看生成的文档。

注意事项

兼容性
- 传统标签与Markdown在 JDK 23 支持混合使用。
- 复杂HTML（如自定义样式）可能无法完全转换，建议逐步迁移。
工具支持
- IDE集成：IntelliJ IDEA、VS Code Java插件已支持Markdown注释语法高亮与实时预览。
- 文档生成：Javadoc需升级至JDK 23版本，或使用第三方工具支持Markdown输出。

总结

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

Have a nice day ~

– / END / –