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

添加的條款的Javadoc生成的文檔中搜索的能力已被期望用于這表現(xiàn)在存在一些時(shí)間JDK-4034228 （“stddoclet：添加@index DOC-注釋標(biāo)記，用于產(chǎn)生從公共字索引”）， JDK-4279638 （“ Javadoc注釋：需要標(biāo)記要包含在API索引中的單詞”）和JDK-4100717 （“允許用戶指定索引條目”）。 JEP 225 （“ Javadoc搜索”）用于“向標(biāo)準(zhǔn)doclet生成的API文檔添加搜索框，該搜索框可用于搜索文檔中的程序元素以及標(biāo)記的單詞和短語(yǔ)。”

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

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

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

不幸的是，在{@index }標(biāo)記中嵌入文本中的空格似乎只會(huì)導(dǎo)致第一個(gè)空格之前的術(shù)語(yǔ)出現(xiàn)在呈現(xiàn)HTML中（并且是唯一可以搜索的部分）。 為了證明這一點(diǎn)，以下荒謬的Java代碼包含三個(gè){@index} Javadoc標(biāo)記，它們代表剛剛討論的三個(gè)示例。

文檔中使用{@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(){} }

當(dāng)在Java 9.0.4的Windows 10計(jì)算機(jī)上針對(duì)上述代碼執(zhí)行Javadoc工具時(shí)，生成HTML頁(yè)面如下所示：

方法文檔中的“ IEEE”之后，生成HTML中缺少“ 754”，而“ Dual-Pivot”之后，則缺少了“ Quicksort”。 下一個(gè)代碼清單顯示了這些缺少文本的片段的生成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輸出中，很明顯為什么只有第一個(gè)空格之前的文本才出現(xiàn)在頁(yè)面中并且可以搜索。 每個(gè)可搜索條目的與“ searchTagResult”類相關(guān)聯(lián)的“ id”屬性由可搜索字符串組成。 因?yàn)镠TML“ id”屬性不能有空格 ，所以“ id”值只能使用第一個(gè)空格之前的字符。

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

刪除空格

• “ {@index IEEE 754}”成為“ {@index IEEE754}”
• “ {@index Dual-PivotQuicksort}”變?yōu)椤?{@index Dual-PivotQuicksort}”

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

• “ {@index IEEE 754}”成為“ {@index IEEE-754}”
• “ {@index Dual-Pivot-Quicksort}”變?yōu)椤?{@index Dual-Pivot-Quicksort}”

為詞組中的每個(gè)單詞使用單獨(dú)的{@index}

• “ {@index IEEE 754}”成為“ {@index IEEE} {@index 754}”
• “ {@index Dual-Pivot Quicksort}”變?yōu)椤?{@index Dual-Pivot} {@index Quicksort}”

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

• “ {@index Dual-Pivot}快速排序”變?yōu)椤?{@index Dual-Pivot}快速排序”

用常見的單個(gè)單詞表示法表示多個(gè)單詞短語(yǔ)

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

JEP 225的“動(dòng)機(jī)”部分（“ Javadoc搜索”）很好地總結(jié)了這種在Javadoc中搜索術(shù)語(yǔ)的功能的好處：

如果您還不熟悉標(biāo)準(zhǔn)doclet的布局，則很難瀏覽它們。 可以使用外部搜索引擎，但這可能會(huì)導(dǎo)致頁(yè)面過時(shí)或不相關(guān)。 可以使用瀏覽器的內(nèi)置搜索功能，但僅限于在當(dāng)前頁(yè)面內(nèi)搜索，而不是整個(gè)文檔中的內(nèi)容。

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

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

總結(jié)

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

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