Java SE 21およびJDK 21
機械翻訳について

標準ドックレット(JDK 21)のドキュメンテーション・コメント仕様

このドキュメントでは、APIのHTMLドキュメントを生成するために使用される、JDK 21のjavadocツールの標準ドックレットで認識されるドキュメント・コメントの形式を指定します。

javadocツールのコンテキストでは、ドキュメント・コメントの内容の解釈は、コメントを処理するために使用されるドックレットまでです。 他のドックレットは、標準ドックレットと同じ構文を受け入れることも、代替の構文をサポートすることもできます。 しかし、多くのツールでサポートされているため、標準ドックレットでサポートされている構文は「デ・ファクト」標準になっています。

一般的な構文

ドキュメントのコメントは、モジュール、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、列挙メンバーまたはフィールド宣言の直前に配置された場合にのみ認識されます。 メソッドの本体に置かれているドキュメンテーション・コメントは無視されます。 宣言文ごとに1つの文書コメントしか認識されません。

ドキュメント・コメントの全体的な形式は、最初の「メインの説明」の後に、コメントが適用される宣言に関する追加情報を提供する一連の「ブロック・タグ」が続きます。 説明テキストには、次に説明するように、「インライン・タグ」および「HTMLコンテンツ」を含めることができます。 各行の先頭にある「先行アスタリスク」および先行する空白は無視されます。

ブロック・タグのみが含まれ、メインの説明がないコメントを使用できます。

履歴な理由から、パッケージのドキュメント・コメントは、パッケージのソース・ディレクトリにあるpackage.htmlというファイルで提供される場合があります。 この場合、ドキュメンテーション・コメントは<body>タグの内容であり、Javaタイプ(たとえば、@seeタグ)への参照は完全修飾でなければなりません。 標準ドックレットでは、overview.htmlなどのファイルで追加のドキュメントを提供することもできます。 このようなコンテンツのルールは、package.htmlのルールと同じです。

メイン摘要

ドキュメント・コメントの主な説明は、コメントの先頭から最初のブロック・タグまで、存在する場合は最初のブロック・タグまで、存在しない場合はコメントの末尾までです。 先頭と末尾の空白は無視されます。 そのような内容がない場合、主な説明は欠落していると言われています。

メインの説明はブロック・タグ続けることはできません。

メインの説明の最初の文は、宣言されたエンティティの簡潔で完全な説明を含むサマリー文である必要があります。

ブロック・タグ

ブロック・タグの形式は@identifier contentで、生成されたドキュメントに組み込まれる追加の詳細を提供します。 各ブロック・タグは、先頭のアスタリスク、空白文字および最初のコメント・デリミタ(/**)を無視して、行の先頭に表示する必要があります。 これは、テキスト内のそれ以外の位置で@文字を使用しても、タグの開始としては解釈されないことを意味しています。 行の最初に@文字を使用してもタグとして解釈されないようにするには、HTMLエンティティの&#064;を使用してください。 ブロック・タグの内容は、次のブロック・タグまたはドキュメント・コメントの最後までのタグの後にあるテキストです。 コンテンツは複数の行にまたがることができます。

ブロック・タグの数に制限はありません。一部のタグは繰り返すことができ、他のタグは繰り返せません。

インライン・タグ

インライン・タグの形式は{@ identifier content }で、説明のコンテキスト内で詳細を提供します。 通常、説明テキストおよびHTMLが許可されている場合は常に表示されますが、一部のインライン・タグはメインの説明の先頭でのみ使用できます。

一部のインライン・タグには自由形式のテキストが含まれている場合があります。 このようなテキストに中カッコが明示的に含まれている場合、インライン・タグの閉じカッコを判別できるように、中カッコは"貸借一致"である必要があります。これは、適切にネストされた左中カッコと右中カッコの数が等しいことを意味します。 テキストのその他の字句分析は実行されません。特に、', ", \や@などの文字は考慮されません。

インライン・タグで囲まれた@で始まる行は、ブロック・タグの開始とみなされません。

テキスト・コンテンツがHTMLの場合、エンティティ&lbrace;および&rbrace;を使用してカッコのバランスがとれていないことがあります。

HTMLコンテンツ

HTMLコンテンツは形式的にチェックされていませんが、一部のツールでは一般的なエラーを検出するのに役立ついくつかのチェックが行われます。

適切な標準に準拠したドキュメントを生成できるようにするには、ドキュメント・コメントでHTML構成を使用する際に、次の考慮事項を考慮する必要があります:

行の先頭のアスタリスク

ドキュメント・コメントを読むと、各行のアスタリスク(*)が破棄され、最初のアスタリスク(*)の前にある空白とタブも破棄されます。 行で先頭のアスタリスクを省略すると、先頭の空白は削除されなくなり、インデントを保持して<pre>タグ内のドキュメント・コメントにコード例を直接貼り付けることができます。 ブラウザは、空白文字をタブよりも一律に解釈します。 インデントは、左余白(区切り記号/**または<pre>タグではなく)に相対的です。

エスケープ・シーケンス

次のエスケープ・シーケンスは、テキスト、エンティティおよびHTMLが表示されるあらゆる場所でサポートされ、不便または表現が困難な文字を表します:

エスケープ・シーケンスはコンテキストに依存し、エスケープされた文字を単独で使用すると、構文の解釈が異なる場合にのみ使用できます。 その他の状況では、これらの文字シーケンスは文字どおりに解釈され、追加の解釈は行われません。

エスケープ・シーケンスは、リテラル・テキストを含むインライン・タグでは使用できません。これには、{@code}、{@literal}、{@snippet}およびユーザー定義タグが含まれます。

参照

参照は、周囲の宣言の要素を参照するドキュメント・コメントの構成です。 コンテキストに応じて、モジュール、パッケージ、クラスおよびインタフェース、コンストラクタ、メソッド、注釈メンバー、フィールド、列挙メンバー、パラメータ、レコード・コンポーネント、およびメソッドまたはコンストラクタによってスローされる例外の名前を参照できます。

参照の最も一般的な形式は次のとおりです:

この形式は、@see、{@link}および{@linkplain}タグで使用されます。

先頭のコンポーネントは、周囲のコンテキストから推測できる場合は省略できます。 後続のコンポーネントは、不要な場合は省略できます。 通常、参照はドキュメントのコメントが存在するスコープで評価されます。 特に、コンパイル単位のimport文は、クラス名およびインタフェース名の評価時に考慮されます。

classは、トップレベルまたはネストされたクラスまたはインタフェースです。

memberは、任意のコンストラクタ、メソッド、注釈メンバー、フィールドまたは列挙メンバーにできますが、ネストされたクラスまたはインタフェースにはできません。 Javaソース・コードと同様に、コンストラクタはクラスの名前を使用して識別されます。 通常、コンストラクタまたはメソッドの名前の後に、カッコで囲まれたパラメータ・タイプのリストが続く必要がありますが、メソッドまたはコンストラクタがオーバーロードされず、同じクラスまたはインタフェース内のフィールドまたは列挙メンバーの名前でもない場合、パラメータ・タイプおよびカッコは省略できます。 パラメータ・リストが指定されている場合、パラメータ・リスト内のトークンの間に空白文字が表示されることがあります。空白文字は参照内のほかの場所には表示されません。 ドキュメントのコメントを含むクラスと同じクラスのメンバーへの参照である場合、'#'はわかりやすく保持できますが、#までの参照および#を含む参照のすべての部分を省略できます。

パラメータ化された型は、参照のクラスおよびメンバー部分で使用できます。注釈は参照のどこにも使用できません。 コンストラクタまたはメソッドのパラメータ・リスト内のトークン間で空白文字が発生する可能性があります。 後続の/を名前に追加して、同じ名前のパッケージまたはクラスが存在する場合にモジュールを参照できます。

ノート: このフォームでは、特定のパラメータまたはレコード・コンポーネントの宣言を参照できません。

ドキュメント・コメントの見出しなど、生成されたドキュメントに任意のURIフラグメントへの参照を生成するための代替フォームが用意されています。 この形式では、区切り文字として二重ハッシュ・マーク(##)を使用します:

fragmentは、指定したプログラム要素をドキュメント化するページ内でURIフラグメントとして解釈されます。

@param、@throws、@serialFieldなどの他のタグは、各タグに関連する特定の種類の参照のみをサポートできます。 詳細は、個々のタグの説明を参照してください。

コメント継承

クラスとインタフェースの継承

クラスおよびインタフェースからの継承が行われる可能性のあるすべての場合に、コメントの継承が行われます。

最初の2つのケースでは、標準ドックレットは、オーバーライドするメソッドのドキュメントで"オーバーライド"という小見出しを生成します。 そのコメントが継承されているかどうかにかかわらず、オーバーライドされているメソッドへのリンクが書き込まれます。

3番目のケースでは、指定されたクラスのメソッドがインタフェースにメソッドを実装すると、標準ドックレットによって、オーバーライドするメソッドのドキュメントにサブ・ヘッダー"指定者"が生成されます。 そのコメントが継承されているかどうかにかかわらず、実装されているメソッドへのリンクが書き込まれます。

メソッド・コメントの継承

標準ドックレットでは、クラスやインタフェースのメソッド・コメントの継承により、不足しているテキストを埋めたり、メソッド・コメントを明示的に継承したりすることができます。 コンストラクタ、フィールド、およびネストされたクラスは、ドキュメンテーション・コメントを継承しません。

ノート: ドキュメンテーション・コメントを実際にコピーに利用するには、継承したメソッドのソース・ファイルが-sourcepathオプションで指定したパスに置かれていることが必要になります。 コマンド行で、クラスもパッケージも渡す必要はありません。

欠落テキストの入力

主な説明、または@return、@param、または@throwsタグがメソッド・コメントにない場合、その情報はオーバーライドするメソッドまたは(もしあれば)を実装するメソッドからコピーされます。

特定のパラメータの@paramタグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。 特定の例外の@throwsタグが見つからない場合、その例外が宣言されている場合にかぎり、その@throwsタグがコピーされます。

明示的な継承

メソッドの主説明または@return、@param、@throwsタグ・コメントに{@inheritDoc}インライン・タグを挿入します。 継承した対応する主説明またはタグ・コメントは、その箇所にコピーされます。

メソッド・コメントのアルゴリズム

メソッドにドキュメンテーション・コメントがないか、{@inheritDoc}タグがある場合、標準ドックレットは次のアルゴリズムを使用して該当するコメントを検索します。 このアルゴリズムは、もっとも限定的で適用可能なドキュメンテーション・コメントを検索するように設計されており、スーパー・クラスよりもインタフェースが優先されるようになっています。

  1. 直接実装された各(または拡張)インタフェースを、型宣言でimplements (またはextends)という語の後に表示される順序で調べます。 このメソッドについて最初に見つかったドキュメンテーション・コメントを採用します。
  2. ステップ1でドキュメンテーション・コメントが見つからなかった場合は、直接実装されている(または、拡張されている)インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用します(その際の順序は、ステップ1でインタフェースを調べたときの順序と同じ)。
  3. ステップ2でドキュメンテーション・コメントが見つからなかった場合で、このクラスがObject以外のクラスであるが、インタフェースではない場合は、次のように処理します。
    1. スーパー・クラスにこのメソッドについてのドキュメンテーション・コメントが記述されていれば、そのコメントを採用します。
    2. ステップ3aでドキュメンテーション・コメントが見つからなかった場合は、スーパー・クラスに対して、このアルゴリズム全体を再帰的に適用します。

標準タグ

次のセクションでは、標準ドックレットでサポートされている標準ブロック・タグとインライン・タグについて説明します。

ノート: 標準ドックレットは、同じ一般的な構文規則に従うユーザー定義タグもサポートしています。

@author

-authorオプションを使用すると、指定された名前テキストを持つ"著者"エントリを生成されたドキュメントに追加します。 1つのドキュメンテーション・コメントに複数の@authorタグを含めることができます。 1つの@authorタグに1つの名前を指定することも、複数の名前を指定することもできます。 前者の場合、標準ドックレットはカンマ(,)と名前の間にスペースを挿入します。 後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにコピーされます。 したがって、カンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1つのタグに複数の名前を指定してください。

JDK 1.0で導入

{@code}

<code>{@literal text }</code>と等価です。

テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、コード・フォントでtextを表示します。 これにより、(<Object>)、(3 < 4)、またはarrow (->)などのパラメータの型のように、ドキュメンテーション・コメントにHTMLエンティティ(&lt;および&gt;)の代わりに通常の山カッコ(<および>)を使用することができます。 たとえば、ドキュメンテーション・コメントのテキスト{@code A<B>C}は、生成されたHTMLページでそのままA<B>Cと表示されます。 つまり、<B>は太字であると解釈されず、コード・フォントになります。 コード・フォントなしで同じ機能を使用する場合は、{@literal}タグを使用します。

JDK 1.5で導入

@deprecated

このタグは、@Deprecated注釈と共に使用され、このAPIがもはや(それが仕事を続けても)で使用されないことを示します。 標準ドックレットは、非推奨されたテキストを主要な説明の前に移動し、イタリック体で置き、太字の警告で先行します。

deprecated-textの最初の文では、少なくとも、そのAPIが非推奨になった時期と、代替使用するべきAPIを読者に提示する必要があります。 標準ドックレットは、最初の文を要約セクションと索引にコピーします。 その後の文では、それが非推奨になった理由を説明することもできます。 置換APIを指す{@link}タグを含める必要があります。

JDK 1.0で導入

{@docRoot}

生成されるページから見た、生成ドキュメントの(生成先の)ルート・ディレクトリへの相対パスを表します。 このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。 通常は、各ページの下部から著作権のページにリンクします。

この{@docRoot}タグは、コマンド行からも、ドキュメンテーション・コメントの中でも使用できます。 このタグはすべてのドキュメンテーション・コメントで有効です: 任意のタグ(@return、@param、@deprecatedタグなど)のテキスト部分を含む、概要、モジュール、パッケージ、クラス、インタフェース、コンストラクタ、メソッドおよびフィールド。

たとえば、ヘッダー、フッター、またはボトムが定義されているコマンドラインでは、次のようになります:

javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'.

makeファイルで{@docRoot}タグをこのように使用する場合、一部のメイク・ファイル・プログラムは、中括弧{}文字をエスケープする特別な方法を必要とします。 たとえば、Inprise MAKEバージョン5.2をWindows上で実行する場合は、{{@docRoot}}のように、中カッコを二重にする必要があります。 さらに、-bottomなどのオプションに対する引数を、単一引用符ではなく、二重引用符で囲む必要があります。href引数の値を囲む引用符は省略します。

たとえば、ドキュメントのコメントでは次のようになります:

/**
 * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
 */

このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。 式<a href="{@docRoot}/copyright.html">は、java/lang/Object.javaの場合は<a href="../../copyright.html">に、java/lang/ref/Reference.javaの場合は<a href="../../../copyright.html">に解決されます。

JDK 1.3で導入

@exception

このタグは@throwsタグと同等です。これは推奨されるフォームです。

JDK 1.0で導入

@hidden

生成されたAPIドキュメントからプログラム要素を非表示にします。 このタグは、そのような項目がまったく表示されないようにAPIを設計することが他に不可能な場合に使用できます。

JDK 9で導入

{@index}

標準のドックレットによって生成された索引ファイルに、単語またはフレーズと省略可能な短い説明が含まれることを宣言します。 インデックス・エントリは、生成されたドキュメントのこの時点で表示される語句にリンクされます。 この説明は、頭字語のように、索引付けされる語句がそれ自身ではっきりしていない場合に使用することができます。

JDK 9で導入

{@inheritDoc}

もっとも近い継承可能なクラスまたは実装可能なインタフェースから、このタグの現在のドキュメンテーション・コメントに、ドキュメントを継承(コピー)します。 この機能により、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使って記述することができます。

このタグは、ドキュメンテーション・コメントの次の位置でのみ有効です。

継承階層でコメントを見つける方法については、「メソッド・コメントの継承」を参照してください。 このタグが見つからない場合、コメントは、このセクションで説明するルールに応じて、自動的に継承されるかどうかが決まります。

JDK 1.4で導入

参照クラスの指定されたモジュール、パッケージ、クラスまたはメンバー名のドキュメントを指す表示可能なテキスト・ラベルを持つインライン・リンクを挿入します。 このタグはすべてのドキュメンテーション・コメントで有効です: @return、@paramおよび@deprecatedタグなどの任意のタグの説明部分を含む、概要、モジュール、パッケージ、クラス、インタフェース、コンストラクタ、メソッドおよびフィールド。

このタグは、@seeタグの「第三フォーム」に似ています。 主な違いは、{@link}タグがリンクを"関連項目"セクションに配置するのではなく、インライン・リンクを生成することです。 インライン・テキストの他の部分と区別するために、{@link}タグの最初と最後に中カッコを記述します。 ラベルの中で右中カッコ(})を使う必要がある場合は、HTMLエンティティ表記「&#125;」を使います。

1つの文の中で使用できる{@link}タグの数に制限はありません。

たとえば、次のコメントではgetComponentAt(int, int)メソッドを参照しています。

Use the {@link #getComponentAt(int, int) getComponentAt} method.

標準ドックレットでは、上記のコードから次のHTMLが生成されます(同じパッケージの別のクラスを参照している場合)。

Use the <a href="Component.html#getComponentAt(int,int)">getComponentAt</a> method.

上記の行は、Webページ上では次のように表示されます。

getComponentAtメソッドを使用します。

JDK 1.2で導入

{@linkplain}

リンクのラベルがコード・フォントではなくプレーン・テキストで表示される点以外は{@link}と同じ動作になります。 ラベルがプレーン・テキストで記述されていると便利です。 たとえば、 

Refer to {@linkplain #add() the overridden method}.

次のように表示されます:

「オーバーライドされたメソッド」を参照してください。

JDK 1.4で導入

{@literal}

テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、textを表示します。 これにより、ドキュメンテーション・コメント内のHTMLエンティティ(&lt;および&gt;)の代わりに山カッコ(<および>)を使用することができます(パラメータ・タイプ(<Object>)、不等式(3 < 4)、または矢印(->)など)。 たとえば、ドキュメンテーション・コメントのテキスト{@literal A<B>C}は、生成されたHTMLページでそのままA<B>Cとブラウザに表示されます。 <B>は太字であると解釈されません(コード・フォントにならない)。 コード・フォントのテキストと同じ機能を使用するには、{@code}タグを使用します。

JDK 1.5で導入

@param

"Parameters"セクションに、指定されたパラメータ名の後に指定された説明が続くパラメータを追加します。 説明は複数の行に続きます。 このタグは、メソッド、コンストラクタ、またはクラスのドキュメンテーション・コメント内でのみ有効です。 パラメータ名には、メソッドまたはコンストラクタ内のパラメータの名前、またはクラス、メソッド、またはコンストラクタの型パラメータの名前を指定できます。 このようなパラメータ名の前後に山カッコを使用して、型パラメータの使用を示します。

クラスの型パラメータの例:

/**
 * @param <E> Type of element stored in a list
 */
public interface List<E> extends Collection<E> { ... }

メソッドの型パラメータを含むパラメータの例:

/**
 * @param string  the string to be converted
 * @param type    the type to convert the string to
 * @param <T>     the type of the element
 * @param <V>     the value of the element
 */
<T, V extends T> V convert(String string, Class<T> type) { ... }

JDK 1.0で導入

@provides

このタグは、モジュール宣言のドキュメンテーション・コメントにのみ表示され、モジュールが提供するサービスの実装を文書化します。 この記述は、このサービス・プロバイダのインスタンスを取得する方法、およびプロバイダの重要な特徴を特定するために使用されてもよい。

JDK 9で導入

@return

ブロック・タグとして、指定された説明を持つ"戻り値"セクションを追加し、メソッドによって返される値の詳細を指定します。

インライン・タグとして、メソッドのメイン説明の最初の文のコンテンツ、および@return descriptionも存在しているかのように"戻り値"セクションを提供します。 デフォルトの英語ロケールでは、最初の文はReturns description .です

このタグは、メソッドのドキュメンテーション・コメントでのみ有効です。 インライン・タグとして、メソッドのメイン説明の先頭でのみ発生する可能性があります。

JDK 1.0ではブロック・タグとして、JDK 16ではインライン・タグとして導入されました。

@see

"関連項目"見出しに、参照を指すリンクまたはテキスト・エントリを追加します。 1つのドキュメンテーション・コメントには、任意の数の@seeタグを指定できます。すべての@seeタグの内容は、同じ見出しの下にグループ化されます。 @seeタグには、3種類の形式があります。 他のプログラム要素を参照する形式が最も一般的です。 このタグは、すべてのドキュメンテーション・コメントで有効です。 文内のインライン・リンクをパッケージ、クラスまたはメンバーに挿入するには、{@link}を参照してください。

stringのテキスト・エントリを追加します。 リンクは生成されません。 文字列は、URLで利用できない情報への参照である可能性があります。 標準ドックレットは、最初の文字として二重引用符(")を検索することによって、これを他のケースと区別します。

urlで定義されているリンクを追加します。 URLは、相対URLまたは絶対URLです。 標準ドックレットは、最初の文字として小文字の記号(<)を検索することによって、これを他の場合と区別します。

指定されたプログラム要素のドキュメントを指す表示可能なテキスト・ラベルを持つリンクを追加します。

referenceは、任意の有効なプログラム要素に「参照」できます。 この要素が文書化されたクラスにある場合、標準ドックレットによってその要素へのリンクが作成されます。

外部参照クラスへのリンクを作成するには、-linkオプションを使います。 外部参照クラスは、コマンドラインでjavadocツールに渡されないクラスです。 生成ドキュメント内で外部参照クラスにリンクしている箇所は、外部参照または外部リンクと呼ばれます。 たとえば、java.awtパッケージでのみ標準ドックレットを実行すると、Objectなどの任意のクラスが外部参照クラスになります。 外部参照クラスにリンクするには、-linkおよび-linkofflineオプションを使用します。 外部参照クラスのソース・コメントは、javadocコマンドの実行で利用できません。

参照クラスに属していない名前のドキュメントを参照するには、他の2つの@seeタグ形式を使います。

labelは、リンク・ラベルとして使用されるテキストであり、プログラム要素への参照ではオプションです。 エレメント参照にラベルが指定されていない場合、参照のターゲットに基づいてデフォルトが生成されます。 自動生成されたテキストとは異なるテキストにする場合は、ラベルを使用します。 URIフラグメントへの参照の場合、ラベルを指定する必要があります。 ラベルには空白文字を含めることができます。

JDK 1.0で導入

@serial

デフォルトの直列化可能フィールドのドキュメンテーション・コメントで使用します。 「クラスの直列化可能なフィールドおよびデータのドキュメント化」を参照してください。

Oracleの「クラスを直列化形式仕様に含めるための基準」も参照してください。

オプションのフィールド記述は、フィールドの意味を説明し、許容可能な値をリストする必要があります。 必要に応じて、複数の行に渡って説明を記述できます。 標準ドックレットは、この情報を、直列化された形式のページに追加します。

クラスを直列化可能にした後で直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。

includeおよびexclude引数は、直列化された形式ページにクラスまたはパッケージを含めるか除外するかを示します。 これらの引数には、次のような効果があります。

たとえば、javax.swingパッケージには、package-info.javaの@serial excludeタグが付けられています。 パブリック・クラスjava.security.BasicPermissionには、@serial excludeタグが付けられています。 package-privateクラスjava.util.PropertyPermissionCollectionは、@serial includeタグで指定されています。

クラス・レベルで指定された@serialタグは、パッケージ・レベルで指定された@serialタグをオーバーライドします。

JDK 1.2で導入

@serialData

data-descriptionの値を使用して、直列化された形式でのデータの型と順序をドキュメント化します。 このデータには、writeObjectメソッドによって書き込まれるオプションのデータ、およびExternalizable.writeExternalメソッドによって書き込まれるすべてのデータ(基底クラスを含む)が含まれます。

@serialDataタグは、readObject, writeObject, readExternal, writeExternal, readResolveメソッドおよびwriteReplaceメソッドのドキュメント・コメントで使用できます。

JDK 1.2で導入

@serialField

Serializable classのserialPersistentFieldsメンバーのObjectStreamFieldコンポーネントを記録します。 各ObjectStreamFieldコンポーネントに対して@serialFieldタグを1つ使用してください。

JDK 1.2で導入

@since

生成されたドキュメントに、指定したsince-text値を持つ"以来"見出しを追加します。 このテキストには、特別な内部構造はありません。 このタグは任意のドキュメント・コメントで有効です: 概要、モジュール、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールド。 このタグは、たとえば、since-text値で指定されたソフトウェア・リリース以降にこの変更または機能が存在することを意味: @since 1.5。

Javaプラットフォームのソース・コードの場合、@sinceタグは、JavaプラットフォームAPI仕様のバージョンを示します。そのソース・コードがリファレンス実装に追加された時期を示すとはかぎりません。 複数の@sinceタグが許可され、複数の@authorタグのように扱われます。 プログラム要素が複数のAPIで使用される場合、複数のタグを使用できます。

JDK 1.1で導入

@snippet

生成されたドキュメントにコード例を示すフラグメント("snippet")が含まれます。 bodyまたは外部ファイル(あるいはその両方)をattributesで指定することによって、タグ内でコードをインラインで指定できます。 コンテンツ内では、テキスト内のリージョンを識別し、これらのリージョンにテキストを表示する方法を指示するために、「マークアップ・タグ」を行コメントに配置できます。

スニペットの詳細は、attributesとして、name = valueペアの形式で、最初のタグ名の後に配置できます。 属性名は常に単純な識別子です。 属性値には、識別子、符号なし整数、または単一引用符または二重引用符のいずれかで囲むことができます。エスケープ文字はサポートされません。 属性名が存在する場合に、属性値と前述の=を省略できます。 属性はタグ名から分離され、空白や改行などの空白文字で区切られます。

スニペットは、APIと生成されたHTMLの両方でスニペットを識別するために使用でき、スニペットへのリンクの作成に使用できるid属性を指定できます。 生成されたHTMLでは、IDはスニペットを表すために生成される最も外側の要素に配置されます。

コード・フラグメントは通常Javaソース・コードですが、プロパティ・ファイルのフラグメント、他の言語のソース・コード、またはプレーン・テキストの場合もあります。 スニペットでは、スニペットのコンテンツの種類を識別するlang属性を指定できます。 インライン・スニペットの場合、デフォルト値はjavaです。 外部スニペットの場合、デフォルト値はスニペット・コンテンツを含むファイルの名前の拡張から導出されます。

インライン・スニペット

インライン・スニペットには、タグ自体に含まれるスニペットの内容が含まれます。

生成されたドキュメントに含まれるスニペットの内容は、コロン(:)の後の最初の改行と閉じ中カッコ(})の間のテキストです。

HTMLエンティティを含む<、>、&などの文字をエスケープする必要はありません。また、ドキュメントのコメント・タグをエスケープする必要はありません。

周囲の空白は、String::stripIndentを使用してコンテンツから削除されます。

インライン・スニペットの内容には、次の2つの制限があります:

  1. */は囲んでいるドキュメントのコメントを終了するため、文字シーケンス*/はコンテンツ内の任意の場所で使用できません。 これには、/* ... */コメントの使用、//コメント内、または正規表現を表すために使用されるリテラルなどの文字列リテラル内の使用が含まれます。 この制限は、ドキュメント・コメントのすべてのコンテンツに適用されます。@snippetタグに固有ではありません。

  2. インライン・スニペットのコンテンツには、中カッコ文字のバランスされたペアのみを含めることができます。 全体のインライン・タグは、開始中カッコに一致する最初の右カッコで終了します。 この制限は、すべてのインライン・タグに適用されます。@snippetタグに固有ではありません。

外部スニペット

外部スニペットとは、スニペットの内容を含む個別のクラスまたはファイルを指します。

外部スニペットでは、コロン、改行および後続の内容は省略できます。

インライン・スニペットとは異なり、外部スニペットにはコンテンツに制限はありません。 特に、/* ... */コメントを含めることができます。

外部コードのロケーションは、クラス名、class属性を使用するか、file属性を使用して短い相対ファイル・パスで指定できます。 いずれの場合も、ファイルは{@snippet ...}タグでソース・コードを含むディレクトリのsnippet-filesサブディレクトリをルートとするパッケージ階層に配置できます。 または、javadocツールの--snippet-pathオプションで指定された補助検索パスにファイルを配置することもできます。 snippet-filesサブディレクトリの使用は、補助ドキュメント・ファイルのdoc-filesサブディレクトリの使用に似ています。

外部スニペットのファイルには、ドキュメントの各部分に表示される異なるスニペット・タグで参照される複数のリージョンを含めることができます。

ハイブリッド・スニペット

ハイブリッド・スニペットは、内部スニペットと外部スニペットの両方です。 これには、文書化されているクラスのソース・コードをだれでも読み取る便宜のために、タグ自体内のスニペットの内容が含まれ、スニペットの内容を含む個別のファイルも参照します。

インライン・スニペットとしてハイブリッド・スニペットを処理した結果が、そのハイブリッド・スニペットを外部スニペットとして処理した結果と一致しない場合、エラーになります。

マークアップ・タグ

マークアップ・タグは、スニペットのコンテンツ内のリージョンを定義します。 また、テキストの一部の強調表示、テキストの変更、ドキュメントの他の場所へのリンクなど、コンテンツの表示も制御します。 内部、外部およびハイブリッド・スニペットで使用できます。

マークアップ・タグは@nameで始まり、必要な引数が続きます。 これらのコメントは、//コメント(または他の言語または形式での同等)に配置されるため、ソース・コードの本文を非段階的に干渉しないため、インライン・スニペットでは/* ... */コメントを使用できないためです。 このようなコメントは、「マークアップ・コメント」と呼ばれます。

複数のマークアップ・タグを同じマークアップ・コメントに配置できます。 コメントがコロン(:)で終了しないかぎり、マークアップ・タグはコメントを含むソース行に適用されます。この場合、タグが直後の行にあるかのようになります。 後者の構文は、マークアップ・コメントが特に長い場合や、スニペットのコンテンツの構文形式ではコメントを非コメント・ソースと同じ行に表示できない場合に役立ちます。 生成された出力にマークアップ・コメントは表示されません。

他のシステムではマークアップ・コメントと同様にメタ・コメントを使用するため、@で始まるコメントの後に認識されない名前は、マークアップ・コメントとして無視され、生成された出力に表示されます。 名前が認識され、その後マークアップ・コメントにエラーがある場合は、エラーが報告されます。 このような場合に生成される出力は、スニペットから生成される出力に関して未定義です。

リージョン

リージョンとは、スニペットによって表示されるテキストを識別する、オプションの名前付きの行の範囲です。 また、テキストの強調表示や変更など、アクションの範囲も定義します。

リージョンの開始は、次のいずれかでマークされます

リージョンの終了は、@endまたは@end region= nameでマークされます。 名前が指定されている場合、タグはその名前で始まるリージョンを終了します。 名前が指定されていない場合、タグは、一致する@endタグがまだない最近開始されたリージョンを終了します。

一致する@startタグと@endタグの異なるペアで作成されたリージョンに制約はありません。 リージョンは重複することも可能ですが、このような使用方法が共通であるとは想定していません。

強調表示

行または行の範囲でコンテンツを強調表示するには、@highlightに続けて、考慮されるテキストの範囲、そのスコープ内のテキスト、および強調表示のタイプを指定する引数を使用します。

regionまたはregion= nameが指定されている場合、スコープはそのリージョンであり、対応する@endタグまでです。 それ以外の場合、スコープは現在の行のみです。

スコープ内のリテラル文字列の各インスタンスを強調表示するには、substring= stringを使用して文字列を指定します。stringは、単一または二重引用符で囲まれた識別子またはテキストです。 スコープ内の正規表現に一致するテキストの各インスタンスを強調表示するには、regex= stringを使用します。 これらの属性のどちらも指定されていない場合、スコープ全体が強調表示されます。

強調表示のタイプは、typeパラメータで指定できます。 有効なタイプ名は、bold、italicおよびhighlightedです。 タイプの名前はCSSクラス名に変換され、システム・スタイル・シートでプロパティを定義したり、ユーザー定義スタイル・シートでオーバーライドしたりできます。

表示されたテキストの変更

スニペットの内容は、外部ツールによってアクセスおよび検証できるコードとして記述しますが、コンパイルしないフォームで表示すると便利です。 たとえば、インポートされたタイプを使用するコードとともに、説明のためにimport文を含めることが望ましい場合があります。 または、省略記号やその他のマーカーを使用してコードを表示し、その時点で追加のコードを挿入する必要があることを示すことが望ましい場合があります。 これを行うには、スニペットの内容の一部を置換テキストに置き換えます。

一部のテキストを置換テキストで置き換えるには、@replaceの後に、考慮するテキストの範囲、置換対象のスコープ内のテキストおよび置換テキストを指定する引数を使用します。

regionまたはregion= nameが指定されている場合、スコープはそのリージョンであり、対応する@endタグまでです。 それ以外の場合、スコープは現在の行のみです。

スコープ内のリテラル文字列の各インスタンスを置き換えるには、文字列をsubstring= string (stringは、単一または二重引用符で囲まれた識別子またはテキスト)で指定します。 スコープ内の正規表現に一致するテキストの各インスタンスを置き換えるには、regex= stringを使用します。 これらの属性のどちらも指定されていない場合、スコープ全体が置換されます。

置換テキストをreplacementパラメータで指定します。 正規表現を使用して置換するテキストを指定する場合、$ numberまたは$ nameを使用して、String::replaceAllで定義されている正規表現にあるグループを置換できます。

テキストを削除するには、空の置換文字列とともに@replaceを使用します。 テキストを挿入するには、@replaceを使用して、置換テキストを挿入する任意のテキストを置換します。 no-opテキストは、'//'マーカーまたは空の文(;)です。

テキストのリンク

テキストをAPIの他の部分の宣言にリンクするには、@linkに続けて、考慮されるテキストの範囲、リンクするスコープ内のテキストおよびリンクのターゲットを指定する引数を使用します。

regionまたはregion= nameが指定されている場合、スコープはそのリージョンであり、対応する@endタグまでです。 それ以外の場合、スコープは現在の行のみです。

スコープ内のリテラル文字列の各インスタンスをリンクするには、substring= stringを使用して文字列を指定します。stringは、単一または二重引用符で囲まれた識別子またはテキストです。 スコープ内の正規表現に一致するテキストの各インスタンスをリンクするには、regex= stringを使用します。 これらの属性のどちらも指定されていない場合、スコープ全体がリンクされます。

targetパラメータを使用してターゲットを指定します。 値の形式は、標準のインライン{@link ...}タグで使用される形式と同じです。

JDK 18で導入

@spec

URLおよびタイトルの観点から外部仕様を識別します。 URLは絶対URLまたは相対URLです。 相対URLは、"ベースURL"に対して評価されます。

同じURLを指定するすべてのタグは、同じ対応するタイトルを指定する必要があります。逆に、URLが異なるタグのタイトルは異なる必要があります。

JDK 20で導入

{@summary}

API記述の最初の文を特定して使用するためのデフォルト・ポリシーの代わりに、API記述の要約を特定します。 タグは、メインの説明の先頭で使用した場合にのみ意味を持ちます。 いずれの場合でも、タグはコンテンツをレンダリングするだけでレンダリングされます。

JDK 10で導入

{@systemProperty}

システム・プロパティの名前としてproperty-nameを指定します。 名前は"ドット識別子"にする必要があります。 特に、空白文字や}などの文字を含めることはできません。 タグで他のコンテンツは許可されません。追加コンテンツが今後使用するために予約される可能性があります。 このタグは、すべてのドキュメント・コメントで使用できます。

JDK 12で導入

@throws

指定された名前の後に指定された説明が続く例外を"Throws"セクションに追加します。

exception-nameは、メソッドによってスローされる可能性がある例外に対して「参照」する必要があり、例外クラスの名前または型変数のいずれかである必要があります。 このタグは、メソッドまたはコンストラクタのドキュメンテーション・コメント内でのみ有効です。

ドキュメント・コメントでは、同じ例外または異なる例外に対して複数の@throwsタグを使用できます。

チェックされたすべての例外が確実に文書化されるように、throws句の例外に@throwsタグが存在しない場合、標準ドックレットは、@throwsタグで文書化されたかのように、生成された出力(説明なし)にその例外を追加します。

オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、@throwsドキュメンテーションがそのメソッドからサブクラスにコピーされます。 インタフェース・メソッドから実装メソッドにコピーされる場合も同様です。 @throwsタグにドキュメンテーションを継承させるには、{@inheritDoc}タグを使用できます。

@exceptionタグはこのタグと同等ですが、@throws形式が推奨されるようになりました。

JDK 1.2で導入

@uses

このタグは、モジュール宣言のドキュメンテーション・コメントにのみ表示され、モジュールがサービスを使用できることを文書化します。 この記述は、必要とされる可能性のあるサービスの特性、およびサービスのためのプロバイダが利用できない場合にモジュールが何をするかを指定するために使用され得ます。

JDK 9で導入

{@value}

コンパイル時定数値を持つ静的フィールドの値を表示します。

書式文字列は省略できます。その場合は、フィールドのタイプに応じてデフォルトの書式が使用されます。 書式文字列を指定する場合は、パーセント文字(%)で開始するか、二重引用符文字(")で囲む必要があります。 パーセント文字を1文字のみ含める必要があります。 文字列は、java.util.Formatterのドキュメントで指定されている書式文字列の定義に準拠している必要があります。 書式文字列で指定する変換は、定数値の型に適している必要があります。

静的フィールドのドキュメント・コメントにfield_reference引数を指定せずに{@value}タグを使用すると、その定数の値が表示されます:

/**
 * The value of this constant is {@value}.
 */
public static final String SCRIPT_START = "<script>"

ドキュメントのコメントでfield-reference引数とともに使用すると、{@value}タグは、指定された定数の値を表示します:

/**
 * Evaluates the script starting with {@value #SCRIPT_START}.
 */
public String evalScript(String script) {}

JDK 1.4で導入されました。formatはJDK 20で追加されました。

@version

-versionオプションを使用すると、指定されたversion-text値を持つ"バージョン"小見出しを生成された文書に追加します。 このタグは、このコードが含まれるソフトウェアの現在のリリース番号を保持するように意図されています。これに対し、@sinceは、このコードが導入されたリリース番号を保持します。 version-textの値には、特別な内部構造はありません。

1つのドキュメンテーション・コメントに複数の@versionタグを含めることができます。 必要に応じて、@versionタグごとに1つのリリース番号を指定することも、タグごとに複数のリリース番号を指定することもできます。 前者の場合、標準ドックレットはカンマ(,)と名前の間にスペースを挿入します。 後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにコピーされます。 したがって、カンマ以外のローカライズされた区切り記号が必要な場合は、1行に複数の名前を使用できます。

JDK 1.0で導入

タグを使用できる場所

次の表に、どのコンテキストでどのタグを使用できるかをまとめます。

タグを使用できるコンテキスト
タグ モジュール パッケージ 型 コンストラクタ メソッド フィールド その他
@author ✓ ✓ ✓ ✓
{@code} ✓ ✓ ✓ ✓ ✓ ✓ ✓
@deprecated ✓ ✓ ✓ ✓ ✓
{@docRoot} ✓ ✓ ✓ ✓ ✓ ✓ ✓
@exception ✓ ✓
@hidden ✓ ✓ ✓
{@index} ✓ ✓ ✓ ✓ ✓ ✓ ✓
{@inheritDoc} ✓
{@link} ✓ ✓ ✓ ✓ ✓ ✓ ✓
{@linkplain} ✓ ✓ ✓ ✓ ✓ ✓ ✓
{@literal} ✓ ✓ ✓ ✓ ✓ ✓ ✓
@param ✓ ✓ ✓
@provides ✓
@return ✓
@see ✓ ✓ ✓ ✓ ✓ ✓ ✓
@serial ✓ ✓ ✓
@serialData *
@serialField *
@since ✓ ✓ ✓ ✓ ✓ ✓ ✓
{@snippet} ✓ ✓ ✓ ✓ ✓ ✓ ✓
{@summary} ✓ ✓ ✓ ✓ ✓ ✓ ✓
{@systemProperty} ✓ ✓ ✓ ✓ ✓ ✓ ✓
@throws ✓ ✓
@uses ✓
{@value} ✓ ✓ ✓ ✓ ✓ ✓ ✓
@version ✓ ✓ ✓ ✓

ノート: