java18学习笔记-JavaDoc的@snippet注释标签
| 416: | Reimplement Core Reflection with Method Handles |
java18为JavaDoc的标准文档引入@snippet标签，以简化在API文档中包含示例源代码的过程。
一下文档详细的介绍了JavaDoc的各个标签的作用，引入版本，代码示例和展示
JavaDoc的其他标签
JDK 1.0引入JavaDoc并同时引入下面标签
@author - 标识作者信息
@version - 版本号说明
@param - 方法参数描述
@return - 返回值说明
@see - 相关引用链接
@deprecated - 标记已废弃API
@exception/@throws - 异常说明（1.2后推荐@throws）
代码示例
import java.io.IOException;
public class JavaDocTest {/*** 测试1.0加入的JavaDoc标签* @see java.lang.Object#toString()* @version V1.0* @author 张先生* @param args 参数* @return 返回值* @deprecated* @throws IOException*/public String test1(String... args) throws IOException {System.out.println("Hello World!");return "";}public JavaDocTest() {}
}展示
JDK 1.1新增
@since - 引入版本
代码示例
/**** @since djk1.0*/public String test2(String... args) {System.out.println("Hello World!");return "";}展示
JDK 1.2新增
{@link} - 内联式引用链接
@serial - 序列化字段说明
@serialData - 序列化数据规范
{@link}和@see功能类似，{@link}可以放在文档中间而@see只能作为开头使用
代码示例
/*** 哈哈哈，请看方法{@link java.lang.Object#toString()}*/public String test3(String... args) {System.out.println("Hello World!");return "";}展示
JDK 1.3新增
{@docRoot} (1.3) - 文档根路径引用
标注文档引用路径。<a href="{@docRoot}/../specs/serialization/protocol.html#stream-elements">显示的文字</a> 需要配合a标签使用
（但是测试的时候并不能引用到文档而且，也没有地址错误检查，@link和@see有）
代码示例
选自java18中 String的chars()方法
/*** Returns a stream of {@code int} zero-extending the {@code char} values* from this sequence. Any char which maps to a <a* href="{@docRoot}/java.base/java/lang/Character.html#unicode">surrogate code* point</a> is passed through uninterpreted.** @return an IntStream of char values from this sequence* @since 9*/@Overridepublic IntStream chars() {return StreamSupport.intStream(isLatin1() ? new StringLatin1.CharsSpliterator(value, Spliterator.IMMUTABLE): new StringUTF16.CharsSpliterator(value, Spliterator.IMMUTABLE),false);}展示
JDK 1.4新增
{@inheritDoc} (1.4) - 继承父类注释
{@linkplain} (1.4) - 带纯文本的链接
{@value} (1.4) - 常量值引用
@inheritDoc 可以继承父类注释，自己写的优先级更高
@linkplain 在java18测试下和@link并无差异
@value可以引入静态字段{@value #静态字段名}
代码示例
为了方便直接类implements CharSequence然后实现方法
并加入了静态变量string
private static final String string="HaHaHaHaHaHa";/*** 自己写的优先级更高哦* 纯文本的链接linkplain{@linkplain java.lang.Object#toString() 显示的文本 }* 链接link{@link java.lang.Object#toString() 显示的文本}** 测试@value {@value #string}.** @inheritDoc* @return 返回固定0*/@Overridepublic int length() {return 0;}展示
JDK 1.5新增
{@code} - 代码片段标记
{@literal} - 原样文本输出
@code以代码片段展示，更友好的查看代码在java18中加入了@snippet，更好的处理
@literal以原文本展示，不会解析html标签等
代码示例
/*** 以代码形式展示{@code CODE}* <a href="{@docRoot} ">点击这里</a>* {@literal <a href="{@docRoot} ">点击这里</a> }** @param args* @return*/public String test5(String... args) {System.out.println("Hello World!");return "";}展示
JDK 8新增
@apiNote - API使用说明
@implSpec - 实现规范说明
@implNote - 实现细节备注
@apiNote - 一般在jdk提供的Util里面会有使用说明，例如Arrays.compare(T[] a, T[] b)使用说明必须传入非空元素或引用
@implSpec - 一般是能够继承或实现的方法上备注，例如CharSequence.isEmpty()方法说明了默认实现
@implNote - 一般写在继承的某个方法上，对比与父类的一些改变等，例如List中的sort(Comparator<? super E> c)方法
代码示例
List<String> list1 = Arrays.asList(strings1);list1.sort(String::compareTo);展示
@snippet标签
相当于扩展了@code
属性
class— 包含代码片段内容的类file— 包含代码片段内容的文件id— 代码段的标识符，用于标识生成的文档中的代码段lang— 代码段的语言或格式region- 要显示的内容中区域的名称-
start— 标记区域的开始region— 区域名称
-
end- 标记区域的终点region— 地区名称;对于匿名区域可以省略
-
-
highlight- 突出显示行或区域内的文本substring- 要突出显示的文字文本regex-要突出显示的文本的正则表达式region- 用于定义查找要突出显示的文本的范围的区域type- 突出显示的类型，例如 、 或bolditalichig hlighted(默认)
-
replace- 替换行或区域内的文本substring— 要替换的文字文本regex— 要替换的文本的正则表达式region- 用于定义查找要突出显示的文本的范围的区域replacement— 替换文本
-
link- 链接行或区域内的文本substring— 要替换的文字文本regex— 要替换的文本的正则表达式region- 用于定义查找要突出显示的文本的范围的区域target— 链接的目标，以适合 {@link ...} 标签的形式之一表示type— 链接类型：link（默认）linkplain
highlight replace link
代码示例
/*** A simple program.* {@snippet :* test6 {* System.out.println("Hello World!"); // @highlight substring="println"* System.out.println("Hello World!"); // @highlight substring="println" type = "highlighted"* System.out.println("Hello World!"); // @highlight substring="println" type = "bold"* System.out.println("Hello World!"); // @highlight substring="println" type = "italic"* System.out.println("94123"); // @highlight regex="[0-9]+"* for (var arg : args) { // @highlight region regex = "\barg\b"* if (!arg.isBlank()) {* System.out.println(arg);* }* } // @end* System.out.println("Hello World!"); // @replace regex='".*"' replacement="..."* System.out.println("Hello World!"); // @replace substring ='System' replacement="..."* System.out.println("94123"); // @replace regex="[0-9]+" replacement="xxx"* for (var arg : args) { // @replace region regex = "\barg\b" replacement="..."* if (!arg.isBlank()) {* System.out.println(arg);* }* }* System.out.println("Hello World!"); // @link regex='".*"' target="System#out"* System.out.println("Hello World!"); // @link substring="System.out" target="System#out"* System.out.println("94123"); // @link regex="[0-9]+" target="System#out"* for (var arg : args) { // @link region regex = "\barg\b" target="System#out"* if (!arg.isBlank()) {* System.out.println(arg);* }* }* }* }*/public String test6(String... args) {System.out.println("Hello World!");return "";}展示
file
代码示例
创建文件夹snippet-files（file和class默认的路径会带上这个，class有个问题是此目录下的创建class会报错，复制进去class文件直接报错）创建文件config.properties
文件中写入
// @start region="example" id="111"
demo.serialnumber=61E3F9C4A2E5D296DE76463E9AB23372CA0EB28DE249F3CA9881C401BFD1710C
//@end JavaDocTest javaDocTest = new JavaDocTest();
展示
