新的javadoc注释@apiNote

Question

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

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

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

Answer 1

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

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

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

Answer 2

如果不是标准的，我会说它们现在是“官方的”。请参阅JDK-8068562。正如 Nicolai 上面指出的，他的博客文章New Javadoc Tags @apiNote、@implSpec 和 @implNote给出了很好的概述。它们得到 Netbeans 的支持，最近Eclipse 中的Content Assist认可了它们。在Effective Java，第三版中讨论并推荐了它们。它们在整个核心 Java 库源代码中使用。