在Java18之前,已经支持在JavaDoc中引入代码片段,这样可以在某些场景下更好的展示描述信息,但是之前的支持功能有限,比如我想高亮代码片段中的某一段代码是无能为力的。现在Java18优化了这个问题,增加了@snippet
来引入更高级的代码片段。
Java18之前@code的使用
在Java18之前,使用<pre>{@code ...}</pre>
来引入代码片段。
package com.morris.java21;
/**
* Java17中JavaDoc使用代码片段
*/
public class Java17DocDemo {
/**
* calc the sum of a and b.
*
* 代码如下:
* <pre>{@code
* public int add(int a, int b) {
* return a + b;
* }
* }</pre>
*
* @param a a
* @param b b
* @return sum of a and b
*/
public int add(int a, int b) {
return a + b;
}
}
生成JavaDoc:
>C:\Program\jdk\jdk-17.0.11\bin\javadoc.exe -d src\main\resources\java17-doc -encoding utf-8 src\main\java\com\morris\java21\Java17DocDemo.java
正在加载源文件src\main\java\com\morris\java21\Java17DocDemo.java...
正在构造 Javadoc 信息...
正在构建所有程序包和类的索引...
标准 Doclet 版本 17.0.11+7-LTS-207
正在构建所有程序包和类的树...
正在生成src\main\resources\java17-doc\com\morris\java21\Java17DocDemo.html...
正在生成src\main\resources\java17-doc\com\morris\java21\package-summary.html...
正在生成src\main\resources\java17-doc\com\morris\java21\package-tree.html...
正在生成src\main\resources\java17-doc\overview-tree.html...
正在构建所有类的索引...
正在生成src\main\resources\java17-doc\allclasses-index.html...
正在生成src\main\resources\java17-doc\allpackages-index.html...
正在生成src\main\resources\java17-doc\index-all.html...
正在生成src\main\resources\java17-doc\index.html...
正在生成src\main\resources\java17-doc\help-doc.html...
效果如下:
Java18中@snippet的使用
从Java18开始,可以使用@snippet
来生成注释,且可以高亮某个代码片段。
/**
* 高亮显示代码片段
* {@snippet :
* public void hello() {
* System.out.println("Hello World!"); // @highlight substring="println"
* }
* }
*
*/
public void hello() {
System.out.println("Hello World!");
}
效果如下:
高亮显示代码片段
可以在注释中使用@highlight
来指定高亮某些字段。
/**
* 高亮显示代码片段
* {@snippet :
* public void hello() {
* System.out.println("Hello World!"); // @highlight substring="println"
* }
* }
*
*/
public void hello() {
System.out.println("Hello World!");
}
效果如下:
正则高亮显示代码片段
甚至可以使用正则来高亮某一段中的某些关键词:
/**
* 正则高亮显示代码片段
* {@snippet :
* for (var arg : args) { // @highlight region regex = "\barg\b"
* if (!arg.isBlank()) {
* System.out.println(arg);
* }
* }// @end
* }
*
* @param args 打印数组
*/
public void print(String[] args) {
for (var arg : args) {
if (!arg.isBlank()) {
System.out.println(arg);
}
}
}
效果如下:
替换代码片段
可以使用正则表达式来替换某一段代码。
/**
* 替换代码片段
* {@snippet :
* public void hi() {
* System.out.println("Hello Java18!"); // @replace regex='".*"' replacement="..."
* }
* }
*
*/
public void hi() {
System.out.println("Hello Java18!");
}
效果如下: