javadoc {packages|source-files} [options] [@argfiles]
packages
デフォルトでは、javadocは、現在のディレクトリおよびサブディレクトリで指定されたパッケージを探します。-sourcepathオプションを使用して、パッケージを探すディレクトリのリストを指定します。
source-files
options
@argfiles
javadocコマンドは、一連のJavaソース・ファイルにある宣言およびドキュメンテーション・コメントを解析し、デフォルトでは、publicクラス、protectedクラス、ネストされたクラス(匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて記述した一連のHTMLページを生成します。javadocコマンドは、APIドキュメントの生成や、一連のソース・ファイルの実装ドキュメントの生成に使用できます。
javadocコマンドは、パッケージ全体、個々のソース・ファイル、またはその両方に対して実行できます。パッケージ全体のドキュメント化を行うには、-subpackagesオプションを使用してディレクトリおよびそのサブディレクトリを再帰的にたどるか、パッケージ名の明示的なリストを渡します。個々のソース・ファイルをドキュメント化するには、Javaソース・ファイル名のリストを渡します。簡単な例を参照してください。
javadocコマンドは、ソースで終わるファイル、およびソース・ファイルで説明しているその他のファイルを処理します。個々のソース・ファイル名を渡してjavadocを実行する場合、どのソース・ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソース・ファイル名を明示的に指定しなくても、javadocコマンドは3つの方法で実行できます。パッケージ名を渡し、-subpackagesオプションを使用するか、またはソース・ファイル名にワイルドカードを使用することができます。これらの場合、javadocコマンドがソース・ファイルの処理を行うのは、そのファイルが次のすべての要件を満たす場合のみです。
リンクの処理
処理の実行中に、javadocコマンドは、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、相互参照リンクを追加します。リンクは、次の場所に表示されます。@タグの説明については、javadocタグを参照してください。
コマンド行で指定しなかったクラスについての既存のテキスト(別に生成したテキスト)に対してリンクを追加するには、-linkおよび-linkofflineオプションを利用できます。
処理の詳細
javadocコマンドは実行するたびに1つの完全なドキュメントを生成します。前の実行の結果を変更または直接取り込む、増分ビルドを行いません。ただし、javadocコマンドは、他の実行の結果にリンクできます。
javadocコマンドの実装にはJavaコンパイラが必要で、Javaコンパイラに依存しています。javadocコマンドはjavacコマンドの一部を呼び出し、宣言をコンパイルして、メンバーの実装を無視します。javadocコマンドは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、HTMLを生成します。さらに、Jjavadocコマンドは、ソース・コードのドキュメンテーション・コメントから、ユーザーの提供したドキュメントも取得します。ドキュメンテーション・コメントを参照してください。
javadocコマンドは、メソッド本体を持たない純粋なスタブ・ファイルであるソース・ファイルに対して実行できます。したがって、APIの実装前の設計の早い段階で、ドキュメンテーション・コメントを記述してjavadocコメントを実行できます。
コンパイラに依存することによって、HTML出力は、実際の実装に正確に対応します。実際の実装は、明示的なソース・コードにではなく、暗黙のソース・コードに依存する場合があります。たとえば、javadocコマンドは、コンパイル済クラス・ファイルには存在するがソース・コードには存在しないデフォルト・コンストラクタをドキュメント化します。
多くの場合、javadocコマンドでは、ソース・ファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。すべてのデバッグやトラブルシューティングを完了する前にドキュメントを生成できます。javadocコマンドはドキュメンテーション・コメントの基本的なチェックを行います。
javadocコマンドは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、 javadocコマンドは、ブートストラップ・クラス、拡張機能、またはユーザー・クラスにかかわらず、すべての参照クラスを検索できる必要があります。クラスの検出方法 (http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html)を参照してください
通常、作成するクラスは、拡張クラスとして、またはjavadocコマンドのクラス・パスでロードされる必要があります。
javadocコマンドの出力の内容と形式は、ドックレットを使用してカスタマイズできます。javadocコマンドには、標準ドックレットと呼ばれるデフォルトの組込みドックレットがあります。標準ドックレットは、HTML形式のAPIドキュメントを生成します。標準ドックレットを修正またはサブクラスを作成することや、HTML、XML、MIF、RTFなどの好みの出力形式を生成する独自のドックレットを記述することも可能です。
-docletオプションでカスタム・ドックレットが指定されていない場合、javadocコマンドは、デフォルトの標準ドックレットを使用します。javadocコマンドには、使用されているドックレットに関係なく使用できるいくつかのオプションがあります。標準ドックレットでは、これらの他に、いくつかのコマンド行オプションが追加されます。オプションを参照してください。
javadocコマンドは、次のタイプのソース・ファイルから出力を生成します。そのファイルは、クラスのJava言語ソース・ファイル(.java)、パッケージ・コメント・ファイル、概要コメント・ファイル、およびその他の未処理のファイルです。ここでは、ドキュメント化しないがソース・ツリーに存在する場合があるテスト・ファイルやテンプレート・ファイルについても説明します。
それぞれのクラスまたはインタフェース、およびそのメンバーは、独自のドキュメンテーション・コメントを持つことができ、それをソース・ファイル内に保持します。ドキュメンテーション・コメントを参照してください。
それぞれのパッケージは、独自のドキュメンテーション・コメントを持つことができ、それを専用のソース・ファイルに保持します。その内容は、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.
* <p>
* 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
<HTML>
<BODY>
Provides the classes necessary to create an applet and the
classes an applet uses to communicate with its applet context.
<p>
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
</BODY>
</HTML>
package.htmlファイルは通常のHTMLファイルであり、パッケージ宣言を含んでいません。パッケージ・コメント・ファイルの内容はHTMLで記述しますが、例外が1つあります。このドキュメンテーション・コメントには、コメント区切り文字である/**と*/、または行頭のアスタリスクを含めない、という点です。コメントを書く場合は、最初の文をパッケージのサマリーとし、<body>タグと最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージ・タグを含めることができます。すべてのブロック・タグは、主説明の後に配置する必要があります。@seeタグをパッケージ・コメント・ファイルに追加する場合には、完全修飾名を使用する必要があります。
コメント・ファイルの処理
javadocコメントを実行すると、パッケージ・コメント・ファイルが検索されます。パッケージ・コメント・ファイルが見つかった場合は、javadocコマンドは次の手順を実行します。
文の終わりは、クラスやメンバーの主説明の最初の文の終わりと同じルールによって判断されます。
ドキュメント化する各アプリケーションまたはパッケージ・セットは、独自の概要ドキュメンテーション・コメントを持つことができ、それは専用のソース・ファイルに保持されます。その内容は、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コマンドは次の手順を実行します。
ソース・ファイルには、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: * <img src="doc-files/Button.gif"> */
ソース・ツリーのテストおよびテンプレート・ファイルを、ソース・ファイルが存在するディレクトリまたはサブディレクトリと同じディレクトリに格納できます。テストおよびテンプレート・ファイルが処理されるのを防ぐには、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など)。
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ディレクトリは、ソース・ツリー内に存在する場合にのみ、生成先に作成されます。生成されるファイルを参照してください。
- Applet.html: Appletクラスの使用
- AppletContext.html: AppletContextインタフェースの使用
- AppletStub.html: AppletStubインタフェースの使用
- AudioClip.html: AudioClipインタフェースの使用
- Applet.html: Appletソース・コード
- AppletContext.html: AppletContextソース・コード
- AppletStub.html: AppletStubソース・コード
- AudioClip.html: AudioClipソース・コード
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 <b>doc</b> 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コマンドは次のアルゴリズムを使用して適用できるコメントを検索します。アルゴリズムは、最も特定される適用可能なドキュメンテーション・コメントを探し、スーパークラスよりもインタフェースを優先するように設計されています。
javadocコマンドは、Javaのドキュメンテーション・コメント内に埋め込まれた特別なタグを解析します。javadocタグを使用すると、完全な整形式のAPIをソース・コードから自動的に生成できます。タグはアットマーク記号(@)で始まり、大文字と小文字が区別されます。これらのタグは、表示されているとおりに大文字と小文字を使用して入力する必要があります。タグは、行の先頭(先頭の空白文字と省略可能なアスタリスクの後)に置く必要があります。そうしないと、テキストとして扱われます。慣例として、同じ名前のタグは1箇所にまとめます。たとえば、@seeタグが複数ある場合は、すべて同じ場所にまとめて配置します。詳細は、タグを使用できる場所を参照してください。
タグには、次のタイプがあります。
カスタム・タグについては、-tag tagname:Xaoptcmf:"taghead"を参照してください。タグを使用できる場所も参照してください。
@author name-text
-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}
<code>{@literal}</code>と同じです。
テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、textをコード・フォントで表示します。これにより、ドキュメンテーション・コメントでは、パラメータの型(<Object>)、不等号(3 < 4)、矢印(<-)などで、通常の山カッコ(<および>)をHTMLエンティティ(<および>)のかわりに使用できます。たとえば、ドキュメンテーション・コメント・テキスト{@code A<B>C}は、A<B>Cとして変更されずに生成されたHTMLページに表示されます。つまり、<B>が太字として解釈されず、そのフォントはコード・フォントになります。コード・フォントなしで同じ機能を実現するには、{@literal}タグを使用します。
@deprecated deprecated-text
この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}
生成されるページからの、生成ドキュメントの(生成先)ルート・ディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。通常は、各ページの最下部から著作権のページにリンクします。
この{@docRoot}タグは、コマンド行でもドキュメンテーション・コメント内でも使用できます。このタグは、任意のタグ(@return、@paramおよび@deprecatedタグなど)のテキスト部分を含む、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
{@docRoot}タグをmakefile内でこのように利用する場合、一部のmakefileプログラムでは、中カッコ{}文字を特別にエスケープする必要があります。たとえば、Inprise MAKEバージョン5.2をWindows上で実行する場合は、{{@docRoot}}のように、中カッコを二重にする必要があります。-bottomオプションなどのオプションへの引数を囲むのに、二重(一重ではなく)引用符も必要です(href引数を囲む引用符は省略)。
/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/
@exception class-name description
@throwsタグと同じです。@throws class-name descriptionを参照してください。
{@inheritDoc}
最も近い継承可能なクラスまたは実装可能なインタフェースから、このタグの位置にある現在のドキュメンテーション・コメントに、ドキュメントを継承(コピー)します。これにより、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使用して記述することができます。
このタグは、ドキュメンテーション・コメントの次の位置でのみ有効です。
継承階層でコメントを見つける方法に関する説明は、メソッド・コメントの継承を参照してください。このタグが見つからない場合、コメントは、この項で説明するルールに応じて、自動的に継承されるかどうかが決まります。
{@link package.class#member label}
表示テキスト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.
Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.
Use the getComponentAt method.
{@linkplain package.class#member label}
{@link}タグと同じ動作をしますが、リンク・ラベルがコード・フォントではなくプレーン・テキストで表示される点が異なります。ラベルがプレーン・テキストで記述されていると便利です。たとえば、「Refer to {@linkplain add() the overridden method}.」は「Refer to the overridden method」と表示されます。
{@literal text}
テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、textを表示します。これにより、ドキュメンテーション・コメントでは、パラメータの型(<Object>)、不等号(3 < 4)、矢印(<-)などで、山カッコ(<および>)をHTMLエンティティ(<および>)のかわりに使用できます。たとえば、ドキュメンテーション・コメント・テキスト{@literal A<B>C}は、A<B>Cとしてブラウザの生成されたHTMLページで変更されずに表示されます。<B>は太字として解釈されません(コード・フォントになりません)。コード・フォントで同じ機能を実現するには、{@code}タグを使用します。
@param parameter-name description
「パラメータ」セクションに、指定されたparameter-nameの後に指定されたdescriptionを続けてパラメータを追加します。ドキュメンテーション・コメントを記述するときには、descriptionを複数行にわたって記述することもできます。このタグは、メソッド、コンストラクタ、またはクラスのドキュメンテーション・コメント内でのみ有効です。JavadocツールでのDocコメントの記述方法の@paramに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@param)を参照してください。
parameter-nameは、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタの型パラメータの名前になります。山カッコでこのパラメータ名を囲み、型パラメータを使用することを指定します。
クラスの型パラメータの例:
/**
* @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) {
}
@return description
「戻り値」セクションを追加して、descriptionのテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーション・コメントでのみ有効です。JavadocツールでのDocコメントの記述方法の@returnに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return)を参照してください。
@see reference
「関連項目」見出しを追加して、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>タグは常に表示テキストを囲む形で含まれます。
注意: 外部参照クラスは、コマンド行でjavadocコマンドに渡されないクラスです。生成ドキュメント内で外部参照クラスにリンクしている箇所は、外部参照または外部リンクと呼ばれます。たとえば、java.awt packageに対してのみjavadocコマンドを実行した場合、Objectなどのjava.lang内のすべてのクラスが外部参照クラスになります。-linkおよび-linkofflineオプションを使用して、外部参照クラスへリンクします。外部参照クラスのソース・コメントはjavadocコマンドの実行には使用できません。
この例では、@seeタグ(Characterクラス内)が、Stringクラスのequalsメソッドを参照しています。タグには、名前String#equals(Object)とラベルequalsの両方の引数が含まれています。
/** * @see String#equals(Object) equals */
<dl> <dt><b>See Also:</b> <dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a> </dl>
関連項目:
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
前のリストに関するメモ:
@seeタグの検索順序
javadocコマンドは、ソース・ファイル、パッケージ・ファイル、概要ファイルに表示される@seeタグを処理します。後者の2つのファイルでは、完全修飾の名前を@seeタグに指定する必要があります。ソース・ファイルでは、完全修飾の名前、または部分修飾の名前を指定できます。
次に、@seeタグの検索順序を示します。
javadocコマンドは、各クラスについて項目1-3を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にその外側を囲んでいるクラスEを検索した後、Eのスーパークラスを検索してから、Eを囲んでいるクラスを検索します。項目4と5では、javadocコマンドが1つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません(その順序は、個々のコンパイラによって異なります)。項目5では、javadocコマンドは、java.langを検索します。このパッケージは、すべてのプログラムに自動的にインポートされるからです。
javadocコマンドは、完全修飾でないソース・ファイルで@seeタグを見つけると、Javaコンパイラと同じ順序で指定された名前を検索します(ただし、javadocコマンドは、特定の名前空間のあいまいさを検出しません。これは、ソース・コードにこれらのエラーが存在していないことを前提としているためです)。この検索順序は、Java言語仕様で正式に定義されています。javadocコマンドは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてからその名前を検索します。具体的には、次の順序で検索します。
javadocコマンドは、必ずしもサブクラスを検索するとは限りません。また、実行中に他のパッケージのドキュメントが生成される場合でも、他のパッケージを検索しません。たとえば、@seeタグがjava.awt.event.KeyEventクラス内に含まれていて、java.awt package内のある名前を参照していても、そのクラスがインポートしないかぎりjavadocコマンドはそのパッケージを検索しません。
名前が表示される方法
labelを省略すると、package.class.memberが表示されます。一般に、これは現在のクラスおよびパッケージに応じて適切に短縮されます。短縮されるとは、javadocコマンドにより必要最小限の名前のみが表示されるということです。たとえば、String.toUpperCase()メソッドに、同じクラスのメンバーへの参照と他のクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースのみです(次のリストを参照)。パッケージ名を全体的に削除するには、-noqualifierオプションを使用します。
@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 <a href="spec.html">Java Spec</a> // Java Spec
@see "The Java Programming Language" // "The Java Programming Language"
注意: @seeタグを拡張してドキュメント化されないクラスにリンクするには、-linkオプションを使用します。
@serial field-description | include | exclude
デフォルトの直列化可能フィールドのドキュメンテーション・コメントで使用します。クラスの直列化可能なフィールドおよびデータの文書化 (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引数は、直列化された形式ページにクラスまたはパッケージを含めるか除外するかを示します。次のように機能します。
たとえば、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
データの説明値を使用して、直列化された形式でのデータの型と順序をドキュメント化します。このデータには、writeObjectメソッドによって書き込まれる省略可能なデータ、およびExternalizable.writeExternalメソッドによって書き込まれるすべてのデータ(ベース・クラスを含む)が含まれます。
@serialDataタグは、writeObject、readObject、writeExternal、readExternal、writeReplaceおよびreadResolveメソッドのドキュメンテーション・コメントで使用できます。
@serialField field-name field-type field-description
SerializableクラスのserialPersistentFieldsメンバーのObjectStreamFieldコンポーネントをドキュメント化します。ObjectStreamFieldコンポーネントごとに1つの@serialFieldタグを使用します。
@since since-text
生成ドキュメントに、指定されたsince-textの値の「導入されたバージョン」見出しを追加します。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドで有効です。このタグは、特定の変更または機能が、since-textの値によって指定されたソフトウェア・リリース以降、存在していることを意味します。たとえば、@since 1.5です。
Javaプラットフォームのソース・コードの場合、@sinceタグは、JavaプラットフォームAPI仕様のバージョンを示します。ソース・コードがリファレンス実装に追加された時期を示すとは限りません。複数の@sinceタグを使用でき、複数の@authorタグのように扱われます。プログラム要素が複数のAPIで使用される場合、複数のタグを使用できます。
@throws class-name description
@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}
定数の値を表示します。{@value}タグが静的フィールドのドキュメンテーション・コメントで引数なしで使用されている場合、その定数の値を表示します。
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "<script>"
/**
* Evaluates the script starting with {@value #SCRIPT_START}.
*/
public String evalScript(String script) {}
これらの定数の値は「定数フィールド値」 (http://docs.oracle.com/javase/8/docs/api/constant-values.html)にも表示されます
@version version-text
-versionオプションが使用されている場合、生成ドキュメントに「バージョン」小見出しを追加して、指定されたversion-textの値を書き込みます。このタグはこのコードが含まれるソフトウェアの現在のリリース番号を保持するためのものであるのに対し、@sinceタグは、このコードが導入されたリリース番号を保持します。version-textの値には、特別な内部構造はありません。JavadocツールでのDocコメントの記述方法の@versionに関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@version)を参照してください
1つのドキュメンテーション・コメントに複数の@versionタグを含めることができます。必要に応じて、1つの@versionタグに1つのリリース番号を指定することも、複数のリリース番号を指定することもできます。前者の場合は、javadocコマンドによって名前と名前の間にカンマ(,)と空白文字が挿入されます。後者の場合は、テキスト全体が解析されることなく、生成ドキュメントにコピーされます。したがって、カンマではなく、各言語に対応した名前区切り文字を使用する必要があるときに、1行に複数の名前を指定できます。
ここでは、タグを使用できる場所について説明します。次のタグがすべてのドキュメンテーション・コメントで使用できます。@see、@since、@deprecated、{@link}、{@linkplain}および{@docroot}。
概要タグは、概要ページのドキュメンテーション・コメントで使用できるタグです(このドキュメンテーション・コメントは、通常overview.htmlという名前のソース・ファイル内にあります)。他のドキュメンテーション・コメントの場合と同様に、これらのタグは、主説明の後で使用する必要があります。
注意: Java SE 1.2では、概要ドキュメント内の{@link}タグにbugがあります。テキストは正しく表示されますが、リンクが設定されません。現在のところ、{@docRoot}タグは、概要ドキュメント内では機能しません。
概要タグは、次のとおりです。
@see reference || @since since-text || @serialField field-name field-type field-description || @author name-text || @version version-text || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||
パッケージ・タグは、パッケージのドキュメンテーション・コメントで使用できるタグで、ドキュメンテーション・コメントはpackage.htmlまたはpackage-info.javaという名前のソース・ファイル内にあります。ここで使用できる@serialタグは、includeまたはexclude引数を指定したもののみです。
パッケージ・タグは、次のとおりです。
@see reference || @since since-text || @serial field-description | include | exclude || @author name-text || @version version-text || {@linkplain package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||
次に、クラスまたはインタフェースのドキュメンテーション・コメントで使用できるタグを示します。@serialタグは、includeまたはexclude引数を指定して、クラスまたはインタフェースのドキュメンテーション内でのみ使用できます。
@see reference || @since since-text || @deprecated deprecated-text || @serial field-description | include | exclude || @author name-text || @version version-text || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||
クラス・コメントの例:
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.13, 06/08/06
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
これらのタグは、フィールドに表示できます。
@see reference || @since since-text || @deprecated deprecated-text || @serial field-description | include | exclude || @serialField field-name field-type field-description || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} || {@value package.class#field}
フィールド・コメントの例:
/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;
次に、コンストラクタまたはメソッドのドキュメンテーション・コメントで使用できるタグを示します。ただし、@returnはコンストラクタでは使用できず、 {@inheritDoc}には制限があります。
@see reference || @since since-text || @deprecated deprecated-text || @param parameter-name description || @return description || @throws class-name description || @exception class-name description || @serialData data-description || {@link package.class#member label} || {@linkplain package.class#member label} || {@inheritDoc} || {@docRoot}
注意: @serialDataタグは、writeObject、readObject、writeExternal、readExternal、writeReplaceおよびreadResolveメソッドのドキュメンテーション・コメントでのみ使用できます。
メソッド・コメントの例:
/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
...
}
javadocコマンドは、ドックレットを使用して出力を決定します。javadocコマンドは、-docletオプションでカスタム・ドックレットが指定されている場合以外は、デフォルトの標準ドックレットを使用します。javadocコマンドには、任意のドックレットとともに使用できるコマンド行オプションがあります。これらのオプションについては、Javadocオプションで説明します。標準ドックレットでは、この他に、いくつかの追加のコマンド行オプションが提供されます。これらのオプションについては、標準ドックレットのオプションで説明します。どのオプション名も、大文字と小文字が区別されません。ただし、オプションの引数では、大文字と小文字が区別されます。
オプションは次のとおりです。
次のオプションは、すべてのドックレットに使用可能なコアのJavadocオプションです。標準ドックレットでは、ドックレットの他の部分を提供します。-bootclasspath、-breakiterator、-classpath、-doclet、-docletpath、-encoding、-exclude、-extdirs、-help、-locale、-overview、-package、-private、-protected、-public、-quiet、-source、-sourcepath、-subpackagesおよび-verbose。
-overview path/filename
javadocコマンドに対して、path/filename で指定されたソース・ファイルから概要ドキュメント用のテキストを取得し、そのテキストを「概要」ページ(overview-summary.html)に配置するように指定します。path/filenameは、現在のディレクトリからの相対パスです。
filenameの値で任意の名前を使用し、pathで任意の配置先を指定できますが、通常はoverview.htmlという名前を付け、ソース・ツリー内の最上位パッケージ・ディレクトリを含むディレクトリに配置します。この場所に配置すると、パッケージをドキュメント化するときにpathを指定する必要がなくなります。これは、-sourcepathオプションによってこのファイルが指し示されるからです。
たとえば、java.langパッケージのソース・ツリーが/src/classes/java/lang/の場合、概要ファイルを/src/classes/overview.htmlに配置できます
実際の例を参照してください。
path/filenameで指定するファイルについては、概要コメント・ファイルを参照してください。
「概要」ページが作成されるのは、javadocコマンドに複数のパッケージ名を渡した場合のみです。詳細は、HTMLフレームを参照してください。「概要」ページのタイトルは、-doctitleによって設定されます。
-Xdoclint:(all|none|[-]<group>)
このオプションにより、javadocコマンドは生成された出力に含まれるすべてのドキュメント・コメントをチェックします。通常どおり、標準オプション-public、-protected、-packageおよび-privateで生成された出力に含む項目を選択できます。
-Xdoclintが有効になっている場合は、javacコマンドと同様にメッセージで問題がレポートされます。javadocコマンドは、メッセージ、ソース・ファイルのコピーおよびエラーが検出された正確な位置を指すキャレットを出力します。メッセージは、重大度、および生成されたドキュメントがバリデータを使用して実行された場合にエラーが発生する可能性に応じて、警告またはエラーになります。たとえば、不正な参照またはJavadocコメントの欠落は、javadocコマンドが無効なHTMLを生成する原因にならないため、これらの問題は警告としてレポートされます。構文エラーまたはHTML終了タグの欠落は、javadocコマンドが無効なHTMLを生成する原因になるため、これらの問題はエラーとしてレポートされます。
デフォルトでは、-Xdoclintオプションは有効になっています。オプション-Xdoclint:noneで無効にします。
-Xdoclintオプションでレポートされる内容は次のオプションで変更します。
変数groupは次のいずれかの値を持ちます。
-Xdoclintオプションを複数回指定して、複数のカテゴリのエラーと警告をチェックするオプションを有効にできます。または、前のオプションを使用して、複数のエラーおよび警告カテゴリを指定できます。たとえば、次のコマンドのいずれかを使用して、filenameファイル内のHTML、構文およびアクセシビリティの問題をチェックします。
javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility filename javadoc -Xdoclint:html,syntax,accessibility filename
javadocコマンドは、無効な入力の修正を試行せず、レポートのみ行います。
-public
-protected
-package
-private
-help
-doclet class
-docletpath classpathlist
-1.1
-source release
-sourcepath sourcepathlist
複数のパスはコロン(:)で区切ります。
javadocコマンドは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使用して、ドキュメント化されるソース・ファイルの位置のみでなく、それ自体はドキュメント化されないがドキュメント化されるソース・ファイルから継承されたコメントを持つソース・ファイルの位置も確認できます。
-sourcepathオプションを使用できるのは、javadocコマンドにパッケージ名を渡す場合のみです。javadocコマンドに渡されるソース・ファイルは検索されません。ソース・ファイルを特定するには、そのディレクトリに移動するか、「1つ以上のクラスのドキュメント化」に示すように各ファイルの前にパスを含めます。-sourcepathが省略された場合、javadocコマンドは、クラス・パスを使用してソース・ファイルを検索します(-classpathを参照)。デフォルトの-sourcepathは、クラス・パスの値です。-classpathを省略してパッケージ名をjavadocコマンドに渡すと、javadocコマンドは現在のディレクトリ(およびそのサブディレクトリ)からソース・ファイルを検索します。
sourcepathlistには、ドキュメント化するパッケージのソース・ツリーのルート・ディレクトリを設定します。
たとえば、com.mypackageという名前のパッケージをドキュメント化する場合に、そのソース・ファイルが/home/user/src/com/mypackage/*.javaにあるとします。ソース・パスをcom\mypackageが含まれるディレクトリ/home/user/srcに指定してから、次のように、パッケージ名を指定します。
javadoc -sourcepath /home/user/src/ com.mypackage
/home/user/src/com/mypackage
2つのソース・パスを設定するには、次のようにします。
javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage
-classpath classpathlist
複数のパスはコロン(:)で区切ります。
javadocコマンドは、指定されたパス以下のすべてのサブディレクトリを検索します。classpathlistの値を指定するときは、クラス・パスのドキュメントにある指示に従ってください。
-sourcepathが省略された場合、javadocコマンドは-classpathを使用して、ソース・ファイルおよびクラス・ファイルを検索します(後方互換性のため)。ソース・ファイルとクラス・ファイルを別々のパスから検索する必要がある場合は、-sourcepathと-classpathの両方を使用します。
たとえば、com.mypackageをドキュメント化する場合に、そのソース・ファイルがディレクトリ/home/user/src/com/mypackageにあり、このパッケージが/home/user/lib内のライブラリに依存しているとき、次のように指定します。
javadoc -sourcepath /home/user/lib -classpath /home/user/src com.mypackage
javadocコマンドが-classpathを使用してユーザー・クラスを検索する方法についての、拡張機能クラスやブートストラップ・クラスに関連した詳細は、クラスの検索方法 (http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html)を参照してください。
*のベース名を含むクラス・パス要素は、.jarまたは.JARを拡張子に持つディレクトリ内のすべてのファイルのリストを指定するのと同等とみなされます。
たとえば、ディレクトリmydirにa.jarとb.JARが含まれている場合、クラス・パス要素foo/*はA.jar:b.JARに展開されますが、JARファイルの順番は未指定となります。非表示のファイルを含む、指定したディレクトリ内のすべてのJARファイルがリストに含まれます。*からなるクラス・パス・エントリは、現在のディレクトリ内のすべてのJARファイルのリストに展開されます。CLASSPATH環境変数も同様に展開されます。クラス・パスのワイルドカードの展開は、Java Virtual Machine (JVM)の開始前に行われます。Javaプログラムは、System.getenv("CLASSPATH")の呼び出しによってなど、環境を問い合せる場合を除き、展開されていないワイルドカードを参照しません。
-subpackages package1:package2:...
たとえば、次のコマンドは、javaおよびjavax.swingという名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。
javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
-exclude packagename1:packagename2:...
次の例では、java.io、java.util、java.mathなどは組み込まれますが、java.netとjava.langをルートに持つパッケージは除外されます。java.langのサブパッケージであるjava.lang.refが除外される点に注意してください。
javadoc -sourcepath /home/user/src -subpackages java -exclude
java.net:java.lang
-bootclasspath classpathlist
classpathlistパラメータ内のディレクトリは、セミコロン(;)で区切る(Windowsの場合)か、コロン(:)で区切ります(Oracle Solarisの場合)。
-extdirs dirist
-verbose
-quiet
-breakiterator
Java SE 1.5では-breakiterator警告メッセージが削除され、デフォルトの文区切りアルゴリズムは変更されていません。ソース・コードを変更せず、SE 1.4.xでの-breakiteratorオプションの警告を除去していない場合でも、何もする必要はありません。Java SE 1.5.0からは警告は消滅しています。
-locale language_country_variant
注意: -localeオプションは、標準ドックレットが提供するすべてのオプション、またはその他の任意のドックレットが提供するすべてのオプションより前(左側)に指定する必要があります。そうしないと、ナビゲーション・バーが英語で表示されます。このコマンド行オプションのみ、指定する順序に依存します。標準ドックレットのオプションを参照してください。
ロケールを指定すると、指定したロケールのリソース・ファイルがjavadocコマンドによって選択されて、メッセージ(ナビゲーション・バー、リストと表の見出し、ヘルプ・ファイルの目次、stylesheet.cssのコメントなどの文字列)のために使用されます。また、アルファベット順にソートされるリストのソート順、および最初の文の終わりを判断するための文の区切り文字も、指定したロケールによって決まります。-localeオプションは、ドキュメント化されるクラスのソース・ファイル内で指定されているドキュメンテーション・コメントのテキストのロケールを決定するものではありません。
-encoding
-Jflag
Jとflagの間に空白文字はありません。
使用しているjavadocコマンドのバージョンを確認するには-versionオプションを使用します。出力ストリームには標準ドックレットのバージョン番号が含まれます。Javadocコマンドの実行を参照してください。
javadoc -J-version java version "1.7.0_09" Java(TM) SE Runtime Environment (build 1.7.0_09-b05) Java HotSpot(TM) 64-Bit Server VM (build 23.5-b02, mixed mode)
-javafx
getterおよびsetterメソッドに対して明示的に記載されているドキュメント・コメントがない場合、プロパティ・メソッドのドキュメント・コメントがこれらのメソッドに対して生成されたドキュメントに自動的にコピーされます。このオプションは、プロパティのデフォルト値を記述できる新しい@defaultValueタグも追加します。
例:
javadoc -javafx MyClass.java -d testdir
-d directory
たとえば、次の例では、com.mypackageパッケージのドキュメントが生成され、その結果が/user/doc/ディレクトリに保存されます。javadoc -d /user/doc/ com.mypackage
-use
-version
-author
-splitindex
-windowtitle title
-doctitle title
-title title
-header header
-footer footer
-top
-bottom text
-link extdocURL
このディレクトリ内にpackage-listファイルが存在する必要があります(存在しない場合は、-linkofflineオプションを使用します)。javadocコマンドは、package-listファイルからパッケージ名を読み取った後、そのURLでこれらのパッケージにリンクします。javadocコマンドの実行時に、extdocURLの値が、作成された<A HREF>リンク内にコピーされます。したがって、extdocURLはファイルではなくディレクトリへのURLである必要があります。extdocURLに絶対リンクを使用すると、ユーザーのドキュメントを任意のWebサイト上のドキュメントにリンクできます。相対位置へリンクするのみの場合は相対リンクを使用できます。相対リンクを使用する場合、渡す値は宛先ディレクトリから、リンクされているパッケージを含むディレクトリへである必要があります(-dオプションで指定)。絶対リンクを指定する場合、通常、HTTPリンクを使用します。ただし、Webサーバーを持たないファイル・システムにリンクする場合は、ファイル・リンクを使用できます。生成されたドキュメンテーションにアクセスする全員が同じファイル・システムを共有する場合にのみファイル・リンクを使用します。どの場合も、どのオペレーティング・システムでも、URLが絶対または相対のいずれでも、またhttp:またはfile:のいずれでも、URLメモ: Uniform Resource Locators (http://www.ietf.org/rfc/rfc1738.txt)に指定されているとおり、区切り文字としてスラッシュを使用します。
-link http://<host>/<directory>/<directory>/.../<name> -link file://<host>/<directory>/<directory>/.../<name> -link <directory>/<directory>/.../<name>
-linkofflineおよび-linkオプションの違い
次の場合に、-linkオプションを使用します。
外部APIドキュメントへの絶対URLを使用する場合(そのURLに接続し、読取りを行うことがシェルによって許可されていない場合)は-linkofflineオプションを使用します。このような状況は、ファイアウォールの内側からファイアウォールの外側にあるドキュメントにリンクしようとする場合に発生します。
例 1 外部ドキュメントへの絶対リンク
javadoc -link http://docs.oracle.com/javase/8/docs/api/ com.mypackage
例 2 外部ドキュメントへの相対リンク
-linkオプションは、宛先ディレクトリ(docs/spi)からの相対パスです。
注意
-linkオプションを使用すると、コードからは参照されていても、今回のjavadocの実行ではドキュメント化されないクラスにリンクできるようになります。リンクから有効なページに移動できるようにするには、それらのHTMLページがある場所を調べ、その場所をextdocURLに指定する必要があります。これにより、サードパーティのドキュメンテーションがjava.*ドキュメンテーション( http://docs.oracle.com)へリンクすることができます。javadocコマンドで、現在の実行で生成しているドキュメンテーション内のAPIへのリンクのみを作成する場合には、-linkオプションを省略します。-linkオプションを指定しないと、javadocコマンドは外部参照のためのドキュメンテーションへのリンクを作成しません。ドキュメンテーションが存在するのかどうか、またはどこに存在するのかがわからないからです。-linkオプションでは、生成ドキュメンテーション内の複数の場所にリンクを作成できます。ソース・ファイルの処理を参照してください。もう1つの用途は、パッケージ・セットの間にクロスリンクを作成することです。一方のパッケージ・セットに対してjavadocコマンドを実行した後、他方のパッケージ・セットに対してjavadocコマンドを再度実行すると、両セット間に双方向のリンクを作成できます。
クラスの参照方法
表示される外部参照クラスへのリンクの場合(およびそのテキスト・ラベルだけではなく)、クラスは次の方法で参照される必要があります。メソッドの本体でクラスを参照するのみでは十分ではありません。import文、宣言のいずれかで参照する必要があります。次に、クラスjava.io.Fileを参照する方法の例を示します。
すべてのタイプのimport文の場合。ワイルドカードによるインポート、名前による明示的なインポート、またはjava.lang.*に対する自動インポート。
Java SE 1.3.nおよび1.2.nでは、名前による明示的なインポートのみ機能します。ワイルドカードによるimport文も、import java.lang.*の自動インポートも機能しません。
宣言の場合: void mymethod(File f) {}
参照は、メソッド、コンストラクタ、フィールド、クラスまたはインタフェースの戻り型またはパラメータ・タイプ、あるいは実装、拡張またはスロー文にあります。
重要な結果として、-linkオプションを使用しても、この制限のために誤って表示されないリンクが多数発生する可能性があります。テキストはハイパーテキスト・リンクが付けられずに表示されます。リンクが表示する警告から、これらのリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するための最も簡単な方法はそのクラスをインポートすることです。
パッケージ・リスト
-linkオプションには、javadocコマンドによって生成されるpackage-listという名前のファイルが、-linkオプションに指定したURLに存在していることが必要です。package-listファイルは、その場所にあるドキュメント化されたパッケージの名前のリストが入った単純なテキスト・ファイルです。前述の例では、javadocコマンドは、指定したURLでpackage-listという名前のファイルを検索し、パッケージ名を読み取って、そのURLでこれらのパッケージにリンクします。
たとえば、Java SE APIのパッケージ・リストは http://docs.oracle.com/javase/8/docs/api/package-listにあります。
このパッケージ・リストは次のような内容で始まっています。
java.applet java.awt java.awt.color java.awt.datatransfer java.awt.dnd java.awt.event java.awt.font and so on ....
-linkオプションを指定せずにjavadocを実行した場合、外部参照クラスに属する名前を見つけると、その名前をリンクなしで出力します。一方、-linkオプションを指定した場合、javadocコマンドは、指定されたextdocURLの場所にあるpackage-listファイルでそのパッケージ名を検索します。パッケージ名が見つかると、extdocURLが名前の前に付加されます。
すべてのリンクが正しく機能するためには、外部参照のすべてのドキュメントが、指定したURLに存在する必要があります。javadocコマンドは、指定されたpackage-listが存在するかどうかのみをチェックし、これらのページが存在するかどうかはチェックしません。
複数のリンク
複数の-linkオプションを指定すると、任意の数の外部生成ドキュメントへのリンクを作成できます。Javadoc 1.2には、複数の-linkオプションを指定できないという既知のbugがあります。これはJavadoc 1.2.2で修正されました。リンクする外部ドキュメントごとに、次のように別々のリンク・オプションを指定します。javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn com.mypackage extdocURL1、extdocURL2、... extdocURLnは、それぞれ外部ドキュメントのルートを指し、各ルートには、package-listという名前のファイルが入っています。
クロスリンク
以前に作成された複数のドキュメントをクロスリンクする場合、ブートストラップが必要になることがあります。どのドキュメントについてもpackage-listが存在していない場合は、最初のドキュメントに対してjavadocコマンドを実行する時点で、2番目のドキュメントのpackage-listはまだ存在していません。したがって、外部リンクを作成するには、2番目のドキュメントを生成した後で、最初のドキュメントを生成しなおす必要があります。
この場合、最初のドキュメント生成の目的は、package-listを作成することです(パッケージ名を把握している場合は手動で作成してもかまいません)。次に、2番目のドキュメントとその外部リンクを生成します。必要な外部のpackage-listファイルが存在しない場合は、javadocコマンドから警告が出力されます。
-linkoffline extdocURL packagelistLoc
指定したjavadocコマンドの実行で、複数の-linkオプションを指定できます。Javadoc 1.2.2より前では、-linkfileオプションは1回しか指定できませんでした。
外部ドキュメントへの絶対リンク
http://docs.oracle.com/javase/8/docs/api/index.htmlに示すような、java.lang、 java.ioおよびその他のJava SEパッケージにリンクする必要がある場合があります。
ただし、シェルにはWebアクセス権がありません。この場合、次を行います。
次のコマンドは、Java SEプラットフォーム・パッケージへのリンクを持つcom.mypackageパッケージのドキュメントを生成します。生成ドキュメントには、たとえばクラスtrees内のObjectクラスへのリンクが含まれています。-sourcepathなど、他の必要なオプションは表示されません。
javadoc -linkoffline http://docs.oracle.com/javase/8/docs/api/ . com.mypackage
外部ドキュメントへの相対リンク
-linkofflineを相対パスとともに使用することはあまりありません。理由は単純で、通常は-linkで間に合うからです。-linkofflineオプションを使用する場合、通常、package-listファイルはローカルで、相対リンクを使用する場合はリンク先のファイルもローカルなので、通常は-linkofflineオプションの2つの引数に、異なるパスを指定する必要はありません。2つの引数が同一の場合、-linkオプションを使用できます。
package-listファイルの手動での作成
package-listファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルのコピーを手動で作成し、packagelistLocでそのパスを指定することができます。com.apipackageが最初に生成された時点でcom.spipackageのパッケージ・リストが存在しないという前出のケースが一例として挙げられます。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。また、package-listファイルが生成されないJavadoc 1.0または1.1で生成されたパッケージ用にpackage-listファイルを作成する場合にも、この方法が使用できます。同様に、2つの企業が未公開のpackage-listファイルを共有できるため、クロスリンクを設定したドキュメントを同時にリリースすることも可能になります。
複数ドキュメントへのリンク
参照先の生成ドキュメントごとに1回、-linkofflineオプションを含めることができます。
javadoc -linkoffline extdocURL1 packagelistLoc1 -linkoffline extdocURL2 packagelistLoc2 ...
ドキュメントの更新
プロジェクトに何十または何百のパッケージが含まれる場合にも、-linkofflineオプションを使用できます。ソース・ツリー全体ですでにjavadocコマンドを実行したことがある場合、ドキュメンテーション・コメントにわずかな変更を迅速に加え、ソース・ツリーの一部でjavadocコマンドを再実行することができます。2回目の実行は、ドキュメンテーション・コメントを変更し、宣言は変更しない場合にのみ正しく処理されることに注意してください。ソース・コードに対して宣言を追加、削除、または変更した場合は、索引、パッケージ・ツリー、継承されるメンバーのリスト、「使用」ページなどの場所で、リンクが壊れることがあります。
まず、この新しい小規模な実行で使用する、新しい生成先ディレクトリ(updateなど)を作成します。この例では、元の生成先ディレクトリの名前はhtmlです。最も単純な例では、htmlディレクトリの親ディレクトリに移動します。-linkofflineオプションの第1引数にカレント・ディレクトリ(.)を設定し、第2引数にpackage-listが検索されるhtmlへの相対パスを設定し、更新するパッケージのパッケージ名のみを渡します。
javadoc -d update -linkoffline . html com.mypackage
javadocコマンドの終了後、update/com/package内の生成されたクラスのページをコピーし(概要や索引は除く)、html/com/package内の元のファイルに上書きします。
-linksource
このオプションは、-public、-package、-protectedおよび-privateの各オプションとは関係なく、非公開のクラス、フィールド、非公開のメソッドの本体をはじめとする組み込まれたソース・ファイル内のすべての非公開実装の詳細を公開します。-privateオプションもあわせて指定しないかぎり、非公開のクラスやインタフェースの一部には、リンクを介してアクセスできないことがあります。
各リンクは、その宣言内の識別子名の上に作成されます。たとえば、Buttonクラスのソース・コードへのリンクは、Buttonという語の上に作成されます。
public class Button extends Component implements Accessible
public String getLabel()
-group groupheading packagepattern:packagepattern
-groupオプションを指定しない場合は、見出しPackagesおよび適切な小見出しを持つ1つのグループに配置されます。小見出しにすべてのドキュメント化されるパッケージ(すべてのグループ)が含まれるわけではない場合、残りのパッケージは「その他のパッケージ」というサブ見出しを持つ独立したグループに入れられます。
たとえば、次のjavadocコマンドでは、3つのドキュメント化されたパッケージが「コア」、「拡張」および「その他のパッケージ」に分けられます。java.lang*では、最後のドット(.)を指定していません。java.lang.*のようにドットを入れると、 java.langパッケージは除外されることになります。
javadoc -group "Core Packages" "java.lang*:java.util"
-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new
java.lang
java.lang.reflect
java.util
拡張機能パッケージ
javax.servlet
Other Packages
java.new
-nodeprecated
-nodeprecatedlist
-nosince
-notree
-noindex
-nohelp
-nonavbar
-helpfile path\filename
javadoc -helpfile /home/user/myhelp.html java.awt.
-stylesheet path/filename
javadoc -stylesheet file /home/user/mystylesheet.css com.mypackage
-serialwarn
-charset name
たとえば、javadoc -charset "iso-8859-1" mypackageは次の行を生成された各ページのヘッダーに挿入します。
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
およびオプションも参照してください。
-docencoding name
-docencodingオプションを省略し、-encodingオプションを使用すると、生成されたHTMLファイルの暗号化は-encodingオプションで特定されます。例: javadoc -docencoding "iso-8859-1" mypackageおよびオプションも参照してください。
-keywords
<META NAME="keywords" CONTENT="java.lang.String class"> <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER"> <META NAME="keywords" CONTENT="length()"> <META NAME="keywords" CONTENT="charAt()">
-tag tagname:Xaoptcmf:"taghead"
タグの配置: Xaoptcmf引数により、ソース・コード内でタグを配置できる場所が決まり、タグを無効にできるかどうか(Xを使用して)が決まります。タグの配置位置を制限しない場合はaを指定します。それ以外の文字の組合せも可能です。
X (タグの無効化)
a (すべて)
o (概要)
p (パッケージ)
t (タイプ、つまりクラスとインタフェース)
c (コンストラクタ)
m (メソッド)
f (フィールド)
シングル・タグの例: ソース・コード内の任意の位置で使用できるタグのタグ・オプションの例を示します。-tag todo:a:"To Do:"
@todoタグをコンストラクタ、メソッドおよびフィールドとのみ使用する場合、-tag todo:cmf:"To Do:"を使用します。
最後のコロン(:)は、パラメータ区切り文字ではなく、見出しテキストの一部になっています。@todoタグを含む、ソース・コード用のいずれかのタグ・オプションを使用します。たとえば、@todo The documentation for this method needs workです。
タグ名内のコロン: タグ名内でコロンを使用する場合はバックスラッシュを使用してエスケープします。次のドキュメンテーション・コメントには、-tag ejb\\:bean:a:"EJB Bean:"オプションを使用します。
/** * @ejb:bean */
タグの順序: -tagおよび-tagletオプションの順序によって、タグの出力順が決まります。カスタム・タグと標準タグを組み合せて使用することもできます。標準タグのタグ・オプションは、順序を決定するためだけのプレースホルダです。標準タグの名前のみを取ります。標準タグの小見出しは変更できません。これを次の例に示します。-tagオプションを指定しないと、-tagletオプションの位置により、順序が決まります。タグが両方とも存在する場合、コマンド行の最後にある方がその順序を決定します。これは、タグやタグレットがコマンド行に指定された順番に処理されるためです。たとえば、-tagletおよび-tagオプションが名前todo値を持つ場合、コマンド行に最後に指定されたものが順序を決定します。
タグの完全セットの例: この例では、出力のParametersとThrowsの間にTo Doを挿入します。Xを使用して、@exampleタグが、ソース・コード内の今回の実行では出力されないタグであることも指定します。@argfileタグを使用する場合は、次のように、引数ファイル内の別々の行にタグを配置できます(行の継続を示す文字は不要)。
-tag param -tag return -tag todo:a:"To Do:" -tag throws -tag see -tag example:X
標準タグは、最初、デフォルトの順序でリスト内に内部的に格納されます。-tagオプションを使用すると、それらのタグはこのリストに追加されます。標準タグは、デフォルトの位置から移動されます。そのため、標準タグの-tagオプションを省略すると、それはデフォルトの位置に配置されたままになります。
競合の回避: 固有の名前空間を作成する場合、パッケージに使用されているcom.mycompany.todoのようなドットで区切りの命名規則を使用できます。Oracleは、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Oracleが定義する同じ名前のタグの動作をオーバーライドします。@todoという名前のタグまたはタグレットをユーザーが作成した場合、その後にOracleが同じ名前の標準タグを作成しても、そのタグまたはタグレットは常にユーザーが定義したのと同じ動作を保持します。
注釈vs. Javadocタグ: 一般に、追加する必要のあるマークアップが、ドキュメントに影響を与えたりドキュメントを生成したりするためのものである場合、そのマークアップはJavadocタグにします。それ以外の場合は注釈にします。JavadocツールでのDocコメントの記述方法のカスタム・タグと注釈に関する項 (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#annotations)を参照してください。
-tagletオプションを使用して、より複雑なブロック・タグやカスタム・インライン・タグも作成できます。
-taglet class
タグレットは、ブロックタグまたはインライン・タグで便利です。タグレットは任意の数の引数をとることができます。また、テキストを太字にする、箇条書きを作成する、テキストをファイルに書き出す、その他のプロセスを開始するなどのカスタム動作を実装できます。タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガーするなどの副作用は得られます。タグレットへのパスを指定するには、-tagletpathオプションを使用します。次に、生成されるページのParametersとThrowsの間にTo Doタグレットを挿入する例を示します。または、-tagletオプションをその-tagオプションのかわりに使用することができますが、読み取りが困難になる可能性があります。
-taglet com.sun.tools.doclets.ToDoTaglet -tagletpath /home/taglets -tag return -tag param -tag todo -tag throws -tag see
-tagletpath tagletpathlist
-docfilesubdirs
-excludedocfilessubdir name1:name2
-noqualifier all | packagename1:packagename2...
次の例では、すべてのパッケージ修飾子を省略します。-noqualifier all
次の例では、java.langおよびjava.ioパッケージ修飾子を省略します: -noqualifier java.lang:java.io。
次の例では、javaで始まるパッケージ修飾子およびcom.sunサブパッケージを省略しますが、javaxは省略しません。-noqualifier java.*:com.sun.*
パッケージ修飾子が前述の動作に従って表示される場合、名前は適切に短縮されます。「名前が表示される方法」を参照してください。このルールは、-noqualifierオプションを使用するかどうかにかかわらず有効です。
-notimestamp
-nocomment
-sourcetab tablength
javadocコマンドを短くしたり簡潔にしたりするために、javadocコマンドに対する引数(-Jオプションを除く)が入った1つ以上のファイルを指定することができます。このことを利用すれば、どのオペレーティング・システム上でも、任意の長さのjavadocコマンドを作成できます。
引数ファイルには、javacのオプションとソース・ファイル名を自由に組み合せて記述できます。ファイル内の各引数は、スペースまたは改行で区切ります。ファイル名に埋め込まれた空白がある場合、ファイル名全体を二重引用符で囲みます。
引数ファイル内のファイル名は、引数ファイルの位置ではなく、現在のディレクトリに相対的となります。これらのリストでは、ワイルドカード(*)は使用できません。たとえば、*.javaとは指定できません。アットマーク(@)を使用して、ファイルを再帰的に解釈することはできません。また、-Jオプションもサポートされていません。このオプションは起動ツールに渡されますが、起動ツールでは引数ファイルをサポートしていないからです。
javadocを実行するときに、各引数ファイルのパスとファイル名の先頭に@文字を付けて渡します。javadocコマンドは、アットマーク(@)文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。
例 1 単一の引数ファイル
例 2 2つの引数ファイル
次の内容を含む、optionsという名前のファイルを作成します。
-d docs-filelist -use -splitindex -windowtitle 'Java SE 7 API Specification' -doctitle 'Java SE 7 API Specification' -header '<b>Java(TM) SE 7</b>' -bottom 'Copyright © 1993-2011 Oracle and/or its affiliates. All rights reserved.' -group "Core Packages" "java.*" -overview /java/pubs/ws/1.7.0/src/share/classes/overview-core.html -sourcepath /java/pubs/ws/1.7.0/src/share/classes
com.mypackage1 com.mypackage2 com.mypackage3
javadoc @options @packages
例 3 パスを使用した引数ファイル
javadoc @path1/options @path2/packages
例 4 オプション引数
<font size="-1">
<a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved. <br/>
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.</font>
-bottomオプションを引数ファイルの最初に含めて、次のようにjavadocコマンドを実行することもできます。javadoc @bottom @packages
javadocコマンドのリリース番号はjavadoc -J-versionオプションで特定できます。出力ストリームには標準ドックレットのリリース番号が含まれます。-quietオプションで無効にできます。
Java言語で記述されたプログラムからjavadocコマンドを起動するには公開プログラマティック・インタフェースを使用します。このインタフェースはcom.sun.tools.javadoc.Mainにあります(またjavadocコマンドは再入可能です)。詳細は、標準ドックレット (http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/standard-doclet.html#runningprogrammatically)を参照してください。
次の手順では、標準HTMLドックレットを呼び出します。カスタム・ドックレットを呼び出すには、-docletおよび-docletpathオプションを使用しますドックレットの概要 (http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html)を参照してください
javadocコマンドは、パッケージ全体に対して実行することも、個々のソース・ファイルに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。
次の例では、ソース・ファイルは/home/src/java/awt/*.javaにあります。生成先ディレクトリは/home/htmlです。
1つ以上のパッケージのドキュメント化
パッケージをドキュメント化するには、そのパッケージのソース・ファイルを、そのパッケージと同じ名前のディレクトリ内に格納する必要があります。
パッケージ名が(java.awt.colorのようにドットで区切られた)複数の識別子から構成されている場合、後続の各識別子が下位のサブディレクトリ(ava/awt/colorなど)に対応している必要があります。
1つのパッケージのための複数のソース・ファイルを、異なる場所にあるそのような2つのディレクトリ・ツリーに分けて格納することもできます。ただし、その場合は-sourcepathによってその両方の場所を指定する必要があります。たとえば、src1/java/awt/colorとsrc2/java/awt/color。
ディレクトリの変更(cdコマンドを使用)または-sourcepathオプションにより、javadocコマンドを実行できます。次の例で両方の選択肢を示します。
例 1 1つ以上のパッケージから再帰的に実行
javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude
例 2 ルートへの移動および明示的なパッケージの実行
cd /home/src/ javadoc -d /home/html java.awt java.awt.event
例 3 1つのツリーの明示的なパッケージの任意のディレクトリから実行
javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
例 4 複数のツリーの明示的なパッケージの任意のディレクトリから実行
javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event
1つ以上のクラスのドキュメント化
また、1つ以上のソース・ファイルを渡して、javadocコマンドを実行することもできます。javadocは、次の2つの方法のいずれかで実行できます。1つはディレクトリを変更する方法(cdを使用)、もう1つはソース・ファイルへのパスを完全に指定する方法です。相対パスは、現在のディレクトリを起点とします。ソース・ファイルを渡すときは、-sourcepathオプションは無視されます。アスタリスク(*)のようなコマンド行ワイルドカードを使用すると、クラスのグループを指定できます。
例 1 ソース・ディレクトリに変更
この例では、ButtonクラスとCanvasクラス、および名前がGraphicsで始まるクラスについて、HTML形式のドキュメントが生成されます。パッケージ名ではなくソース・ファイルがjavadocコマンドに引数として渡されているので、ドキュメントは、クラスのリストとメイン・ページという2つのフレームを持つことになります。
cd /home/src/java/awt javadoc -d /home/html Button.java Canvas.java Graphics*.java
例 2 パッケージのルート・ディレクトリに変更
cd /home/src/ javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
例 3 任意のディレクトリからのファイルのドキュメント化
javadoc -d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java
パッケージおよびクラスのドキュメント化
パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に、前述の2つの例を組み合せた例を示します。-sourcepathオプションは、パッケージへのパスに対しては使用できますが、個々のクラスへのパスに対しては使用できません。
javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java
次のコマンド行およびmakefileバージョンのjavadocコマンドをJavaプラットフォームAPIで実行します。Java SE 1.2で約1500個のpublicおよびprotectedクラスのドキュメントを生成するには、180MBのメモリーを使用します。どちらの例もオプションの引数で絶対パスが使用されているため、任意のディレクトリから同じjavadocコマンドを実行できます。
コマンド行の例
次のコマンドは、一部のシェルに対して長すぎる可能性があります。この制限を回避するには、コマンド行引数ファイルを使用します。または、シェル・スクリプトを記述します。
この例では、packagesは処理するパッケージを含む名前で、java.applet java.langなどです。各オプションの、一重引用符で囲まれた引数の内側には、改行文字を挿入できません。たとえば、この例をコピー・アンド・ペーストする場合は、-bottomオプションから改行文字を削除してください。
javadoc -sourcepath /java/jdk/src/share/classes \ -overview /java/jdk/src/share/classes/overview.html \ -d /java/jdk/build/api \ -use \ -splitIndex \ -windowtitle 'Java Platform, Standard Edition 7 API Specification' \ -doctitle 'Java Platform, Standard Edition 7 API Specification' \ -header '<b>Java(TM) SE 7</b>' \ -bottom '<font size="-1"> <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/> Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/> Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.</font>' \ -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \ -group "Extension Packages" "javax.*" \ -J-Xmx180m \ @packages
プログラマティック・インタフェース
Javadoc Access APIでは、新しいプロセスを実行しなくても、JavadocツールをJavaアプリケーションから直接起動できます。
たとえば、次の文はコマンドjavadoc -d /home/html -sourcepath /home/src -subpackages java -exclude java.net:java.lang com.exampleと同等です。
import javax.tools.DocumentationTool;
import javax.tools.ToolProvider;
public class JavaAccessSample{
public static void main(String[] args){
DocumentationTool javadoc = ToolProvider.getSystemDocumentationTool();
int rc = javadoc.run( null, null, null,
"-d", "/home/html",
"-sourcepath", "home/src",
"-subpackages", "java",
"-exclude", "java.net:java.lang",
"com.example");
}
}
runメソッドの最初の3つの引数は、入力、標準出力、および標準エラー・ストリームを指定します。NullはSystem.in、System.outおよびSystem.errそれぞれのデフォルト値です。
ここでは、GNU makefileの例を示します。makefileの引数は、一重引用符で囲みます。Windows makefileの例については、Javadoc FAQのmakefilesのセクション (http://www.oracle.com/technetwork/java/javase/documentation/index-137483.html#makefiles)を参照してください
javadoc -sourcepath $(SRCDIR) \ /* Sets path for source files */
-overview $(SRCDIR)/overview.html \ /* Sets file for overview text */
-d /java/jdk/build/api \ /* Sets destination directory */
-use \ /* Adds "Use" files */
-splitIndex \ /* Splits index A-Z */
-windowtitle $(WINDOWTITLE) \ /* Adds a window title */
-doctitle $(DOCTITLE) \ /* Adds a doc title */
-header $(HEADER) \ /* Adds running header text */
-bottom $(BOTTOM) \ /* Adds text at bottom */
-group $(GROUPCORE) \ /* 1st subhead on overview page */
-group $(GROUPEXT) \ /* 2nd subhead on overview page */
-J-Xmx180m \ /* Sets memory to 180MB */
java.lang java.lang.reflect \ /* Sets packages to document */
java.util java.io java.net \
java.applet
WINDOWTITLE = 'Java(TM) SE 7 API Specification'
DOCTITLE = 'Java(TM) Platform Standard Edition 7 API Specification'
HEADER = '<b>Java(TM) SE 7</font>'
BOTTOM = '<font size="-1">
<a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
GROUPEXT = '"Extension Packages" "javax.*"'
SRCDIR = '/java/jdk/1.7.0/src/share/classes'
エラーおよび警告メッセージには、ファイル名と宣言行(ドキュメンテーション・コメント内の特定の行ではない)の行番号が含まれます。
たとえば、メッセージ「エラー: Class1.javaを読み込めません」は、javadocコマンドがClass1.javaを現在のディレクトリにロードしようとしていることを意味します。クラス名はそのパス(絶対または相対)で表示されます。
CLASSPATH
Windowsの例: .;C:\classes;C:\home\java\classes
Oracle Solarisの例: .:/home/classes:/usr/local/java/classes