Java修炼终极指南：37. 在Java API文档中添加代码片段

我相信你对为你的项目生成Java API文档（Javadoc）非常熟悉。我们可以通过命令行使用Javadoc工具、通过IDE支持、通过Maven插件（maven-javadoc-plugin）等方式来生成Javadoc。

在编写Javadoc时，一个常见的情况是添加代码片段来举例说明非平凡类或方法的使用。在JDK 18之前，可以通过`{@code…}`或`<pre>`标签在文档中添加代码片段。添加的代码被视为纯文本，不会进行正确性验证，也无法被其他工具发现。让我们快速举一个例子：

/** * 一个带有激光测距功能的测距仪，测距范围从0到60英尺， * 包括高精度计算表面积和体积 * * <pre>{@code * Telemeter.Calibrate.at(0.00001); * Telemeter telemeter = new Telemeter(0.15, 2, "IP54"); * }</pre> */ public class Telemeter { // ... }

在捆绑的代码中，你可以看到完整的示例。Javadoc是通过maven插件（maven-javadoc-plugin）在构建时生成的，所以只需触发构建即可。

从JDK 18开始，JEP 413 – Java API文档中的代码片段，我们通过全新的`{@snippet…}`标签支持在文档中添加代码片段。通过`@snippet`添加的代码可以被第三方工具发现和验证（但不是javadoc工具本身）。

例如，之前的代码片段可以通过`@snippet`添加如下：

/** * 一个带有激光测距功能的测距仪，测距范围从0到60英尺， * 包括高精度计算表面积和体积 * * {@snippet : * Telemeter.Calibrate.at(0.00001); * Telemeter telemeter = new Telemeter(0.15, 2, "IP54"); * } */ public class Telemeter { // ... }

输出的截图如下所示：

图2.13 – 来自`@snippet`的简单输出

有效的代码从分号（:）后面的换行符开始，并在关闭右大括号（}）之前结束。代码的缩进与代码块中的缩进相同，因此编译器会移除偶然的空白字符，我们可以根据关闭右大括号（}）来缩进代码。请查看以下图表：

图2.14 – 代码片段的缩进

在上面的例子中，关闭右大括号与打开左大括号对齐，而在下面的例子中，我们将关闭右大括号向右移动了。

**添加属性**

我们可以通过名称=值对为`@snippet`指定属性。例如，我们可以通过`lang`属性为代码片段提供编程语言提示。属性的值可供外部工具使用，并出现在生成的HTML中。以下是两个例子：

* {@snippet lang="java" : * Telemeter.Calibrate.at(0.00001); * Telemeter telemeter = new Telemeter(0.15, 2, "IP54"); * }

在生成的HTML中，你将很容易识别到这个属性作为`<code class="language-java"> … </code>`。

如果代码是结构化文本，如属性文件，则可以遵循以下示例：

* {@snippet lang="properties" : * telemeter.precision.default=42 * telemeter.clazz.default=2 * }

在生成的HTML中，你将得到`<code class="language-properties"></code>`。

接下来，让我们看看如何更改代码片段中显示的内容。

**使用标记注释和区域**

我们可以通过标记注释来可视化地更改代码片段。标记注释出现在行尾，并包含一个或多个标记标签，形式为`@name args`，其中args通常是name=value对。常见的标记注释包括高亮显示、链接和内容（文本）修改。

**高亮显示**

可以通过不带参数的`@highlight`来高亮显示整行代码，如下图所示：

图2.15 – 高亮显示整行代码

如你在此图中看到的，第一行代码被加粗了。如果我们想高亮显示多行代码，则可以定义区域。一个区域可以被视为匿名的或具有显式名称。匿名区域由标记标签的参数中的单词region界定，并在区域末尾放置`@end`标签。以下是一个高亮显示两个区域（一个匿名的和一个名为R1的）的示例：

图2.16 -使用区域高亮显示代码块

正则表达式允许我们高亮显示代码的特定部分。例如，高亮显示引号之间的所有内容可以通过`@highlight regex='".*"'`来实现。或者，仅高亮显示单词Calibrate可以通过substring="Calibrate"参数来实现，如下图所示：

图2.17 – 仅高亮显示单词"Calibrate"

接下来，让我们谈谈在代码中添加链接。

**链接**

可以通过`@link`标签在代码中添加链接。常见的参数是substring="…"和target="…"。例如，以下代码片段为文本Calibrate提供了一个链接，该链接导航到Calibrate.at()方法的描述：

图2.18 – 在代码中添加链接

接下来，让我们看看如何修改代码的文本。

**修改代码的文本**

有时我们可能需要更改代码的文本。例如，我们想在文档中渲染`Telemeter.Calibrate.at(eps, "HIGH");`而不是`Telemeter.Calibrate.at(0.00001, "HIGH");`。因此，我们需要将0.00001替换为eps。这正是`@replace`标签的用途所在。常见参数包括substring="…"（或regex="…"）和replacement="…"。以下是代码片段：

图2.19 – 替换代码的文本

如果你需要在代码块中执行多个替换，则依赖于区域。在以下示例中，我们对代码块应用了一个简单的正则表达式：

图2.20 – 通过简单正则表达式和匿名区域应用多个替换

如果你需要在同一行上执行更多替换，只需链式使用多个`@replace`标签（此语句适用于所有标签，如`@highlight`、`@link`等）。

**使用外部片段**

到目前为止，我们只使用了内联片段。但是，有些情况下使用内联片段不是一个方便的方法（例如，如果我们需要重复文档中的某些部分）或无法使用它们（例如，如果我们要嵌入/*…*/注释，这些注释无法添加到内联片段中）。

对于这些情况，我们可以使用外部片段。无需任何进一步配置，JDK会自动识别放置在包含片段标签的包（文件夹）的子文件夹中的外部片段。这个子文件夹应命名为snippet-files，并且可以包含作为Java源代码、纯文本文件或属性文件的外部片段。在以下图表中，我们有一个名为MainSnippet.txt的单个外部文件：

图2.21 – snippet-files中的外部片段

如果外部片段不是Java文件，则可以通过`{@snippet file …}`加载，如下所示：

{@snippet file = MainSnippet.txt} {@snippet file = "MainSnippet.txt"} {@snippet file = 'MainSnippet.txt'}

但是，我们还可以自定义外部片段的位置和文件夹名称。例如，让我们将外部片段放置在名为snippet-src的文件夹中，如下所示：

图2.22 – 自定义文件夹和位置中的外部片段

这次，我们需要指示编译器在哪里找到外部片段。这是通过向javadoc传递`–snippet-path`选项来完成的。当然，你可以通过命令行、IDE或maven-javadoc-plugin来传递它，如下所示：

<additionalJOption> --snippet-path C:...srcsnippet-src </additionalJOption>

这个路径相对于你的机器，所以请根据你的pom.xml文件相应地调整它。接下来，可以像之前对MainSnippet.txt所做的那样加载AtSnippet.txt和ParamDefaultSnippet.properties。但是，加载Java源代码，如DistanceSnippet.java，可以通过`{@snippet class…}`来完成，如下所示：

{@snippet class = DistanceSnippet} {@snippet class = "DistanceSnippet"} {@snippet class = 'DistanceSnippet'}

但是，不要明确添加.java扩展名，因为你会得到一个错误，指出在源代码路径或片段路径上找不到文件：DistanceSnippet/java.java。

**外部片段中的区域**

外部片段通过`@start region=…`和`@end region=…`支持区域。例如，在AtSnippet.txt中，我们有以下区域：

// 这是文档中使用的示例 // @start region=only-code Telemeter.Calibrate.at(0.00001, "HIGH"); // @end region=only-code

现在，如果我们按如下方式加载区域：

{@snippet file = AtSnippet.txt region=only-code}

我们只会得到区域中的代码，而不会得到文本`// 这是文档中使用的示例`。以下是另一个带有两个区域的属性文件的示例：

# @start region=dist sc=[0,0] ec=[0,0] interpolation=false # @end region=dist # @start region=at eps=0.1 type=null # @end region=at

dist区域用于在文档中显示distance()方法参数的默认值：

图2.23 – 使用dist区域展示了distance()方法参数的默认值

而at区域则用于在文档中显示at()方法参数的默认值：

图2.24 – 使用'at'区域展示了at()方法参数的默认值

在外部片段中，我们可以使用与内联片段中相同的标签。例如，在以下图表中，你可以看到AtSnippet.txt的完整源代码：

图2.25 – AtSnippet.txt的源代码

请注意@highlight和@replace的存在。

从JDK 19开始，Javadoc的搜索功能也得到了改进。换句话说，JDK 19 可以生成一个独立的搜索页面，用于在Javadoc API文档中搜索。此外，搜索语法也得到了增强，以支持多个搜索词。

你可以在捆绑的代码中练习这些示例。通过添加适当的代码片段和标记，你可以为你的Java API文档提供更加丰富和有用的内容，帮助读者更好地理解和使用你的代码库。