1. 概述
完善的文档能帮助开发者轻松使用库。Javadoc 是生成 Java 代码文档的利器。Java 18 引入了 @snippet 标签，让代码片段集成到文档中变得异常简单。
本教程将探讨如何使用 @snippet 标签在文档中添加代码片段。
2. @snippet 标签之前
在 Java 18 之前，我们只能用 @code 标签添加代码片段。但这存在明显局限：
- ❌
@code标签将代码视为普通文本 - ❌ 不验证代码片段语法
- ❌ 无语法高亮功能
3. 使用 @snippet 标签
Java 18 引入 @snippet 标签解决了上述问题，它具备以下特性：
- ✅ 内置语法高亮
- ✅ 简化代码嵌入流程
- ✅ 支持从外部源导入代码
- ✅ 可通过 Compiler Tree API 验证代码片段
@snippet 标签有两种使用方式：内联片段和外部代码片段。
3.1 内联代码片段
内联片段允许直接在 Javadoc 注释中编写代码，语法结构如下：
{@snippet : "代码片段占位符" }
实际使用示例：
/**
* 以下代码展示 {@code helloBaeldung()} 方法内容
* {@snippet :
* public void helloBaeldung() {
* System.out.println("Hello From Team Baeldung");
* }
* }
*/
public class GreetingsInlineSnippet {
public void helloBaeldung() {
System.out.println("Hello From Team Baeldung");
}
}
生成的文档效果：
3.2 外部代码片段
支持从外部文件或类导入代码片段，需先用 @start 和 @end 标记目标区域。
以二分查找实现为例：
public class BinarySearch {
public int search(int[] list, int item) {
int index = Integer.MAX_VALUE;
int low = 0;
int high = list.length - 1;
// @start region="binary"
while (low <= high) {
int mid = high - low;
int guess = list[mid];
if (guess == item) {
index = mid; break;
} else if (guess > item) {
low = mid - 1;
} else {
low = mid + 1;
}
low++;
}
// @end region="binary"
return index;
}
}
在文档中引用该区域：
/**
* 外部代码片段展示二分查找的循环逻辑
* {@snippet class="BinarySearch" region="binary"}
*/
public class GreetingsExternalSnippet {
public void helloBinarySearch() {
System.out.println("Hi, it's great knowing that binary search uses a loop under the hood");
}
}
⚠️ 关键配置：
- 外部文件需放在
snippet-files目录 - 生成文档时需指定路径：
$ javadoc -d doc com.baeldung.snippettag --snippet-path snippet-files
生成效果：
从配置文件导入
同样支持从 properties 等文件导入：
# @start region="zone"
local.timezone = GMT+1
local.zip = 94123
# @end region="zone"
引用方式：
/**
* 时区配置示例
* {@snippet file="application.properties" region="zone"}
*
*/
public class GreetingsExternalSnippet {
// ...
}
效果：
3.3 @highlight 标签
使用 @highlight 标签突出显示关键代码：
/**
* {@snippet :
* public void helloBaeldung() {
* System.out.println("Hello From Team Baeldung"); // @highlight
* }
* }
*/
效果：
高级用法
精确高亮子字符串：
/** * {@snippet : * public void helloBaeldung() { * System.out.println("Hello From Team Baeldung"); // @highlight substring="println" * } * } */
多行范围高亮：
/** * 多行文本高亮 * {@snippet : * public void helloBaeldung() { * System.out.println("Hello From Team Baeldung"); // @highlight region substring="println" * String country = "USA"; * System.out.println("Hello From Team " + country); // @end * } * } */
3.4 @replace 标签
@replace 标签可动态替换代码中的文本：
/**
* {@snippet :
* public void helloBaeldung() {
* System.out.println("Hello From Team Baeldung"); // @replace regex='".*"' replacement="..."
* }
* }
*/
效果：
3.5 @link 标签
@link 标签可创建到其他文档的链接：
/**
* 链接示例
* {@snippet :
* public void helloBaeldung() {
* System.out.println("Hello From Team Baeldung"); // @link substring="System.out" target="System#out"
* }
* }
*/
效果：
4. 总结
本文介绍了 @snippet 标签的核心用法：
- ✅ 内联片段：直接在注释中编写代码
- ✅ 外部片段：从文件/类导入代码
- ✅ 增强标签：
@highlight/@replace/@link提升可读性
相比 @code 标签，@snippet 提供了更强大的代码集成能力，其语法高亮和代码验证特性使其成为 Javadoc 工具箱中的利器。
完整示例代码请查阅 GitHub 仓库。