javadoc 標(biāo)簽

如果您已經(jīng)在使用Java 8，則可能會(huì)看到一些新的Javadoc標(biāo)簽： @apiNote ， @implSpec和@implNote 。 他們?cè)趺戳?#xff1f; 如果要使用它們，該怎么辦？

總覽

該帖子將快速查看標(biāo)簽的來源和當(dāng)前狀態(tài)。 然后，它將解釋它們的含義并詳細(xì)說明如何將它們與IDE，Javadoc工具一起使用，以及如何通過Maven的Javadoc插件使用。

我在GitHub上創(chuàng)建了一個(gè)演示項(xiàng)目，以顯示一些示例和Maven pom.xml的必要補(bǔ)充。 為了使Maven規(guī)避變得更容易，它已經(jīng)包含了生成的javadoc 。

語境

起源

新的Javadoc標(biāo)記是JSR-335的副產(chǎn)品，它引入了lambda表達(dá)式。 它們是在默認(rèn)方法的上下文中提出的，因?yàn)樗鼈冃枰鼧?biāo)準(zhǔn)化和更細(xì)粒度的文檔。

2013年1月，Brian Goetz 提出了動(dòng)機(jī)，并為這些新標(biāo)簽提出了建議 。 經(jīng)過簡短的討論，三個(gè)星期后它變成了功能請(qǐng)求 。 到4月， JDK Javadoc制造商已更新 ， 郵件列表通知他們可以使用了。

當(dāng)前狀態(tài)

重要的是要注意，新標(biāo)簽未正式記錄（在Javadoc標(biāo)簽的正式列表中丟失），因此可能會(huì)發(fā)生變化。 此外，實(shí)施者M(jìn)ike Duigou 寫道 ：

沒有計(jì)劃在JDK文檔使用范圍之外嘗試普及這些特定標(biāo)簽。

因此，雖然理解它們的含義肯定有益，但是團(tuán)隊(duì)?wèi)?yīng)該仔細(xì)考慮使用它們是否值得依靠無證行為帶來的風(fēng)險(xiǎn)。 我個(gè)人認(rèn)為，我認(rèn)為已經(jīng)在JDK上進(jìn)行了大量投資，以至于無法撤消。 如果有必要，也可以在代碼庫中輕松刪除或搜索/替換它們的出現(xiàn)。

由布魯克林博物館根據(jù)CC-BY 3.0發(fā)行 。

讓我們切入事物的核心。 這些新標(biāo)簽的含義是什么？ 它們?cè)谀睦镆约叭绾问褂?#xff1f;

含義

新的Javadoc標(biāo)記在功能請(qǐng)求的說明中進(jìn)行了很好的解釋（我對(duì)布局進(jìn)行了一些更改）：

關(guān)于API中的方法，我們可能要記錄很多事情。 從歷史上看，我們將它們定義為“規(guī)范”（例如，必要的后置條件）或“實(shí)施說明”（例如，使用戶了解引擎蓋發(fā)生了什么的提示。）但是，實(shí)際上，有四個(gè)方框（和我們已經(jīng)將它們?nèi)肓藘蓚€(gè)，或者實(shí)際上是1.5）：

{API，實(shí)現(xiàn)} x {規(guī)范，注釋}

（我們有時(shí)使用規(guī)范性/信息性術(shù)語來描述規(guī)范/注釋之間的差異。）以下是每個(gè)框中的內(nèi)容的一些描述。

1. API規(guī)范。
這是我們認(rèn)識(shí)和喜愛的。 一種描述，該描述同樣適用于該方法的所有有效實(shí)現(xiàn)，包括前提條件，后置條件等。

2. API注釋。
與API有關(guān)的評(píng)論，原理或示例。

3.實(shí)施規(guī)范。
在這里，我們說的是成為有效的默認(rèn)實(shí)現(xiàn)（或類中的可重寫實(shí)現(xiàn)）的含義，例如“ throws UOE”。 同樣，這是我們描述putIfAbsent的默認(rèn)值的putIfAbsent 。 正是從這個(gè)盒子中，將要實(shí)施的人獲得了足夠的信息，以就是否要覆蓋做出明智的決定。

4.實(shí)施說明。
有關(guān)實(shí)現(xiàn)的信息性注釋，例如特定于此版本此JDK中此類中的實(shí)現(xiàn)的性能特征，并且可能會(huì)發(fā)生變化。 允許這些內(nèi)容在平臺(tái)，供應(yīng)商和版本之間有所不同。

建議：添加三個(gè)新的Javadoc標(biāo)記@apiNote ， @implSpec和@implNote 。 （剩下的框，API Spec，不需要新標(biāo)簽，因?yàn)橐呀?jīng)使用了Javadoc。） @impl {spec，note}可以很好地應(yīng)用于類中的具體方法或接口中的默認(rèn)方法。

因此，新的Javadoc標(biāo)記旨在對(duì)注釋中給出的信息進(jìn)行分類。 它區(qū)分方法的規(guī)范，類的規(guī)范...（與API的所有用戶有關(guān)–這是“常規(guī)”注釋，如果有的話將為@apiSpec ），以及其他更短暫或不太通用的文檔。 更具體地說，API用戶不能依賴任何用@implSpec或@implNote編寫的內(nèi)容 ，因?yàn)檫@些標(biāo)記與方法的這種實(shí)現(xiàn)有關(guān)，而沒有提及重寫實(shí)現(xiàn)。

這表明使用這些標(biāo)簽將主要使API設(shè)計(jì)人員受益。 但是在這種情況下，即使是從事大型項(xiàng)目的Joe Developer也可以被視為設(shè)計(jì)師，因?yàn)樗拇a肯定會(huì)在將來的某個(gè)時(shí)候被同事使用和/或更改。 在這種情況下，如果注釋清楚地描述了API的不同方面，將很有幫助。 例如，它是方法規(guī)范的“線性運(yùn)行”部分（因此不應(yīng)降級(jí)）或當(dāng)前實(shí)現(xiàn)的詳細(xì)信息（因此可以更改）。

例子

讓我們看一些例子！ 首先從演示項(xiàng)目中展示如何使用標(biāo)簽的基本原理，然后從JDK看到其在生產(chǎn)中的使用。

彩票

該項(xiàng)目包含一個(gè)虛擬庫中的界面Lottery 。 該接口最初包含在庫的1.??0版中，但是必須為1.1版添加新方法。 為了保持向后兼容性，這是默認(rèn)方法，但是計(jì)劃是在2.0版中使其抽象（給客戶一些時(shí)間來更新其代碼）。

使用新標(biāo)簽，該方法的文檔可以清楚地區(qū)分其文檔的含義：

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廣泛使用新標(biāo)簽。 一些例子：

• ConcurrentMap ：
  • 幾個(gè)@implSpec定義默認(rèn)實(shí)現(xiàn)的行為，例如在replaceAll 。
• Objects使用@apiNote解釋為什么添加了看似無用的方法isNull和nonNull 。
• 抽象類Clock在其類注釋中使用@implSpec和@implNote來區(qū)分必須注意哪些實(shí)現(xiàn)以及如何實(shí)現(xiàn)現(xiàn)有方法。

遺產(chǎn)

當(dāng)覆蓋方法沒有注釋或通過{@inheritDoc}繼承其注釋時(shí)，不包括新標(biāo)記。 這是一件好事，因?yàn)樗鼈兺ǔ２贿m用。 要繼承特定標(biāo)簽，只需將片段@tag {@inheritDoc}到注釋中。

演示項(xiàng)目中的實(shí)現(xiàn)類檢查了各種可能性。 自述文件提供了概述。

工具支援

集成開發(fā)環(huán)境

您可能希望在IDE中看到改進(jìn)的文檔（JDK的文檔，也許是您自己的文檔）。 那么，當(dāng)前最受歡迎的人如何處理它們？

Eclipse顯示標(biāo)簽及其內(nèi)容，但不提供特殊的呈現(xiàn)方式，例如對(duì)標(biāo)簽標(biāo)題進(jìn)行排序或整理。 有一個(gè)功能要求來解決此問題。

IntellyJ的當(dāng)前社區(qū)版本14.0.2既不顯示標(biāo)簽也不顯示其內(nèi)容。 這顯然已在平安夜解決（請(qǐng)參見票證 ），所以我想下一個(gè)版本將不再有此問題。 不過，我無法透露任何有關(guān)渲染的信息。

NetBeans既不顯示標(biāo)簽也不顯示內(nèi)容，我找不到任何票證可以解決此問題。

總而言之，這不是一個(gè)漂亮的圖片，但考慮到這不是官方的Javadoc功能，這是可以理解的。

生成Javadoc

如果您開始在自己的代碼中使用這些標(biāo)記，您將很快意識(shí)到由于未知標(biāo)記，生成Javadoc失敗。 這很容易解決，您只需要告訴它如何處理它們即可。

命令行

這可以通過命令行參數(shù)-tag來完成。 以下參數(shù)允許這些標(biāo)簽隨處可見（例如，在軟件包，類型，方法等上），并為它們提供JDK當(dāng)前使用的標(biāo)頭：

向Javadoc講述新標(biāo)簽

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

（我閱讀了官方文檔，好像這些參數(shù)應(yīng)該是-tag apiNote：a：“ API注意：” [請(qǐng)注意引號(hào)]，但這對(duì)我不起作用。如果您想限制使用新標(biāo)簽或完全不包含它們， -tag的文檔告訴您如何執(zhí)行此操作。）

默認(rèn)情況下，所有新標(biāo)簽都添加到生成文檔的末尾，這會(huì)將它們放在下面，例如@param和@return 。 要更改此設(shè)置，必須按所需順序列出所有標(biāo)簽，因此必須將已知標(biāo)簽添加到上述三個(gè)標(biāo)簽下方的列表中 ：

在新標(biāo)簽之后列出已知標(biāo)簽

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

Maven

Maven的Javadoc插件具有配置設(shè)置標(biāo)記 ，該標(biāo)記用于詳細(xì)創(chuàng)建相同的命令行參數(shù)。 GitHub上的演示項(xiàng)目展示了pom中的外觀 。

反射

我們已經(jīng)看到添加了新的Javadoc標(biāo)記@apiNote ， @implSpec和@implNote ，以允許將文檔劃分為具有不同語義的部分。 了解它們對(duì)每個(gè)Java開發(fā)人員都有幫助。 API設(shè)計(jì)人員可能選擇在他們自己的代碼中使用它們，但必須記住，它們?nèi)匀粵]有文檔記錄，因此可能會(huì)發(fā)生變化。

我們最終看了一些涉及的工具，發(fā)現(xiàn)需要改進(jìn)IDE支持，但是可以對(duì)Javadoc工具和Maven插件進(jìn)行參數(shù)化以充分利用它們。

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

javadoc 標(biāo)簽

總結(jié)

以上是生活随笔為你收集整理的javadoc 标签_新的Javadoc标签@ apiNote，@ implSpec和@implNote的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。