03、Java 18 新特性 - Javadoc 中支持代码片段

在Java 18 之前,已经支持在 Javadoc 中引入代码片段,这样可以在某些场景下更好的展示描述信息,但是之前的支持功能有限,比如我想高亮代码片段中的某一段代码是无能为力的。现在 Java 18 优化了这个问题,增加了 @snippet 来引入更高级的代码片段。

在Java 18 之前,使用 <pre>{@code ...}</pre> 来引入代码片段。

 /**
  * 时间工具类
  * Java 18 之前引入代码片段:
  * <pre>{@code
  *     public static String timeStamp() {
  *        long time = System.currentTimeMillis();
  *         return String.valueOf(time / 1000);
  *     }
  * }</pre>
  *
  */

生成Javadoc 之后,效果如下:
 

3.1、高亮代码片段

从Java 18 开始,可以使用 @snippet 来生成注释,且可以高亮某个代码片段。

/**
 * 在 Java 18 之后可以使用新的方式
 * 下面的代码演示如何使用 {@code Optional.isPresent}:
 * {@snippet :
 * if (v.isPresent()) {
 *     System.out.println("v: " + v.get());
 * }
 * }
 *
 * 高亮显示 println
 *
 * {@snippet :
 * class HelloWorld {
 *     public static void main(String... args) {
 *         System.out.println("Hello World!");      // @highlight substring="println"
 *     }
 * }
 * }
 *
 */

效果如下,更直观,效果更好。
 

3.2、正则高亮代码片段

甚至可以使用正则来高亮某一段中的某些关键词:

/** 
  * 正则高亮:![在这里插入图片描述](https://img-blog.csdnimg.cn/ae58ca6d07a542e98479b660d284b991.png#pic_center)

  * {@snippet :
  *   public static void main(String... args) {
  *       for (var arg : args) {                 // @highlight region regex = "\barg\b"
  *           if (!arg.isBlank()) {
  *               System.out.println(arg);
  *           }
  *       }                                      // @end
  *   }
  *   }
  */

生成的Javadoc 效果如下:
 

3.3、替换代码片段

可以使用正则表达式来替换某一段代码。

 /** 
   * 正则替换:
   * {@snippet :
   * class HelloWorld {
   *     public static void main(String... args) {
   *         System.out.println("Hello World!");  // @replace regex='".*"' replacement="..."
   *     }
   * }
   * }
   */

这段注释会生成如下 Javadoc 效果。

class HelloWorld {
   
     
    public static void main(String... args) {
   
     
        System.out.println(...);
    }
}

3.4、附:Javadoc 生成方式

# 使用 javadoc 命令生成 Javadoc 文档
➜  bin ./javadoc -public -sourcepath ./src -subpackages com -encoding utf-8 -charset utf-8 -d ./javadocout
# 使用 Java 18 的 jwebserver 把生成的 Javadoc 发布测试
➜  bin ./jwebserver -d /Users/darcy/develop/javadocout

访问测试: