【java21】java21新特性之JavaDoc中支持代码片段

news2024/9/24 17:41:33

在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!");
}