JDK 8的启发性Javadoc

标准JDK 8 API文档的一个不错的功能之一就是能够查看所有或不同类别的方法，正如我在博客文章JDK 8 Javadoc Tweaked For Methods Listings中所讨论的那样。尽管这种分类既方便又有用，但是与JDK 8中许多新类和程序包相关联的文本注释无疑更有用，尤其是当我们中的许多人开始采用JDK 8时。我看一些非常有用的示例这篇文章中的JDK 8 API文档。在快速浏览JDK 8 Javadoc文档的过程中，对JDK 8完全陌生的任何人都必须学习有关JDK 8库的知识。

熟悉的String类文档中提供了JDK 8 API文档有用性的良好示例。该类具有两个新的重载静态方法，即join（CharSequence，CharSequence…）和join（CharSequence定界符，Iterable元素）。 Javadoc对这两个新方法的注释不仅解释了方法的行为，而且还通过演示使用方法的代码来说明它们。这类似于我一直发现对String.substring（int，int）方法有帮助的Javadoc注释。

全新的StringJoiner类在类级Javadoc注释中包含其用法的代码示例。其中一个代码示例似乎旨在简化“传统Java开发”，而第二个示例则应用了lambda表达式和流的功能。

代码示例也广泛用于其他新类（至JDK 8）的Javadoc文档中，尤其是在java.util.streams包中。 java.util.stream.Collectors类的类级Javadoc文档提供了Collectors的7种潜在用途（例如累积和分组）的代码示例。 Stream接口在接口上提供了有用的JDK 8文档的示例。有关应用Stream接口的文本详细信息，并附有一个简单的代码示例，该示例演示了“使用Stream和IntStream的聚合操作”。 java.util.stream包本身具有有关Streams的出色描述文本，其中包括一个使用Stream的简单示例，并对该示例进行了详细讨论。 java.util.stream的软件包文档进一步讨论了使用Streams的几个不同方面，例如流操作和管道，并行性，副作用和归约。

就像在使用JDK 8 lambda表达式时理解Streams很重要一样，在使用lambda表达式时理解功能接口也很有用，并且java.util.function包级描述提供了很好的概述。

带有启发性代码示例的基于Java的JDK 8文档的另一个很好的示例是Calendar.Builder的文档，我在JDK 8的Calendar.Builder中介绍了该类。

到目前为止，我所讨论的大多数基于JDK 8 Javadoc的文档都提供了代码示例，这些示例演示了所描述的包，类或接口的使用。一些新的JDK API文档使用代码通过显示以前需要编写但被新功能替换的代码来演示新的API功能。众所周知的Java Map接口中有很好的例子。 Java Map界面在JDK 8中指定了几个新方法，并且这些新JDK 8方法中的许多都包括Javadoc文档，该文档指示在JDK 8之前完成与新添加的方法相同的操作所需的代码。例如，方法computeIfAbsent ， computeIfPresent ， forEach ， getOrDefault和putIfAbsent方法都具有注释，这些注释提供了代码，以证明“默认实现等效”。尽管这可能解释了Map实现的默认行为，但对于理解这些方法模拟或替换的JDK 8之前的代码的类型也很有用。

JDK 8引入了一个全新的Date / Time API，并且java.time软件包对API进行了很好的软件包级概述。这个全新软件包中的构造具有单独的级别注释，这些注释对于学习此API很有用。示例包括Clock ， Instant ， LocalDateTime ， Period和ZonedDateTime 。封装级文档可以帮助澄清之间的关系LOCALDATE的， LocalDateTime ，本地时间， ZonedDateTime和即时。

JDK 8 Javadoc不仅针对标准JDK API进行了更改。 JDK 8 对javadoc工具进行了一些增强，这将影响开发人员自己的Javadoc注释和代码。注意-Xdoclint：none选项（在Stephen Colebourne的博客文章“在JDK 8 Javadoc中关闭doclint”中提到）也很重要，可以防止破坏不符合“ W3C HTML 4.01 HTML”的Javadoc。关于Javadoc Java SE 8增强功能的最后一个项目符号指出，此Javadoc HTML一致性合规性“在Javac中也可用，尽管默认情况下未启用该功能。” 该项目符号告诉我们，可以通过运行javadoc -X来了解有关-Xdoclint:none标志的更多信息。

结论

我有时会听到，当代码说明自己时，永远不需要注释。我相信一定程度上是对的，但是JDK 8引入的有关程序包，类和接口及其方法的有用Javadoc注释的存在，将使JDK 8的采用比阅读这些构造的每个代码清单都快得多。将。它强化了我的观点，即我们通常不需要对执行某些操作的特定代码行进行注释，但是大多数情况下确实需要对接口和协定进行注释。在我的理想世界中，代码编写得如此好，以至于唯一必要的注释就是Javadoc样式注释（ /** */ ），而我们只需要很少的//或/* */样式注释。在可读性和可理解性方面，JDK 8延续了最近的JDK主要修订版中出现的趋势，该修订版对Javadoc注释进行了改进。