新的 javadoc 注解 @apiNote

Question

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

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

使用@apiNote 编译的javadoc 示例可以在Reduce method documentation 找到

Answer 1

来自@bargenson 引用的邮件列表项：

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

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

Answer 2

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