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

検索タグ

検索タグは、@indexタグを使用して、記述されたソース・コードのJavadocコメント内の任意の場所で定義された検索可能アイテムです。

例: - {@index "Java Collections Framework"} - {@index jrt jrt}

一致規則

次の各項では、エンティティ・シグネチャと照合される問合せ文字列の特殊なルールについて説明します。

大文字と小文字の区別

問合せ文字列に大文字が含まれていない場合、検索は大/小文字を区別しない方法で実行されます。 問合せ文字列に大文字が含まれている場合、大文字と小文字が一致した結果は一致したものとみなされ、大文字と小文字が一致しない結果の前に表示されます。 また、「キャメル・ケースの一致」セクションで説明されているルールが適用されます。

左の境界

問合せ文字列の先頭は、左ワード境界または左ワード境界の前にあるセパレータに一致する必要があります。

左ワード境界とみなされるのは、次のとおりです:

• 識別子の先頭
• カメルーン識別子内の大文字
• 識別子で_に続く文字

部分一致

問合せ文字列が識別子の先頭と一致するかぎり、名前識別子の末尾の文字が欠落していても、問合せ文字列は識別子と一致します。

キャメル・ケースの一致

部分一致のルールは、大文字の後にキャメル文字の識別子の中で任意の数の小文字または非文字が続く場合にも適用されます。

問合せ文字列の大文字、0個以上の小文字または非準拠の文字が続く文字は、エンティティ・シグネチャの文字シーケンスと完全に同じで、0個以上の小文字または非プロセッサ文字が続くものと一致します。

空白と複数の検索語

問合せ文字列に空白文字が含まれている場合、空白文字で区切られた問合せ文字列の一部は検索語とみなされます。 エンティティが複数の検索語で構成される問合せ文字列と一致するには、次の3つの条件を満たす必要があります:

• すべての検索語はエンティティ・シグネチャと一致する必要があります。
• 検索語は、問合せ文字列に表示される順序でエンティティ・シグネチャと一致する必要があります。
• 各検索語の一致は、「左の境界」セクションで定義されたエンティティ・シグネチャの左側の単語の境界と一致する必要があります。

複数の連続するスペース文字は、単一のスペース文字と同等とみなされます。 問合せ文字列全体が空白で構成されている場合、検索は実行されません。

コアおよび周辺機器の一致

エンティティ名を表すエンティティ・シグネチャの一部はシグネチャのコア・コンポーネントとみなされ、シグネチャのその他の部分は周辺コンポーネントとみなされます。

問合せ文字列にコア・コンポーネントの少なくとも一部が含まれ、一致する場合のみ、エンティティは検索結果に含まれます。

メソッドまたはコンストラクタのパラメータ・タイプは、そのシグネチャのコア・コンポーネントとはみなされませんが、(で検索文字列を開始することによって、特定のパラメータ・タイプを持つメソッドまたはコンストラクタを検索できます。

子要素へのアクセス

コード要素に一致する問合せ文字列を検索文字列に入力すると、2レベルのコード要素を接続する際に使用するセパレータを追加することで、要素の子要素に一致します。

結果のランク付け

識別子全体に一致する結果は、大文字で始まるケース識別子のセグメントや識別子の先頭など、識別子の一部のみをカバーする一致より上位にランク付けされます。 識別子全体に一致する結果は、検索結果のリストの上位に表示されます。

例:

• 問合せ文字列setは、java.util.Setとjava.util.HashSetのタイプを照合しますが、前者は後者より上位にランク付けされます。
• 問合せ文字列java.lang.refは、パッケージjava.lang.refとjava.lang.reflectの両方に一致しますが、前者はパッケージ名全体に一致するため後者より上位にランク付けされます。

大/小文字を区別する検索と大/小文字を区別しない検索の両方を実行すると、大/小文字を区別しない検索の結果よりも高いランクが付けられます。

サポートされるブラウザ

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