可编译的 Javadoc 代码段
相关 JEP:
干净整洁更新及时并且有规范的示例的 API 文档会让你获益良多,并且如果 API 文档的代码如果能编译,能随着你的源码变化而变化,就更完美了,Java 18 就给了 Javadoc 这些特性。
我们编写一个 Maven 项目试一下(代码库地址:https://github.com/HashZhang/code-snippet-test )
首先,我们想在普通 maven 项目的 src/main/java
和 src/test/java
以外新添加一个目录 src/demo/java
用于存放示例代码。因为示例代码我们并不想打包到最后发布的 jar 包,示例代码也需要编译,所以我们把这个示例代码目录标记为测试代码目录(为啥不放入 src/test/java
,因为我们还是想区分开示例代码与单元测试代码的):
我们需要 maven 插件来执行生成 javadoc,同时我们要指定代码段扫描的目录(即你的源码中,执行代码段文件所处于的目录,这个目录我们这里和源码目录 src/main/java
隔离开了,是 src/demo/java
):
首先,我们创建我们的 API 类,即:
可以看到,我们在注释中指定了代码段读取的文件以及读取的区域,我们现在来编写示例代码:
从示例代码中,我们可以看到对于引用区域的指定(位于 @start
与 @end
之间).
目前项目结构是:
执行 mvn javadoc:javadoc
,在 target/site
目录下就能看到生成的 Javadoc,Javadoc 中可以包含你项目中的代码段:
你还可以高亮你的一些注释,或者使用 CSS 编辑样式,这里就不再赘述了
预览的新特性
Switch 模式匹配(第二次预览)
Java 17 中的第一次预览 Java 18 中的第二次预览
Java 17 中正式发布了 Sealed Class(封闭类),在这特性的基础上,我们可以在 Switch 中进行模式匹配了,举一个简单的例子:
在某些情况下,我们可能想枚举一个接口的所有实现类,例如:
我们如何能确定我们枚举完了所有的 Shape 呢? Sealed Class 这个特性为我们解决这个问题,Sealed Class 可以在声明的时候就决定这个类可以被哪些类继承:
Sealed Class (可以是 abstract class 或者 interface )在声明时需要指定所有的实现类的名称。针对继承类,有如下限制:
- Sealed Class 的继承类必须和 Sealed Class 在同一个模块下,如果没有指定模块,就必须在同一个包下
- 每个继承类必须直接继承 Sealed Class,不能间接继承
- 每个继承类必须是下面三种之一:
- final 的 class,Java Record 本身就是 final 的
- sealed 的 class,可以进一步指定会被哪些子类实现
- non-sealed 的 class,也是一种扩展,但是打破 Sealed Class 的限制,Sealed Class 不知道也不关心这种的继承类还会有哪些子类。
举个例子即:
加入了 Switch 模式匹配之后,上面的 area 方法就可以改写成(我们需要在编译参数和启动参数中加上 --enable-preview
启用预览):