跳到主要内容

JEP 225：Javadoc 搜索

QWen Max 中英对照

概述​

在由标准 doclet 生成的 API 文档中添加一个搜索框，可以用来搜索文档中的程序元素以及标记的单词和短语。该搜索框会出现在由标准 doclet 生成的所有页面的头部。

目标​

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

非目标​

实现一个通用的搜索引擎来搜索文档注释中的所有单词并不是目标。虽然在后续工作中可能会考虑这一点，但在此 JEP 中更改通用的三框架/无框架布局或其内容也并非目标。

动机​

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

描述​

可以搜索什么？​

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

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

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

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

生成的 API 页面上有一个搜索框，提供以下功能：

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

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

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

库​

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

测试​

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

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