跳到主要内容

JEP 225：Javadoc 搜索

概括​

向标准 doclet 生成的 API 文档添加搜索框，可用于搜索文档中的程序元素以及标记的单词和短语。搜索框出现在标准 doclet 生成的所有页面的页眉中。

目标​

搜索功能在本地实现，不依赖任何服务器端计算资源。

非目标​

实现通用搜索引擎来搜索文档注释中的所有单词并不是目标。改变本 JEP 中的一般三帧/无帧布局或其内容也不是目标，尽管在后续工作中可能会考虑这一点。

动机​

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

描述​

可以搜索什么？​

  • 模块、包、类型和成员的声明名称均已建立索引并可搜索。由于方法可以重载，因此方法参数类型的简单名称也会被索引并可以搜索。方法参数名称没有索引。

  • 使用新的内联标签 索引的搜索词或短语@index是可搜索的。其他内联标签不能嵌套在 内@index。@index只能搜索声明文档注释中标有 的短语或搜索词。例如，域特定术语“ulps”在整个java.lang.Math类中使用，但不会出现在任何类或方法声明名称中。为了帮助 Math API 的用户，API 设计者可以在类级别或方法级别文档注释中标记各种出现的“ulps”。标记是使用 实现的{@index ulps}。 “ulps”将由 索引javadoc。

生成的索引的格式和位置可能会随着时间的推移而改变，并且不得被其他工具依赖。

默认情况下，运行javadoc将生成一个索引，允许生成的 HTML 支持搜索框。客户端 JavaScript 用于生成搜索结果。选项-noindex可javadoc用于禁用索引和搜索功能。与可能生成或可能不会生成的所有其他文件一样，javadoc不会删除输出目录中的任何过时文件。用户有责任在运行之前确保输出目录为空javadoc，以确保输出目录中不存在先前运行中的过时文件。

生成的 API 页面上有一个搜索框，并提供：

  • 可以根据用户输入调用搜索的工具。搜索输入支持驼峰式搜索。例如，要搜索 addFocusListener() 方法，用户只需在搜索框中键入“addFL”即可。搜索输入不支持正则表达式，尽管在后续工作中可能会考虑这一点。

  • 结果，包括与输入的字符完全匹配的结果，后跟包含字符串中任何位置输入的字符的结果。多个结果显示为搜索框下方的简单滚动列表。结果被分类为“模块”、“包”、“类型”、“成员”和“搜索标签”，以便于分类和适当的用户选择；和

  • 基于用户选择的页面重定向。

图书馆​

jQuery UI Autocomplete 和 JSZip 用作实现的一部分，以提供独立于浏览器的自动完成实现。这是一个客户端功能。

测试​

提供测试以确保以下内容：

  • 搜索索引的准确性
  • 新@index标签的使用
  • 自动完成选择和重定向的准确性
  • 验证是否存在恶意注入