javadoc(1) 基本ツール javadoc(1)
# 名前
javadoc - Javaソース・ファイルから、APIドキュメントのHTMLページを生成します。
# 概要
```
javadoc {packages|source-files} [options] [@argfiles]
```
*packages*
**java.lang java.lang.reflect java.awt**など、空白で区切ってドキュメント化するパッケージの名前。サブパッケージもドキュメント化する場合は、**-subpackages**オプションを使用してパッケージを指定します。
デフォルトでは、**javadoc**は、現在のディレクトリおよびサブディレクトリで指定されたパッケージを探します。**-sourcepath**オプションを使用して、パッケージを探すディレクトリのリストを指定します。
*source-files*
**Class.java Object.java Button.java**のように空白で区切った、ドキュメント化するJavaソース・ファイルの名前。デフォルトでは、**javadoc**は、現在のディレクトリで指定されたクラスを探します。ただし、**/home/src/java/awt/Graphics\*.java**のように、クラス・ファイルのフルパスを指定し、ワイルドカード文字を使用できます。現在のディレクトリからの相対パスも指定できます。
*options*
空白で区切られたコマンド行オプション。オプションを参照してください。
*@argfiles*
**javadoc**コマンド・オプション、パッケージ名およびソース・ファイル名のリストを任意の順序で含むファイルの名前。
# 説明
**javadoc**コマンドは、一連のJavaソース・ファイルにある宣言およびドキュメンテーション・コメントを解析し、デフォルトでは、publicクラス、protectedクラス、ネストされたクラス(匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて記述した一連のHTMLページを生成します。**javadoc**コマンドは、APIドキュメントの生成や、一連のソース・ファイルの実装ドキュメントの生成に使用できます。
**javadoc**コマンドは、パッケージ全体、個々のソース・ファイル、またはその両方に対して実行できます。パッケージ全体のドキュメント化を行うには、**-subpackages**オプションを使用してディレクトリおよびそのサブディレクトリを再帰的にたどるか、パッケージ名の明示的なリストを渡します。個々のソース・ファイルをドキュメント化するには、Javaソース・ファイル名のリストを渡します。簡単な例を参照してください。
## ソース・ファイルの処理
**javadoc**コマンドは、ソースで終わるファイル、およびソース・ファイルで説明しているその他のファイルを処理します。個々のソース・ファイル名を渡して**javadoc**を実行する場合、どのソース・ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソース・ファイル名を明示的に指定しなくても、**javadoc**コマンドは3つの方法で実行できます。パッケージ名を渡し、**-subpackages**オプションを使用するか、またはソース・ファイル名にワイルドカードを使用することができます。これらの場合、**javadoc**コマンドがソース・ファイルの処理を行うのは、そのファイルが次のすべての要件を満たす場合のみです。
•ファイル名の接頭辞(**.java**を削除)が有効なクラス名である。
•ソース・ツリーのルートからの相対的なパス名が、区切り文字をドットに変換すると、有効なパッケージ名になる。
•パッケージ文に有効なパッケージ名が含まれている。
リンクの処理
処理の実行中に、**javadoc**コマンドは、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、相互参照リンクを追加します。リンクは、次の場所に表示されます。@タグの説明については、javadocタグを参照してください。
•宣言(戻り値の型、引数の型、フィールドの型)。
•**@see**タグから生成された*「関連項目」*セクション。
•**{@link}**タグから生成されたインライン・テキスト。
•**@throws**タグから生成された例外の名前。
•インタフェースのメンバーに対する*「定義」*リンクと、クラスのメンバーに対する*「オーバーライド」*リンク。メソッド・コメントの継承を参照してください。
•パッケージ、クラス、およびメンバーをリストしているサマリー表。
•パッケージおよびクラスの継承ツリー。
•索引。
コマンド行で指定しなかったクラスについての既存のテキスト(別に生成したテキスト)に対してリンクを追加するには、**-link**および**-linkoffline**オプションを利用できます。
処理の詳細
**javadoc**コマンドは実行するたびに1つの完全なドキュメントを生成します。前の実行の結果を変更または直接取り込む、増分ビルドを行いません。ただし、**javadoc**コマンドは、他の実行の結果にリンクできます。
**javadoc**コマンドの実装にはJavaコンパイラが必要で、Javaコンパイラに依存しています。**javadoc**コマンドは**javac**コマンドの一部を呼び出し、宣言をコンパイルして、メンバーの実装を無視します。**javadoc**コマンドは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、HTMLを生成します。さらに、J**javadoc**コマンドは、ソース・コードのドキュメンテーション・コメントから、ユーザーの提供したドキュメントも取得します。ドキュメンテーション・コメントを参照してください。
**javadoc**コマンドは、メソッド本体を持たない純粋なスタブ・ファイルであるソース・ファイルに対して実行できます。したがって、APIの実装前の設計の早い段階で、ドキュメンテーション・コメントを記述して**javadoc**コメントを実行できます。
コンパイラに依存することによって、HTML出力は、実際の実装に正確に対応します。実際の実装は、明示的なソース・コードにではなく、暗黙のソース・コードに依存する場合があります。たとえば、**javadoc**コマンドは、コンパイル済クラス・ファイルには存在するがソース・コードには存在しないデフォルト・コンストラクタをドキュメント化します。
多くの場合、**javadoc**コマンドでは、ソース・ファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。すべてのデバッグやトラブルシューティングを完了する前にドキュメントを生成できます。**javadoc**コマンドはドキュメンテーション・コメントの基本的なチェックを行います。
**javadoc**コマンドは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、 **javadoc**コマンドは、ブートストラップ・クラス、拡張機能、またはユーザー・クラスにかかわらず、すべての参照クラスを検索できる必要があります。クラスの検出方法 (http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html)を参照してください
通常、作成するクラスは、拡張クラスとして、または**javadoc**コマンドのクラス・パスでロードされる必要があります。
## [Javadocのドックレット](#Javadoc)
**javadoc**コマンドの出力の内容と形式は、ドックレットを使用してカスタマイズできます。**javadoc**コマンドには、標準ドックレットと呼ばれるデフォルトの組込みドックレットがあります。標準ドックレットは、HTML形式のAPIドキュメントを生成します。標準ドックレットを修正またはサブクラスを作成することや、HTML、XML、MIF、RTFなどの好みの出力形式を生成する独自のドックレットを記述することも可能です。
**-doclet**オプションでカスタム・ドックレットが指定されていない場合、**javadoc**コマンドは、デフォルトの標準ドックレットを使用します。**javadoc**コマンドには、使用されているドックレットに関係なく使用できるいくつかのオプションがあります。標準ドックレットでは、これらの他に、いくつかのコマンド行オプションが追加されます。オプションを参照してください。
# ソース・ファイル
**javadoc**コマンドは、次のタイプのソース・ファイルから出力を生成します。そのファイルは、クラスのJava言語ソース・ファイル(**.java**)、パッケージ・コメント・ファイル、概要コメント・ファイル、およびその他の未処理のファイルです。ここでは、ドキュメント化しないがソース・ツリーに存在する場合があるテスト・ファイルやテンプレート・ファイルについても説明します。
## クラスのソース・ファイル
それぞれのクラスまたはインタフェース、およびそのメンバーは、独自のドキュメンテーション・コメントを持つことができ、それをソース・ファイル内に保持します。ドキュメンテーション・コメントを参照してください。
## パッケージ・コメント・ファイル
それぞれのパッケージは、独自のドキュメンテーション・コメントを持つことができ、それを専用のソース・ファイルに保持します。その内容は、**javadoc**コマンドによって生成されるパッケージのサマリー・ページに組み込まれます。このコメントには、通常、そのパッケージ全体に当てはまるドキュメントを記述します。
パッケージ・コメント・ファイルを作成するには、次のいずれかのファイルにコメントを格納できます。
•**package-info.java**ファイルには、パッケージ宣言、パッケージ注釈、パッケージ・コメント、およびJavadocタグを格納できます。このファイルが優先されます。
•**package.html**ファイルには、パッケージ・コメントとJavadocタグのみを格納できます。パッケージ注釈は格納できません。
各パッケージは、**package.html**ファイルまたは**package-info.java**ファイルのいずれかを1つ持つことができますが、その両方を持つことはできません。このどちらかのファイルをソース・ファイルとともに、ソース・ツリー内のそのパッケージ・ディレクトリ内に配置してください。
package-info.javaファイル
**package-info.java**ファイルには、次の構造のパッケージ・コメントを含めることができます。コメントは、パッケージ宣言の前に配置されます。
**注意:** コメント区切り文字である**/\*\***および**\*/**が存在する必要がありますが、中間の行の先頭のアスタリスクは省略可能です。
```
/**
* Provides the classes necessary to create an
* applet and the classes an applet uses
* to communicate with its applet context.
*
* The applet framework involves two entities:
* the applet and the applet context.
* An applet is an embeddable window (see the
* {@link java.awt.Panel} class) with a few extra
* methods that the applet context can use to
* initialize, start, and stop the applet.
*
* @since 1.0
* @see java.awt
*/
package java.lang.applet;
```
package.htmlファイル
**package.html**ファイルには、次の構造のパッケージ・コメントを含めることができます。コメントは、**<body>**要素に配置されます。
ファイル: **java/applet/package.html**
```
Provides the classes necessary to create an applet and the
classes an applet uses to communicate with its applet context.
The applet framework involves two entities: the applet
and the applet context. An applet is an embeddable
window (see the {@link java.awt.Panel} class) with a
few extra methods that the applet context can use to
initialize, start, and stop the applet.
@since 1.0
@see java.awt
```
**package.html**ファイルは通常のHTMLファイルであり、パッケージ宣言を含んでいません。パッケージ・コメント・ファイルの内容はHTMLで記述しますが、例外が1つあります。このドキュメンテーション・コメントには、コメント区切り文字である**/\*\***と**\*/**、または行頭のアスタリスクを含めない、という点です。コメントを書く場合は、最初の文をパッケージのサマリーとし、**<body>**タグと最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージ・タグを含めることができます。すべてのブロック・タグは、主説明の後に配置する必要があります。**@see**タグをパッケージ・コメント・ファイルに追加する場合には、完全修飾名を使用する必要があります。
コメント・ファイルの処理
**javadoc**コメントを実行すると、パッケージ・コメント・ファイルが検索されます。パッケージ・コメント・ファイルが見つかった場合は、**javadoc**コマンドは次の手順を実行します。
•処理できるようにコメントをコピーします。package.htmlの場合、**javadoc**コマンドは、**<body>**と**</body>** HTMLタグ間ですべてのコンテンツをコピーします。**<title>**タグ、ソース・ファイルの著作権文または他の情報を配置する**<head>**セクションを含めることができますが、これらは生成されたドキュメントに表示されません。
•パッケージ・タグを処理します。パッケージ・タグを参照してください。
•処理したテキストを生成されたパッケージのサマリー・ページの下部に挿入します。Javaプラットフォーム、Standard Edition API仕様の概要 (http://docs.oracle.com/javase/8/docs/api/overview-summary.html)を参照してください
•パッケージのサマリー・ページの先頭に、パッケージ・コメントの最初の文をコピーします。さらに、**javadoc**コマンドは、概要ページのパッケージ・リストに、パッケージ名とパッケージ・コメントの最初の文を追加します。Javaプラットフォーム、Standard Edition API仕様の概要 (http://docs.oracle.com/javase/8/docs/api/overview-summary.html)を参照してください
文の終わりは、クラスやメンバーの主説明の最初の文の終わりと同じルールによって判断されます。
## 概要コメント・ファイル
ドキュメント化する各アプリケーションまたはパッケージ・セットは、独自の概要ドキュメンテーション・コメントを持つことができ、それは専用のソース・ファイルに保持されます。その内容は、**javadoc**コマンドによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージ・セット全体に当てはまるドキュメントを記述します。
このファイルにはoverview.htmlなどの名前を付けることができ、どこに配置してもかまいません。一般的な場所は、ソース・ツリーの最上部です。
たとえば、**java.applet**パッケージのソース・ファイルが/home/user/src/java/appletディレクトリに格納されている場合、概要コメント・ファイルは/home/user/src/overview.htmlに作成できます。
異なるパッケージのセットに対して**javadoc**コマンドを複数回実行する場合は、同じ1つのソース・ファイルのセットに対して複数の概要コメント・ファイルを作成できます。たとえば、内部ドキュメント用に**-private**を指定して**javadoc**コマンドを1回実行した後、公開ドキュメント用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメント・ファイルの1文目で、そのドキュメントを公開用または内部用として記述できます。
概要コメント・ファイルの内容は、HTMLで記述された1つの大きなドキュメンテーション・コメントです。最初の文はアプリケーションまたはパッケージのセットのサマリーとします。**<body>**タグと最初の文の間にタイトルやその他のテキストを含めないようにします。{**@link}**などのインライン・タグを除くすべてのタグは、主説明の後に配置する必要があります。**@see**タグを追加する場合には、完全修飾名を使用する必要があります。
**javadoc**コマンドの実行時に、**-overview**オプションを使用して概要コメント・ファイル名を指定します。このファイルは、パッケージ・コメント・ファイルと同じように処理されます。**javadoc**コマンドは次の手順を実行します。
•**<body>**と**</body>**タグ間で、処理するすべてのコンテンツをコピーします。
•概要タグがあれば処理します。概要タグを参照してください。
•処理したテキストを生成された概要ページの下部に挿入します。JavaプラットフォームStandard Edition API仕様の概要 (http://docs.oracle.com/javase/8/docs/api/overview-summary.html)を参照してください
•概要サマリー・ページの先頭に、概要コメントの最初の文をコピーします。
## 未処理のファイル
ソース・ファイルには、**javadoc**コマンドによって宛先ディレクトリにコピーされる、任意のファイルを含めることができます。このようなファイルには、通常、グラフィック・ファイル、サンプルのJavaソースおよびクラス・ファイル、一般的なJavaソース・ファイルのドキュメンテーション・コメントの影響を受けない多くの内容を含む独立したHTMLファイルなどがあります。
未処理のファイルを含めるには、doc-filesというディレクトリにファイルを配置します。doc-filesディレクトリは、ソース・ファイルを含む任意のパッケージ・ディレクトリのサブディレクトリになることができます。doc-filesサブディレクトリは、パッケージごとに1つ用意できます。
たとえば、ボタンのイメージを**java.awt.Button**クラスのドキュメントに含める場合には、そのイメージ・ファイルを/home/user/src/java/awt/doc-files/ディレクトリに置きます。doc-filesディレクトリを/home/user/src/java/doc-filesに置かないでください。javaはパッケージではないからです。ソース・ファイルを含めることもできません。
**javadoc**コマンドはファイルを参照しないので、未処理のファイルへのすべてのリンクは、コードに含まれている必要があります。**javadoc**コマンドはディレクトリとそのすべての内容を宛先にコピーします。次の例では、Button.javaドキュメンテーション・コメントのリンクがどのように見えるかを示しています。
```
/**
* This button looks like this:
* 
*/
```
## テストおよびテンプレート・ファイル
ソース・ツリーのテストおよびテンプレート・ファイルを、ソース・ファイルが存在するディレクトリまたはサブディレクトリと同じディレクトリに格納できます。テストおよびテンプレート・ファイルが処理されるのを防ぐには、**javadoc**コマンドを実行し、明示的に個別のソース・ファイル名を渡します。
テスト・ファイルは、有効な、コンパイル可能なソース・ファイルです。テンプレート・ファイルは、有効な、互換性のあるソース・ファイルではありませんが、多くの場合、**.java**接尾辞を持っています。
テスト・ファイル
テスト・ファイルを、名前なしパッケージや、ソース・ファイルが存在するパッケージとは別のパッケージに属するようにする場合、テスト・ファイルをソース・ファイルの下のサブディレクトリに配置し、そのディレクトリに無効な名前を付けます。テスト・ファイルをソースと同じディレクトリに配置し、パッケージ名を示すコマンド行引数を指定して**javadoc**コマンドを呼び出すと、テスト・ファイルは警告またはエラーを引き起こします。ファイルが無効な名前を持つサブディレクトリ内に存在する場合、テスト・ファイル・ディレクトリはスキップされ、エラーまたは警告は発行されません。たとえば、ソース・ファイルのテスト・ファイルをcom.package1に追加するには、無効なパッケージ名のサブディレクトリに配置します。次のディレクトリ名にはハイフンが含まれているため無効です。
```
com/package1/test-files/
```
テスト・ファイルにドキュメンテーション・コメントが含まれる場合、**javadoc**コマンドの個別の実行で、ワイルドカードを含んだテスト・ソース・ファイル名(**com/package1/test-files/\*.java**など)を渡して、テスト・ファイルのドキュメントを生成するように設定できます。
テンプレート・ファイル
テンプレート・ファイルをソース・ディレクトリに配置するが、**javadoc**コマンドを実行するときにエラーを生成しない場合、ファイルに**Buffer-Template.java**などの無効な名前を付けて、処理させないようにします。**javadoc**コマンドは、接尾辞の**.java**が削除されると有効なクラス名になる名前を持つソース・ファイルのみを処理します。
# 生成されるファイル
デフォルトでは、**javadoc**コマンドは、HTML形式のドキュメントを生成する標準ドックレットを使用します。標準ドックレットは、ここで説明する、基本内容ページ、相互参照ページ、サポート・ページを生成します。各HTMLページは個別のファイルに対応します。**javadoc**コマンドは、2つのタイプのファイルを生成します。最初のタイプには、クラスおよびインタフェースに応じた名前が付けられます。2番目のタイプには、最初のタイプのファイルとの競合を防ぐために、ハイフンが含まれます(package-summary.htmlなど)。
## 基本内容ページ
•記載されているクラスまたはインタフェースごとに1つのクラスまたはインタフェース・ページ(classname.html)。
•記載されているパッケージごとに1つのパッケージ・ページ(package-summary.html)。**javadoc**コマンドは、ソース・ツリーのパッケージ・ディレクトリ内にあるpackage.htmlまたはpackage-info.javaという名前のファイル内のHTMLテキストをすべて組み入れます。
•パッケージのセット全体に対して1つの概要ページ(overview-summary.html)。概要ページは、生成ドキュメントの先頭ページになります。**javadoc**コマンドは、**-overview**オプションで指定されたファイル内のHTMLテキストをすべて組み入れます。概要ページが作成されるのは、**javadoc**コマンドに複数のパッケージ名を渡した場合のみです。HTMLフレームおよびオプションを参照してください。
## 相互参照ページ
•パッケージのセット全体に対して1つのクラス階層ページ(overview-tree.html)。階層ページを表示するには、ナビゲーション・バーの「概要」をクリックしてから、「階層ツリー」をクリックします。
•パッケージごとに1つのクラス階層ページ(package-tree.html)。階層ページを表示するには、特定のパッケージ、クラス、またはインタフェースのページに移動し、「階層ツリー」をクリックしてそのパッケージの階層を表示します。
•パッケージごとに1つの使用ページ(package-use.html)と、クラスおよびインタフェースごとに1つずつの使用ページ(class-use/classname.html)。使用ページでは、指定したクラス、インタフェース、またはパッケージの一部を使用しているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。たとえば、クラスまたはインタフェースAを例にすると、その使用ページには、Aのサブクラス、Aとして宣言されたフィールド、Aを返すメソッド、A型のパラメータを持つメソッドおよびコンストラクタが組み込まれます。使用ページを表示するには、パッケージ、クラス、またはインタフェースに移動し、ナビゲーション・バーの「使用」リンクをクリックします。
•すべての非推奨APIとその推奨する代替をリストする非推奨APIページ(deprecated-list.html)。非推奨APIは将来の実装で削除される可能性があるので使用しないでください。
•定数フィールドの値用の定数フィールド値ページ(constant-values.html)。
•直列化された形式ページ(serialized-form.html)。フィールドおよびメソッドの説明を含む、直列化可能かつ外部化可能なクラスに関する情報用のページです。このページ内の情報は、APIを使用する開発者ではなく、再実装者に必要な情報です。直列化された形式ページへアクセスするには、直列化されたクラスに移動して、そのクラス・コメントにある「関連項目」セクションで「直列化された形式」をクリックします。標準ドックレットは直列化された形式ページを生成します。このページには、Serializableを実装するすべてのクラス(publicまたは非public)が、その**readObject**や**writeObject**メソッド、直列化されたフィールド、および**@serial**、**@serialField**、**@serialData**タグからのドキュメンテーション・コメントとともにリストされます。直列化可能なpublicクラスを除外するには、そのクラス(またはそのパッケージ)を**@serial** excludeでマークします。直列化可能なpackage-privateクラスを含めるには、そのクラス(またはそのパッケージ)を**@serial** includeでマークします。リリース1.4では、**-private**オプションを指定せずに**javadoc**コマンドを実行することにより、publicクラスおよびprivateクラスの完全に直列化された形式を生成できます。オプションを参照してください。
•索引ページ(**index-\*.html**)。すべてのクラス名、インタフェース名、コンストラクタ名、フィールド名、およびメソッド名がアルファベット順に並んでいます。索引ページは、Unicodeを扱えるように国際化されています。1つのファイルとして生成することも、先頭文字(英語の場合A–Z)ごとに別々のファイルとして生成することもできます。
## サポート・ページ
•ヘルプ・ページ(help-doc.html)。ナビゲーション・バーや前述の各ページに関する説明が記載されています。デフォルトのヘルプ・ファイルを独自のカスタム・ヘルプ・ファイルでオーバーライドするには、**-helpfile**を使用します。
•表示用のHTMLフレームを作成する1つのindex.htmlファイル。フレーム付きの先頭ページを表示するにはこのファイルをロードします。index.htmlファイルには、テキスト・コンテンツは含まれていません。
•複数のフレーム・ファイル(**\*-frame.html**)。パッケージ、クラス、およびインタフェースのリストが含まれています。フレーム・ファイルはHTMLフレームを表示します。
•パッケージ・リスト・ファイル(package-list)。**-link**および**-linkoffline**オプションで使用されます。パッケージ・リスト・ファイルはテキスト・ファイルであり、どのリンクからもアクセスできません。
•スタイルシート・ファイル(stylesheet.css)。生成されるページの一部の要素について色、フォント・ファミリ、フォント・サイズ、フォント・スタイル、および配置を制御します。
•doc-filesディレクトリ。宛先ディレクトリにコピーするイメージ、サンプル・コード、ソース・コードなどのファイルが格納されます。これらのファイルは、**javadoc**コマンドによって処理されません。このディレクトリは、ソース・ツリーの中に存在する場合にのみ処理されます。
オプションを参照してください。
## [HTMLフレーム](#HTML)
**javadoc**コマンドは、コマンドに渡された値に基づき、最小限必要な数(2または3)のフレームを生成します。**javadoc**コマンドに引数として1つのパッケージ名または1つのパッケージに含まれるソース・ファイルを渡す場合は、パッケージのリストが省略されます。そのかわりに、**javadoc**コマンドは左側の列に1つのフレームを作成し、クラスのリストを表示します。複数のパッケージ名を渡した場合は、**javadoc**コマンドは、すべてのパッケージをリストする第3のフレームと概要ページ(overview-summary.html)を作成します。フレームを省略するには、「フレームなし」リンクをクリックするか、overview-summary.htmlページからページ・セットを表示します。
## 生成されるファイルの構造
生成されるクラス・ファイルおよびインタフェース・ファイルは、Javaソース・ファイルおよびクラス・ファイルと同じディレクトリ階層に編成されます。1つのサブパッケージにつき1つのディレクトリ、という構造になります。
たとえば、**java.applet.Applet**クラス用に生成されるドキュメントは、java/applet/Applet.htmlに格納されます。
生成先ディレクトリの名前が**apidocs**だとすると、**java.applet**パッケージのファイルの構造は、次のとおりです。前述のように、*frame*という語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外のHTMLファイルは、すべて右側のフレームに表示されます。
ディレクトリは太字です。アスタリスク(\*)は、**javadoc**コマンドへの引数がパッケージ名ではなくソース・ファイル名である場合に省略されるファイルおよびディレクトリを示しています。引数がソース・ファイル名の場合、空のパッケージ・リストが作成されます。doc-filesディレクトリは、ソース・ツリー内に存在する場合にのみ、生成先に作成されます。生成されるファイルを参照してください。
•**apidocs**: 最上位レベル・ディレクトリ
•index.html: HTMLフレームを設定する初期ページ
•\*overview-summary.html: パッケージ・リストとサマリー
•overview-tree.html: すべてのパッケージのクラス階層
•deprecated-list.html: すべてのパッケージの非推奨API
•constant-values.html: すべてのパッケージの静的フィールド値
•serialized-form.html: すべてのパッケージの直列化されたフォーム
•\*overview-frame.html: 左上のフレームに表示するすべてのパッケージ
•allclasses-frame.html: 左下のフレームに表示するすべてのクラス
•help-doc.html: Javadocページの編成に関するヘルプ
•index-all.html: **-splitindex**オプションなしで作成されたデフォルトの索引
•**index-files**: **-splitindex**オプションを指定して作成されたディレクトリ
•index-<number>.html: **-splitindex**オプションを指定して作成された索引ファイル
•package-list: 外部参照を解決するためのパッケージ名
•stylesheet.css: フォント、色、位置などを定義します
•**java**: パッケージ・ディレクトリ
•**applet**: サブパッケージ・ディレクトリ
•Applet.html: **Applet**クラス・ページ
•AppletContext.html: **AppletContext**インタフェース
•AppletStub.html: **AppletStub**インタフェース
•AudioClip.html: **AudioClip**インタフェース
•package-summary.html: クラスとサマリー
•package-frame.html: 左下のフレームに表示するパッケージ・クラス
•package-tree.html: このパッケージのクラス階層
•package-use.html: このパッケージが使用される場所
•**doc-files**: イメージおよびサンプル・ファイルのディレクトリ
•**class-use**: イメージおよびサンプル・ファイルの場所
\- Applet.html: Appletクラスの使用
\- AppletContext.html: **AppletContext**インタフェースの使用
\- AppletStub.html: **AppletStub**インタフェースの使用
\- AudioClip.html: **AudioClip**インタフェースの使用
•**src-html**: ソース・コード・ディレクトリ
•**java**: パッケージ・ディレクトリ
•**applet**: サブパッケージ・ディレクトリ
\- Applet.html: Appletソース・コード
\- AppletContext.html: **AppletContext**ソース・コード
\- AppletStub.html: **AppletStub**ソース・コード
\- AudioClip.html: **AudioClip**ソース・コード
## 生成されるAPI宣言
**javadoc**コマンドは、それぞれのクラス、インタフェース、フィールド、コンストラクタ、およびメソッドの記述の最初に、そのAPI用の宣言を生成します。たとえば、**Boolean**クラスの宣言は、次のようになります。
```
public final class Boolean
extends Object
implements Serializable
```
**Boolean.valueOf**メソッドの宣言は次のとおりです。
```
public static Boolean valueOf(String s)
```
**javadoc**コマンドは、修飾子**public**、**protected**、**private**、**abstract**、**final**、**static**、**transient**、および**volatile**を含めることができますが、**synchronized**および**native**はできません。**synchronized**および**native**修飾子は、実装の詳細とみなされているため、API仕様には含まれません。
APIでは、並行性セマンティクスについて、キーワード**synchronized**に依存するのではなく、コメントの主説明としてドキュメント化する必要があります。たとえば、「1つのenumerationを複数のスレッドから並行して使用することはできない」のように記述します。ドキュメントには、これらのセマンティクスを実現する方法を記述しないでください。たとえば、**Hashtable**オプションはスレッドセーフである必要がありますが、「エクスポートされるすべてのメソッドを同期化してそれを実現する」のように指定する根拠はありません。より高度な並行性のために、バケット・レベルで内部的に同期化する権限を保有しておくことをお薦めします。
# ドキュメンテーション・コメント
このセクションでは、ソース・コードのコメントとコメントの継承について説明します。
## ソース・コード・コメント
ソース・コードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーション・コメントを記述することができます。各パッケージにもドキュメンテーション・コメントを作成できます。構文は若干異なりますが、概要にもドキュメンテーション・コメントを作成できます。ドキュメンテーション・コメントは、**/\*\***と、終わりを表す**\*/**の間にある文字から構成されます。先頭のアスタリスクは各行で使用でき、次の項で詳しく説明します。コメントのテキストは、複数行にわたって記述できます。
```
/**
* This is the typical format of a simple documentation comment
* that spans two lines.
*/
```
スペースを節約するには、コメントを1行に入れます。
```
/** This comment takes up only one line. */
```
コメントの配置
ドキュメンテーション・コメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールド宣言の直前に配置される場合にのみ認識されます。メソッドの本体に置かれているドキュメンテーション・コメントは無視されます。**javadoc**コマンドは、宣言文ごとに1つのドキュメンテーション・コメントしか認識しません。タグを使用できる場所を参照してください。
よくある間違いは、クラス・コメントとクラス宣言の間に**import**文を置いてしまうことです。**javadoc**コマンドはクラス・コメントを無視するので、**import**文をこの場所に配置しないでください。
```
/**
* This is the class comment for the class Whatever.
*/
import com.example; // MISTAKE - Important not to put import statement here
public class Whatever{ }
```
コメントのパーツ
ドキュメンテーション・コメントには、主説明とその後に続くタグ・セクションが含まれます。主説明は、開始区切り文字**/\*\***で始まり、タグ・セクションまで続きます。タグ・セクションは、先頭文字が**@**の行で定義される最初のブロック・タグから始まります(先頭のアスタリスク、空白文字、先頭の区切り文字**/\*\***は除く)。主説明を記述せず、タグ・セクションのみのコメントを記述することもできます。主説明は、タグ・セクション以降に続けることはできません。タグの引数は、複数行にわたって記述できます。タグの数に制限はありません。何回も記述できるタグと、1回しか記述できないタグがあります。たとえば、次の**@see**タグからタグ・セクションは始まります。
```
/**
* This sentence holds the main description for this documentation comment.
* @see java.lang.Object
*/
```
ブロックおよびインライン・タグ
タグは、**javadoc**コマンドが処理するドキュメンテーション・コメント内の特殊なキーワードです。タグには2つのタイプがあります。1つは**@tag**タグのように表記されるブロック・タグ(スタンドアロン・タグとも呼ばれる)、もう1つは**{@tag}**タグのように中カッコで囲んで表記されるインライン・タグです。ブロック・タグが解釈されるには、行頭のアスタリスク、空白文字、区切り文字(**/\*\***)を除いて、行の先頭に置く必要があります。これは、**@**文字をテキスト内の別の場所で使用しても、タグの開始として解釈されないことを意味しています。**@**文字を使用して行を開始しても、それが解釈されないようにするには、HTMLエンティティ**@**を使用します。それぞれのブロック・タグには、関連付けられたテキストがあります。このテキストは、タグの後から、次のタグの前、またはドキュメンテーション・コメントの最後までの間に記述されたテキストです(タグまたはコメント区切り文字を除く)。この関連テキストは、複数行にわたって記述できます。インライン・タグは、テキストを記述できる場所であればどこにでも置くことができ、解釈されます。次の例にはブロック・タグ**@deprecated**とインライン・タグ**{@link}**が含まれています。javadocタグを参照してください。
```
/**
* @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
*/
```
HTMLでのコメントの記述
テキストはHTMLエンティティとHTMLタグを使用してHTMLで記述される必要があります。使用するブラウザがサポートする任意のHTMLのバージョンを使用できます。標準ドックレットは、カスケーディング・スタイル・シートおよびフレームを含め、ドキュメンテーション・コメント以外の部分でHTML 3.2に準拠したコードを生成します。フレーム・セットのため、生成されたファイルにはHTML 4.0が推奨されます。
たとえば、より小さい記号(<)およびより大きい記号(>)のエンティティは、**<**および**>**と記述する必要があります。同様に、アンパサンド(&)は**&**と記述する必要があります。次の例では、太字のHTMLタグ**<b>**を使用しています。
```
/**
* This is a doc comment.
* @see java.lang.Object
*/
```
先頭のアスタリスク
**javadoc**コマンドによるドキュメンテーション・コメントの解析時に、各行の先頭にあるアスタリスク(\*)文字は破棄されます。最初のアスタリスク(\*)文字より前にある空白やタブも破棄されます。行頭のアスタリスクを省略した場合、インデントを保持したままでサンプル・コードを**<PRE>**タグ内のドキュメンテーション・コメントに直接貼り付けられるように、先頭の空白文字は削除されなくなります。ブラウザは、空白文字をタブよりも一律に解釈します。インデントの起点は(区切り文字**/\*\***または**<PRE>**タグではなく)左マージンになります。
最初の文
各ドキュメンテーション・コメントの最初の文は、宣言されているエンティティに関する簡潔かつ完全なサマリー文である必要があります。この文は、空白、タブ、または行終了文字が続く最初のピリオド、または最初のブロック・タグがある位置で終わります。最初の文は、**javadoc**コマンドによってHTMLページの先頭にあるメンバーのサマリーの部分にコピーされます。
複数フィールドの宣言
Javaプラットフォームでは、1つの文で複数のフィールドを宣言できます。ただし、この文には、1つのドキュメンテーション・コメントしか記述できません。そのコメントが、すべてのフィールドに対してコピーされます。フィールドごとにドキュメンテーション・コメントを記述する必要がある場合は、各フィールドを別々の文で宣言する必要があります。たとえば、次のドキュメンテーション・コメントは、1つの宣言として記述すると不適切です。この場合は、宣言を2つに分けることをお薦めします。
```
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this
```
**javadoc**コマンドは、上のコードから次のようなドキュメントを生成します。
```
public int x
```
The horizontal and vertical distances of point (x, y).
```
public int y
```
The horizontal and vertical distances of point (x, y).
ヘッダー・タグの使用
メンバーに対してドキュメンテーション・コメントを記述するときには、**<H1>**および**<H2>**などのHTML見出しタグを使用しないことをお薦めします。**javadoc**コマンドは、完全な構造化ドキュメントを作成するので、このような構造化タグが使用されていると、生成ドキュメントの形式が悪影響を受けることがあります。ただし、クラスやパッケージのコメントでは、これらの見出しを使用して独自の構造を指定してかまいません。
## メソッド・コメントの継承
**javadoc**コマンドでは、クラスおよびインタフェースでメソッド・コメントを継承して、欠落したテキストを入力したり、明示的にメソッド・コメントを継承することができます。コンストラクタ、フィールド、およびネストされたクラスは、ドキュメンテーション・コメントを継承しません。
**注意:** ドキュメンテーション・コメントをコピーに利用するには、継承したメソッドのソース・ファイルが**-sourcepath**オプションで指定したパスのみに置かれている必要があります。コマンド行で、クラスもパッケージも渡す必要はありません。この点はリリース1.3.*n*以前とは対照的です。これまでは、クラスがドキュメント化されるクラスであることが必要でした。
欠落テキストの入力
主説明、または**@return**、**@param**、**@throws**タグがメソッド・コメントから欠落している場合、**javadoc**コマンドは、対応する主説明またはタグ・コメントを、それがオーバーライドまたは実装しているメソッド(ある場合)からコピーします。メソッド・コメントの継承を参照してください。
特定のパラメータの**@param**タグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。特定の例外の**@throws**タグが見つからない場合、その例外が宣言されている場合にかぎり、**@throws**タグがコピーされます。
この動作はリリース1.3以前の動作とは対照的です。これまでのバージョンでは、主説明またはタグが存在すれば、コメントは一切継承されませんでした。
javadocタグおよびオプションを参照してください。
明示的な継承
**{@inheritDoc}**インライン・タグをメソッドの主説明または**@return**、**@param**、**@throws**タグ・コメントに挿入します。対応する継承された主説明またはタグ・コメントは、その場所にコピーされます。
## クラスおよびインタフェースの継承
コメントの継承は、クラスおよびインタフェースからの継承の、考えられるすべての場合に発生します。
•クラスのメソッドがスーパークラスのメソッドをオーバーライドしている場合
•インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドしている場合
•クラスのメソッドがインタフェースのメソッドを実装している場合
最初の2つのケースでは、**javadoc**コマンドは、オーバーライドしているメソッドのドキュメント内に*「オーバーライド」*という小見出しを生成します。コメントが継承されているかどうかにかかわらず、オーバーライドされているメソッドへのリンクが含まれます。
3つ目のケース(特定のクラスのメソッドがインタフェースのメソッドを実装している場合)では、**javadoc**コマンドは、オーバーライドしているメソッドのドキュメント内に*「定義」*という小見出しを生成します。コメントが継承されているかどうかにかかわらず、実装されているメソッドへのリンクが含まれます。
## メソッド・コメントのアルゴリズム
メソッドにドキュメンテーション・コメントがない、または**{@inheritDoc}**タグがある場合、**javadoc**コマンドは次のアルゴリズムを使用して適用できるコメントを検索します。アルゴリズムは、最も特定される適用可能なドキュメンテーション・コメントを探し、スーパークラスよりもインタフェースを優先するように設計されています。
1.直接に実装されている(または、拡張されている)インタフェースを、メソッドの宣言で**implements**(または**extends**)という語の後に出現する順序で、1つずつ調べます。このメソッドについて最初に見つかったドキュメンテーション・コメントを採用します。
2.手順1でドキュメンテーション・コメントが見つからなかった場合は、直接実装されている(または、拡張されている)インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用します(その際の順序は、手順1でインタフェースを調べたときの順序と同じ)。
3.手順2でドキュメンテーション・コメントが見つからなかった場合で、このクラスが**Object**以外のクラスであるが、インタフェースではない場合は、次のように処理します。
1.スーパークラスにこのメソッドについてのドキュメンテーション・コメントが記述されている場合は、そのコメントを採用します。
2.手順3aでドキュメンテーション・コメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を再帰的に適用します。
# [JAVADOCタグ](#JAVADOC)
**javadoc**コマンドは、Javaのドキュメンテーション・コメント内に埋め込まれた特別なタグを解析します。**javadoc**タグを使用すると、完全な整形式のAPIをソース・コードから自動的に生成できます。タグはアットマーク記号(**@**)で始まり、大文字と小文字が区別されます。これらのタグは、表示されているとおりに大文字と小文字を使用して入力する必要があります。タグは、行の先頭(先頭の空白文字と省略可能なアスタリスクの後)に置く必要があります。そうしないと、テキストとして扱われます。慣例として、同じ名前のタグは1箇所にまとめます。たとえば、**@see**タグが複数ある場合は、すべて同じ場所にまとめて配置します。詳細は、タグを使用できる場所を参照してください。
タグには、次のタイプがあります。
•ブロック・タグ: ブロック・タグは主説明に続くタグ・セクション内にのみ配置します。ブロック・タグは、*@tag*の形式をとります。
•インライン・タグ: インライン・タグは主説明内またはブロック・タグのコメント内の任意の場所に配置します。インライン・タグは*{@tag}*のように中カッコで囲みます。
カスタム・タグについては、-tag tagname:Xaoptcmf:"taghead"を参照してください。タグを使用できる場所も参照してください。
## タグの説明
@author *name-text*
JDK 1.0で導入
**-author**オプションが使用されている場合、指定した名前のテキストの作成者エントリを生成されるドキュメントに追加します。1つのドキュメンテーション・コメントに複数の**@author**タグを含めることができます。1つの**@author**タグに1つの名前を指定することも、複数の名前を指定することもできます。前者の場合は、**javadoc**コマンドによって名前と名前の間にカンマ(,)と空白文字が挿入されます。後者の場合は、テキスト全体が解析されることなく、生成ドキュメントにコピーされます。したがって、カンマではなく、各言語に対応した名前区切り文字を使用する必要があるときに、1行に複数の名前を指定できます。JavadocツールでのDocコメントの記述方法の@authorに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@author)を参照してください。
{@code *text*}
JDK 1.5で導入
**<code>{@literal}</code>**と同じです。
テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、textをコード・フォントで表示します。これにより、ドキュメンテーション・コメントでは、パラメータの型(**<Object>**)、不等号(**3 < 4**)、矢印(**<-**)などで、通常の山カッコ(<および>)をHTMLエンティティ(**<**および**>**)のかわりに使用できます。たとえば、ドキュメンテーション・コメント・テキスト**{@code A<B>C}**は、**A<B>C**として変更されずに生成されたHTMLページに表示されます。つまり、**<B>**が太字として解釈されず、そのフォントはコード・フォントになります。コード・フォントなしで同じ機能を実現するには、**{@literal}**タグを使用します。
@deprecated *deprecated-text*
JDK 1.0で導入
このAPIは動作し続けますが、このAPIを使用しないことを薦めるコメントを追加します。**javadoc**コマンドは、**deprecated-text**を主説明の前に移動してイタリックにし、その前に太字の警告「推奨されていません。」を追加します。このタグは、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
非推奨テキストの最初の文では、そのAPIが推奨されなくなった時期と、代替として使用するAPIをユーザーに提示する必要があります。**javadoc**コマンドは、この最初の文を、サマリー・セクションと索引にコピーします。その後の文で非推奨になった理由を説明することもできます。代替APIを指し示す**{@link}**タグ(Javadoc 1.2以降の場合)を含める必要があります。
*@deprecated annotation*タグを使用してプログラム要素を非推奨にします。APIを非推奨にする方法と時期 (http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation.html)を参照してください。
JavadocツールでのDocコメントの記述方法の@deprecatedに関する項
(http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@deprecated)も参照してください。
{@docRoot}
JDK 1.3で導入
生成されるページからの、生成ドキュメントの(生成先)ルート・ディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。通常は、各ページの最下部から著作権のページにリンクします。
この**{@docRoot}**タグは、コマンド行でもドキュメンテーション・コメント内でも使用できます。このタグは、任意のタグ(**@return**、**@param**および**@deprecated**タグなど)のテキスト部分を含む、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
•コマンド行で、header、footerまたはbottomが定義されている場合、**javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'**となります。
**{@docRoot}**タグをmakefile内でこのように利用する場合、一部の**makefile**プログラムでは、中カッコ**{}**文字を特別にエスケープする必要があります。たとえば、Inprise MAKEバージョン5.2をWindows上で実行する場合は、**{{@docRoot}}**のように、中カッコを二重にする必要があります。**-bottom**オプションなどのオプションへの引数を囲むのに、二重(一重ではなく)引用符も必要です(**href**引数を囲む引用符は省略)。
•ドキュメンテーション・コメントでは
```
/**
* See the Copyright.
*/
```
このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。式: **<a href="{@docRoot}/copyright.html">**は、**java/lang/Object.java**の場合**<a href="../../copyright.html">**に、**java/lang/ref/Reference.java**の場合**<a href="../../../copyright.html">**に解決されます。
@exception *class-name description*
JDK 1.0で導入
**@throws**タグと同じです。@throws class-name descriptionを参照してください。
{@inheritDoc}
JDK 1.4で導入
最も近い継承可能なクラスまたは実装可能なインタフェースから、このタグの位置にある現在のドキュメンテーション・コメントに、ドキュメントを継承(コピー)します。これにより、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使用して記述することができます。
このタグは、ドキュメンテーション・コメントの次の位置でのみ有効です。
•メソッドの主説明ブロック内。この場合、主説明は、上位階層のクラスまたはインタフェースからコピーされます。
•メソッドの**@return**、**@param**、**@throws**タグのテキスト引数内。この場合、タグ・テキストは、上位階層の対応するタグからコピーされます。
継承階層でコメントを見つける方法に関する説明は、メソッド・コメントの継承を参照してください。このタグが見つからない場合、コメントは、この項で説明するルールに応じて、自動的に継承されるかどうかが決まります。
{@link *package.class#member label*}
JDK 1.2で導入
表示テキストlabelとともにインライン・リンクを挿入します。labelは、参照クラスの指定されたパッケージ、クラス、またはメンバーの名前のドキュメントを指し示します。このタグは、**@return**、**@param**および**@deprecated**タグなどの任意のタグのテキスト部分を含む、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。JavadocツールでのDocコメントの記述方法の@linkに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#{@link)を参照してください。
このタグは**@see**タグに似ています。どちらのタグも、**package.class#member**と**label**の参照方法と、有効な構文が同じです。主な違いは、**{@link}**タグでは、「関連項目」セクションにリンクが配置されるかわりに、インライン・リンクが生成されるという点です。インライン・テキストの他の部分と区別するために、**{@link}**タグの最初と最後に中カッコを記述します。ラベル内で右中カッコ(**}**)を使用する必要がある場合、HTMLエンティティ記法**}**を使用します。
1つ文の中で使用できる**{@link}**タグの数に制限はありません。このタグは、ドキュメンテーション・コメントの主説明部分、または**@deprecated**、**@return**、**@param**タグなどの任意のタグのテキスト部分で使用できます。
たとえば、次のコメントでは**getComponentAt(int,int)**メソッドを参照しています。
```
Use the {@link #getComponentAt(int, int) getComponentAt} method.
```
標準ドックレットでは、このコードから次のHTMLが生成されます(このコメントが同じパッケージの別のクラスを参照している場合)。
```
Use the getComponentAt method.
```
前の行は、次のようにWebページに表示されます。
```
Use the getComponentAt method.
```
{@linkplain *package.class#member label*}
JDK 1.4で導入
**{@link}**タグと同じ動作をしますが、リンク・ラベルがコード・フォントではなくプレーン・テキストで表示される点が異なります。ラベルがプレーン・テキストで記述されていると便利です。たとえば、「**Refer to {@linkplain add() the overridden method}**.」は「Refer to the overridden method」と表示されます。
{@literal *text*}
JDK 1.5で導入
テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、textを表示します。これにより、ドキュメンテーション・コメントでは、パラメータの型(**<Object>**)、不等号(**3 < 4**)、矢印(<-)などで、山カッコ(**<および>**)をHTMLエンティティ(**<**および**>**)のかわりに使用できます。たとえば、ドキュメンテーション・コメント・テキスト**{@literal A<B>C}**は、**A<B>C**としてブラウザの生成されたHTMLページで変更されずに表示されます。**<B>**は太字として解釈されません(コード・フォントになりません)。コード・フォントで同じ機能を実現するには、**{@code}**タグを使用します。
@param *parameter-name description*
JDK 1.0で導入
「パラメータ」セクションに、指定された**parameter-name**の後に指定されたdescriptionを続けてパラメータを追加します。ドキュメンテーション・コメントを記述するときには、descriptionを複数行にわたって記述することもできます。このタグは、メソッド、コンストラクタ、またはクラスのドキュメンテーション・コメント内でのみ有効です。JavadocツールでのDocコメントの記述方法の@paramに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@param)を参照してください。
**parameter-name**は、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタの型パラメータの名前になります。山カッコでこのパラメータ名を囲み、型パラメータを使用することを指定します。
クラスの型パラメータの例:
```
/**
* @param Type of element stored in a list
*/
public interface List extends Collection {
}
```
メソッドの型パラメータの例:
```
/**
* @param string the string to be converted
* @param type the type to convert the string to
* @param the type of the element
* @param the value of the element
*/
V convert(String string, Class type) {
}
```
@return *description*
JDK 1.0で導入
「戻り値」セクションを追加して、descriptionのテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーション・コメントでのみ有効です。JavadocツールでのDocコメントの記述方法の@returnに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return)を参照してください。
@see *reference*
JDK 1.0で導入
*「関連項目」*見出しを追加して、referenceを指すリンク、またはテキスト・エントリを書き込みます。1つのドキュメンテーション・コメントには任意の数の**@see**タグを含めることができますが、それらはすべて同じ見出しの下にグループ化されます。**@see**タグには、3つのタイプの形式があります。この形式が最も一般的です。このタグは、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドで有効です。パッケージ、クラス、またはメンバーに対するインライン・リンクを文中に挿入する方法は、**{@link}**を参照してください。
**形式1**。@see **string**タグ形式は、*string*のテキスト・エントリを追加します。リンクは生成されません。stringは、書籍またはURLではアクセスできない情報の参照先です。**javadoc**コマンドは、最初の文字として二重引用符(")を検索して、この形式を前述の形式と区別します。たとえば、**@see "The Java Programming Language"**は次のテキストを生成します。
**関連項目**:
"The Java Programming Language"
**形式2**。**@see <a href="URL#value">label</a>**フォームは、**URL#value**で定義されているようにリンクを追加します。**URL#value**パラメータは、相対URLまたは絶対URLです。**javadoc**コマンドは、最初の文字として「より小さい」記号(**<**)を検索して、この形式を他の形式と区別します。たとえば、**@see <a href="spec.html#section">Java Spec</a>**は、次のリンクを生成します:
**関連項目**:
Java Spec
**形式3**。**@see package.class#member label**形式は、表示テキスト・ラベルとともにリンクを追加します。このラベルは参照されているJava言語の指定された名前のドキュメントを指し示します。ラベルはオプションです。ラベルを省略した場合は、表示テキストのかわりに、名前が適切に短縮されて表示されます。**-noqualifier**オプションを使用すると、この表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストにする場合に使用します。「名前が表示される方法」を参照してください。
Java SE 1.2だけは、ラベルではなく名前が**<code>** HTMLタグ内に自動的に表示されます。Java SE 1.2.2からは、ラベルを使用するかしないかにかかわらず、**<code>**タグは常に表示テキストを囲む形で含まれます。
•**package.class#member**には、参照されている任意の有効なプログラム要素の名前を指定します。つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。ただし、メンバー名の前の文字は、シャープ記号(**#**)にする必要があります。classは、任意のトップレベルまたはネストされたクラスか、インタフェースを表します。memberは、任意のコンストラクタ、メソッドまたはフィールドを表します(ネストされたクラスまたはインタフェースではありません)。この名前が、ドキュメント化されるクラスに含まれている場合、**javadoc**コマンドは、その名前へのリンクを作成します。外部参照クラスへのリンクを作成するには、**-link**オプションを使用します。参照クラスに属していない名前のドキュメントを参照するには、他の2つの**@see**タグ形式のどちらかを使用します。「名前の指定」を参照してください。
**注意:** 外部参照クラスは、コマンド行で**javadoc**コマンドに渡されないクラスです。生成ドキュメント内で外部参照クラスにリンクしている箇所は、外部参照または外部リンクと呼ばれます。たとえば、**java.awt package**に対してのみ**javadoc**コマンドを実行した場合、**Object**などの**java.lang**内のすべてのクラスが外部参照クラスになります。**-link**および**-linkoffline**オプションを使用して、外部参照クラスへリンクします。外部参照クラスのソース・コメントは**javadoc**コマンドの実行には使用できません。
•**label**は、省略可能なテキストで、リンクのラベルとして表示されます。ラベルには空白を含めることができます。**label**を省略すると、**package.class.member**が、現在のクラスおよびパッケージに応じて適切に短縮されて表示されます。「名前が表示される方法」を参照してください。
•空白文字が、**package.class#member**と**label**の間の区切り文字になります。カッコの内側の空白文字はラベルの先頭とは解釈されないため、メソッドのパラメータ間に空白文字を入れてもかまいません。
この例では、**@see**タグ(**Character**クラス内)が、**String**クラスのequalsメソッドを参照しています。タグには、名前**String#equals(Object)**とラベル**equals**の両方の引数が含まれています。
```
/**
* @see String#equals(Object) equals
*/
```
標準ドックレットは、次のようなHTMLを生成します。
```
- See Also:
equals
```
前述のコードは、ブラウザに次のように表示され、ラベルは表示リンク・テキストになっています。
**関連項目**:
equals
名前の指定
この**package.class#member**という名前は、**java.lang.String#toUpperCase()**のような完全修飾名にすることも、**String#toUpperCase()**や**#toUpperCase()**のような非完全修飾名にすることもできます。名前が完全修飾より短い場合は、**javadoc**コマンドは、標準のJavaコンパイラの検索順序を使用して探します。「@seeタグの検索順序」を参照してください。名前は、メソッド引数の間など、カッコ内のスペースを含めることができます。部分的に修飾した短い名前を指定することの利点は、入力する文字数が減ることや、ソース・コードが読みやすくなることです。次のリストに様々な形式の名前を示します。ここで、**Class**にはクラスまたはインタフェースを、Typeにはクラス、インタフェース、配列、またはプリミティブを、methodにはメソッドまたはコンストラクタを、それぞれ指定できます。
```
Typical forms for @see package.class#member
Referencing a member of the current class
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)
Referencing another class in the current or imported packages
@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
@see Class#constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class
Referencing an element in another package (fully qualified)
@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
@see package.Class#constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package
```
前のリストに関するメモ:
•最初のタイプの形式(パッケージとクラスを省略)の場合、**javadoc**コマンドは、現在のクラスの階層のみを検索します。つまり、現在のクラスかインタフェース、そのスーパークラスかスーパーインタフェース、またはその外側を囲んでいるクラスかインタフェースからメンバーを検索します(検索項目1–3)。現在のパッケージの他の部分や、他のパッケージは検索しません(検索項目4–5)。「@seeタグの検索順序」を参照してください。
•メソッドまたはコンストラクタの入力時に、**getValue**のようにカッコなしの名前を使用した場合、同じ名前のフィールドが存在していなければ、**javadoc**コマンドはそのメソッドへのリンクを作成します。このメソッドがオーバーロードされている場合、**javadoc**コマンドは、検索で最初に見つかったメソッドにリンクします。結果は前もって特定できません。
•ネストされたクラスは、すべての形式について、**outer.inner**として指定する必要があります。単純に**inner**とはしないでください。
•すでに述べたように、クラスとメンバーとの間の区切り文字としては、ドット(**.**)ではなくシャープ記号(**#**)を使用します。このように指定すると、**javadoc**コマンドは、あいまいさを解決できます。ドットは、クラス、ネストされたクラス、パッケージ、およびサブパッケージを区切るためにも使用されるからです。ただし、**javadoc**コマンドでは、あいまいさがなければドットは正しく解析されますが、警告は表示されます。
@seeタグの検索順序
**javadoc**コマンドは、ソース・ファイル、パッケージ・ファイル、概要ファイルに表示される**@see**タグを処理します。後者の2つのファイルでは、完全修飾の名前を**@see**タグに指定する必要があります。ソース・ファイルでは、完全修飾の名前、または部分修飾の名前を指定できます。
次に、**@see**タグの検索順序を示します。
1.現在のクラスまたはインタフェース。
2.外側を囲んでいるクラスとインタフェース(最も近いものから検索)。
3.スーパークラスとスーパーインタフェース(最も近いものから検索)。
4.現在のパッケージ。
5.インポートされているパッケージ、クラス、およびインタフェース(**import**文の順序に従って検索)。
**javadoc**コマンドは、各クラスについて項目1-3を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にその外側を囲んでいるクラスEを検索した後、Eのスーパークラスを検索してから、Eを囲んでいるクラスを検索します。項目4と5では、**javadoc**コマンドが1つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません(その順序は、個々のコンパイラによって異なります)。項目5では、**javadoc**コマンドは、*java.lang*を検索します。このパッケージは、すべてのプログラムに自動的にインポートされるからです。
**javadoc**コマンドは、完全修飾でないソース・ファイルで**@see**タグを見つけると、Javaコンパイラと同じ順序で指定された名前を検索します(ただし、**javadoc**コマンドは、特定の名前空間のあいまいさを検出しません。これは、ソース・コードにこれらのエラーが存在していないことを前提としているためです)。この検索順序は、Java言語仕様で正式に定義されています。**javadoc**コマンドは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてからその名前を検索します。具体的には、次の順序で検索します。
1.現在のクラスまたはインタフェース。
2.外側を囲んでいるクラスとインタフェース(最も近いものから検索)。
3.スーパークラスとスーパーインタフェース(最も近いものから検索)。
4.現在のパッケージ。
5.インポートされているパッケージ、クラス、およびインタフェース(**import**文の順序に従って検索)。
**javadoc**コマンドは、必ずしもサブクラスを検索するとは限りません。また、実行中に他のパッケージのドキュメントが生成される場合でも、他のパッケージを検索しません。たとえば、**@see**タグが**java.awt.event.KeyEvent**クラス内に含まれていて、**java.awt package**内のある名前を参照していても、そのクラスがインポートしないかぎり**javadoc**コマンドはそのパッケージを検索しません。
名前が表示される方法
**label**を省略すると、**package.class.member**が表示されます。一般に、これは現在のクラスおよびパッケージに応じて適切に短縮されます。短縮されるとは、**javadoc**コマンドにより必要最小限の名前のみが表示されるということです。たとえば、**String.toUpperCase()**メソッドに、同じクラスのメンバーへの参照と他のクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースのみです(次のリストを参照)。パッケージ名を全体的に削除するには、**-noqualifier**オプションを使用します。
**参照のタイプ**: **@see**タグは同じクラス、同じパッケージのメンバーを参照します
**例**: **@see String#toLowerCase()**
**表示**: **toLowerCase()** - パッケージおよびクラス名を省略します
**参照のタイプ**: **@see**タグは別のクラス、同じパッケージのメンバーを参照します
**例**: **@see Character#toLowerCase(char)**
**表示**: **Character.toLowerCase(char)** - パッケージ名を省略し、クラス名を含みます
**参照のタイプ**: **@see**タグは異なるクラス、異なるパッケージのメンバーを参照します
**例**: **@see java.io.File#exists()**
**表示**: **java.io.File.exists()** - パッケージおよびクラス名を含みます
@seeタグの例
右側のコメントは、**@see**タグが**java.applet.Applet**などの別のパッケージのクラス内にある場合に、名前がどのように表示されるかを示しています。JavadocツールでのDocコメントの記述方法の@seeに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@see)を参照してください。
```
See also:
@see java.lang.String // String
@see java.lang.String The String class // The String class
@see String // String
@see String#equals(Object) // String.equals(Object)
@see String#equals // String.equals(java.lang.Object)
@see java.lang.Object#wait(long) // java.lang.Object.wait(long)
@see Character#MAX_RADIX // Character.MAX_RADIX
@see Java Spec // Java Spec
@see "The Java Programming Language" // "The Java Programming Language"
```
**注意:** **@see**タグを拡張してドキュメント化されないクラスにリンクするには、**-link**オプションを使用します。
@serial *field-description* | include | exclude
JDK 1.2で導入
デフォルトの直列化可能フィールドのドキュメンテーション・コメントで使用します。クラスの直列化可能なフィールドおよびデータの文書化 (http://docs.oracle.com/javase/8/docs/platform/serialization/spec/serial-arch.html#5251)を参照してください
Oracleの直列化された形式の仕様にクラスを含める基準 (http://www.oracle.com/technetwork/java/javase/documentation/serialized-criteria-137781.html)も参照してください
**field-description**(省略可能)では、フィールドの意味を説明し、取り得る値のリストを示す必要があります。必要な場合は、複数の行に渡って説明を記述できます。標準ドックレットは、この情報を、直列化された形式ページに追加します。相互参照ページを参照してください。
クラスを直列化した後に直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。
**include**および**exclude**引数は、直列化された形式ページにクラスまたはパッケージを含めるか除外するかを示します。次のように機能します。
•**Serializable**を実装しているpublicまたはprotectedクラスは、そのクラス(またはそのクラスが属するパッケージ)が**@serial exclude**タグでマークされていないかぎり、含められます。
•**Serializable**を実装しているprivateまたはpackage-privateクラスは、そのクラス(またはそのクラスが属するパッケージ)が**@serial include**タグでマークされていないかぎり、除外されます。
たとえば、**javax.swing**パッケージはpackage.htmlまたはpackage-info.java内で**@serial** **exclude**タグでマークされています。publicクラス**java.security.BasicPermission**は**@serial exclude**タグでマークされています。package-privateクラス**java.util.PropertyPermissionCollection**は**@serial include**タグでマークされています。
クラス・レベルの**@serial**タグはパッケージ・レベルの**@serial**タグをオーバーライドします。
@serialData *data-description*
JDK 1.2で導入
データの説明値を使用して、直列化された形式でのデータの型と順序をドキュメント化します。このデータには、**writeObject**メソッドによって書き込まれる省略可能なデータ、および**Externalizable.writeExternal**メソッドによって書き込まれるすべてのデータ(ベース・クラスを含む)が含まれます。
**@serialData**タグは、**writeObject**、**readObject**、**writeExternal**、**readExternal**、**writeReplace**および**readResolve**メソッドのドキュメンテーション・コメントで使用できます。
@serialField *field-name* *field-type* *field-description*
JDK 1.2で導入
**Serializable**クラスの**serialPersistentFields**メンバーの**ObjectStreamField**コンポーネントをドキュメント化します。**ObjectStreamField**コンポーネントごとに1つの**@serialField**タグを使用します。
@since *since-text*
JDK 1.1で導入
生成ドキュメントに、指定された**since-text**の値の*「導入されたバージョン」*見出しを追加します。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドで有効です。このタグは、特定の変更または機能が、**since-text**の値によって指定されたソフトウェア・リリース以降、存在していることを意味します。たとえば、**@since 1.5**です。
Javaプラットフォームのソース・コードの場合、**@since**タグは、JavaプラットフォームAPI仕様のバージョンを示します。ソース・コードがリファレンス実装に追加された時期を示すとは限りません。複数の**@since**タグを使用でき、複数の**@author**タグのように扱われます。プログラム要素が複数のAPIで使用される場合、複数のタグを使用できます。
@throws *class-name* *description*
JDK 1.2で導入
**@exception**タグと同じ動作をします。JavadocツールでのDocコメントの記述方法の@throwsに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@exception)を参照してください
**@throws**タグは、生成ドキュメントに*Throws*小見出しを追加して、**class-name**および**description**テキストを書き込みます。*class-name*は、そのメソッドからスローされる可能性のある例外の名前です。このタグは、メソッド、コンストラクタのドキュメンテーション・コメント内でのみ有効です。このクラスが完全指定の名前で記述されていない場合、**javadoc**コマンドは、検索順序に従ってクラスを探します。複数の**@throws**タグを、同じ例外または違う例外の指定したドキュメンテーション・コメントで使用できます。「@seeタグの検索順序」を参照してください。
すべてのチェック済例外がドキュメント化されるようにするために、**@throws**タグがthrows節内の例外用に存在しない場合は、**@throws**タグでドキュメント化されたかのように、**javadoc**コマンドによって例外がHTML出力に説明なしで追加されます。
オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、**@throws**のドキュメントがそのメソッドからサブクラスにコピーされます。インタフェース・メソッドから実装メソッドにコピーされる場合も同様です。**{@inheritDoc}**タグを使用して、**@throws**タグがドキュメンテーションを継承するように強制できます。
{@value *package.class#field*}
JDK 1.4で導入
定数の値を表示します。**{@value}**タグが静的フィールドのドキュメンテーション・コメントで引数なしで使用されている場合、その定数の値を表示します。
```
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "