新的 javadoc 注释@apiNote

java javadoc java-8

2022-09-01 21:05:54

我在LongStream类文档中发现了一个新的和未记录的javadoc标签。javadoc 标签@apiNote似乎用于详细说明有关方法的一些解释，但没有关于此标签的文档或发行说明。

它的真正目的是什么？其文档在哪里？

使用@apiNote编译的javadoc示例可以在Reduce方法文档中找到

答案 1

从@bargenson引用的邮件列表项目：

这些标记是通过使用 javadoc 工具命令行上的 -tag 功能启用的。它们不是作为标准的javadoc标签提出的，并且在未来的Java版本中可能会以不同的方式实现。由于它们仅作为 JDK API 文档的自定义标记实现，因此您无法在自己的代码中自动使用它们。（当然，如果您喜欢这些标签，可以将相同的命令行选项添加到javadoc调用中）。

所以它们根本不是标准的Javadoc标签。

答案 2

我会说他们现在是“官方的”，如果不是标准的。请参见 JDK-8068562。正如Nicolai在上面指出的那样，他的博客文章New Javadoc Tags@apiNote，@implSpec和@implNote给出了很好的概述。它们由 Netbeans 支持，由 IntelliJ 支持，并由 Eclipse 支持。它们在 Effective Java，Third Edition 中进行了讨论和推荐。它们在整个核心 Java 库源代码中使用。