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
*/
@Override
public 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
*/
@Override
public 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();
展示
中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。
更多推荐
8
0- 0
已为社区贡献1条内容
所有评论(0)