使用Java 9向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”属性中不允许使用空格，因此在处理单个短语中需要搜索的多个单词时，需要使用以下变通方法之一。

1. 删除空格
   • “ {@index IEEE 754}”成为“ {@index IEEE754}”
   • “ {@index Dual-PivotQuicksort}”变为“ {@index Dual-PivotQuicksort}”
2. 用允许的字符替换空格（例如，连字符）
   • “ {@index IEEE 754}”成为“ {@index IEEE-754}”
   • “ {@index Dual-Pivot-Quicksort}”变为“ {@index Dual-Pivot-Quicksort}”
3. 为词组中的每个单词使用单独的{@index}
   • “ {@index IEEE 754}”成为“ {@index IEEE} {@index 754}”
   • “ {@index Dual-Pivot Quicksort}”变为“ {@index Dual-Pivot} {@index Quicksort}”
4. 仅在词组中最重要的词上使用{@index}
   • “ {@index Dual-Pivot}快速排序”变为“ {@index Dual-Pivot}快速排序”
5. 用常见的单个单词表示法表示多个单词短语
   • 这就是Javadoc工具文档中的“ ulps”效果好而不是“最后一个单元”效果好的原因。

JEP 225的“动机”部分（“ Javadoc搜索”）很好地总结了这种在Javadoc中搜索术语的功能的好处：

如果您还不熟悉标准doclet的布局，则很难浏览它们。 可以使用外部搜索引擎，但这可能会导致页面过时或不相关。 可以使用浏览器的内置搜索功能，但仅限于在当前页面内搜索，而不是整个文档中的内容。

尽管在Java 9中向Javadoc生成的文档中添加搜索功能是次要的功能，但可以用来使自己的Java代码的文档对其他开发人员和该代码的用户更加有用。

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