このドキュメントでは、API用のHTMLドキュメントを生成するために使用される、JDK 22のjavadoc
ツールの標準ドックレットで認識されるドキュメント・コメントの形式を指定します。
javadoc
ツールのコンテキストでは、ドキュメント・コメントの内容の解釈は、コメントを処理するために使用されるドックレットまでです。 他のドックレットは、標準ドックレットと同じ構文を受け入れることも、代替の構文をサポートすることもできます。 しかし、多くのツールでサポートされているため、標準ドックレットでサポートされている構文は「デ・ファクト」標準になっています。
一般的な構文
ドキュメント・コメントは、ソース・コードに、ドキュメント化に使用する宣言の近くに表示されるスタイル化されたコメントです。
ドキュメント・コメントは、モジュール、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、列挙メンバーまたはフィールドの宣言の直前に配置された場合にのみ認識されます。
メソッドの本体に置かれているドキュメンテーション・コメントは無視されます。 宣言文ごとに1つの文書コメントしか認識されません。
ドキュメント・コメントの全体的な形式は、最初の「メインの説明」の後に、コメントが適用される宣言に関する追加情報を提供する一連の「ブロック・タグ」が続きます。 説明テキストには、次に説明するように、「インライン・タグ」および「HTMLコンテンツ」を含めることができます。 各行の先頭にある「先行アスタリスク」および先行する空白は無視されます。
ブロック・タグのみが含まれ、メインの説明がないコメントを使用できます。
履歴な理由から、パッケージのドキュメント・コメントは、パッケージのソース・ディレクトリにあるpackage.htmlというファイルで提供される場合があります。 この場合、ドキュメンテーション・コメントは<body>
タグの内容であり、Javaタイプ(たとえば、@see
タグ)への参照は完全修飾でなければなりません。 標準ドックレットでは、overview.htmlなどのファイルで追加のドキュメントを提供することもできます。 このようなコンテンツのルールは、package.htmlのルールと同じです。
メイン摘要
ドキュメント・コメントの主な説明は、コメントの先頭から最初のブロック・タグまで、存在する場合は最初のブロック・タグまで、存在しない場合はコメントの末尾までです。 先頭と末尾の空白は無視されます。 そのような内容がない場合、主な説明は欠落していると言われています。
メインの説明はブロック・タグ続けることはできません。
欠落している主な説明の例。
最初のブロック・タグの前にコンテンツがありません:
/** * @param ... * ... */
空のドキュメント・コメント:
/** * */
メインの説明の最初の文は、宣言されたエンティティの簡潔で完全な説明を含むサマリー文である必要があります。
ブロック・タグ
ブロック・タグの形式は@
identifier contentで、生成されたドキュメントに組み込まれる追加の詳細を提供します。 各ブロック・タグは、先頭のアスタリスク、空白文字および最初のコメント・デリミタ(/**
)を無視して、行の先頭に表示する必要があります。 これは、テキスト内のそれ以外の位置で@
文字を使用しても、タグの開始としては解釈されないことを意味しています。 行の最初に@
文字を使用してもタグとして解釈されないようにするには、HTMLエンティティの@
を使用してください。 ブロック・タグの内容は、次のブロック・タグまたはドキュメント・コメントの最後までのタグの後にあるテキストです。 コンテンツは複数の行にまたがることができます。
ブロック・タグの数に制限はありません。一部のタグは繰り返すことができ、他のタグは繰り返せません。
インライン・タグ
インライン・タグの形式は{@
identifier content }
で、説明のコンテキスト内で詳細を提供します。 通常、説明テキストおよびHTMLが許可されている場合は常に表示されますが、一部のインライン・タグはメインの説明の先頭でのみ使用できます。
一部のインライン・タグには自由形式のテキストが含まれている場合があります。 このようなテキストに中カッコが明示的に含まれている場合、インライン・タグの閉じカッコを判別できるように、中カッコは"貸借一致"である必要があります。これは、適切にネストされた左中カッコと右中カッコの数が等しいことを意味します。 テキストのその他の字句分析は実行されません。特に、'
, "
, \
や@
などの文字は考慮されません。
インライン・タグで囲まれた@
で始まる行は、ブロック・タグの開始とみなされません。
テキスト・コンテンツがHTMLの場合、エンティティ{
および}
を使用してカッコのバランスがとれていないことがあります。
HTMLコンテンツ
HTMLコンテンツは形式的にチェックされていませんが、一部のツールでは一般的なエラーを検出するのに役立ついくつかのチェックが行われます。
適切な標準に準拠したドキュメントを生成できるようにするには、ドキュメント・コメントでHTML構成を使用する際に、次の考慮事項を考慮する必要があります:
HTMLコンストラクトは、HTML 5で記述する必要があります。
生成されたドキュメントのページ内の適切な構造化ヘッダーをサポートするには、モジュール、パッケージおよびタイプのドキュメント・コメントのヘッダー、(ネストした型を含む)は
<h2>
で始まり、必要に応じてそれを増やします。同様に、コンストラクタ、メソッド、フィールドおよびその他のメンバーのドキュメント・コメントのヘッダーも<h4>
で始まる必要があります。doc-files
サブディレクトリなどのスタンドアロンHTMLファイルでは、ヘッダーは<h1>
から開始する必要があります。プログラム要素の宣言で生成されたドキュメント内の位置を識別するために使用される一意の識別子との競合を回避するため、ユーザー定義の
id
属性の値には、Java識別子の有効な文字ではない文字(-
など)が含まれる必要があります。
行の先頭のアスタリスク
ドキュメント・コメントを読むと、各行のアスタリスク(*
)が破棄され、最初のアスタリスク(*
)の前にある空白とタブも破棄されます。 行で先頭のアスタリスクを省略すると、先頭の空白は削除されなくなり、インデントを保持して<pre>
タグ内のドキュメント・コメントにコード例を直接貼り付けることができます。 ブラウザは、空白文字をタブよりも一律に解釈します。 インデントは、左余白(区切り記号/**
または<pre>
タグではなく)に相対的です。
エスケープ・シーケンス
次のエスケープ・シーケンスは、テキスト、エンティティおよびHTMLが表示されるあらゆる場所でサポートされ、不便または表現が困難な文字を表します:
@@
は、@
を表すために、blockまたは「インライン」タグの導入の一部として解釈されないようにするために、@/
は、*/
を表す*@/
の一部として/
を表すために、囲みコメントが途中で終了するのを避けるために、@*
、*
を表します。それ以外の場合は、行の先頭で「破棄されました」になります。
エスケープ・シーケンスはコンテキストに依存し、エスケープされた文字を単独で使用すると、構文の解釈が異なる場合にのみ使用できます。 その他の状況では、これらの文字シーケンスは文字どおりに解釈され、追加の解釈は行われません。
エスケープ・シーケンスは、リテラル・テキストを含むインライン・タグでは使用できません。これには、{@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
オプションを使用すると、指定された名前テキストを持つ"著者"エントリを生成されたドキュメントに追加します。 1つのドキュメンテーション・コメントに複数の@author
タグを含めることができます。 1つの@authorタグに1つの名前を指定することも、複数の名前を指定することもできます。 前者の場合、標準ドックレットはカンマ(,
)と名前の間にスペースを挿入します。 後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにコピーされます。 したがって、カンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1つのタグに複数の名前を指定してください。
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}
タグを含める必要があります。
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}
このタグを含むメソッド・ドキュメント・コメント・パートが、スーパークラスまたはスーパー・インタフェースでオーバーライドされたメソッドと同じであることを示します。これは、自動的に決定されるか、指定されます。
オーバーライドされたメソッドが対応するパートの欠落である場合、エラーになります。
このタグを使用すると、より一般的なコメントを継承階層の上位に書き、継承された部分を記述できます。
このタグは、メソッドのオーバーライド宣言のドキュメント・コメント内の次の場所でのみ有効です。
オーバーライドされたメソッドのドキュメント・コメント自体の対応する部分で{@inheritDoc}
または{@inheritDoc
supertype }
が使用されている場合、そのタグが最初に処理されます。 (これは、必要に応じて再帰的に適用される場合があります。)
m
をクラスまたはインタフェースT
内のメソッド宣言にします。 m
のドキュメント・コメントに{@inheritDoc}
または{@inheritDoc
supertype }
が含まれている場合、スーパークラスまたはスーパー・インタフェース(このタグは、このタグの対応する部分を使用します。)は次のように決定されます。
- タグの形式が
{@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
自動スーパータイプ検索は、その階層を次の順序で移動します: 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
"関連項目"見出しに、参照を指すリンクまたはテキスト・エントリを追加します。 1つのドキュメンテーション・コメントには、任意の数の@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
タグが付けられています。 パブリック・クラス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
コンポーネントに対して@serialField
タグを1つ使用してください。
JDK 1.2で導入
@since
@since
since-text
生成されたドキュメントに、指定したsince-text値を持つ"以来"見出しを追加します。 このテキストには、特別な内部構造はありません。 このタグは任意のドキュメント・コメントで有効です: 概要、モジュール、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールド。 このタグは、たとえば、since-text値で指定されたソフトウェア・リリース以降にこの変更または機能が存在することを意味: @since 1.5
。
Javaプラットフォームのソース・コードの場合、@since
タグは、JavaプラットフォームAPI仕様のバージョンを示します。そのソース・コードがリファレンス実装に追加された時期を示すとはかぎりません。 複数の@since
タグが許可され、複数の@author
タグのように扱われます。 プログラム要素が複数のAPIで使用される場合、複数のタグを使用できます。
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
の後に、考慮するテキストの範囲、置換対象のスコープ内のテキストおよび置換テキストを指定する引数を使用します。
region
またはregion=
nameが指定されている場合、スコープはそのリージョンであり、対応する@end
タグまでです。 それ以外の場合、スコープは現在の行のみです。
スコープ内のリテラル文字列の各インスタンスを置き換えるには、文字列をsubstring=
string (stringは、単一または二重引用符で囲まれた識別子またはテキスト)で指定します。 スコープ内の正規表現に一致するテキストの各インスタンスを置き換えるには、regex=
stringを使用します。 これらの属性のどちらも指定されていない場合、スコープ全体が置換されます。
置換テキストをreplacement
パラメータで指定します。 正規表現を使用して置換するテキストを指定する場合、$
numberまたは$
nameを使用して、String::replaceAllで定義されている正規表現にあるグループを置換できます。
テキストを削除するには、空の置換文字列とともに@replace
を使用します。 テキストを挿入するには、@replace
を使用して、置換テキストを挿入する任意のテキストを置換します。 no-opテキストは、'//'マーカーまたは空の文(;
)です。
テキストのリンク
@link
- 行またはリージョン内のリンク・テキストsubstring
- リンクするリテラル・テキストregex
- リンクするテキストの正規表現region
- リンクするテキストを検索する範囲を定義するリージョンtarget
- リンクのターゲット。{@link ...}
タグに適した形式の1つで表されますtype
- リンクのタイプ:link
(デフォルト)またはlinkplain
のいずれか
テキストをAPIの他の部分の宣言にリンクするには、@link
に続けて、考慮されるテキストの範囲、リンクするスコープ内のテキストおよびリンクのターゲットを指定する引数を使用します。
region
またはregion=
nameが指定されている場合、スコープはそのリージョンであり、対応する@end
タグまでです。 それ以外の場合、スコープは現在の行のみです。
スコープ内のリテラル文字列の各インスタンスをリンクするには、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の値には、特別な内部構造はありません。
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 |
✓ | ✓ | ✓ | ✓ |
ノート:
- 「メソッド」には、注釈インタフェースのメンバーが含まれます。
- 「フィールド」には、列挙型クラスのメンバーが含まれます。
- 「その他」には、宣言に関連付けられていない概要ページと、パッケージ・ディレクトリの
doc-files
サブディレクトリにあるHTMLファイルが含まれています。 「概要」ページは、通常、javadoc
コマンドのオプションとともに指定されます。 @serialData
は、readObject
、writeObject
、readExternal
、writeExternal
、readResolve
およびwriteReplace
メソッドのドキュメント・コメントでのみ使用できます。@serialField
は、serialPersistentFields
フィールドのドキュメント・コメントでのみ使用できます。