JavaDoc検索仕様

このドキュメントでは、JDK 22のJavaDoc検索機能の動作を指定します。

概要

JavaDoc検索機能は、JDK 9でJEP 225とともに導入されました。 最初のJEPには、検索アルゴリズムのきめ細かい仕様は含まれず、アルゴリズムは初期実装からかなり進化しています。 このドキュメントの目的は、JavaDoc標準ドックレットによって生成されたドキュメントの検索アルゴリズムの最新仕様を提供することです。

定義

このドキュメントでは、entityという用語は、JavaDoc検索機能を使用して検出可能なドキュメント化されたコード内のアーティファクトを記述するために使用されます。 これには、ドキュメンテーション・コメントで定義されたプログラム・エレメントおよびその他の項目が含まれます。

signatureという用語は、JavaDoc検索でエンティティを表すために使用される正確なテキストを表すために使用されます。

separator, identifier, name, simple name, qualified nameおよびfully qualified nameという用語は、「Java言語仕様」セクションの3.8、3.11、6.2および6.7で定義されているように使用されます。 これは、エンティティ・シグネチャのエンコーディングおよび処理にUnicodeを使用することを意味します。

letter, uppercase letter, lowercase letter, digitおよびwhite spaceという用語は、「Unicode標準」の"レター"、"Uppercase_Letter"、"Lowercase_Letter"、"Decimal_Number"および"Space_Separator"の一般カテゴリを指します。

camel-caseという用語は、大文字を使用して識別子内の単語境界をマークする大/小文字の混在識別子を表すために使用されます。

query stringという用語は、ユーザーが検索入力ボックスに入力した文字を説明するために使用します。

次の各項の例は、標準のJava SEクラス・ライブラリを参照するか、そのライブラリから取得します。

検索可能エンティティのカテゴリ

次の項では、JavaDoc Searchでカバーされるプログラム要素とその他のエンティティの種類、およびそのシグネチャの形式を示します。

モジュール

名前付きモジュールのシグネチャは、モジュール名です。

シグネチャの例:

• java.base

パッケージ

パッケージが名前付きモジュールにある場合、パッケージのシグネチャはモジュールの名前、その後に/',、その後にパッケージの完全修飾名が続きます。パッケージが名前付きモジュールにない場合、シグネチャはパッケージの完全修飾名です。

シグネチャの例:

• java.base/java.util.concurrent

型

クラスまたはインタフェース・タイプのシグネチャは、その完全修飾型名です。

シグネチャの例:

• java.lang.Object
• java.util.Map.Entry

メンバー

メンバーのシグネチャは、その包含型の完全修飾名、その後に'.'が続き、そのメンバーの単純名、そのメンバーがコンストラクタまたはメソッドの場合はパラメータ型のリストが続きます。 パラメータ・タイプのリストは'(', followed by the simple names of formal parameter types of the constructor or method separated by ', ', followed by ')です。

シグネチャの例:

• java.lang.Object.wait(long, int)
• java.lang.String.String(String)
• java.lang.Byte.MAX_VALUE

JavaDocタグ

検索可能なエンティティの作成には、様々な「JavaDocタグ」を使用できます。

• {@index}タグは、一般的な検索可能なエンティティを作成するために使用されます。
• {@systemProperty}タグは、システム・プロパティの文書化に使用されます。
• @specタグは、外部仕様を参照するために使用されます。

これらの各タグのシグネチャは、タグで提供される文字列です。

シグネチャとタグの例:

• {@index "Java Collections Framework"}のJava Collections Framework
• {@index jar jar tool}のjar
• {@systemProperty user.timezone}のuser.timezone
• @spec jni/index.html Java Native Interface Specificationの場合はJava Native Interface Specification

検索ルール

次の項では、特定の問合せ文字列のエンティティ・シグネチャの検索に使用されるルールについて説明します。

このドキュメントの目的は、検索機能の実装を説明することではありませんが、一連のアクションを理解することは、適用されるルールを理解するのに役立ちます。 検索には、次のステップが含まれます。

1. 問合せ文字列が解析され、パターンにコンパイルされます。
2. パターンは、すべての検索可能なエンティティのシグネチャと照合されます。
3. シグネチャが一致するエンティティは、次の項で説明するルールに従ってフィルタおよびスコアリングされます。
4. スコアが特定のしきい値を超えているエンティティは、スコア順にユーザーに表示されます。

ステップ3のスコアリング・メカニズムは差引です: 一致するすべてのエンティティの上位スコアで開始され、スコアが減少してエンティティが下位にランク付けされるか、結果から除外されます。

大文字と小文字の区別

検索パターンは、大/小文字を区別しない方法でシグネチャと照合されます。 問合せ文字列に大文字が含まれている場合、大文字が一致するシグネチャは、大文字が一致しないシグネチャよりも高くスコア付けされます。 さらに、大文字を含む問合せ文字列によって、「ケース・マッチ」セクションのルールが適用されます。

単語境界

単語の境界は、一致するエンティティのスコアを決定する上で重要なロールを果たします。 エンティティ・シグネチャでは、次の単語境界とみなされます。

• 識別子の先頭または末尾
• 文字以外の文字で区切られた1つ以上の文字
• 数字以外の文字で区切られた1つ以上の数字
• 大文字と数字が混在する文字列内の大文字

左側の単語の境界

エンティティのシグネチャの一致の開始は、エンティティを検索結果に含めるために、左側の単語の境界または左側の単語の境界の前に置くセパレータである必要があります。

一致のスコアリングは、開始する左側の単語境界のタイプに応じて異なる場合があります。 たとえば、識別子の先頭から始まる一致は、ケース識別子の途中から始まる一致よりも高くスコア付けできます。

例: - 問合せ文字列setは、java.util.Set型とjava.util.HashSet型に一致しますが、前者は後者より高くランク付けされます。

右側の単語の境界

エンティティを検索結果に含めるために、問合せ文字列の終わりは、エンティティのシグネチャの正しい単語境界と一致する必要はありません。

ただし、右の単語境界を含む一致は、(したがって、識別子、名前または単語の一部のみに一致)でない一致よりも高くスコア付けされます。

例:

• 問合せ文字列java.lang.refは、パッケージjava.lang.refとjava.lang.reflectの両方に一致しますが、前者はシグネチャ全体と一致するため、後者より高くランク付けされます。

ケース・マッチ

大文字の後に小文字または数字が続く大文字も単語境界とみなされるため、左および右の単語境界のルールはケース・シグネチャにも適用されます。

また、キャメル・ケースのシグネチャを検索する場合、問合せ文字列から小文字または数字の一部またはすべてを省略できます。

空白と複数の検索語

問合せ文字列の空白は、空白以外の文字の間に存在する場合に有効です。 空白で区切られた問合せ文字列内の空白以外の文字のリージョンは、検索語とみなされます。 複数の検索語を含む問合せ文字列には、次のルールが適用されます。

• すべての検索語は、問合せ文字列内で出現する順序でシグネチャと一致する必要がありますが、必ずしも連続したリージョン内ではありません。
• 単純な問合せ文字列のルールは、個々の検索語に適用されます。 特に、各検索語の一致は、シグネチャの左側の単語境界に配置する必要があります。

検索語間の空白文字の数は重要ではありません。 問合せ文字列の先頭および末尾の空白は重要ではありません。 検索をトリガーするには、問合せ文字列に空白以外の文字を少なくとも1つ含める必要があります。

コア・シグネチャ・リージョン

一部の種類のプログラム要素では、シグネチャ内での一致のロケーションに応じて、追加のフィルタリング・ルールが適用されます。 これは、プログラム要素に固有のシグネチャの一部の一致が、重要度の低い領域の一致よりも優先されるようにするために行われます。

プログラム要素で最も重要と考えられるシグネチャの一部は、コア・リージョンと呼ばれます。 次の表に、このメカニズムが適用されるプログラム要素とそのシグネチャのコア・リージョンを示します。

次に示す例外を除いて、照合はコア・シグネチャ・リージョンの少なくとも一部をカバーしないかぎり、検索結果から除外されます。 問合せ文字列に複数の検索語が含まれる場合、それらのうち少なくとも1つがコア・シグネチャ・リージョンの一部と一致する必要があります。

実行可能メンバーの仮パラメータ・タイプはコア・シグネチャ・リージョンの一部ではありませんが、メンバー名を省略し、(で問合せ文字列を開始すると、コア・リージョン・フィルタリングがバイパスされ、特定のパラメータ・タイプの実行可能メンバーを検索できます。

子要素のリスト

プログラム要素と一致する問合せ文字列は、子要素のシグネチャで使用されるセパレータ文字を追加することで、その子要素すべてに一致する問合せ文字列に変換できます。 これにより、検索結果に含める要素のコア・リージョン・フィルタリングがバイパスされます。

サポートされるブラウザ

検索機能は、次のブラウザでサポートされています。