JavaDoc標準ドックレットのドキュメント・コメント仕様 (JDK 23)

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

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

ドキュメンテーション・コメント

ドキュメント・コメントは、ソース・コードに、ドキュメント化に使用する宣言の近くに表示されるスタイル化されたコメントです。

ドキュメント・コメントが認識されるのは、モジュール、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、注釈インタフェース要素、列挙メンバーまたはフィールドの宣言の直前に配置された場合のみです。言い換えると、宣言の一部である注釈、修飾子、キーワード、識別子、またはその他のJava構文の前に、ドキュメントのコメントが表示されるはずです。

ドキュメント・コメントには2種類あります: 従来のドキュメント・コメントおよびマークダウン・ドキュメントのコメント。

いずれかの種類、または両方の種類を1つのソース・ファイルで使用できます。

宣言文ごとに1つの文書コメントしか認識されません。宣言の前に複数のドキュメント・コメントがある場合は、宣言の最初に最も近いコメントが使用されます。

ドキュメントは、特定のファイルでも提供される場合があります:

package.html: 履歴互換性のため、パッケージのドキュメントは、パッケージのソース・ディレクトリにあるpackage.htmlというファイルに記述できます。一般に、package-info.javaという名前のファイルにドキュメント・コメントを指定することをお薦めします。このファイルには、パッケージ宣言のインポート文および注釈が含まれる場合もあります。
doc-files/*.{html,md}: パッケージに関する追加のドキュメントは、HTMLファイルおよびマークダウン・ファイルで、パッケージのソース・ディレクトリのdoc-filesサブディレクトリにあります。

HTMLファイルは、.htmlで終わるファイル名で識別されます。 HTMLファイルの<main>要素の内容、または<main>要素がない場合は<body>要素が、従来のドキュメント・コメントの内容であるかのように処理されます。

マークダウン・ファイルは、.mdで終わるファイル名で識別されます。マークダウン・ファイルのコンテンツは、マークダウン・ドキュメント・コメントの内容であるかのように処理されます。

従来のドキュメント・コメント

従来のドキュメント・コメントは、/**で始まる「伝統的なコメント」です。このようなコメント「アスタリスクで始まる」の行が先頭の空白の後に存在する場合は、先頭の空白およびアスタリスクが削除されます。アスタリスクの後に表示される空白は削除されません。

従来のドキュメント・コメントには、「HTMLコンテンツ」、「インライン・タグ」および「ブロック・タグ」を含めることができます。「エスケープ・シーケンス」を使用して、不便または表現が困難な文字を表すこともできます。

マークダウン文書コメント

マークダウンを含むドキュメント・コメントは、連続する一連の行で構成され、それぞれがオプションの空白の後に///が続きます。

マークダウンのドキュメント・コメントには、「マークダウン・コンテンツ」 (必要に応じてHTMLを含む)、「インライン・タグ」および「ブロック・タグ」を含めることができます。

一般的な構文

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

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

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

メイン摘要

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

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

欠落している主な説明の例。

最初のブロック・タグの前にコンテンツがありません:
```
/**
 * @param ...
 * ...
 */
```
空のドキュメント・コメント:
```
/**
 *
 */
```

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

ブロック・タグ

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

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

インライン・タグ

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

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

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

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

HTMLコンテンツ

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

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

HTMLコンストラクトは、HTML 5で記述する必要があります。
生成されたドキュメントのページ内で適切に構造化された見出しをサポートするには、モジュール、パッケージおよび型宣言のドキュメント・コメントの見出し(ネストした型を含む)を「見出しレベル」 2から開始し、必要に応じて増加させる必要があります。同様に、コンストラクタ、メソッド、フィールドおよびその他のメンバーのドキュメント・コメントの見出しは、見出しレベル4から開始する必要があります。スタンドアロンのHTMLファイル(doc-filesサブディレクトリなど)では、見出しは見出しレベル1で開始する必要があります。
プログラム要素の宣言で生成されたドキュメント内の位置を識別するために使用される一意の識別子との競合を回避するため、ユーザー定義のid属性の値には、Java識別子の有効な文字ではない文字(-など)が含まれる必要があります。

マークダウン・コンテンツ

マークダウン・コードの各行の先頭と末尾の水平空白は重要になる可能性があるため、このようなコメントの内容は次のように決定されます:

先頭の空白および3つの初期/文字は、各行から削除されます。
先行する空白文字を削除して、先行する空白文字が最小の空白行で空白以外の行の先行する空白文字が残るまで、行は左にシフトされます。
重要な場合があるため、先頭の空白と各行の末尾の空白は保持されます。たとえば、行の先頭にある空白は「インデントされたコード・ブロック」を示し、行の末尾にある空白は「改行」を示す場合があります。

ノート: 先頭に付随する空白を削除するポリシーは、末尾の空白行に対して特別な処理を必要としない点を除き、String.stripIndentの場合と同様です。

コメントの各行で///の後に表示される文字に制限はありません。特に、コメントには、独自のコメントを含むコード・サンプルが含まれる場合があります:

/// Here is an example:
///
/// ```
/// /** Hello World! */
/// public class HelloWorld {
///     public static void main(String... args) {
///         System.out.println("Hello World!"); // the traditional example
///     }
/// }
/// ```

新しい種類のドキュメント・コメントを視覚的に区別するだけでなく、行末の(//)コメントを使用すると、従来の(/* ... */)コメントの使用に固有のコメントの内容に対する制限がなくなります。特に、従来のコメント(JLS 3.7)内で文字シーケンス*/を使用することはできませんが、従来のコメントを含むサンプル・コード、"地球儀"式を含む文字列および正規表現を含む文字列を記述する場合は、使用することが望ましい場合があります。

ノート: コメントに空白行を含めるには、オプションの空白文字で始まり、その後に///が続く必要があります。完全に空白行を指定すると、前後のコメントは個別のコメントとして扱われます。その場合、最後のコメントを除くすべてのコメントは破棄され、最後のコメントのみが後続の宣言のドキュメント・コメントとみなされます。

たとえば:

/// This is an example ...
///
/// ... of a 3-line comment containing a blank line.

次の例の空白行は最初のコメントを終了するため、空白行のあとに続くコメントは個別のコメントとして扱われます。

/// This comment will be treated as a "dangling comment" and will be ignored.

/// This is the comment for the following declaration.
public void m() { }

2つの///コメントの間に出現する可能性のある///以外のコメントについても同様です。

構文

マークダウン・ドキュメント・コメントの全体的な構文は、マークダウンのCommonMarkバリアントの構文です。リンクの機能拡張により、他のプログラム要素への便利なリンクが可能になります。すべてのJavaDocタグと同様に、単純な「GFMパイプ表」がサポートされています。

Headings

「ATXヘッダー」と「setext見出し」の両方がサポートされています。 HTMLの見出しとは異なり、マークダウンの見出しはレベル1から始まり、ドキュメントのコメントの内容に関係なくそこから増加する必要があります。 (これらは、生成されたドキュメントの正しい見出しレベルに変換されます。)

リンク

参照リンクの一般的な形式は[text][label]で、textは表示するテキスト、labelはリンクの宛先のラベルで、その後は[label]: uriという形式の行によって定義されます。「折りたたみ」および「ショートカット」フォームは、labelがtextと同じ場合にも使用できます。

ドキュメント・コメントで、参照リンクのラベルを明示的に定義する場合は、同じドキュメント・コメントで定義する必要があります。ただし、定義されておらず、構文的に「参照」とプログラム要素が一致する場合、そのプログラム要素への参照として暗黙的に定義されます。ラベルがプログラム・エレメントへの参照のように見えるが、そのエレメントがないと、エラーになります。

次のすべては、表示されるテキストが異なるjava.lang.Object#hashCode()へのリンクを表します:

[the default hashcode for an object][java.lang.Object#hashCode()]
[the default hashcode][Object#hashCode()] - この場合、完全修飾名は必要ありません
[Object#hashCode()][] - 参照リンクの縮小形式の使用
[Object#hashCode()] - 参照リンクのショートカット形式の使用

次の例に示すように、任意の種類のプログラム要素にリンクできます:

/// * a module [java.base/]
/// * a package [java.util]
/// * a class [String]
/// * a field [String#CASE_INSENSITIVE_ORDER]
/// * a method [String#chars()]

「インライン・リンク」はドキュメント・コメントでもサポートされていますが、プログラム要素をラベルとして認識すると、参照リンクがインライン・リンクよりも一般的に有用であることがわかります。

参照リンクの標準ルールに従って、参照内の大カッコの使用をエスケープする必要があります。これは、配列パラメータを使用してメソッドへの参照を作成する場合に発生することがあります。次に、String.copyValueOf(char[])へのリンクを示します

[String#copyValueOf(char\[\])]

参照リンクの通常のレンダリングでは、デフォルトのプレーン・フォントが使用されます。モノ・スペース・フォントを使用する場合は、バック・ティックを使用してコード・スパン内にテキストを囲む必要があります。プログラム要素への参照では、テキストが参照(縮小フォームやショートカット・フォームを使用する場合など)と同じ場合はモノ・スペース・フォントが自動的に使用され、それ以外の場合はデフォルトのプレーン・フォントが使用されます。次に、これらのフォームが既存のlinkおよびlinkplainタグにどのように対応するかを示します。

[an object][Object] ⇒ {@linkplain Object an object}
[Object][] ⇒ {@link Object}
[Object] ⇒ {@link Object}
[`a link in monospace font`][Object] ⇒ {@link Object a link in monospace font}
[a link with `mixed` fonts][Object] ⇒ {@linkplain Object a link with {@code mixed} fonts}

ノート: ドキュメント・コメント内の他の場所でユーザー定義のリンク参照定義を参照するドキュメント・コメントの最初の文で参照リンクを使用することはできません。かわりに、この状況でインライン・リンクを使用できます。

表

単純表は、「GitHubフレーバ・マークダウン」で定義された構文を使用してサポートされます。たとえば、単純な表は次のように記述できます:

/// | Latin | Greek |
/// |-------|-------|
/// | a     | alpha |
/// | b     | beta  |
/// | c     | gamma |

ノート: アクセシビリティに必要なキャプションやその他の機能はサポートされていません。このような場合は、引き続きHTML表を使用することをお薦めします。

インライン・タグとブロック・タグ

「インライン・タグ」および「ブロック・タグ」はいずれもマークダウン・ドキュメント・コメントで使用できますが、「コード・スパン」および「フェンス」または「インデント」コード・ブロックのリテラル・テキスト内では使用できません。

マークアップを含むテキストを含むタグについては、マークダウン・ドキュメントのコメントで、マークアップもマークダウン形式になります。

従来のドキュメント・コメントと同様に、インライン・タグのコンテンツは、空白行を含む複数の行にまたがる場合があります。

「参照リンク」を明示的な「リンク・ラベル」とともに使用する場合、参照とラベルはコメントの同じ部分に存在する必要があります: メインの説明、またはインライン・タグまたはブロック・タグのいずれか。参照リンクは、コメントの別の部分で定義されたラベルを参照したり、別のコメントで定義したラベルを参照したりすることはできません。

inheritDocタグは、1つ以上のスーパータイプのドキュメントを含めるために使用されます。タグを含むコメントの形式が、継承するドキュメントを含むコメントの形式と同じである必要はありません。ライブラリ内のコメントはすべて同じ形式を使用する可能性がありますが、異なる著者によって記述された異なるライブラリ内のコメントを処理する場合、その可能性は低くなります。

構文の強調表示と埋込み言語

「フェンス・コード・ブロック」のオープン・フェンスの後には、対応する生成されたHTMLでCSSクラス名を導出するために使用される最初の単語である「情報文字列」が続き、JavaScriptライブラリで(Prismなど)を強調表示したり、図(Mermaidなどで)をレンダリングしたりする構文を有効にするために使用できます。

ノート: JavaScriptライブラリは、javadoc --add-scriptオプションを使用してドキュメントに追加できます。

エスケープ・シーケンス

従来のドキュメント・コメントでは、テキスト、エンティティおよびHTMLが出現する場合でも、次のようなエスケープ・シーケンスがサポートされており、他の方法では不便または表現が困難な文字を表します:

@@は、@を表すために、blockまたはinlineタグの導入の一部として解釈されないようにするために、
@/は、*/を表す*@/の一部として/を表すために、囲みコメントが途中で終了するのを避けるために、
@*、*を表します。それ以外の場合は、行の先頭で「破棄」になります。

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

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

参照

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

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

module/package.class#member

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

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

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

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

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

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

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

module/package.class##fragment

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

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

メソッド・ドキュメント

メソッド宣言のドキュメント・コメントには、少なくとも次の内容を指定する必要があります。

「メインの説明」
メソッド・タイプ・パラメータごとのparamタグ(存在する場合)
戻り型がvoidでない場合、結果のreturnタグ
仮パラメータごとのparamタグ(存在する場合)
throws句(ある場合)で、例外タイプごとのthrowsタグ(選択または選択解除)。

そのリストに記載されている項目がメソッド宣言のドキュメント・コメントになく、次のいずれかがtrueの場合、エラーになります。

宣言がオーバーライドされていないか、または
宣言がオーバーライドされ、そのコンテンツにinheritDocタグが指定された場合、エラーになります。

それ以外の場合、欠落している項目は、その内容として{@inheritDoc}とともに提供されたものとみなされます。

この仕様では、オーバーライド・メソッド宣言は、@Override (JLS 9.6.4.4)で注釈を付けることができるが、レコード・コンポーネントのアクセッサ・メソッド宣言ではないメソッド宣言です。

メソッド・ドキュメントでは省略による継承が可能です: メソッド宣言のドキュメント・コメントが一部の項目のみを提供する場合、残りの項目は継承されているとみなされます。たとえば、次のように指定します。

/**
 * @param scale a non-zero number
 * @throws IllegalArgumentException if scale is 0
 */
 @Override
 <T> T magnify(int scale, T element) throws MagnificationException

次のことを前提としています。

/**
 * {@inheritDoc}
 *
 * @param <T> {@inheritDoc}
 * @param scale a non-zero number
 * @param element {@inheritDoc}
 * @return {@inheritDoc}
 * @throws IllegalArgumentException if scale is 0
 * @throws MagnificationException {@inheritDoc}
 */
 @Override
 <T> T magnify(int scale, T element) throws MagnificationException

ただし、すべての欠落アイテムを継承できるわけではありません。たとえば、メソッドが、このメソッドがオーバーライドするメソッドによってドキュメント化されていない例外Xを宣言する場合、その例外のドキュメント・アイテムは継承できず、このメソッドのドキュメント・コメントによってのみ指定できます。 (@throws X {@inheritDoc}の追加または想定はエラーになります。) その項目が指定されていない場合、その項目は欠落しているとみなされます。

(@Overrideは、宣言がオーバーライドされていることを強調するために、これらの例にのみ追加されます。その注釈はドキュメントには影響しません。)

ノート: inheritDocタグのみで構成されるドキュメント・コメントでは、メソッドの主な説明のみが明示的に示されます:

/**
 * {@inheritDoc}
 */

その他の項目がある場合は、省略によって継承されます。

ノート: 欠落しているアイテムとないアイテムを決定するのは、オーバーライドされたメソッドではなく、オーバーライドされたメソッドです。

たとえば、オーバーライドするメソッドがスローされた例外Xを宣言し、そのメソッドのドキュメント・コメントに@throws X ...が含まれていない場合、そのドキュメント・アイテムは欠落しています。オーバーライドされたメソッドがスローされた例外を宣言しない場合、オーバーライドされたメソッドがスローされた場合でも、そのドキュメント・アイテムは欠落しません。

この動作は、通常、チェックされていない例外を処理するときに認識されます。非チェック例外は通常、throws句には現れないため、明示的にドキュメント化されていないかぎり、例外は欠落しません。これにより、標準ドックレットがチェック済例外を未チェック例外とは異なる方法で処理するという誤解が生じます。

実際、同様の動作がチェック例外とともにレプリケートされる場合があります。 XがYのスーパータイプになるように、2つのチェック例外XおよびYを宣言するメソッドを考えてみます。オーバーライドするメソッドがXを宣言し、Yを宣言しない場合、@throws Y ...は欠落しません。

クラスおよびインタフェースでのメソッドのオーバーライド

メソッド宣言がスーパークラスまたは拡張スーパー・インタフェース内のメソッドをオーバーライドすると、標準ドックレットは、オーバーライドするメソッドのドキュメントにサブヘッダー"オーバーライド"を生成します。

クラス内のメソッド宣言がインタフェース内のメソッドをオーバーライドすると、標準ドックレットは、オーバーライドするメソッドのドキュメント内のサブヘッダー"指定者"を生成します。

どちらの場合も、オーバーライドされたメソッドへのリンクが含まれます。

標準タグ

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

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

`author`

@author name-text

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

メンバー・クラスまたはインタフェースの説明に@authorタグがない場合、標準ドックレットは、包含クラスまたはインタフェース内のそのようなタグを(再帰的に)検索します。

JDK 1.0で導入

`code`

{@code text }

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

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

JDK 1.5で導入

`deprecated`

@deprecated deprecated-text

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

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

ノート:

履歴上の理由から、「従来のドキュメントのコメント」で使用する場合、@deprecatedタグの使用は、@Deprecated注釈を使用しない場合でも、関連付けられた宣言を非推奨としてマークするのに十分です。
「マークダウン・ドキュメントのコメント」では、@Deprecated注釈を使用して、宣言を非推奨としてマークする必要があります。@deprecatedタグは、説明的な詳細を提供する単なる付加です。
注釈も存在しない場合、タグは無視されます。

JDK 1.0で導入

`docRoot`

{@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`

@exception exception-name description

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

JDK 1.0で導入

`hidden`

@hidden

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

JDK 9で導入

`index`

{@index word description }
{@index "phrase" description }

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

JDK 9で導入

`inheritDoc`

{@inheritDoc}
{@inheritDoc supertype }

このタグを含むメソッド・ドキュメント・コメント・パートが、スーパークラスまたはスーパー・インタフェースでオーバーライドされたメソッドと同じであることを示します。これは、自動的に決定されるか、指定されます。

オーバーライドされたメソッドが対応するパートの欠落である場合、エラーになります。

このタグを使用すると、より一般的なコメントを継承階層の上位に書き、継承された部分を記述できます。

このタグは、メソッドのオーバーライド宣言のドキュメント・コメント内の次の場所でのみ有効です。

「メインの説明」
param、returnおよびthrowsタグの説明。

オーバーライドされたメソッドのドキュメント・コメント自体の対応する部分でinheritDocタグが使用されている場合は、そのタグが最初に処理されます。 (これは、必要に応じて再帰的に適用される場合があります。)

mをクラスまたはインタフェースT内のメソッド宣言にします。 mのドキュメント・コメントにinheritDocタグが含まれている場合、スーパークラスまたはスーパー・インタフェース(このタグは、このタグの対応する部分を使用します。)は次のように決定されます:

タグの形式が{@inheritDoc S}の場合、スーパークラスまたはスーパー・インタフェースはSです。 mがTからSのメソッドをオーバーライドしない場合、エラーになります。
タグの形式が{@inheritDoc}の場合、スーパークラスまたはスーパー・インタフェースは、自動スーパータイプ検索を使用して決定されます。 自動検索で判断できない場合、エラーになります。

自動スーパータイプ検索

スーパータイプの検索は、2つのフェーズで実行されます: 再帰フェーズ、最終フェーズ。簡単にするために、検索はSから始まります。ここで、S = Tは、T (そうしないと、検索は不要になります。)には何もありません。 S (S = T)から開始する場合、メソッドが(JLS 8.4.8.1)をオーバーライドしないため、最初の条件は常に"otherwise"に分割されます。

再帰フェーズ

SがT.mがオーバーライドするメソッドを宣言する場合、Sはスーパータイプで、それ以外の場合は次のようになります。

Sが、java.lang.Objectではない直接スーパークラス(JLS 8.1.4)を持つクラスである場合、検索の再帰フェーズはそのスーパークラスに適用されます。そのアプリケーションでスーパータイプが見つからない場合:

Sにダイレクト・スーパー・インタフェース(JLS 8.1.5)がある場合、検索の再帰フェーズは、extends (Sがクラスである場合)句またはimplements (Sがインタフェースの場合)句にリストされている順序で、スーパータイプが見つかったか、スーパー・インタフェースが使い果たされるまで、これらの各スーパー・インタフェースに適用されます。

最終フェーズ

検索の再帰フェーズでスーパータイプが見つからない場合は、java.lang.Objectがスーパータイプかどうかを確認する最後の試行が行われます。 Tがクラスで、mがjava.lang.Objectのメソッドをオーバーライドする場合、またはTがインタフェースで、mのシグネチャがjava.lang.Object (JLS 8.4.2)のpublicメソッドのシグネチャとオーバーライドされる場合は、java.lang.Objectがスーパータイプになります。それ以外の場合、検索でスーパータイプが見つかりません。

ノート: 検索は、java.lang.Objectをスーパータイプとして早期に考慮しないように、2つのフェーズで実行されます。より具体的なドキュメントが使用可能な場合、java.lang.Objectでは、パブリック・メソッド(equals, hashCode, toStringなど)に関する一般的なドキュメントが過剰に提供されることがあります。

たとえば、次の回路図階層を考えてみます。

interface A
interface B extends A
interface C
class D implements B, C
interface E
class F extends D implements E

    (A)
     ^
      \
      (B) (C)    [java.lang.Object]
       ^   ^
        \ /
        [D] (E)
         ^   ^
          \ /
          [F]

「同じ階層が視覚的に表されます。」

自動スーパータイプ検索は、その階層を次の順序で移動します: F, D, B, A, C, E, java.lang.Object.

    (4)
     ^
      \
      (3) (5)    [7]
       ^   ^
        \ /
        [2] (6)
         ^   ^
          \ /
          [1]

「同じトラバーサル順序が視覚的に表されます。」

ノート: 継承されたメソッドのソース・ファイルは、ドキュメント・コメントをコピーできるように、ソース・パスにある必要があります。コマンド行で、クラスもパッケージも渡す必要はありません。

ノート: マークダウン・コメントを使用する場合、タグを含むコメントとそのタグによって継承されるドキュメントを含むコメントは、マークダウン・ドキュメント・コメントまたは従来の(マークダウンなし)コメントの両方である必要があります。

JDK 1.4で導入され、JDK 22以降のオプションの引数を受け入れます。

`link`

{@link reference label }

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

このタグは、seeタグの「第三者」に似ています。主な違いは、linkタグがリンクを"関連項目"セクションに配置するのではなく、インライン・リンクを生成することです。 linkタグは、インライン・テキストの残りの部分から分離するために、中カッコで始まり、終わります。ラベルの中で右中カッコ(})を使う必要がある場合は、HTMLエンティティ表記「}」を使います。

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`

{@linkplain reference label }

リンク・ラベルがコード・フォントではなくプレーン・テキストで表示されることを除き、linkタグと同じように動作します。ラベルがプレーン・テキストで記述されていると便利です。たとえば、

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

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

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

JDK 1.4で導入

`literal`

{@literal text }

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

JDK 1.5で導入

`param`

@param parameter-name description
@param <type-parameter-name> description

"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) { ... }

メソッドの仮パラメータまたは型パラメータの説明でinheritDocタグを使用する場合、オーバーライドされたメソッド・ドキュメントの対応する部分は、パラメータの名前(JLS 8.4.2とJLS 8.4.4)ではなく、パラメータの位置を使用して照合されます。

たとえば、次のメソッド宣言を考えてみます。

/**
 ...
 * @param scale a non-zero number
 ...
 * @param <T> the type of the element being magnified
 ...
 */
 <T> T magnify(int scale, T element) throws MagnificationException

次に、ドキュメントの継承に関するかぎり、次の2つのコメントは同等です。

/**
 ...
 * @param s {@inheritDoc}
 * @param e {@inheritDoc}
 ...
 * @param <E> {@inheritDoc}
 */
 @Override
 <E> E magnify(int s, E e) throws MagnificationException

/**
 ...
 * @param scale {@inheritDoc}
 * @param element {@inheritDoc}
 ...
 * @param <T> {@inheritDoc}
 */
 @Override
 <T> T magnify(int scale, T element) throws MagnificationException

パラメータ名が異なる場合、そのパラメータ名はオーバーライドされたメソッドとオーバーライドされたメソッドの両方で他の場所から参照される可能性があるため、このようなパラメータ・ドキュメントを継承する際には注意が必要です。

JDK 1.0で導入

`provides`

@provides service-type description

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

JDK 9で導入

`return`

@return description
{@return description }

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

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

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

ドキュメントを継承する場合は、次のいずれかの形式のreturnタグを使用できます:

/**
 * {@return {@inheritDoc}}
 ...
 */
<T> T magnify(int scale, T element) throws MagnificationException

/**
 ...
 * @return {@inheritDoc}
 */
 <T> T magnify(int scale, T element) throws MagnificationException

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

`see`

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

@see "string"

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

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

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

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

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

参照クラスに属さない名前のドキュメントを参照するには、他の2つのseeタグ・フォームのいずれかを使用します。

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

ラベルの内容が、ターゲット・リンクへの参照の単なる省略形ではなく、フレーズであるように見える場合、リンクはプレーン・フォントで表示されます。そうでない場合、リンクはモノ・スペース・フォントで表示されます。

JDK 1.0で導入

`serial`

@serial field-description
@serial include
@serial exclude

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

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

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

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

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

Serializableを実装しているpublicまたはprotectedクラスは、通常はそのページに含められます。ただし、そのクラスまたはそのクラスが属するパッケージが@serial excludeタグで指定されていると、そのページから除外されます。
Serializableを実装しているprivateまたはpackage-privateクラスは、通常はそのページから除外されます。ただし、そのクラスまたはそのクラスが属するパッケージが@serial includeタグで指定されていると、そのページに含められます。

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

クラス・レベルのserialタグは、パッケージ・レベルのserialタグよりも優先されます。

JDK 1.2で導入

`serialData`

@serialData data-description

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

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

JDK 1.2で導入

`serialField`

@serialField field-name field-type field-description

Serializable classのserialPersistentFieldsメンバーのObjectStreamFieldコンポーネントを記録します。 ObjectStreamFieldコンポーネントごとに1つのserialFieldタグを使用します。

JDK 1.2で導入

`since`

@since since-text

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

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

メンバー・クラスまたはインタフェースの説明に@sinceタグがない場合、標準ドックレットは、包含クラスまたはインタフェース内のそのようなタグを(再帰的に)検索します。

JDK 1.1で導入

`snippet`

{@snippet attributes }
{@snippet attributes :
body }

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

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

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

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

インライン・スニペット

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

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

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

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

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

*/は囲んでいるドキュメントのコメントを終了するため、文字シーケンス*/はコンテンツ内の任意の場所で使用できません。これには、/* ... */コメントの使用、//コメント内、または正規表現を表すために使用されるリテラルなどの文字列リテラル内の使用が含まれます。この制限は、ドキュメント・コメントのすべてのコンテンツに適用されます。snippetタグに固有ではありません。
インライン・スニペットのコンテンツには、中カッコ文字のバランスされたペアのみを含めることができます。全体のインライン・タグは、開始中カッコに一致する最初の右カッコで終了します。この制限は、すべてのインライン・タグに適用されます。snippetタグに固有ではありません。

外部スニペット

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

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

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

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

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

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

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

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

マークアップ・タグ

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

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

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

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

リージョン

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

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

@start region= name、または
regionまたはregion= nameを指定する@highlight、@replaceまたは@linkタグ。名前は、一致する@endタグで必要ない場合は省略できます。

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

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

強調表示

@highlight - 行またはリージョン内のテキストの強調表示
- substring - 強調表示されるリテラル・テキスト
- regex - 強調表示されるテキストの正規表現
- region - 強調表示するテキストを検索する範囲を定義するリージョン
- type - 強調表示のタイプ(bold、italic、highlightedなど)

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

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

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

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

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

@replace - 行またはリージョン内のテキストの置換
- substring - 置換するリテラル・テキスト
- regex - 置換するテキストの正規表現
- region - 置換するテキストを検索する範囲を定義するリージョン
- replacement - 置換テキスト

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

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

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

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

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

テキストのリンク

@link - 行またはリージョン内のリンク・テキスト
- substring - リンクするリテラル・テキスト
- regex - リンクするテキストの正規表現
- region - リンクするテキストを検索する範囲を定義するリージョン
- target - リンクのターゲット。linkタグに適した形式のいずれかで表されます
- type - リンクのタイプ: link (デフォルト)またはlinkplainのいずれか

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

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

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

JDK 18で導入

`spec`

@spec URL title

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

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

JDK 20で導入

`summary`

{@summary text }

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

JDK 10で導入

`systemProperty`

{@systemProperty property-name }

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

JDK 12で導入

`throws`

@throws exception-name description

メソッドまたはコンストラクタの詳細の"Throws"セクションに、指定された名前の後に指定された説明が続く例外を追加します。

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

ドキュメント・コメントでは、同じ例外または異なる例外に対して複数のthrowsタグを使用できます。そのようなコメントがinheritDocタグでターゲット指定されている場合は、その種類のすべての例外が"Throws"セクションにコピーされます。

ノート: 未チェックの例外クラスは、throws句から除外される可能性があるため、メソッドのドキュメントでは欠落しているとはみなされません。このような例外の説明を継承するには、対応するthrowsタグとその説明にinheritDocタグを追加します。

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

exceptionタグは、このタグと同等ですが、throwsタグを使用することをお薦めします。

JDK 1.2で導入

`uses`

@uses service-type description

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

JDK 9で導入

`value`

{@value format field-reference }

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

書式文字列は省略できます。その場合は、フィールドのタイプに応じてデフォルトの書式が使用されます。書式文字列を指定する場合は、パーセント文字(%)で始めるか、二重引用符文字(")で囲む必要があります。パーセント文字を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

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

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

メンバー・クラスまたはインタフェースの説明に@versionタグがない場合、標準ドックレットは、包含クラスまたはインタフェース内のそのようなタグを(再帰的に)検索します。

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`	✓	✓	✓				✓

ノート:

「メソッド」には、注釈インタフェースのメンバーが含まれます。
「フィールド」には、列挙型クラスのメンバーが含まれます。
「その他」には、宣言に関連付けられていない「概要」ページと、モジュールまたはパッケージ・ディレクトリのdoc-filesサブディレクトリのHTMLおよびマークダウン・ファイルが含まれます。「概要」ページは、通常、javadocコマンドのオプションとともに指定されます。
serialDataタグは、readObject, writeObject, readExternal, writeExternal, readResolveおよびwriteReplaceメソッドのドキュメント・コメントでのみ使用できます。
serialFieldタグは、serialPersistentFieldsフィールドのドキュメント・コメントでのみ使用できます。