Javadoc検索の仕様

このドキュメントでは、JDK 18の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個以上の小文字または非プロセッサ文字が続くものと一致します。

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

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

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

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

子要素へのアクセス

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

結果のランク付け

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

例

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

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

空白

問合せ文字列の空白は、コンテキストに応じて処理されます。

• 2つの識別子を分離する空白は重要であるとみなされます。 一致するシグネチャは、対応する位置に空白が含まれている必要があります。
• セパレータの前後、または問合せ文字列の先頭または末尾の空白は無視されます。 一致するシグネチャには、対応する位置に空白を含めることも、含めないこともできます。

問合せ文字列またはシグネチャの実際の空白文字の数にかかわらず、空白は一致します。 問合せ文字列の1つ以上の空白文字が、シグネチャの1つ以上の空白文字と一致しています。

問合せ文字列全体が空白で構成されている場合、検索は実行されません。

サポートされるブラウザ

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