當前位置：首頁 > 编程语言 > java >内容正文

java

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

發布時間：2023/12/3 java 41 豆豆

生活随笔收集整理的這篇文章主要介紹了 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插件進行參數化以充分利用它們。

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