標準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注釋進行了改進。

翻譯自: https://www.javacodegeeks.com/2014/03/the-illuminating-javadoc-of-jdk-8.html

總結

以上是生活随笔為你收集整理的JDK 8的启发性Javadoc的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。