新的javadoc注释@apiNote

Question

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

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

可以在Reduce method documentation

找到使用@apiNote的已编译的javadoc示例

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，并且在有效Java第三版中进行了讨论和推荐。在整个核心Java库源代码中都使用了它们。

它们在Eclipse中不会造成任何问题，但是Eclipse在通过Content Assist支持它们方面一直滞后，因此您可能需要对Eclipse Bug 540485进行投票。