javadoc 标签_新的Javadoc标签@ apiNote，@ implSpec和@implNote

javadoc 标签

如果您已经在使用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插件进行参数化以充分利用它们。