java javadoc

有一個相對較舊的網頁，稱為“ Proposed Javadoc Tags ”，最初似乎是與Javadoc 1.2一起編寫的，其中列出了“ Sun有朝一日可能會在Javadoc中實現的標簽”。 在此列表中的標簽是@category ， @example ， @tutorial ， @index ， @exclude ， @todo ， @internal ， @obsolete和@threadsafety 。 其中一個標簽@index已從“建議標簽”移至“標準標簽”，并已包含在Java 9中@index Javadoc工具文檔指出， @index標簽用于指定索引的“搜索詞或短語”可以在Java 9的新Javadoc搜索功能中進行搜索 。

JDK-4034228 （“ stddoclet：添加@index doc-comment標簽以根據常用詞生成索引”）的存在證明了一段時間以來一直希望能夠在Javadoc生成的文檔中添加用于搜索的術語的能力， JDK-4279638 （“ Javadoc注釋：需要標記要包含在API索引中的單詞”）和JDK-4100717 （“允許用戶指定索引條目”）。 JEP 225 （“ Javadoc搜索”）用于“向標準doclet生成的API文檔添加搜索框，該搜索框可用于搜索文檔中的程序元素以及標記的單詞和短語。”

Java 9及更高版本中的Javadoc將自動在“搜索”中包含多個構造，這些構造可從生成HTML輸出中執行。 默認情況下，這些可搜索的字符串是基于方法的名稱，成員的名稱，類型的名稱，包的名稱和模塊的名稱的字符串。 @index提供的@index是，未內置在這些剛列出的結構的名稱中的短語或搜索詞可以顯式地包含在搜索索引中。

在幾個示例中，可以添加用于搜索Javadoc生成的文檔的自定義文本的功能可能會很有用。 Javadoc工具文檔引用了“特定于域的術語ulps”（“ 最后一個單位 ”），并解釋說，盡管“ ulps在整個java.lang.Math類中都使用過”，但它“不會出現在任何類或方法聲明名稱。” 使用@index將允許Math類的API設計人員在可搜索索引中添加“ ulps ”，以幫助人們在搜索“ ulps”時找到Math類。 在有效Java的第三版中 ，喬什·布洛赫（Josh Bloch）引用了另一個可能在其中使用Javadoc {@index}示例。 在第56條中，Bloch引用了一個使用{@index IEEE 754} （“ IEEE浮點算法標準 ”）的示例。

我最近在JDK中遇到了一個案例，我認為使用{@index}是合適的。 我最近在Dual-Pivot Quicksort上發布了文章，但意識到在搜索Javadoc生成的輸出時，找不到與該術語匹配的任何內容。 通過{@index}在Javadoc搜索索引中添加“ Dual Pivot Quicksort”和“ Mergesort”之類的詞似乎很有用。

不幸的是，在{@index }標記中嵌入文本中的空格似乎只會導致第一個空格之前的術語出現在呈現HTML中（并且是唯一可以搜索的部分）。 為了證明這一點，以下可笑的Java代碼包含三個{@index} Javadoc標記，它們代表剛剛討論的三個示例。

文檔中使用{@index}的Java代碼

package dustin.examples.javadoc;/*** Used to demonstrate use of JDK 9's Javadoc tool* "@index" tag.*/ public class JavadocIndexDemonstrator {/*** This method complies with the {@index IEEE 754} standard.*/public void doEffectiveJava3Example(){}/*** Accuracy of the floating-point Math methods is measured in* terms of {@index ulps}, "units in the last place."*/public void doMathUlpsExample(){}/*** This method uses a version of the {@index Dual-Pivot Quicksort}.*/public void doDualPivotQuicksort(){} }

當在Java 9.0.4的Windows 10計算機上針對上述代碼執行Javadoc工具時，生成HTML頁面如下所示：

方法文檔中在“ IEEE”之后生成HTML中缺少“ 754”，在“ Dual-Pivot”之后缺少“ Quicksort”。 下一個代碼清單顯示了這些文本缺少的生成HTML源代碼。

HTML來源

<div class="block">This method uses a version of the <a id="Dual-Pivot" class="searchTagResult">Dual-Pivot</a>.</div>. . . <div class="block">This method complies with the <a id="IEEE" class="searchTagResult">IEEE</a> standard.</div>

從剛剛顯示HTML輸出中，很明顯為什么只有第一個空格之前的文本才出現在頁面中并且可以搜索。 與每個可搜索條目的“ searchTagResult”類相關聯的“ id”屬性由可搜索字符串組成。 因為HTML“ id”屬性不能有空格 ，所以“ id”值只能使用第一個空格之前的字符。

由于“ id”屬性中不允許使用空格，因此在處理單個短語中需要搜索的多個單詞時，需要使用以下變通方法之一。

刪除空格

• “ {@index IEEE 754}”成為“ {@index IEEE754}”
• “ {@index Dual-PivotQuicksort}”變為“ {@index Dual-PivotQuicksort}”

用允許的字符替換空格（例如，連字符）

• “ {@index IEEE 754}”成為“ {@index IEEE-754}”
• “ {@index Dual-Pivot-Quicksort}”變為“ {@index Dual-Pivot-Quicksort}”

為詞組中的每個單詞使用單獨的{@index}

• “ {@index IEEE 754}”成為“ {@index IEEE} {@index 754}”
• “ {@index Dual-Pivot Quicksort}”變為“ {@index Dual-Pivot} {@index Quicksort}”

僅在詞組中最重要的詞上使用{@index}

• “ {@index Dual-Pivot}快速排序”變為“ {@index Dual-Pivot}快速排序”

用常見的單個單詞表示法表示多個單詞短語

• 這就是Javadoc工具文檔中的“ ulps”效果好而不是“最后一個單元”效果好的原因。

JEP 225的“動機”部分（“ Javadoc搜索”）很好地總結了這種在Javadoc中搜索術語的功能的好處：

如果您還不熟悉標準doclet的布局，那么很難瀏覽它們。 可以使用外部搜索引擎，但這可能會導致頁面過時或不相關。 可以使用瀏覽器的內置搜索功能，但僅限于在當前頁面內搜索，而不是整個文檔中的內容。

盡管在Java 9中向Javadoc生成的文檔添加搜索功能是次要的功能，但是它可以用于使自己的Java代碼的文檔對其他開發人員和該代碼的用戶更加有用。

翻譯自: https://www.javacodegeeks.com/2018/01/adding-terms-javadoc-search-java-9.html

java javadoc

總結

以上是生活随笔為你收集整理的java javadoc_使用Java 9向Javadoc搜索添加术语的全部內容，希望文章能夠幫你解決所遇到的問題。

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