@apinote_新的Javadoc标签@ apiNote，@ implSpec和@implNote

@apinote

如果您已经在使用Java 8，则可能会看到一些新的Javadoc标签： @apiNote ， @implSpec和@implNote 。 他们怎么了？ 如果要使用它们，该怎么办？

总览

该帖子将快速查看标签的来源和当前状态。 然后，它将解释它们的含义并详细说明如何将它们与IDE，Javadoc工具一起使用，以及如何通过Maven的Javadoc插件使用。

我在GitHub上创建了一个演示项目，以显示一些示例和Maven pom.xml的必要补充。 为了使Maven规避变得更容易，它已经包含了生成的javadoc 。

语境

起源

新的Javadoc标记是JSR-335的副产品，它引入了lambda表达式。 它们是在默认方法的上下文中提出的，因为它们需要更标准化和更细粒度的文档。

2013年1月，Brian Goetz 提出了动机，并为这些新标签提出了建议。 经过简短的讨论，三个星期后它变成了功能请求。 到4月， JDK Javadoc制造商已更新， 邮件列表通知他们可以使用了。

当前状态

重要的是要注意，新标记未正式记录(它们在Javadoc标记的正式列表中缺失)，因此可能会发生变化。 此外，实施者Mike Duigou写道：

没有计划尝试在JDK文档使用范围之外推广这些特定标签。

因此，虽然理解它们的含义肯定有益，但是团队应该仔细考虑使用它们是否值得依靠无证行为带来的风险。 我个人认为，我认为已经在JDK上进行了大量投资，以至于无法撤消。 如果有必要，也可以在代码库中轻松删除或搜索/替换它们的出现。

由布鲁克林博物馆根据CC-BY 3.0发行。

让我们切入事物的核心。 这些新标签的含义是什么？ 以及它们在哪里以及如何使用？

含义

新的Javadoc标记在功能请求的描述中得到了很好的解释(我对布局进行了一些更改)：

关于API中的方法，我们可能要记录很多事情。 从历史上看，我们将它们定义为“规范”(例如，必要的后置条件)或“实施说明”(例如，使用户了解引擎盖发生了什么的提示。)但实际上，有四个方框(和我们已经将它们塞入了两个，或者实际上是1.5)：

{API，实现} x {规范，注释}

(有时，我们使用术语“规范性” /“信息性”来描述规范/注释之间的差异。)以下是每个框中的内容的一些描述。

1. API规范。这是我们认识和喜爱的。 一种描述，该描述同样适用于该方法的所有有效实现，包括前提条件，后置条件等。

2. API注释。与API有关的评论，基本原理或示例。

3.实施规范。在这里，我们说的是成为有效的默认实现(或类中的可重写实现)的含义，例如“ throws UOE”。 同样，这是我们描述putIfAbsent的默认值的putIfAbsent 。 正是从这个盒子中，将要实施的人获得了足够的信息，以就是否要覆盖做出明智的决定。

4.实施说明。有关实现的信息性注释，例如特定于此版本的此JDK中此类的实现的性能特征，并且可能会发生变化。 允许这些内容在平台，供应商和版本之间有所不同。

建议：添加三个新的Javadoc标记@apiNote ， @implSpec和@implNote 。 (剩下的框，API Spec，不需要新标签，因为已经使用Javadoc了。) @impl {spec，note}可以很好地应用于类中的具体方法或接口中的默认方法。

因此，新的Javadoc标记旨在对注释中给出的信息进行分类。 它区分方法，类，…行为的规范(与API的所有用户有关-这是“常规”注释，如果有的话，则为@apiSpec )和其他更短暂或不太通用的文档。 更具体地说，API用户不能依赖用@implSpec或@implNote编写的任何内容，因为这些标记与该方法的这种实现有关，对覆盖的实现一无所知。

这表明使用这些标签将主要使API设计人员受益。 但是在这种情况下，即使是从事大型项目的Joe Developer也可以被视为设计师，因为他的代码肯定会在将来的某个时候被他的同事使用和/或更改。 在这种情况下，如果注释清楚地描述了API的不同方面，将很有帮助。 例如，它是方法规范的“线性运行”部分(因此不应降级)或当前实现的详细信息(因此可以更改)。

例子

让我们看一些例子！ 首先从演示项目中展示如何使用标签的基本原理，然后从JDK看到其在生产中的使用。

彩票

该项目包含一个虚拟库中的界面Lottery 。 该接口最初包含在库的1.​​0版中，但必须为1.1版添加新方法。 为了保持向后兼容性，这是默认方法，但计划是在2.0版中使其抽象(给客户一些时间来更新其代码)。

使用新标签，该方法的文档可以清楚地区分其文档的含义：

Lottery.pickWinners的文件

/**
 * Picks the winners from the specified set of players.
 * <p>
 * The returned list defines the order of the winners, where the first
 * prize goes to the player at position 0. The list will not be null but
 * can be empty.
 *
 * @apiNote This method was added after the interface was released in
 *          version 1.0. It is defined as a default method for compatibility
 *          reasons. From version 2.0 on, the method will be abstract and
 *          all implementations of this interface have to provide their own
 *          implementation of the method.
 * @implSpec The default implementation will consider each player a winner
 *           and return them in an unspecified order.
 * @implNote This implementation has linear runtime and does not filter out
 *           null players.
 * @param players
 *            the players from which the winners will be selected
 * @return the (ordered) list of the players who won; the list will not
 *         contain duplicates
 * @since 1.1
 */
default List<String> pickWinners(Set<String> players) {
	return new ArrayList<>(players);
}

JDK

JDK广泛使用新标签。 一些例子：

• ConcurrentMap ：
  • 几个@implSpec定义默认实现的行为，例如在replaceAll 。
• Objects使用@apiNote来解释为什么添加了看似无用的方法isNull和nonNull原因。
• 抽象类Clock在其类注释中使用@implSpec和@implNote来区分必须注意哪些实现以及如何实现现有方法。

遗产

当覆盖方法没有注释或通过{@inheritDoc}继承其注释时，不包括新标记。 这是一件好事，因为它们通常不适用。 要继承特定标签，只需将片段@tag {@inheritDoc}到注释中。

演示项目中的实现类研究了各种可能性。 自述文件提供了概述。

工具支援

集成开发环境

您可能希望在IDE中看到经过改进的文档(JDK的文档，也许是您自己的文档)。 那么，目前最受欢迎的游戏如何处理呢？

Eclipse显示标签及其内容，但不提供特殊的呈现方式，例如对标签标题进行排序或整理。 有一个功能要求来解决此问题。

IntellyJ的当前社区版本14.0.2既不显示标签也不显示其内容。 这显然在圣诞节前夕解决了(请参见票证)，所以我想下一个版本将不再有此问题。 不过，关于渲染我什么也不能说。

NetBeans既不显示标签也不显示内容，我找不到任何票证可以解决此问题。

总而言之，这不是一个漂亮的图片，但考虑到这不是Javadoc的正式功能，这是可以理解的。

生成Javadoc

如果您开始在自己的代码中使用这些标记，您将很快意识到由于未知标记，生成Javadoc失败。 这很容易解决，您只需要告诉它如何处理它们即可。

命令行

这可以通过命令行参数-tag来完成。 以下参数允许这些标记随处可见(例如，在软件包，类型，方法等上)，并为它们提供JDK当前使用的标头：

向Javadoc讲述新标签

-tag "apiNote:a:API Note:"
-tag "implSpec:a:Implementation Requirements:"
-tag "implNote:a:Implementation Note:"

(我阅读了官方文档，好像这些参数应该是-tag apiNote：a：“ API注意：” [请注意引号]，但这对我不起作用。如果您想限制使用新标签或完全不包含它们， -tag的文档告诉您如何执行此操作。)

默认情况下，所有新标签都添加到生成文档的末尾，这会将它们放在下面，例如@param和@return 。 要更改此设置，必须按所需顺序列出所有标签，因此必须将已知标签添加到上述三个标签下方的列表中：

在新标签之后列出已知标签

-tag "param"
-tag "return"
-tag "throws"
-tag "since"
-tag "version"
-tag "serialData"
-tag "see"

Maven

Maven的Javadoc插件具有配置设置标记，该标记用于详细创建相同的命令行参数。 GitHub上的演示项目展示了pom中的外观。

反射

我们已经看到添加了新的Javadoc标记@apiNote ， @implSpec和@implNote ，以允许将文档分为具有不同语义的部分。 了解它们对每个Java开发人员都有帮助。 API设计人员可能选择在他们自己的代码中使用它们，但必须记住，它们仍然没有文档记录，因此可能会发生变化。

最后，我们看了一些涉及的工具，发现需要改进IDE支持，但是可以对Javadoc工具和Maven插件进行参数化以充分利用它们。

翻译自: https://www.javacodegeeks.com/2015/01/new-javadoc-tags-apinote-implspec-and-implnote.html

@apinote