Javadoc搜索规范

本文档规定了JDK 21的Javadoc搜索功能的行为。

概述

Javadoc搜索功能是在JDK 9中通过JEP 225引入的。然而，最初的规范只包含了对搜索算法的非常基本描述。因此，有时选择和排名搜索结果略显不足。

这份额外规范的目的是通过定义更好的规则来改进最初的实现，以提高搜索结果的选择和排名。

定义

术语entity用于描述文档代码的构件，其中包括代码元素以及额外的搜索标签。

术语signature用于描述实体在Javadoc搜索中的表示方式。

术语name和identifier的定义参考Java语言规范，第6.2节。

术语white space和separator的定义参考Java语言规范，第3.6节和第3.11节。

术语camel-case用于描述利用大写字母标记标识符内单词边界的混合大小写标识符。

术语query string用于描述用户在搜索输入框中输入的字符。

以下各节中的所有示例均指或取自标准的OpenJDK类库。

可搜索实体

以下列表描述了文档代码的实体及其签名的构建方式。对于某些元素，签名仅包含实体的名称，而对于其他元素，它包含有关包含实体或参数类型的信息。

模块

模块的签名等于模块名称。

示例：- java.base

包

包的签名由包名称组成。

如果包属于命名模块，则模块名称将以/分隔添加到签名之前，并可包含在搜索中。

示例：- java.base/java.util.concurrent

类型

类型（类、接口、枚举、注解类型）的签名由类型名称组成。

如果类型是嵌套类型，则父类型的名称将以.分隔添加到签名之前，并可包含在搜索中。

如果类型包含在包中，则包名称将以.分隔添加到签名之前，并可包含在搜索中。

示例：- java.lang.Object - java.util.Map.Entry

成员

成员（方法、构造函数、字段）的签名由成员名称前面加上定义类型并以.分隔组成。

如果成员是方法或构造函数，则参数类型的名称将附加到名称之间用(和)括起来，并以,分隔以标识重载方法。

示例：- java.lang.Object.wait(long, int) - java.lang.String.String(String) - java.lang.Byte.MAX_VALUE

搜索标签

搜索标签是在文档源代码的Javadoc注释中使用@index标签定义的任意可搜索项。

示例：- {@index "Java Collections Framework"} - {@index jrt jrt}

匹配规则

以下各节描述了查询字符串与实体签名匹配的特殊规则。

区分大小写

如果查询字符串不包含任何大写字符，则搜索将以不区分大小写的方式执行。如果查询字符串包含大写字符，则具有匹配大小写的结果被视为更好的匹配，并在不匹配大小写的结果之前显示。此外，将应用驼峰匹配部分中描述的规则。

左边界

查询字符串的开头必须与左单词边界匹配，或者与左单词边界之前的分隔符匹配。

以下被视为左单词边界：

• 标识符的开头
• 驼峰标识符中的大写字母
• 标识符内_后面的字符

部分匹配

如果名称标识符末尾的字符缺失，只要查询字符串与标识符的开头匹配，查询字符串就会匹配标识符。

驼峰匹配

部分匹配规则也适用于驼峰标识符中的大写字符后跟任意数量的小写或非字母字符。

查询字符串中的大写字符后跟零个或多个小写或非字母字符，将与实体签名中完全相同的字符序列匹配，后跟零个或多个小写或非字母字符。

空格和多个搜索项

如果查询字符串包含空格字符，则由空格字符分隔的查询字符串部分被视为搜索项。对于实体与由多个搜索项组成的查询字符串匹配，必须满足以下三个条件：

• 所有搜索项必须与实体的签名匹配。
• 搜索项必须按照它们在查询字符串中出现的顺序与实体的签名匹配。
• 每个搜索项的匹配必须与实体的签名中的左单词边界对齐，如左边界部分所定义。

多个连续的空格字符被视为等同于单个空格字符。如果查询字符串完全由空格组成，则不执行搜索。

核心和外围匹配

实体签名中代表实体名称的部分被视为签名的核心组件，而签名的其他部分被视为外围组件。

只有当查询字符串包含并匹配其核心组件的至少一部分时，实体才会包含在搜索结果中。

虽然方法或构造函数的参数类型不被视为签名的核心组件，但可以通过以(开头的搜索字符串来搜索具有特定参数类型的方法或构造函数。

访问子元素

匹配代码元素的查询字符串可以转换为匹配元素的子元素的搜索字符串，方法是附加用于连接两个代码元素级别的分隔符。

结果排名

与仅覆盖标识符部分的匹配相比，完全匹配标识符的结果排名更高，例如以大写字母开头的驼峰标识符的一部分，或标识符的开头部分。匹配完整标识符的结果将出现在搜索结果列表的较高位置。

示例：

• 查询字符串set匹配类型java.util.Set和java.util.HashSet，但前者的排名高于后者。
• 查询字符串java.lang.ref匹配包java.lang.ref和java.lang.reflect，但前者的排名高于后者，因为它匹配整个包名。

在执行区分大小写搜索时，与执行不区分大小写搜索的结果相比，区分大小写搜索的结果排名更高。

支持的浏览器

以下浏览器支持搜索功能。