新的 javadoc 注解 @apiNote

Posted 2023-02-21

【中文标题】新的 javadoc 注解 @apiNote

【英文标题】：New javadoc annotation @apiNote

【发布时间】：2014-05-05 14:07:35

【问题描述】：

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

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

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

【问题讨论】：

您可以在 OpenJDK 邮件列表中找到有关它的信息：mail.openjdk.java.net/pipermail/core-libs-dev/2013-April/…

您可以在我的帖子New Javadoc Tags @apiNote, @implSpec and @implNote 中找到更多关于此标签及其两个伙伴@implNote 和implSpec 的起源、意义和支持。

【参考方案1】：

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

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

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

【参考方案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 库源代码中使用。

【讨论】：

来自您的第一个链接：'新标签是特定于 JDK 的，目前不打算成为标准 javadoc 标签。'