JEP 225: Javadoc Search | Javadoc 搜索
摘要
在由标准 doclet 生成的 API 文档中添加一个搜索框，用于在文档中搜索程序元素和标记的单词和短语。搜索框显示在标准 doclet 生成的所有页面的页眉中。
目标
搜索功能在本地实现，不依赖于任何服务器端的计算资源。
非目标
本 JEP 不旨在实现一个通用的搜索引擎，用于搜索文档注释中的所有单词。本 JEP 也不旨在更改一般的三框架/无框架布局或其内容，尽管可以在随后的工作中考虑这一点。
动机
标准 doclet 生成的 API 文档页面如果你对它们的布局不熟悉，可能很难导航。可以使用外部搜索引擎，但可能会导致过时或不相关的页面。浏览器内置的搜索功能可以使用，但仅限于在当前页面中搜索，无法搜索整个文档体。
描述
可以搜索什么？
模块、包、类型（类、接口等）和成员的声明名称被索引并可搜索。由于方法可以被重载，方法参数类型的简单名称也被索引并可搜索。方法参数的名称没有被索引。
使用新的内联标签
@index对索引的搜索词语或短语进行标记可进行搜索。其他内联标签不能嵌套在@index内部。只有在声明的文档注释中用@index标记的短语或搜索词语可以进行搜索。例如，"ulps" 这个特定领域的术语在java.lang.Math类中广泛使用，但不出现在任何类或方法的声明名称中。为了帮助 Math API 的用户，API 设计者可以在类级别或方法级别的文档注释中标记各种出现的 "ulps"。使用{@index ulps}进行标记。"ulps" 将被javadoc索引。
生成的索引的格式和位置可能会随着时间的推移而发生变化，并且其他工具不应依赖该索引。
准备进行搜索
默认情况下，运行 javadoc 命令将生成一个允许生成的 HTML 支持搜索框的索引。客户端使用 JavaScript 生成搜索结果。可以使用 -noindex 选项来禁用索引和搜索功能。与可能会生成或不生成的所有其他文件一样，javadoc 不会删除输出目录中的任何过时文件。用户需要确保在运行 javadoc 之前，输出目录为空，以确保没有来自之前运行的过时文件存在于输出目录中。
如何进行搜索
生成的 API 页面上提供了一个搜索框，提供以下功能：
根据用户的输入调用搜索的方法。搜索输入支持驼峰式搜索。例如，要搜索
addFocusListener()方法，用户只需在搜索框中键入 "addFL" 即可。搜索输入不支持正则表达式，尽管这可能会在随后的工作中考虑。显示结果，包括与输入字符完全匹配的结果，以及在字符串的任何位置包含输入字符的结果。多个结果以简单的滚动列表形式显示在搜索框下方。结果被分类为 "Modules"、"Packages"、"Types"、"Members" 和 "Search Tags"，以便更容易分类和选择适当的结果。
基于用户选择进行页面重定向。
使用的库
jQuery UI Autocomplete 和 JSZip 被用作实现的一部分，以提供一个与浏览器无关的自动完成实现。这是一个客户端功能。
测试
提供以下测试来确保：
- 搜索索引的准确性
- 新的
@index标签的使用 - 自动完成选择和重定向的准确性
- 防止恶意注入的验证