Java ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている JavadocTM の例は、Microsoft Windows の場合のものです。
@tag
)
-option
)
javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages
pkg1:pkg2:...] [ @argfiles ]
引数を指定する順序は任意です。Javadoc ツールでの、処理対象の
.java
ファイルを決定する方法の詳細については、「ソースファイルの処理」を参照してください。
options
- このドキュメントで説明されているコマンド行オプションです。Javadoc オプションの標準的な使用法については、「使用例」を参照してください。
packagenames
- スペースで区切られた一連のパッケージ名です。たとえば、
java.lang java.lang.reflect java.awt
のように指定します。ドキュメント化するパッケージを個別に指定する必要があります。ワイルドカードは使用不可です。再帰的処理のためには、-subpackages を使用します。Javadoc ツールは、-sourcepath
を使ってこれらのパッケージ名を検索します。「1 つ以上のパッケージのドキュメント化」の例を参照してください。sourcefilenames
- スペースで区切られた一連のソースファイル名です。 各ファイルは、パスで始まります。アスタリスク (*) などのワイルドカードを含めることができます。Javadoc ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、その拡張子を除いた名前が実際に有効なクラス名であるすべてのファイルです (「Identifiers」を参照)。したがって、ハイフンを含む名前 (
X-Buffer
など) や、その他の無効な文字を含む名前を付けることによって、それらのファイルをドキュメント化の対象から除外できます。これは、テスト用のファイルや、テンプレートから生成されたファイルの場合に便利です。ソースファイル名の前に指定したパスによって、javadoc がそのファイルを検索する場所が決まります。Javadoc ツールは、これらのソースファイル名を検索するときに-sourcepath
は使いません。相対パスは、現在のディレクトリからの相対パスです。Button.java
を渡すことは、./Button.java
を渡すことと同じです。ソースファイル名をフルパスで指定すると、/home/src/java/awt/Graphics*.java
のようになります。「1 つ以上のクラスのドキュメント化」の例を参照してください。また、「パッケージとクラスのドキュメント化」の例のように、パッケージ名とソースファイル名を混在させることもできます。-subpackages
pkg1:pkg2:...- ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。パッケージ名またはソースファイル名を指定する必要はありません。
@argfiles
- Javadoc オプション、パッケージ名、およびソースファイル名を任意の順序で並べたリストが含まれる 1 つ以上のファイルです。このファイルの中では、ワイルドカード (*) および
-J
オプションは指定できません。
JavadocTM ツールは、一連の Java ソースファイルにある宣言およびドキュメンテーションコメントを解析し、デフォルトでは public クラス、protected クラス、入れ子にされたクラス (匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連の HTML ページを生成します。また、API (アプリケーションプログラミングインタフェース) ドキュメントの生成や、一連のソースファイルの実装ドキュメントの生成に使用できます。Javadoc ツールは、パッケージ全体、個々のソースファイル、またはその両方に対して実行できます。javadoc ツールをパッケージ全体に対して実行する場合は、最上位ディレクトリから再帰的にたどるために
-subpackages
を使用するか、パッケージ名の明示的なリストを渡します。個々ソースファイルに対して javadoc を実行する場合は、一連のソース (.java
) ファイル名を渡します。具体的な例は、このドキュメントの最後に紹介します。次に、Javadoc によるソースファイルの処理について説明します。ソースファイルの処理
Javadoc ツールは、末尾に.java
の付いたファイル以外に、ソースファイルで説明する他のファイルも処理します。個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、どの.java
ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソースファイル名を明示的に指定しなくても、Javadoc ツールは 3 つの方法で実行できます。この方法は、(1) パッケージ名を渡す、(2)-subpackages
を使用する、(3) ソースファイル名にワイルドカードを使用する (*.java
) という方法です。これらの方法を使用する場合、Javadoc ツールは、.java
ファイルが次のすべての要件を満たしている場合にかぎり、このファイルを処理します。
- 名前から
.java
の接尾辞を取り除くと、実際に有効なクラス名になっている (有効な文字については、「Identifiers」を参照)- ソースツリーのルートから相対的なディレクトリパスが、区切り文字をドットに変換すると、実際に有効なパッケージ名になっている
- パッケージ文には有効なパッケージ名が含まれる (前項目で指定)
リンクの処理 - Javadoc ツールは、処理の実行中に、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、自動的に相互参照リンクを追加します。このようなリンクは、次のような場所に追加されます。
コマンド行で指定しなかったクラスについての既存のテキスト (別に生成したテキスト) に対してハイパーリンクを追加するには、
- 宣言 (戻り値の型、引数の型、フィールドの型)
@see
タグから生成された「関連項目」セクション{@link}
タグから生成されたインラインテキスト@throws
タグから生成された例外の名前- "インタフェースのメンバーに対する「定義」リンクと、クラスのメンバーに対する「オーバーライド」リンク
- パッケージ、クラス、およびメンバーを列挙している概要テーブル
- パッケージおよびクラスの継承ツリー
- 索引
-link
および-linkoffline
オプションを利用できます。その他の処理についての詳細 - Javadoc ツールは、実行するたびに 1 つの完全なドキュメントを作成します。ドキュメントを追加生成することはできません。つまり、Javadoc ツールの以前の実行結果を修正したり、その内容を直接組み入れたりすることはできません。ただし、前述のように、以前の実行結果に対してリンクを追加することはできます。
実装上の理由から、Javadoc ツールは、処理を実行するために java コンパイラを必要とし、java コンパイラに依存しています。Javadoc ツールは
javac
の一部を呼び出すことにより、宣言をコンパイルし、メンバーの実装は無視します。Javadoc ツールは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、その情報から HTML を生成します。さらに、Javadoc ツールは、ソースコードのドキュメンテーションコメントから、ユーザーの提供したドキュメントも取得します。Javadoc ツールは、メソッド本体のない純粋なスタブファイルである
.java
ソースファイルに対しても、実行することができます。したがって、API の作成時には、実装を記述する前の設計の早い段階で、ドキュメンテーションコメントを記述して javadoc ツールを実行できます。コンパイラに依存することによって、HTML 出力は、実際の実装に正確に対応します。実際の実装は、明示的なソースコードにではなく、暗黙のソースコードに依存する場合があります。たとえば、Javadoc ツールは、
.class
ファイル内に存在するが、ソースコード内には存在しないデフォルトコンストラクタ (Java 言語仕様のセクション 8.6.7) をドキュメント化します。通常、Javadoc ツールでは、ソースファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。このため、デバッグやトラブルシューティングを完了する前にドキュメントを生成できます。たとえば、Java 言語仕様によると、抽象メソッドを含むクラスは、それ自体抽象として宣言されなければなりません。このエラーを検出すると、javac コンパイラは停止しますが、Javadoc ツールは警告を出さずに処理を続行します。Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。
Javadoc ツールは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、Javadoc ツールは、ブートストラップクラス、拡張機能、またはユーザークラスにかかわらず、すべての参照クラスを検索できなければなりません。詳細は、「クラスの検索方法」を参照してください。通常、作成するクラスは、拡張機能としてロードするか、Javadoc ツールのクラスパス内に置く必要があります。
Javadoc のドックレット
Javadoc ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。Javadoc ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み」ドックレットがあります。標準ドックレットは、HTML 形式の API ドキュメントを生成します。標準ドックレットを修正またはサブクラス化することや、HTML、XML、MIF、RTF などの好みの出力形式を生成する独自のドックレットを記述することも可能です。ドックレットとその使用法については、次の項目を参照してください。 -doclet コマンド行オプションでカスタムドックレットが指定されていない場合、Javadoc ツールは、デフォルトの標準ドックレットを使用します。javadoc ツールには、使用されているドックレットに関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらのほかに、いくつかのコマンド行オプションが追加されます。どちらのオプションについても、このあとの「オプション」で説明します。関連ドキュメントおよびドックレット
- Javadoc に施された拡張機能 - Javadoc 1.4 で追加された改良点の詳細
- Javadoc FAQ - 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法
- How to Write Doc Comments for Javadoc - ドキュメンテーションコメントの記述方法に関する Sun の規約
- Requirements for Writing API Specifications - Java 2 プラットフォーム仕様を記述する際に使用された標準要件この情報は、ソースファイルのドキュメンテーションコメント形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも役立ちます。検証可能なアサーションを満たすパッケージ、クラス、インタフェース、フィールド、およびメソッドについての要件を定めています。
- ドキュメンテーションコメントの仕様 - ドキュメンテーションコメントのオリジナル仕様については、『Java Language Specification』 (James Gosling、Bill Joy、Guy Steele 共著) の初版の第 18 章「Documentation Comments」を参照してください。この章は、第 2 版では削除されました。
- DocCheck ドックレット - ソースファイル内のドキュメンテーションコメントをチェックし、検出されたエラーや不正のレポートを生成します。Sun Doc Check ユーティリティーの一部です。
- MIF ドックレット - MIF、FrameMaker、PDF の書式で API ドキュメントを自動生成します。MIF は Adobe FrameMaker の交換書式です。
用語
「ドキュメンテーションコメント」、「doc コメント」、「主説明」、「タグ」、「ブロックタグ」、および「インラインタグ」の用語については、「ドキュメンテーションコメント」で説明します以下のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。
- 生成ドキュメント (generated document)
- javadoc ツールが Java ソースコード内のドキュメンテーションコメントから生成したドキュメントのことです。デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。
- name
- Java 言語で書かれたプログラム要素の名前、つまりパッケージ、クラス、インタフェース、フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、
java.lang.String.equals(java.lang.Object)
のように完全修飾することも、equals(Object)
のように部分修飾することもできます。- ドキュメント化されるクラス (documented classes)
- javadoc ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。ドキュメント化するには、ソースファイルが使用可能でなければならず、ソースファイル名またはパッケージ名を javadoc コマンドに渡され、アクセス修飾子 (public、protected、package-private または private) によってフィルタ処理されないようにしなければなりません。ドキュメント化されるクラスは、javadoc ツールの出力に組み込まれるクラス、つまり「包含クラス」とも呼ばれます。
- 包含クラス (included classes)
- ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。「ドキュメント化されるクラス」と同じ。
- 除外クラス (excluded classes)
- ツールの実行によって詳細なドキュメントが生成されないクラスおよびインタフェースのことです。
- 参照クラス (referenced classes)
- ドキュメント化されるクラスおよびインタフェースの定義 (実装) またはドキュメンテーションコメントの中で明示的に参照されているクラスおよびインタフェースのことです。参照の例としては、戻り値の型、パラメータの型、キャストの型、拡張されたクラス、実装されたインタフェース、インポートされたクラス、メソッド本体で使用されるクラス、@see、{@link}、{@linkplain}、{@inheritDoc} タグなどがあります。この定義は 1.3 から変更されています。javadoc ツールを実行するときは、Javadoc のブートクラスパスおよびクラスパス内にあるすべての参照クラスをメモリーにロードする必要があります。参照クラスが見つからない場合は、「クラスが見つかりません」という警告が表示されます。Javadoc ツールは、クラスの存在とそのメンバーの完全指定の名前を判別するのに必要なすべての情報を、.class ファイルから引き出すことができます。
- 外部参照クラス (external referenced classes)
- 参照クラスのうち、javadoc ツールの実行中にドキュメントが生成されないクラスのことです。つまり、これらのクラスは、コマンド行で Javadoc ツールに渡されていません。生成ドキュメント内でこれらのクラスにリンクしている箇所は、「外部参照」または「外部リンク」と呼ばれます。たとえば、
java.awt
パッケージに対してだけ Javadoc ツールを実行した場合、Object
などのjava.lang
内のすべてのクラスが外部参照クラスになります。外部参照クラスにリンクするには、-link
および-linkoffline
オプションを使用します。外部参照クラスには、通常そのソースコメントを javadoc ツールの実行で利用できないという重要な特徴があります。この場合、それらのコメントを継承することはできません。
Javadoc ツールは、4 種類の異なるソースファイルから出力結果を生成します。そのファイルは、クラスの Java 言語ソースファイル (.java
)、パッケージコメントファイル、概要コメントファイル、およびその他の処理されないファイルです。また、ドキュメント化しないがソースツリーに存在する場合があるテストファイルやテンプレートファイルについても説明します。クラスソースコードファイル
それぞれのクラスまたはインタフェース、およびそのメンバーは、独自のドキュメンテーションコメントを持つことができ、それを.java
ファイル内に保持します。ドキュメンテーションコメントの詳細は、「ドキュメンテーションコメント」を参照してください。パッケージコメントファイル
それぞれのパッケージは、独自のドキュメンテーションコメントを持つことができ、それを専用の「ソース」ファイルに保持します。その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、そのパッケージ全体に当てはまるドキュメントを記述します。パッケージコメントファイルを作成する場合、コメントの格納先として、次の 2 つのファイルのいずれかを選択できます。
各パッケージは、単一の
package-info.java
- パッケージ宣言、パッケージ注釈、パッケージコメント、および Javadoc タグを格納できます。このファイルは JDK 5.0 で導入されたものであり、package.html よりも推奨されています。package.html
- 格納できるのはパッケージコメントと Javadoc タグだけです。パッケージ注釈は格納できません。package.html
ファイル、単一のpackage-info.java
ファイルのいずれかを持つことができますが、両方を持つことはできません。このどちらかのファイルを.java
ファイルとともに、ソースツリー内のそのパッケージのディレクトリ内に配置してください。
package-info.java
- このファイルには、次の構造のパッケージコメントを格納できます。コメントはパッケージ宣言の前に配置します。File:
java/applet/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
- このファイルには、次の構造のパッケージコメントを格納できます。 コメントは<body>
要素内に配置します。File:
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>これは単なる通常の HTML ファイルであり、パッケージ宣言を含んでいない点に注意してください。パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に HTML で記述されています。それは、このドキュメンテーションコメントには、コメント区切り文字である
/**
と*/
、および行頭のアスタリスクを含めてはならない、ということです。コメントを書く場合は、最初の文をパッケージの概要とし、<body>
と最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージタグを含めることはできますが、ほかのドキュメンテーションコメントと同様、すべてのブロックタグは、主説明のあとに置かなければなりません。パッケージコメントファイルに@see
タグを追加する場合は、完全指定の名前を使用する必要があります。詳細は、package.html
の例を参照してください。パッケージコメントファイルの処理 - Javadoc ツールは、実行時にパッケージコメントファイルを自動的に検索し、このファイルを見つけると次の処理を行います。
- 処理できるようにコメントをコピーする(
package.html
の場合であれば、<body>
と</body>
HTML タグの間にある内容をすべてコピーする。<head>
を含め、そこに<title>
やソースファイルの著作権記述などの情報を配置することもできるが、生成後のドキュメンテーションにはそれらは一切表示されない)- パッケージタグがあれば、すべて処理する
- 生成したパッケージの概要ページの最後に、処理したテキストを挿入する (例: パッケージの概要)
- パッケージの概要ページの先頭に、パッケージコメントの最初の文をコピーする。さらに、概要ページのパッケージリストに、パッケージ名とパッケージコメントの最初の文を追加する (例: 概要の要約)。文の末尾は、クラスやメンバーの主説明の最初の文の末尾と同じ規則によって判断される
概要コメントファイル
ドキュメント化する各アプリケーションまたはパッケージセットは、独自の概要ドキュメンテーションコメントを持つことができ、それは専用の「ソース」ファイルに保持されます。その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージセット全体に当てはまるドキュメントを記述します。概要コメントファイルを作成する場合は、ファイルに任意の名前を付け、任意の場所に置くことができます。ただし、通常は、ファイル名を
overview.html
にして、ソースツリーの最上位レベルに置きます。たとえば、java.applet
パッケージのソースファイルがC:\user\src\java\applet
ディレクトリに含まれているとすると、C:\user\src\overview.html
に概要コメントファイルを作成することができます。異なるパッケージのセットに対して javadoc を複数回実行する場合は、同じ 1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。たとえば、内部ドキュメンテーション用に -private を指定して javadoc を 1 回実行したあと、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメントファイルの 1 文目で、そのドキュメンテーションを公開用または内部用として記述できます。
概要コメントファイルの内容は、前述のパッケージコメントファイルと同様、HTML で記述された 1 つの大きなドキュメンテーションコメントです。詳細は、前述の説明を参照してください。要点を繰り返すと、このコメントを記述する場合は、最初の文をアプリケーションまたはパッケージセットの要約とし、
<body>
と最初の文の間にタイトルその他のテキストを含めないようにします。概要タグを含めることができます。どのドキュメンテーションコメントについても、インラインタグ ({@link}
など) 以外のすべてのタグは、主説明のあとに置く必要があります。@see
タグを追加する場合は、完全指定の名前を使用しなければなりません。Javadoc ツールの実行時に、-overview オプションを使って概要コメントファイル名を指定します。このファイルは、パッケージコメントファイルと同じように処理されます。
<body>
タグと</body>
タグの間にあるすべての内容を処理のためにコピーする- 概要タグがあれば、すべて処理する
- 生成した概要ページの最後に、処理したテキストを挿入する (例: 概要の要約)
- 概要ページの先頭に、概要コメントの最初の文をコピーする
その他の未処理のファイル
ソースには、Javadoc ツールによって生成先のディレクトリにコピーされる、その他の任意のファイルを含めることができます。一般に、このようなファイルには、グラフィックファイル、サンプルの Java ソース (.java) およびクラス (.class) ファイル、内容が通常の Java ソースファイルのドキュメンテーションコメントの影響を受けない独立した HTML ファイルなどがあります。未処理のファイルをソースに含めるには、それらのファイルを
doc-files
というディレクトリに置きます。このディレクトリは、ソースファイルがある任意のパッケージディレクトリの下に作成できます。このようなサブディレクトリは、パッケージごとに 1 つ用意できます。イメージ、サンプルコード、ソースファイル、.class ファイル、アプレット、および HTML ファイルをこのディレクトリに格納できます。たとえば、ボタンのイメージbutton.gif
をjava.awt.Button
クラスのドキュメントに含める場合は、そのファイルを/home/user/src/java/awt/doc-files/
ディレクトリに置きます。doc-files
ディレクトリを/home/user/src/java/doc-files
に置くことはできません。これは、java
はパッケージではなく、そのディレクトリそのものにソースファイルが入っていないからです。これらの未処理のファイルへのリンクは、すべて明示的に記述する必要があります。これは、Javadoc ツールがそれらのファイルを見ずに、単にディレクトリとその内容を生成先にコピーするだけだからです。たとえば、
Button.java
のドキュメンテーションコメント内のリンクは、次のようになります。/** * This button looks like this: * <img src="doc-files/Button.gif"> */テストファイルおよびテンプレートファイル
一部の開発者から、テストファイルおよびテンプレートファイルを対応するソースファイルの近くのソースツリーに保存したいという要望がありました。つまり、これらのソースファイルと同じディレクトリまたはサブディレクトリに保存したいということです。個別のソースファイル名で明示的に渡して Javadoc ツールを実行する場合は、テストファイルおよびテンプレートファイルを意図的に除外して、処理されないようにすることができます。ただし、パッケージ名またはワイルドカードで渡す場合は、以下のルールに従って、これらのテストファイルおよびテンプレートファイルが処理されないようにする必要があります。
テストファイルとテンプレートファイルの違いは、テストファイルは、正当でコンパイル可能なソースファイルであるのに対して、テンプレートファイルは、そうではないという点です。ただし、テンプレートファイルも「.java」で終わることができます。
テストファイル - 開発者の多くは、あるパッケージのコンパイル可能で実行可能なテストファイルをそのパッケージのソースファイルと同じディレクトリに配置したいと考えています。しかしテストファイルは、名前なしパッケージなど、ソースファイルパッケージとは別のパッケージに属させたいとも考えています (そのため、テストファイルには package ステートメントがないか、またはソースとは別の package ステートメントがある)。このような状況では、コマンド行で指定されているソースのパッケージ名を指定してそのソースがドキュメント化されているときに、テストファイルは警告またはエラーを引き起こします。そのようなテストファイルはサブディレクトリに配置する必要があります。
com.package1
に追加する場合は、それらのテストファイルを、ハイフンが含まれるためパッケージ名としては無効になるサブディレクトリに配置します。com/package1/test-files/こうすると、Javadoc ツールでは警告なしで test ディレクトリをスキップします。テストファイルに doc コメントが含まれる場合、次のようにワイルドカードを含んだテストソースファイル名で渡してテストファイルのドキュメントを生成するように、Javadoc ツールを別個に実行できるように設定できます。たとえば、
com/package1/test-files/*.java
などです。ソースファイルのテンプレート - テンプレートファイルの名前は「.java」で終わることもありますが、テンプレートファイルはコンパイルできません。ソースディレクトリに保持したいソースファイルのテンプレートがある場合は、このファイル名にハイフン (
Buffer-Template.java
など) やその他の不正な Java 文字を使用します。こうすることで、処理されないようになります。これは、Javadoc ツールが処理するのは、「.java」接尾辞を除いた名前が 正規のクラス名であるソースファイルだけであるためです (「Identifiers」参照)。
デフォルトでは、javadoc ツールは、HTML 形式のドキュメントを生成する標準ドックレットを使います。このドックレットは、以下の種類のファイルを生成します。それぞれの HTML ページは、個々のファイルに相当します。以下の各 HTML「ページ」は、それぞれ別のファイルに対応します。javadoc が生成するファイルの名前には、クラスやインタフェースの名前にちなんだものと、そうでないもの (package-summary.html
など) の 2 種類があります。後者のグループのファイル名には、前者のグループとファイル名が競合しないように、ハイフンが含まれています。基本内容ページ
- ドキュメント化するクラスまたはインタフェースごとに 1 つのクラスページまたはインタフェースページ (クラス名
.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/
クラス名.html
)。このページには、特定のクラス、インタフェース、またはパッケージの一部を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。クラスまたはインタフェース A を例にして考えると、その「使用」ページには、A のサブクラス、A として宣言されたフィールド、A を返すメソッド、A 型のパラメータを持つメソッドおよびコンストラクタが表示されます。このページを表示するには、まず、パッケージ、クラス、またはインタフェースのページに移動してから、ナビゲーションバーの「使用」リンクをクリックします。- 非推奨 API ページ (
deprecated-list.html
)。推奨されないすべての名前が一覧表示されます。非推奨名は、一般に改良された API が存在するために使用が推奨されていない API の名前であり、通常、それに置き換わる名前が提示されています。非推奨 API は、将来の実装では削除される可能性があります。- 定数フィールド値ページ (
constant-values.html
)。static フィールドの値用です。- 直列化されたフォームページ (
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 ファイル。このファイルは、フレーム付きの先頭ページを表示する場合にロードします。このファイル自体には、テキスト内容は含まれていません。
- 複数のフレームファイル (
*-frame.html
)。パッケージ、クラス、およびインタフェースのリストが含まれています。HTML フレームを表示するときに使用されます。- パッケージリストファイル (
package-list
)。-link
オプションおよび-linkoffline
オプションで使用されます。これは、HTML ファイルではなくテキストファイルであり、どのリンクからもアクセスできません。- スタイルシートファイル (
stylesheet.css
)。生成されるページ上のいくつかの要素について、色、フォントファミリ、フォントサイズ、フォントのスタイル、および配置を制御します。- doc-files ディレクトリ。生成先ディレクトリにコピーするイメージ、サンプルコード、ソースコードなどのファイルがすべて格納されます。これらのファイルは、Javadoc ツールによって処理されないため、ファイル内に javadoc タグがあっても無視されます。このディレクトリは、ソースツリーの中にある場合にのみ生成されます。
Javadoc ツールは、下の図に示すように、2 ~ 3 つの HTML フレームを生成します。1 つのパッケージしかない場合 (またはパッケージがない場合) は、パッケージの一覧を省略することによって最低限必要な数のフレームを作成します。単一のパッケージに属するソースファイル (*.java) または単一のパッケージ名を引数として javadoc コマンドに渡す場合は、左側の列にクラスの一覧を表示するフレーム (C) 1 つだけが作成されます。Javadoc に複数のパッケージ名を渡した場合は、概要ページ (Detail) に加えて、すべてのパッケージを一覧表示する第 3 のフレーム (P) が作成されます。この概要ページのファイル名は、
overview-summary.html
です。したがって、このファイルは、2 つ以上のパッケージ名を渡した場合にだけ作成されます。「フレームなし」リンクをクリックするか、overview-summary.html を最初に表示すると、フレームを省略できます。HTML フレームに慣れていない場合は、特定のフレームを印刷およびスクロールするには、そのフレームに「フォーカス」がなければならないことに注意してください。フレームにフォーカスを与えるには、そのフレームをクリックします。このようにすると、多くのブラウザでは、矢印キーやページキーを使ってそのフレームをスクロールしたり、「印刷」メニューコマンドを使ってそのフレームを印刷したりできます。
------------ ------------ |C| Detail | |P| Detail | | | | | | | | | | |-| | | | | |C| | | | | | | | | | | | | | ------------ ------------ javadoc *.java javadoc java.lang java.awtHTML フレームが必要かどうかによって、次のどちらかのファイルを開始ページとしてロードします。生成されるファイルの構造
index.html
(フレームあり)overview-summary.html
(フレームなし)生成されるクラスファイルおよびインタフェースファイルは、Java ソースファイルおよびクラスファイルと同じディレクトリ階層に編成されます。1 つのサブパッケージにつき 1 つのディレクトリ、という構造になります。
たとえば、
java.applet.Applet
クラスに対して生成されるドキュメントは、java\applet\Applet.html
に格納されます。生成先のディレクトリの名前がapidocs
だとすると、java.applet パッケージのファイル構造は、その下に構築されます。前述のように、「frame」という語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外の HTML ファイルは、すべて右側のフレームに表示されます。注 - 下の階層図で、ディレクトリは太字 (bold) で示してあります。アスタリスク (*
) は、javadoc への引数がパッケージ名ではなくソースファイル名 (*.java) である場合に省略されるファイルおよびディレクトリを示しています。また、引数がソースファイル名の場合は、package-list
は作成されますが、内容は空です。doc-files ディレクトリは、ソースツリー内に存在する場合にのみ、生成先に作成されます。apidocs 最上位ディレクトリ index.html HTML フレームを設定する初期ページ * overview-summary.html * 全パッケージのリスト。先頭に要約文がある overview-tree.html 全パッケージのクラス階層のリスト deprecated-list.html 全パッケージの推奨されない API のリスト constant-values.html 全パッケージの static フィールドの値のリスト serialized-form.html 全パッケージの直列化された形式のリスト * overview-frame.html 全パッケージのリスト。左上のフレームに表示される allclasses-frame.html 全パッケージの全クラスのリスト。左下のフレームに表示される help-doc.html これらのページの構成を示すユーザーヘルプを表示する index-all.html -splitindex オプションなしで作成されたデフォルト索引 index-files -splitindex オプションを指定して作成されたディレクトリ index-<number>.html -splitindex オプションを指定して作成された索引ファイル package-list パッケージ名のリスト。外部参照を解決するためだけに使用される stylesheet.css フォント、色、配置を定義する HTML スタイルシート 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 このパッケージが使用されている場所のリスト doc-files イメージやサンプルのファイルが格納されるディレクトリ class-use API が使用されている場所のページを格納するディレクトリ 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
を組み込むことができません。これら後者の 2 つの修飾子は、実装の詳細と見なされているため、API 仕様には含まれません。API では、並行性のセマンティクスについて、キーワード
synchronized
に依存するのではなく、コメントによる主説明としてドキュメント化する必要があります。たとえば、「1 つのEnumeration
を複数のスレッドから並行して使用することはできない」などのコメントを記述します。ドキュメントには、これらのセマンティクスを実現する方法を記述するべきではありません。たとえば、Hashtable
はスレッドに対して安全である必要がありますが、「エクスポートされるすべてのメソッドを同期化すればそれを実現できる」のようには指定する根拠はありません。バケットレベルで内部的に同期化する権利を残しておく必要があります。そうすれば、より高度な並行性が提供されます。
オリジナルの「ドキュメンテーションコメントの仕様」は、「関連項目」を参照してください。ソースコードへのコメントの挿入
ソースコードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーションコメント ("doc comments") を記述することができます。各パッケージにドキュメンテーションコメントを作成できます。構文は若干異なりますが、概要にもドキュメンテーションコメントを作成できます。ドキュメンテーションコメントは、非公式に「Javadoc コメント」と呼ばれています (この用語は商標関連の使用法に違反)。ドキュメンテーションコメントは、コメントの始まりを示す文字列/**
と、コメントの終わりを示す文字列*/
の間にある文字で構成されます。行の先頭のアスタリスクは、各行に記述できます。詳細は、以下で説明します。コメントのテキストは、複数行にわたって記述できます。/** * This is the typical format of a simple documentation comment * that spans two lines. */次のようにして 1 行に記述すると、スペースを節約できます。/** This comment takes up only one line. */コメントの配置 - ドキュメンテーションコメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置かれているときにだけ認識されます。クラスの例、メソッドの例、およびフィールドの例を参照してください。メソッドの本体に置かれているドキュメンテーションコメントは無視されます。javadoc ツールでは、1 つの宣言文につき 1 つのドキュメンテーションコメントだけが認識されます。よくある間違いは、クラスのコメントとクラスの宣言の間に
import
文を置いてしまうことです。このような記述はしないでください。このようなクラスコメントは無視されます。/** * This is the class comment for the class Whatever. */ import com.sun; // MISTAKE - Important not to put import statement here public class Whatever { }ドキュメンテーションコメントは主説明のあとにタグセクションが続く - コメントの開始区切り文字である/**
のあとからタグセクションまでが主説明になります。タグセクションは、先頭文字が@
である行で定義される最初のブロックタグから始まります (行の先頭のアスタリスク、空白、および行の先頭の区切り文字/**
は除く)。主説明を記述せず、タグセクションだけのコメントを記述することもできます。主説明は、タグセクション以降に続けることはできません。タグの引数は、複数行にわたって記述できます。タグの数に制限はありません。何回も記述できるタグと、1 回しか記述できないタグがあります。例えば、次の@see
からタグセクションが始まります。/** * This sentence would hold the main description for this doc comment. * @see java.lang.Object */ブロックタグとインラインタグ - 「タグ」は、Javadoc が処理できる、ドキュメンテーションコメント内の特別なキーワードです。@tag
のように記述するブロックタグ (「スタンドアロンタグとも呼ばれる」) と、インラインタグ ({@tag}
のように中括弧で囲んで記述) の 2 種類のタグがあります。ブロックタグが正しく解釈されるためには、行の先頭のアスタリスク、空白、区切り文字 (/**
) を除いて、行の先頭に置かなければなりません。これは、テキスト内のそれ以外の位置で@
文字を使用しても、タグの開始としては解釈されないことを意味しています。行の最初に@
文字を使用してもタグとして解釈されないようにするには、HTML エンティティーの「@
」を使用してください。それぞれのブロックタグには、対応付けられたテキストがあります。このテキストは、タグのあとから、次のタグの前、またはドキュメンテーションコメントの最後までの間に記述されたテキスト (タグやコメント区切り文字を除く) です。この関連テキストは複数行にわたって記述できます。インラインタグは、テキストを記述できる場所であればどこにでも置くことができ、正しく解釈されます。次のコード例には、ブロックタグ@deprecated
と、インラインタグ{@link}
が含まれています。/** * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */コメントは HTML で記述する - テキストは HTML 形式で記述しなければなりません。これは、HTML のエンティティーを使う必要があること、および HTML タグを使用できることを意味します。記述する HTML のバージョンとしては、使用するブラウザがサポートする任意のバージョンを使用できます。標準ドックレットは、カスケーディングスタイルシート (CSS) とフレームを含め、すべての部分 (ドキュメンテーションコメント以外の部分) で HTML 3.2 に準拠したコードを生成するように作成されています。ただし、フレームセット対応のため、生成される各ファイルには「HTML 4.0」と記述されます。
たとえば、より小さい (
<
) およびより大きい (>
) という記号は、<
および>
として記述する必要があります。同様に、アンパサンド (&
) は、&
と記述する必要があります。次の例では、ボールドの HTML タグ<b>
を使っています。次に、ドキュメンテーションコメントを示します。
/** * This is a <b>doc</b> comment. * @see java.lang.Object */行頭のアスタリスク - Javadoc は、ドキュメンテーションコメントを解析するときに、各行の先頭にあるアスタリスク (
*
) をすべて破棄します。また、最初のアスタリスク (*
) より前の空白とタブも破棄します。バージョン 1.4 からは、行の先頭のアスタリスクを省略しても、先頭の空白文字は削除されなくなりました。このため、コード例を直接ドキュメンテーションコメントの<PRE>
タグ内にペーストしても、インデントが保持されます。通常、ブラウザは、空白文字をタブよりも一律に解釈します。インデントは区切り文字/**
または<PRE>
タグよりも左寄りになります。最初の文 - 各ドキュメンテーションコメントの最初の文は、宣言されているエンティティーに関する簡潔かつ完全な要約文である必要があります。この「最初の文」は、直後にスペース、タブ、または改行が続く最初のピリオド (ロケールが英語に設定されている場合)、または最初のタグがある位置で終わります。最初の文は、Javadoc ツールによって HTML ページの最初にあるメンバーの概要の部分にコピーされます。
複数フィールドの宣言 - Java では、1 つの文で複数のフィールドを宣言できます。ただし、この文には、1 つのドキュメンテーションコメントしか記述できません。そのコメントが、すべてのフィールドに対してコピーされます。したがって、フィールドごとにドキュメンテーションコメントを記述する必要がある場合は、各フィールドを別々の文で宣言しなければなりません。たとえば、次のドキュメンテーションコメントは、1 つの宣言として記述すると不適切です。この場合は、宣言を 2 つに分けることをお勧めします。
上記のコードからは、次のようなドキュメントが生成されます。/** * The horizontal and vertical distances of point (x,y) */ public int x, y; // Avoid this見出しタグはなるべく使用しない - メンバーに対してドキュメンテーションコメントを記述するときには、<H1> や <H2> などの HTML 見出しタグは、なるべく使わないでください。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)
メソッドコメントの自動コピー
Javadoc ツールには、次の 2 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラスは、ドキュメンテーションコメントを継承しません。
- 自動的にコメントを継承して、見つからないテキストを埋める - 主説明、または
@return
タグ、@param
タグ、@throws
タグが、メソッドコメントで見つからない場合、Javadoc ツールは、オーバーライドしたメソッドまたは実装している場合はそのメソッドから、対応する主説明またはタグコメントを、次のアルゴリズムに従ってコピーします。厳密には、特定のパラメータの
@param
タグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。特定の例外の@throws
タグが見つからない場合、その例外が宣言されている場合にかぎり、その@throws
タグがコピーされます。この動作はバージョン 1.3 以前の動作とは対照的です。これまでのバージョンでは、主説明またはタグが存在すれば、コメントは一切継承されませんでした。
- {@inheritDoc} タグを持つコメントを明示的に継承する - インラインタグ
{@inheritDoc}
を、メソッドの主説明、または@return
、@param
、@throws
タグコメントに挿入します。継承した対応する主説明またはタグコメントは、その箇所にコピーされます。ドキュメンテーションコメントを実際にコピーに利用するには、継承したメソッドのソースファイルが -sourcepath で指定したパスだけに置かれていることが必要になります。コマンド行で、クラスもパッケージも渡す必要はありません。この点は、クラスがドキュメント化されるクラスでなければならなかった 1.3.x 以前のリリースと異なります。
クラスおよびインタフェースからの継承 - クラスおよびインタフェースから継承する次の 3 つの場合に、コメントの継承が行われます。
- クラスのメソッドがスーパークラスのメソッドをオーバーライドしている
- インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドしている
- クラスのメソッドがインタフェースのメソッドを実装している
最初の 2 つのケース (メソッドがオーバーライドしている場合) では、Javadoc ツールは、そのコメントが継承されているかどうかにかかわらず、オーバーライドしているメソッドのドキュメント内に「オーバーライド」という小見出しを生成し、オーバーライドされているメソッドへのリンクを書き込みます。
3 つ目のケース (特定のクラスのメソッドがインタフェースのメソッドを実装している場合) では、javadoc ツールは、オーバーライドしているメソッドのドキュメント内に「定義」という小見出しを生成し、実装されているメソッドへのリンクを書き込みます。これは、コメントが継承されているかどうかにかかわりません。
メソッドの説明が継承されるアルゴリズム - あるメソッドにドキュメンテーションコメントが記述されていない場合、または {@inheritDoc} タグがある場合、Javadoc ツールは、次のようなアルゴリズムを使用して適切なコメントを検索します。このアルゴリズムは、もっとも適切なドキュメンテーションコメントを検索できるように設計されており、スーパークラスよりもインタフェースが優先されるようになっています。
- 直接に実装されている (または、拡張されている) インタフェースを、メソッドの宣言で implements (または extends) キーワードのあとに登場する順序で、1 つずつ調べる。このメソッドについて最初に見つかったドキュメンテーションコメントを採用する
- 手順 1 でドキュメンテーションコメントが見つからなかった場合は、直接実装されている (または、拡張されている) インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用する (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ)
- 手順 2 でドキュメンテーションコメントが見つからなかった場合で、このクラスが Object 以外のクラスである (インタフェースではない) 場合は、次のように処理する
- スーパークラスにこのメソッドについてのドキュメンテーションコメントが記述されていれば、そのコメントを採用する
- 手順 3a でドキュメンテーションコメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を適用する
Javadoc ツールは、Java のドキュメンテーションコメント内に埋め込まれた特別なタグを解析します。これらのドキュメンテーションタグを使うと、書式の整った完全な API ドキュメントをソースコードから自動的に生成できます。タグは、単価記号 (@
) で始まり、大文字と小文字が区別されます。これらのタグは、定められたとおりの大文字と小文字を使用して記述する必要があります。タグは、行の先頭 (先行する空白と省略可能なアスタリスクは除く) に置かなければなりません。慣例として、同じ名前のタグは 1 か所にまとめて記述するようにします。たとえば、@see
タグが複数ある場合は、すべてを 1 か所にまとめて記述します。今後のリリースで導入されるタグについては、「Proposed Javadoc Tags」を参照してください。
- ブロックタグ - 主説明に続くタグセクション内にのみ記述可能。ブロックタグは、
@tag
の形式をとります。- インラインタグ - 主説明内、またはブロックタグのコメント内に記述可能。インラインタグは、
{@tag}
のように中括弧で囲みます。現時点で有効なタグは、次のとおりです。
タグ 導入された JDK/SDK のバージョン @author
1.0 {@code}
1.5 {@docRoot}
1.3 @deprecated
1.0 @exception
1.0 {@inheritDoc}
1.4 {@link}
1.2 {@linkplain}
1.4 {@literal}
1.5 @param
1.0 @return
1.0 @see
1.0 @serial
1.2 @serialData
1.2 @serialField
1.2 @since
1.1 @throws
1.2 {@value}
1.4 @version
1.0 カスタムタグについては、-tag オプションを参照してください。
@author
name-text- -author オプションが使われている場合、生成ドキュメントに「著者」の項目を追加し、指定された name-text を書き込みます。1 つのドキュメンテーションコメントに複数の
@author
タグを含めることができます。1 つの@author
タグに 1 つの名前を指定することも、1 つのタグに複数の名前を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (,
) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。詳細については、「タグを使用できる場所」および @author タグのドキュメントを参照してください。
@deprecated
deprecated-text 注: JDK 5.0 から、@Deprecated 注釈を使って特定のプログラム要素を非推奨にできるようになりました。この API は動作し続けますが、この API を使用するべきではないことを示すコメントを追加します。Javadoc ツールは、deprecated-text を主説明の前に移動してイタリックにし、その前にボールドの警告「推奨されません。」を追加します。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。deprecated-text の最初の文では、少なくとも、その API が推奨されなくなった時期と、代替使用するべき API を読者に提示する必要があります。Javadoc ツールは、この最初の文だけを、概要セクションと索引にコピーします。そのあとの文では、その API が推奨されない理由を説明することもできます。また、代わりの API を指し示す
{@link}
タグ (Javadoc 1.2 以降の場合) を含める必要があります。次のように記述します。詳細については、@deprecated タグのドキュメントを参照してください。
- Javadoc 1.2 以降では、
{@link}
タグを使用します。これにより、必要な場所にインラインでリンクを作成できます。例を示します。/** * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */- Javadoc 1.1 では、各
@deprecated
タグに対して@see
タグ (インラインにはできない) を記述するのが標準の形式です。推奨されないタグについての詳細は、@deprecated タグのドキュメントを参照してください。
{@code
text}
<code>{@literal}</code>
と同等です。テキストを HTML マークアップまたは入れ子になった javadoc タグとして解釈せずに、text を
code
フォントで表示します。これにより doc コメントでは、パラメータの種類 (<Object>
)、不等号 (3 < 4
)、または矢印 (<-
) などで、HTML エンティティー (<
および>
) ではなく、通常の山括弧 (<
および>
) を使用できます。たとえば、次のドキュメンテーションコメントは、生成された HTML ページで、次のようにそのまま表示されます。{@code A<B>C}
注目すべき点として、A<B>C
<B>
は太字であると解釈されませんが、コードフォントになります。コードフォントなしで同じ機能を実現するには、
{@literal}
を使用します。{@docRoot}
- 生成されるページから見た、生成ドキュメントの (生成先の) ルートディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。通常は、各ページの下部から著作権のページにリンクします。
この
{@docRoot}
タグは、コマンド行からも、ドキュメンテーションコメントの中でも使用できます。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。次に例を示します。
- コマンド行では、ヘッダー、フッター、またはボトムノートは次のように定義します。
javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'注 -{@docRoot}
をこのように利用する場合、一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする必要があります。たとえば、Inprise MAKE バージョン 5.2 を Windows 上で実行する場合は、「{{@docRoot}}
」のように、中括弧を二重にする必要があります。さらに、-bottom
などのオプションに対する引数を、単一引用符ではなく、二重引用符で囲む必要があります。href
引数の値を囲む引用符は省略します。- ドキュメンテーションコメントの中では、次のように使用します。
/** * See the <a href="{@docRoot}/copyright.html">Copyright</a>. */<a href="{@docRoot}/copyright.html">次のように解決されます。<a href="../../copyright.html"> java/lang/Object.java の場合および<a href="../../../copyright.html"> java/lang/ref/Reference.java の場合@exception
class-name description@exception
タグは、@throws
タグと同義です。{@inheritDoc}
- もっとも近い継承可能なクラスまたは実装可能なインタフェースから、このタグの現在のドキュメンテーションコメントに、ドキュメントを継承 (コピー) します。この機能により、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使って記述することができます。
このタグは、ドキュメンテーションコメントの次の位置でのみ有効です。
- メソッドの主説明ブロック内。この場合、主説明は、上位階層のクラスまたはインタフェースからコピーされる
- メソッドの @return、@param、@throws タグのテキスト引数内。この場合、タグテキストは、上位階層の対応するタグからコピーされる
継承階層でコメントを見つける方法に関する正確な説明について、「メソッドコメントの自動コピー」を参照してください。このタグが見つからない場合、コメントは、この節で説明するルールに応じて、自動的に継承されるかどうかが決まります。
{@link
package.class#
member label}
- 表示テキスト label とのインラインリンクを挿入します。label は、参照クラスの指定されたパッケージ、クラス、またはメンバーの名前のドキュメンテーションを指し示します。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
このタグは、
@see
タグとよく似ています。どちらのタグも、package.class#
member および label の参照の仕方が同じで、有効な構文もまったく同じです。大きな違いは、{@link}
は、リンクを「関連項目」セクションに置くのではなく、インラインリンクを生成するということです。また、インラインテキストのほかの部分と区別するために、{@link}
タグの最初と最後に中括弧を記述します。ラベルの中で「}」を使う必要がある場合は、HTML エンティティーの「}」を使います。1 つの文の中で使用できる
{@link}
タグの数に制限はありません。このタグは、ドキュメンテーションコメントの主説明部分、または @deprecated、@return、@param などの任意のタグのテキスト部分で使うことができます。たとえば、次のコメントでは
getComponentAt(int, int)
メソッドを参照しています。{@link #getComponentAt(int, int) getComponentAt} メソッドを使用します。標準ドックレットでは、上記のコメントから次の HTML が生成されます (このコメントが同じパッケージの別のクラスを参照している場合)。<a href="Component.html#getComponentAt(int, int)">getComponentAt</a> メソッドを使用します。この HTML は、Web ページ上では次のように表示されます。getComponentAt メソッドを使用します。{@link}
を、ドキュメント化の対象にしていないクラスにまで拡張するには、-link
オプションを使用します。詳細については、{@link} タグのドキュメントを参照してください。
{@linkplain
package.class#
member label}
- リンクのラベルがコードフォントではなくプレーンテキストで表示される点以外は
{@link}
と同じです。ラベルがプレーンテキストで記述されていると便利です。次の例を参照してください。例:{@linkplain add() the overridden method} を参照してください。これは以下のように表示されます。the overridden method を参照してください。{@literal
text}
- テキストを HTML マークアップまたは入れ子になった javadoc タグとして解釈せずに、text を表示します。これにより doc コメントでは、パラメータの種類 (
<Object>
)、不等号 (3 < 4
)、または矢印 (<-
) などで、HTML エンティティー (<
および>
) ではなく、通常の山括弧 (<
および>
) を使用できます。たとえば、次のドキュメンテーションコメントは、生成された HTML ページはブラウザで次のようにそのまま表示されます。{@literal A<B>C}
注目すべき点として、
A<B>C
<B>
は太字であると解釈されません (コードフォントにならない)。コードフォントで同じ機能を実現するには、
{@code}
を使用します。@param
parameter-name description- 指定した parameter-name と指定した description を使用してパラメータを「Parameters」セクションに追加します。doc コメントを記述するときは、description を複数行に続けることができます。このタグは、メソッド、コンストラクタ、またはクラスの doc コメント内でのみ有効です。
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) { }詳細については、@param タグのドキュメントを参照してください。@return
description- 「戻り値」セクションを追加して、description のテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーションコメントでのみ有効です。
詳細については、@return タグのドキュメントを参照してください。
@see
reference- 「関連項目」見出しを追加し、reference を指すリンクか、またはテキストエントリを書き込みます。1 つのドキュメンテーションコメントには、任意の数の
@see
タグを指定できます。すべての@see
タグの内容は、同じの見出しの下にグループ化されます。@see
タグには、次の 3 種類の形式があります。もっともよく使われるのは、3 番目の形式です。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。パッケージ、クラス、またはメンバーに対するインラインリンクを文中に挿入する方法は、{@link}
を参照してください。
@see
"
string"- string のテキストエントリを追加します。リンクは生成されません。string は、書籍または URL ではアクセスできない情報の参照先です。Javadoc ツールは、最初の文字が二重引用符 (
"
) かどうかを調べて、この形式をほかの 2 つの形式と区別します。例を示します。@see "The Java Programming Language"これは次のようなテキストを生成します。
- 関連項目:
- The Java Programming Language
@see
<a href="
URL#value">
label</a>
- URL#value で定義されたとおりにリンクを追加します。URL#value は、相対 URL または絶対 URL です。Javadoc ツールは、最初の文字が「より小さい」記号 (
<
) かどうかを調べて、この形式をほかの 2 つの形式と区別します。例を示します。@see <a href="spec.html#section">Java Spec</a>これは次のようなリンクを生成します。
- 関連項目:
- Java Spec
@see
package.class#
member label- 指定された名前を持つ、参照されている Java 言語のメンバーについてのドキュメントを指すリンクを、表示テキスト label とともに追加します。label は省略可能です。label を省略すると、リンク先のメンバーの名前が適切に短縮されて表示されます。「名前が表示される方法」を参照してください。-noqualifier を使用すると、表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストを指定する場合に使います。
バージョン 1.2 だけは、ラベルではなく、名前が <code> HTML タグ内に自動的に表示されます。1.2.2 からは、ラベルを使用するか、しないかにかかわらず、<code> は常に表示テキストを囲むかたちで、含まれます。
- package.class
#
member には、参照されている任意の有効なプログラム要素の名前を指定します。つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。ただし、メンバー名ーの前のドットは、シャープ記号 (#
) で置き換えます。class は、任意のトップレベルまたは入れ子にされたクラスまたはインタフェースを表します。member は、任意のコンストラクタ、メソッドまたはフィールド (入れ子にされたクラスまたはインタフェースではない) を表します。指定した名前が、ドキュメント化されているクラスに含まれている場合、Javadoc ツールは、その名前へのリンクを自動的に作成します。外部参照クラスへのリンクを作成するには、-link
オプションを使います。参照クラスに属していない名前のドキュメントを参照するには、ほかの 2 つの形式の@see
タグを使います。この引数については、このあとの「名前の指定」で詳しく説明します。- label は、省略可能なテキストで、リンクのラベルとして表示されます。label には空白を含めることができます。label を省略すると、package.class.member が、現在のクラスおよびパッケージに応じて適切に短縮されて表示されます。「名前が表示される方法」を参照してください。
- 空白文字は、package.class
#
member と label の間の区切り文字です。括弧の内側の空白文字はラベルの先頭とは解釈されないため、メソッドのパラメータ間に空白文字を入れてもかまいません。例 - この例では、
Character
クラスにある@see
タグが、String
クラスのequals
メソッドを参照しています。タグには、名前String#equals(Object)
とラベルequals
の両方の引数が含まれています。標準ドックレットは、次のような HTML を生成します。/** * @see String#equals(Object) equals */これは、ブラウザでは次のように表示され、ラベルがリンクテキストになります。<dl> <dt><b>関連項目:</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 にはメソッドまたはコンストラクタを指定できます。
@see
package.class#member の一般的な形式現在のクラスのメンバーを参照する
@see
#
field
@see
#
method(Type, Type,...)@see
#
method(Type argname, Type argname,...)@see
#
constructor(Type, Type,...)@see
#
constructor(Type argname, Type argname,...)
現在の、またはインポートされたパッケージの別のクラスを参照する
@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
別のパッケージの要素を参照する (完全修飾)
@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)。
- メソッドまたはコンストラクタを指定するときに括弧を付けずに名前だけ (
getValue
など) を使用した場合、同じ名前のフィールドが存在しなければ、Javadoc ツールはそのメソッドに対して正しくリンクを作成します。ただし、括弧と引数を追加するように促す警告メッセージを出力します。このメソッドがオーバーロードされている場合、Javadoc ツールは、検索で最初に見つかったメソッドにリンクします。結果は前もって特定できません。- 入れ子にされたクラスは、上記のどの形式の場合も、単に「inner」ではなく、「outer
.
inner」として指定しなければなりません。- すでに述べたとおり、クラスとメンバーを区切るために、ドット (
.
) ではなくシャープ記号 (#
) を使用することに注意してください。このように指定すると、Javadoc ツールは、あいまいさを解決できます。ドットは、クラス、入れ子にされたクラス、パッケージ、およびサブパッケージを区切るためにも使用されます。ただし、Javadoc ツールでは一般に許容範囲が広く、あいまいさがなければ、ドットでも正しく解析されます。その場合でも警告は表示されます。@see の検索順序 - Javadoc ツールは、ソースファイル (.java)、パッケージファイル (package.html または package-info.java)、または概要ファイル (overview.html) の中に登場する
@see
タグを処理します。後者の 2 つのファイルでは、完全指定の名前を@see
タグに指定しなければなりません。ソースファイルでは、完全指定の名前、または部分指定の名前を指定できます。Javadoc ツールは、
.java
ファイル内で完全指定でない名前が記述された@see
タグを見つけると、Java コンパイラと同じ順序で指定された名前を検索します。ただし、Javadoc ツールは、特定の名前空間のあいまいさを検出しません。これは、ソースコードにこれらのエラーが存在していないことを前提としているためです。この検索順序は、Java 言語仕様第 2 版の第 6 章「Names」で正式に定義されています。Javadoc ツールは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてから名前を検索します。具体的には、次の順序で検索します。
- 現在のクラスまたはインタフェース
- 外側を囲んでいるクラスとインタフェース (もっとも近いものから検索)
- スーパークラスとスーパーインタフェース (もっとも近いものから検索)
- 現在のパッケージ
- インポートされているパッケージ、クラス、およびインタフェース (import 文の順序に従って検索)
Javadoc ツールは、各クラスについて手順 1 ~ 3 を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にそのクラスを囲んでいるクラス E を検索し、その次に E のスーパークラスを検索し、さらにその次に E を囲んでいるクラスを検索します。手順 4 と 5 では、1 つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません。その順序は、個々のコンパイラによって異なります。手順 5 では、Javadoc ツールは、java.lang を検索します。このパッケージは、すべてのプログラムに自動的にインポートされるからです。
Javadoc ツールは、必ずしもサブクラスを検索するとは限りません。また、javadoc の実行中にほかのパッケージのドキュメントが生成される場合でも、ほかのパッケージを検索しません。たとえば、
@see
タグがjava.awt.event.KeyEvent
クラス内にあって、java.awt
パッケージにある名前を参照している場合、Javadoc は、そのクラスがインポートしないかぎりそのパッケージを検索しません。名前が表示される方法 - label を省略すると、package.class.member が表示されます。一般に、package.class.member は、現在のクラスおよびパッケージに応じて適切に短縮されます。「短縮される」とは、必要最小限の名前だけが表示されるということです。たとえば、
String.toUpperCase()
メソッドに、同じクラスのメンバーへの参照とほかのクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースだけです (次の表を参照)。パッケージ名を広域的に削除するには、-noqualifier を使用します。
参照の種類 String.toUpperCase()
での例表示される名前 @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
など) のクラス内にある場合に、名前がどのように表示されるかを示しています。関連項目: @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
オプションを使用します。詳細については、@see タグのドキュメントを参照してください。
@serial
field-description| include | exclude
- デフォルトの直列化可能フィールドのドキュメンテーションコメントで使用します。
field-description (省略可能) では、フィールドの意味を説明し、取り得る値のリストを示す必要があります。必要に応じて、複数の行に渡って説明を記述できます。標準ドックレットは、この情報を、直列化された形式のページに追加します。
クラスを直列化したあとしばらくしてから直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。
include
およびexclude
引数は、直列化された形式のページにクラスまたはパッケージを含めるか除外するかを示します。これらの引数には、次のような効果があります。
Serializable
を実装している public または protected クラスは、通常はそのページに含められます。ただし、そのクラスまたはそのクラスが属するパッケージが@serial exclude
で指定されていると、そのページから除外されます。Serializable
を実装している private または package private クラスは、通常はそのページから除外されます。ただし、そのクラスまたはそのクラスが属するパッケージが@serial include
で指定されていると、そのページに含められます。例:
javax.swing
パッケージは、@serial exclude
で指定されています (package.html
またはpackage-info.java
内)。public クラスjava.security.BasicPermission
は、@serial exclude
で指定されています。package private クラスjava.util.PropertyPermissionCollection
は、@serial include
で指定されています。クラスレベルで指定された @serial タグは、パッケージレベルで指定された @serial タグをオーバーライドします。
これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の第 1.6 節「クラスの直列化可能なフィールドおよびデータの文書化」を参照してください。また、「直列化の FAQ」も参照してください。この FAQ には、「-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。直列化形式仕様にクラスを含める場合には、「Sun の仕様」も参照してください。
@serialField
field-name field-type field-descriptionSerializable
クラスのserialPersistentFields
メンバーのObjectStreamField
コンポーネントをドキュメント化します。各ObjectStreamField
コンポーネントに対して@serialField
タグを 1 つ使う必要があります。@serialData
? data-description- data-description は、直列化された形式でのデータの型と順序を説明するテキストです。このデータには、特に、
writeObject
メソッドによって書き込まれる省略可能なデータ、およびExternalizable.writeExternal
メソッドによって書き込まれるすべてのデータ (基底クラスを含む) が含まれます。
@serialData
タグは、writeObject
、readObject
、writeExternal
、readExternal
、writeReplace
、およびreadResolve
メソッドのドキュメンテーションコメントで使用できます。@since
since-text- 生成ドキュメントに「導入されたバージョン」見出しを追加し、指定された since-text を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、since-text に示されたソフトウェアリリース以降、存在していることを意味します。例を示します。
@since 1.5Java プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。@throws
class-name description@throws
タグと@exception
タグは同義です。生成ドキュメントに「例外」小見出しを追加して、class-name と description テキストを書き込みます。class-name は、そのメソッドからスローされる可能性のある例外の名前です。このタグは、メソッド、コンストラクタの doc コメント内でのみ有効です。このクラスが完全指定の名前で記述されていない場合、Javadoc ツールは、検索順序に従ってクラスを探します。同じまたは異なる例外の doc コメントで、複数の@throws
タグを使用できます。すべてのチェック済み例外がドキュメント化されるようにするために、
@throws
タグが throws 節内の例外用に存在しない場合は、@throws タグのあるドキュメントであるかのように、Javadoc ツールによって例外が HTML 出力に説明なしで自動的に追加されます。オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、
@throws
ドキュメンテーションをそのメソッドからサブクラスにコピーされます。インタフェースメソッドから実装メソッドにコピーされる場合も同様です。@throws にドキュメンテーションを継承させるには、{@inheritDoc} を使用できます。詳細については、@throws タグのドキュメントを参照してください。
{@value
package.class#field}
{@value}
が静的フィールドの doc コメントで 引数なしで使用されている場合、その定数の値が表示されます。/** * The value of this constant is {@value}. */ public static final String SCRIPT_START = "<script>"任意の doc コメント内で引数 package.class#field ありで使用されている場合は、指定した定数の値が表示されます。/** * Evaluates the script starting with {@value #SCRIPT_START}. */ public String evalScript(String script) { }引数 package.class#field は、@see 引数と同一の形式になります。ただし、メンバーが静的フィールドになければならない点が異なります。これらの定数での値は、定数フィールド値ページにも表示されます。
@version
version-text- -version オプションが使われている場合、生成ドキュメントに「バージョン」小見出しを追加して、指定された version-text を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のバージョン番号を保持するように意図されています。これに対し、@since は、このコードが導入されたバージョン番号を保持します。version-text には、特別な内部構造はありません。バージョンタグを使用できる場所を調べるには、「タグを使用できる場所」を参照してください。
1 つのドキュメンテーションコメントに複数の
@version
タグを含めることができます。必要に応じて、@version
タグごとに 1 つのバージョン番号を指定することも、タグごとに複数のバージョン番号を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (,
) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。詳細については、@version タグのドキュメントを参照してください。
タグを使用できる場所
ここでは、タグを使用できる場所について説明します。@see
、@since
、@deprecated
、{@link}
、{@linkplain}
および{@docroot}
のタグは、すべての doc コメントで使用できます。
概要のドキュメンテーションタグ
概要タグは、概要ページのドキュメンテーションコメントで使用できるタグです。このドキュメンテーションコメントは、通常overview.html
という名前のソースファイル内にあります。ほかのドキュメンテーションコメントの場合と同様に、これらのタグは、主説明のあとで使う必要があります。注 - バージョン 1.2 では、概要ドキュメント内の
{@link}
タグにバグがあります。テキストは正しく表示されますが、リンクが設定されません。現在のところ、{@docRoot}
タグは、概要ドキュメント内では動作しません。
概要タグ
@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}
パッケージドキュメンテーションタグ
パッケージタグは、パッケージのドキュメンテーションコメントで使用できるタグです。このドキュメンテーションコメントは、package.html
またはpackage-info.java
という名前のソースファイル内にあります。ここで使用できる@serial
タグは、include
またはexclude
引数を指定したものだけです。
パッケージタグ
@see
@since
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}
クラスおよびインタフェースドキュメンテーションタグ
次に、クラスまたはインタフェースのドキュメンテーションコメントで使用できるタグを示します。ここで使用できる@serial
タグは、include
またはexclude
引数を指定したものだけです。
クラスおよびインタフェースタグ
@see
@since
@deprecated
@serial
@author
@version
{@link}
{@linkplain}
{@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.15, 13 Dec 2006 * @see java.awt.BaseWindow * @see java.awt.Button */ class Window extends BaseWindow { ... }
フィールドドキュメンテーションタグ
次に、フィールドのドキュメンテーションコメントで使用できるタグを示します。
フィールドタグ
@see
@since
@deprecated
@serial
@serialField
{@link}
{@linkplain}
{@docRoot}
{@value}
次にフィールドコメントの例を示します。
/** * The X-coordinate of the component. * * @see #getLocation() */ int x = 1263732;
コンストラクタおよびメソッドドキュメンテーションタグ
次に、コンストラクタまたはメソッドのドキュメンテーションコメント内で表示できるタグを示します。ただし、@return
はコンストラクタでは表示できず、{@inheritDoc}
は表示に制限があります。@serialData
タグは特定の直列化メソッドの doc コメントでのみ使用できます。
メソッドおよびコンストラクタタグ
@see
@since
@deprecated
@param
@return
@throws
(@exception)
@serialData
{@link}
{@linkplain}
{@inheritDoc}
{@docRoot}
次にメソッドのドキュメンテーションコメントの例を示します。
/** * 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 の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、イタリックでないオプションを提供します。Javadoc オプション
- -overview path\filename
- Javadoc に対して、path/filename で指定された「ソース」ファイルから概要ドキュメント用のテキストを取得し、そのテキストを概要ページ (
overview-summary.html
) に配置するように指定します。path/filename は、-sourcepath
への相対パスです。filename と path には、それぞれ任意の名前と場所を指定できますが、通常は、
overview.html
という名前を付けて、ソースツリー内の最上位のパッケージディレクトリがあるディレクトリに配置します。この場所に配置すると、-sourcepath
によってこのファイルが指し示されるので、パッケージをドキュメント化する際に path が不要になります。たとえば、java.lang
パッケージのソースツリーがC:\src\classes\java\lang\
の場合、概要ファイルはC:\src\classes\overview.html
に配置できます。「使用例」を参照してください。path/filename で指定するファイルについては、「概要コメントファイル」を参照してください。
概要ページが作成されるのは、Javadoc に複数のパッケージ名を渡した場合だけです。詳細は、「HTML フレーム」を参照してください。
概要ページのタイトルは、
-doctitle
によって設定されます。- -public
- public クラスおよびメンバーだけを表示します。
- -protected
- protected および public のクラスとメンバーだけを表示します。これはデフォルトの設定です。
- -package
- package、protected、および public のクラスとメンバーだけを表示します。
- -private
- すべてのクラスとメンバーを表示します。
- -help
- オンラインヘルプを表示します。Javadoc とドックレットのコマンド行オプションが一覧表示されます。
- -doclet class
- ドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。完全指定の名前を指定してください。このドックレットにより、出力の内容と形式が定義されます。
-doclet
オプションが使われていない場合、Javadoc は、標準ドックレットを使ってデフォルトの HTML 形式を生成します。このクラスには、start(Root)
メソッドが含まれていなければなりません。この起動クラスへのパスは、-docletpath
オプションによって定義されます。たとえば、MIF ドックレットを呼び出すには、次のように指定します。
-doclet com.sun.tools.doclets.mif.MIFDoclet特定のドックレットを実行した完全な例については、MIF Doclet のドキュメントを参照してください。
- -docletpath classpathlist
-doclet
オプションで指定されているドックレット開始クラスファイル、およびそれに依存する jar ファイルへのパスを指定します。開始クラスファイルが jar ファイル内にある場合、以下の例のように jar ファイルのパスが指定されます。絶対パスまたは現在のディレクトリからの相対パスを指定できます。classpathlist には、複数のパスまたは JAR ファイルを含めることができます。その場合、各パスまたは JAR ファイルを、Solaris の場合にはコロン (:)、Windows の場合にはセミコロン (;) で区切ります。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。jar ファイルへのパスの例には、ドックレット開始クラスファイルが含まれています。jar ファイル名が含まれている点に注目してください。
-docletpath C:\user\mifdoclet\lib\mifdoclet.jarドックレット開始クラスファイルのパスの例。クラスファイル名が省略されている点に注目してください。-docletpath C:\user\mifdoclet\classes\com\sun\tools\doclets\mif\特定のドックレットを実行した完全な例については、MIF Doclet のドキュメントを参照してください。- -1.1
- この機能は、Javadoc 1.4 では削除されました。代替機能はありません。このオプションは、Javadoc 1.1 によって生成されるのと同じ外見と機能を持つドキュメントを作成するためのものでした。入れ子のクラスはサポートされていません。このオプションが必要な場合は、Javadoc 1.2 または 1.3 を使用してください。
- -source release
- 受け付けるソースコードのバージョンを指定します。release には次の値を指定できます。
1.5 Javadoc は、JDK 1.5 で導入された総称および他の言語機能を含んだコードを受け付けます。-source フラグを指定しないと、コンパイラはデフォルトとして 1.5 の動作をします。 1.4 Javadoc は、JDK 1.4 で導入された、アサーションを含むコードを受け付けます。 1.3 Javadoc は、JDK 1.3 以降に導入されたアサーション、総称、または他の言語機能をサポートしません。 javac でコードをコンパイルするときに使用した値に対応する release の値を使用します。
- -sourcepath sourcepathlist
javadoc
コマンドにパッケージ名または-subpackages
を渡すときに、ソースファイル (.java
) を検索するためのパスを指定します。sourcepathlist には、セミコロン (;
) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使って、ドキュメント化されるソースファイルの位置だけでなく、それ自体はドキュメント化されないがドキュメント化されるソースファイルから継承されたコメントを持つソースファイルの位置も確認できます。
-sourcepath
オプションは、javadoc コマンドにパッケージ名を渡すときにだけ使用できます。javadoc
コマンドに渡される.java
ファイルは、このパスからは検索されません。.java
ファイルを検索するには、そのファイルのあるディレクトリに cd によって移動するか、または各ファイルの先頭にパスを含めます (「1 つ以上のクラスのドキュメント化」を参照)。-sourcepath
が省略された場合、Javadoc は、クラスパスを使ってソースファイルを検索します (-classpath を参照)。したがって、デフォルトの -sourcepath は、クラスパスの値です。-classpath も省略してパッケージ名を Javadoc に渡すと、Javadoc は現在のディレクトリおよびそのサブディレクトリからソースファイルを検索します。sourcepathlist には、ドキュメント化するパッケージ名のソースツリーのルートディレクトリを設定します。たとえば、
com.mypackage
という名前のパッケージをドキュメント化する場合に、そのソースファイルが次の場所にあるとします。C:\user\src\com\mypackage\*.javaこの場合、次のようにしてsourcepath
をC:\user\src
、つまりcom\mypackage
を含むディレクトリに指定し、それからパッケージ名com.mypackage
を指定します。C:> javadoc -sourcepath C:\user\src com.mypackageこの方法は、ソースパスの値とパッケージ名を連結して、ドットを (円記号) 「\」に変えると、パッケージのフルパス (C:\user\src\com\mypackage
) になることを理解すると簡単です。C:\user\src\com\mypackage
.2 つのソースパスを設定するには、次のようにします。
C:> javadoc -sourcepath C:\user1\src;C:\user2\src com.mypackage- -classpath classpathlist
- Javadoc が参照クラス (
.class
ファイル) を検索するパスを指定します。参照クラスとは、ドキュメント化されるクラスとそれらのクラスによって参照されるすべてのクラスのことです。classpathlist には、セミコロン (;
) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。classpathlist を指定するときは、クラスパスのドキュメントにある指示に従ってください。
-sourcepath
が省略されている場合、Javadoc ツールは、-classpath
を使って、クラスファイルだけでなくソースファイルも検索します (下位互換性のため)。したがって、ソースファイルとクラスファイルを別々のパスから検索する必要がある場合は、-sourcepath
と-classpath
の両方を使います。たとえば、
com.mypackage
をドキュメント化する場合に、そのソースファイルがディレクトリC:\user\src\com\mypackage
にあり、このパッケージがC:\user\lib
にあるライブラリに依存しているときは、次のように指定します。C:> javadoc -classpath \user\lib -sourcepath \user\src com.mypackageほかのツールと同様に、-classpath
が指定されていない場合は、CLASSPATH 環境変数が設定されていれば、Javadoc ツールはこの環境変数を使います。どちらも設定されていない場合、Javadoc ツールは現在のディレクトリからクラスを検索します。拡張機能クラスおよびブートストラップクラスに関連した、Javadoc ツールが
-classpath
を使ってユーザークラスを検索する方法についての詳細は、「クラスの検索方法」を参照してください。便宜上、
*
のベース名を含むクラスパス要素は、ディレクトリ内の拡張子.jar
または.JAR
を持つすべてのファイルのリストを指定するのと同じとみなされます (Java プログラムはこの 2 つの呼び出しを区別できない)。
たとえば、ディレクトリfoo
にa.jar
とb.JAR
が含まれている場合、クラスパス要素foo/*
はA.jar:b.JAR
に展開されます。ただし、JAR ファイルの順番は指定されません。このリストには、隠しファイルも含め、指定されたディレクトリ内のすべての JAR ファイルが含まれます。*
だけから成るクラスパスエントリは、カレントディレクトリ内のすべての JAR ファイルのリストに展開されます。CLASSPATH
環境変数も、定義時には同様に展開されます。クラスパスのワイルドカード展開は必ず、Java 仮想マシンの起動前に実行されます。したがって、System.getenv("CLASSPATH") 呼び出しのように環境に問い合わせを行わない限り、Java プログラムが展開されていないワイルドカードを認識することはありません。- -subpackages package1:package2:...
- ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソースコードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。各パッケージは最上位パッケージ (
java
) または完全指定のサブパッケージ名 (javax.swing
) になります。ソースファイルを含める必要はありません。引数は、コロンで区切られます (すべてのオペレーティングシステム)。ワイルドカードは不要です (使用不可)。パッケージの検索場所を指定するには、-sourcepath
を使用します。このオプションは、「ソースファイルの処理」で説明したとおり、ソースツリーにあるがパッケージには属していないソースファイルを処理しないので役立ちます。例を示します。
C:> javadoc -d docs -sourcepath C:\user\src -subpackages java:javax.swingこのコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。
-exclude
とともに-subpackages
を使用すると、特定のパッケージを除外できます。- -exclude packagename1:packagename2:...
- 指定されたパッケージとそのサブパッケージを
-subpackages
によって作成されたリストから無条件に除外します。過去の -subpackages オプションの指定によって組み込まれたパッケージ、または将来組み込まれるパッケージも除外の対象となります。例を示します。C:> javadoc -sourcepath C:\user\src -subpackages java -exclude java.net:java.langこのうち、java.io
、java.util
、java.math
は組み込まれますが、java.net
とjava.lang
以下のパッケージは除外されます。ただし、java.lang
のサブパッケージであるjava.lang.ref
は除外されます。- -bootclasspath classpathlist
- ブートクラスが存在するパスを指定します。ブートクラスとは、通常、Java プラットフォームのコアクラスのことです。ブートクラスパスは、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、「javac と javadoc がクラスを検索する方法」を参照してください。classpathlist 内の複数のクラスパスリストは、セミコロン (;) で区切ります。
- -extdirs dirlist
- 拡張機能クラスが存在するディレクトリを指定します。拡張機能クラスとは、Java 拡張機能機構を使うすべてのクラスです。extdirs は、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、前述の
-classpath
を参照してください。dirlist 内の複数のディレクトリは、セミコロン (;) で区切ります。- -verbose
- javadoc の実行中に詳細なメッセージを表示します。verbose オプションを指定しないと、ソースファイルのロード時、ドキュメントの生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時にメッセージが表示されます。verbose オプションを指定すると、各 Java ソースファイルの解析に要した時間 (ミリ秒単位) など、追加のメッセージが表示されます。
- -quiet
- エラーメッセージまたは警告メッセージ以外のメッセージを抑制し、警告とエラーだけが表示されるようにして、これらを特定しやすくします。バージョン文字列も抑制します。
- -breakiterator
- 英語言語というロケール固有のアルゴリズムではなく、
java.text.BreakIterator
の国際化された文境界を使用して、英文の最初の文の終わりを判断します (他のすべてのロケールはすでにBreakIterator
を使用)。「最初の文」とは、パッケージ、クラス、またはメンバーの主説明での最初の文のことです。この文は、パッケージ、クラス、またはメンバーの要約にコピーされ、アルファベット順のインデックスにコピーされます。JDK 1.2 以降、BreakIterator クラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、1.2 以降では、
-breakiterator
オプションは英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。
- 英文のデフォルトの文区切りアルゴリズム - 空白または HTML ブロックタグ (
<P>
など) が続くピリオドで停止する- breakiterator 文区切りアルゴリズム - 一般に、次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止する。このアルゴリズムでは、ほとんどの省略表記が処理される (「The serial no. is valid」は処理されるが「Mr. Smith」は処理されない)。HTML タグや、数字または記号で始まる文では停止しない。HTML タグに埋め込まれている場合でも、「../filename」の最後のピリオドで停止する
注: 1.5.0 からは、1.4.x に設けられていた breakiterator 警告メッセージを削除し、デフォルトの文区切りアルゴリズムを変更していません。つまり、\-breakiterator オプションは、1.5.0 ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャーリリース」(1.5.0) でデフォルトを変更するという、以前の目的とは逆になっています。つまり、ソースコードを変更せず、1.4.x での breakiterator 警告を除去していない場合でも、1.5.0 からは何もする必要がなく、警告は消滅しています。この逆戻りの理由は、breakiterator をデフォルトにするメリットよりも、デフォルトにするために必要となる、互換性のないソースの変更の方が負担が大きかったためです。この件で皆様に余分の手間をおかけし、混乱を招いたことをお詫びいたします。- -locale language_country_variant
重要 -Javadoc がドキュメントを生成するときに使うロケールを指定します。引数には、java.util.Locale のドキュメントで説明されているロケールの名前を指定します。たとえば、-locale
オプションは、標準ドックレットが提供するすべてのオプション、またはその他の任意のドックレットの提供するすべてのオプションより前 (左側) に指定する必要があります。そうしないと、ナビゲーションバーが英語で表示されます。このコマンド行オプションだけは、指定する順序に依存します。en_US
(英語、米国)、en_US_WIN
(Windows で使われる英語) などを指定します。ロケールを指定すると、指定したロケールのリソースファイルが Javadoc によって選択されて、メッセージ (ナビゲーションバー、リストと表の見出し、ヘルプファイルの目次、stylesheet.css のコメントなどの文字列) のために使われます。また、アルファベット順にソートされるリストのソート順、および最初の文の末尾を判別するための文の区切り文字も、指定したロケールによって決まります。ただし、このオプションは、ドキュメント化されるクラスのソースファイル内で指定されているドキュメンテーションコメントのテキストのロケールを決定するものではありません。
- -encoding name
- ソースファイルのエンコーディングの名前 (
EUCJIS/SJIS
など) を指定します。このオプションが指定されていない場合は、プラットフォームのデフォルトコンバータが使われます。-docencoding および -charset も参照してください。
- -Jflag
- javadoc を実行する実行時システム java に、flag を直接渡します。
J
と flag の間に空白を入れてはなりません。たとえば、生成ドキュメントを処理するためにシステムで 32M バイトのメモリーを確保しておく必要がある場合は、Java の-Xmx
オプションを次のように呼び出します。-Xms
は、省略可能です。これは、初期メモリーのサイズを設定するだけのオプションで、必要なメモリーの最小サイズがわかっている場合に便利です。C:> javadoc -J-Xmx32m -J-Xms32m com.mypackage使用している javadoc のバージョンを確認するには、次のように java の「-version
」オプションを呼び出します。C:> javadoc -J-version java version "1.2" Classic VM (build JDK-1.2-V, green threads, sunwjit)出力ストリームには標準ドックレットのバージョン番号が含まれます。標準ドックレットが提供するオプション
- -d directory
- 生成された HTML ファイルを保存する生成先ディレクトリを指定します(「d」は「生成先 (destination)」の意味)。このオプションを省略すると、生成されたファイルは現在のディレクトリに保存されます。値 directory には、絶対ディレクトリ、または現在の作業ディレクトリからの相対ディレクトリを指定できます。バージョン 1.4 では、javadoc を実行すると生成先ディレクトリが自動的に作成されます。
たとえば、次のコマンドは、
com.mypackage
パッケージのドキュメントを生成し、結果をC:\user\doc\
ディレクトリに保存します。C:> javadoc -d \user\doc com.mypackage- -use
- ドキュメント化されるクラスおよびパッケージごとに 1 つの「使用」ページを組み込みます。このページには、その特定のクラスまたはパッケージの API を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドが記述されます。たとえば、クラス C を例にとると、クラス C を使っているものとしては、C のサブクラス、C として宣言されているフィールド、C を返すメソッド、および、型 C のパラメータを持つメソッドとコンストラクタがあります。
たとえば、String の「使用」ページに何が表示されるかを見てみましょう。
java.awt.Font
クラスのgetName()
メソッドは、String
型を返します。したがって、getName()
はString
を使っているので、String
の「使用」ページにはこのメソッドがあります。ただし、ドキュメント化されるのは API の使用だけであって、実装はドキュメント化されません。あるメソッドが、その実装の中で
String
を使っていても、引数として文字列をとったり、文字列を返したりしない場合は、String
の「使用」とはみなされません。生成された「使用」ページにアクセスするには、目的のクラスまたはパッケージに移動し、ナビゲーションバーの「使用」リンクをクリックします。
- -version
- 生成ドキュメントに、@version のテキストを組み込みます。このテキストは、デフォルトでは省略されます。使用している Javadoc ツールのバージョンを確認するには、
-J-version
オプションを使用します。- -author
- 生成ドキュメントに、@author のテキストを組み込みます。
- -splitindex
- 索引ファイルをアルファベットごとに複数のファイルに分割し、文字ごとに 1 つのファイルと、アルファベット以外の文字で始まる索引エントリ用に 1 つのファイルを作成します。
- -windowtitle title
- HTML の <title> タグに配置するタイトルを指定します。指定したタイトルは、ウィンドウのタイトルや、このページに対して作成されたブラウザのブックマーク (お気に入り) に表示されます。このタイトルには HTML タグを含めないでください。タイトルに HTML タグが含まれていると、ブラウザがタグを正しく解釈できません。title の中で引用符を使う場合は、引用符をエスケープする必要があります。-windowtitle が省略されている場合、Javadoc ツールは、このオプションの代わりに -doctitle の値を使います。
C:> javadoc -windowtitle "Java 2 Platform" com.mypackage- -doctitle title
- 概要ファイルの最上部の近くに配置するタイトルを指定します。タイトルは中央揃えになり、レベル 1 の見出しとして、上部ナビゲーションバーのすぐ下に置かれます。title には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。title の中で引用符を使う場合は、引用符をエスケープする必要があります。
C:> javadoc -doctitle "Java<sup><font size=\"-2\">TM</font></sup>" com.mypackage- -title title
- このオプションは、現在は存在しません。Javadoc 1.2 のベータ版にだけ存在しました。このオプションは、
-doctitle
という名前に変更されました。名前を変更した理由は、このオプションが、ウィンドウのタイトルではなくドキュメントのタイトルを定義することを明確にするためです。- -header header
- 各出力ファイルの上端に配置するヘッダーテキストを指定します。ヘッダーは、上部ナビゲーションバーの右側に配置されます。header には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。header の中で引用符を使う場合は、引用符をエスケープする必要があります。
C:> javadoc -header "<b>Java 2 Platform </b><br>v1.4" com.mypackage- -footer footer
- 各出力ファイルの下端に配置するフッターテキストを指定します。フッターは、下部ナビゲーションバーの右側に配置されます。footer には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。footer の中で引用符を使う場合は、引用符をエスケープする必要があります。
- -bottom text
- 各出力ファイルの最下部に配置するテキストを指定します。このテキストは、下部ナビゲーションバーより下の、ページの最下部に配置されます。text には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。text の中で引用符を使う場合は、引用符をエスケープする必要があります。
- -link extdocURL
- javadoc により生成された既存の外部参照クラスのドキュメンテーションへのリンクを作成します。引数を 1 つとります。
- extdocURL は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。あとで例を示します。このディレクトリ内にパッケージリストファイルが存在していなければなりません。存在しない場合は、
-linkoffline
を使用します。Javadoc ツールは、パッケージリスト
ファイルからパッケージ名を読み取り、これらのパッケージをその URL にリンクします。Javadoc ツールを実行すると、作成される<A HREF>
リンク内に extdocURL の値がそのままコピーされます。したがって、extdocURL はファイルへの URL ではなく「ディレクトリへの URL」でなければなりません。extdocURL への絶対リンクを使用すると、ユーザーのドキュメントを任意の Web サイト上のドキュメントにリンクできます。相対位置へリンクするだけでよい場合は相対リンクを使用できます。相対リンクを使用する場合、
-d
を使って、生成先ディレクトリからリンクされるパッケージのあるディレクトリの相対パスを指定する必要があります。通常、絶対リンクを指定する場合は、
http:
リンクを使用します。Web サーバーを持たないファイルシステムにリンクする場合は、file:
リンクを使用できます。ただし、この方法は、すべてのユーザーが生成された同じファイルシステムを共有するドキュメントにアクセスする必要がある場合以外は使用しないでください。すべての場合、すべてのオペレーティングシステムで、絶対 URL と相対 URL、「http:」ベースと「file:」ベースにかかわらず、スラッシュを区切り文字として使用します (URL Memo で指定)。
- http: ベースの絶対リンク:
-link http://<host>/<directory>/<directory>/.../<name>
- file: ベースの絶対リンク:
-link file://<host>/<directory>/<directory>/.../<name>
- 相対リンク:
-link <directory>/<directory>/.../<name>
javadoc の実行時に複数の
-linkoffline または -link の選択-link
オプションを指定して、複数のドキュメントへのリンクを作成することもできます。-link
を使用する場合:次のような場合は、
- 外部 API ドキュメントへの相対パスを使用する場合
- 外部 API ドキュメントへの絶対 URL を使用する場合 (プログラムがその URL に接続し、読み取りを行うことがシェルによって許可されている場合)
-linkoffline
オプションを使用します。
- 外部 API ドキュメントへの絶対 URL を使用する場合 (プログラムがその URL に接続し、読み取りを行うことがシェルによって許可されていない場合)このような状況は、リンク先のドキュメントがファイアウォールの向こう側にある場合に発生します。
外部ドキュメントへの絶対リンクの使用例 -
http://java.sun.com/j2se/1.5.0/docs/api
内のjava.lang
、java.io
、その他の Java 2 プラットフォームパッケージにリンクしたい場合があります。次のコマンドは、com.mypackage
パッケージのドキュメントと Java 2 プラットフォームパッケージへのリンクを生成します。生成されたドキュメントには、たとえばクラスツリー内のObject
クラスへのリンクが含まれています。(-sourcepath
や-d
などの他のオプションは表示されません。)C:> javadoc -link http://java.sun.com/j2se/1.5.0/docs/api com.mypackage外部ドキュメントへの相対リンクの使用例 - 2 つのパッケージがあり、そのドキュメントが Javadoc ツールを複数回実行した結果生成されたものであるとします。さらに、これらのドキュメントが相対パスで分割されているとします。この例の場合、2 つのパッケージは、API であるcom.apipackage
とSPI (サービスプロバイダインタフェース) であるcom.spipackage
です。ドキュメントの格納先はdocs/api/com/apipackage
パッケージとdocs/spi/com/spipackage
パッケージです。API パッケージのドキュメントがすでに生成されていて、現在のディレクトリがdocs
である場合、次のコマンドを実行することによって、この API ドキュメントへのリンクを持つ SPI パッケージをドキュメント化します。C:> javadoc -d ./spi -link ../api com.spipackage
-link
引数は、生成先ディレクトリ (docs/spi
) の相対パスです。詳細 -
-link
オプションを使うと、「コードからは参照されていても、Javadoc の今回の実行ではドキュメント化されない」というクラスにリンクできるようになります。リンクから有効なページに移動できるようにするには、それらの HTML ページがある場所を調べ、その場所を extdocURL に指定する必要があります。このオプションを使うと、たとえば、サードパーティーのドキュメントから、http://java.sun.com
にあるjava.*
のドキュメントにリンクすることができます。今回の実行で Javadoc によって生成されるドキュメント内の API だけを対象にリンクを作成する場合は、
-link
オプションを省略します。-link
オプションが指定されていない場合、Javadoc ツールは、外部参照されたドキュメントへのリンクを作成しません。これは、そのドキュメントが存在するかどうか、および存在する場合はその場所を判別できないからです。このオプションでは、生成ドキュメント内の複数の場所にリンクを作成できます。
また、このオプションを使うと、複数のパッケージ群の間にクロスリンクを作成することもできます。つまり、ある一式のパッケージに対して javadoc を実行したあと、別の一式のパッケージに対して javadoc を実行し、これら 2 つのパッケージ群の間にクロスリンクを作成できます。
クラスの参照方法 - 外部参照クラスへのリンクを、テキストラベルだけではなく実際に表示するには、次の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するだけでは十分ではありません。
import
文または宣言で参照する必要があります。次に、クラスjava.io.File
を参照する方法の例を示します。
- すべての種類の
import
文の場合: ワイルドカードによるインポート、名前による明示的なインポート、またはjava.lang.*
に対する自動的なインポート。たとえば、次のようにすれば十分です。import java.io.*;
1.3.x および 1.2.x では、名前による明示的なインポートだけです。ワイルドカードによるインポート文も、自動インポートjava.lang.*
も使用できません。- 宣言の場合:
void foo(File f) {}
この参照を使用し、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースのリターンタイプまたはパラメータタイプに置くか、implements
、extends
またはthrows
文に置きます。この結果、
-link
オプションを使用しても、この制限のために誤って表示されない多くのリンクが多数発生する可能性があります。テキストはハイパーテキストリンクが付けられずに表示されます。これらのリンクが表示する警告から、このリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するためのもっとも安全な方法は上で説明したとおり、当該のクラスをインポートすることです。パッケージリスト -
-link
オプションは、package-list
という名前のファイルを要求します。このファイルは、Javadoc ツールによって生成され、-link
によって指定した URL に存在します。package-list
ファイルは、その場所にあるドキュメント化されたパッケージの名前のリストが入った単純なテキストファイルです。前の例では、Javadoc ツールは指定された URL にあるpackage-list
という名前のファイルを探し、パッケージ名を読み込んで、その URL にあるそれらのパッケージへのリンクを作成しました。たとえば、Java プラットフォーム v5.0 API のパッケージリストは
http://java.sun.com/j2se/1.5.0/docs/api/package-list
にあり、次のような内容で始まっています。java.applet java.awt java.awt.color java.awt.datatransfer java.awt.dnd java.awt.event java.awt.font その他 ...
-link
オプションを指定せずに javadoc を実行した場合、外部参照クラスに属する名前を見つけると、javadoc はその名前をリンクを持たない形で出力します。一方、-link
オプションを指定した場合は、指定した extdocURL にあるpackage-list
ファイルから該当するパッケージ名が検索されます。パッケージ名が見つかると、extdocURL が名前の前に付加されます。すべてのリンクが正しく機能するためには、外部参照のすべてのドキュメントが、指定した URL に存在していなければなりません。Javadoc ツールは、指定された package-list が存在するかどうかを調べるだけで、指定された URL に目的のページが存在するかどうかはチェックしません。
複数のリンク - 複数の
-link
オプションを指定すると、生成された任意の数の外部ドキュメントに対してリンクを設定できます。Javadoc 1.2 には、複数の-link
オプションを指定できないというバグがあります。これは 1.2.2 で修正されました。リンクする外部ドキュメントごとに、次のように別々のリンクオプションを指定します。
C:> javadoc -link
extdocURL1-link
extdocURL2...-link
extdocURLncom.mypackage
extdocURL1、extdocURL2、... extdocURLn は、それぞれ外部ドキュメントのルートを指し、各ルートには
package-list
という名前のファイルが入っています。クロスリンク - まだ生成されていない 2 つ以上のドキュメントをクロスリンクする場合は、「ブートストラップ」が必要になります。つまり、どのドキュメントについても
package-list
が存在していない場合は、最初のドキュメントに対して javadoc ツールを実行する時点で、2 番目のドキュメントのpackage-list
がまだ存在していません。したがって、外部リンクを作成するには、2 番目のドキュメントを生成したあとで、最初のドキュメントを生成し直す必要があります。この場合、最初のドキュメント生成の目的は、そのドキュメントの
package-list
を作成することです。パッケージ名をすべて把握している場合は、package-list を手動で作成することもできます。次に、2 番目のドキュメントとその外部リンクを生成します。必要な外部のpackage-list
ファイルが存在しない場合、Javadoc ツールは警告を表示します。- -linkoffline extdocURL packagelistLoc
- このオプションは、
-link
オプションを変えたものです。どちらも、javadoc によって生成された外部参照クラスのドキュメントへのリンクを作成します。Javadoc ツール自体がオフラインになっているとき (Web 接続を使ってドキュメントにアクセスできないとき)、Web 上のドキュメントにリンクするには、-linkoffline
オプションを使用します。厳密には、外部ドキュメントの
package-list
ファイルにアクセスできないとき、またはこのファイルが extdocURL で指定された場所とは異なる場所 (通常、packageListLoc で指定可能なローカルな場所) に存在するとき、-linkoffline
を使用します。したがって、extdocURL に WWW 上でしかアクセスできない場合は、-linkoffline
を指定することにより、ドキュメントの生成時に javadoc ツールが Web に接続できなければならないという制約がなくなります。さらに、ドキュメントを更新するための「ハッキング」としての使用も可能です。パッケージのセット全体に対して javadoc を実行したあと、変更した一部のパッケージだけに対して javadoc を実行します。こうして、更新されたファイルを、オリジナルのファイルセットに挿入できるようにします。例をあとで示します。
-linkoffline
オプションは引数を 2 つ取ります。最初の引数は<a href>
リンクに組み込まれる文字列を指定する引数、2 番目の引数はpackage-list
の検索場所を指定する引数です。
- extdocURL は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。相対リンクを使用する場合、
-d
を使って、生成先ディレクトリからリンクされるパッケージのルートの相対パスを指定する必要があります。詳細は、-link
オプションの extdocURL を参照してください。- packagelistLoc には、外部ドキュメントの
package-list
ファイルが入っているディレクトリのパスまたは URL を指定します。これは、URL (http: または file:)または file:)とファイルパスのどちらでもかまいません。とファイルパスのどちらでもかまいません。 また、絶対パスと相対パスのどちらでも指定できます。相対パスの場合は、javadoc が実行されるカレントディレクトリからの相対パスとして指定します。package-list
というファイル名は含めないでください。javadoc の 1 回の実行で、複数の
-linkoffline
オプションを指定できます。1.2.2 より前は、複数のオプションを指定することはできませんでした。外部ドキュメントへの絶対リンクの使用例 -
http://java.sun.com/j2se/1.4/docs/api
内のjava.lang
、java.io
、その他の Java 2 プラットフォームパッケージにリンクしたいが、シェルから Web にアクセスできない場合があります。この場合は、ブラウザでhttp://java.sun.com/j2se/1.4/docs/api/package-list
にあるpackage-list
ファイルを開き、ローカルディレクトリに保存します。さらに、2 番目の引数 packagelistLoc にこのローカルコピーの場所を指定します。この例では、パッケージリストファイルはカレントディレクトリ ".
" に保存されています。次のコマンドは、Java 2 プラットフォーム API へのリンクを含む、com.mypackage
パッケージのドキュメントを生成します。生成されたドキュメントには、たとえばクラスツリー内のObject
クラスへのリンクが含まれています。(-sourcepath
などの他の必要なオプションは表示されません。)C:> javadoc -linkoffline http://java.sun.com/j2se/1.5.0/docs/api . com.mypackage外部ドキュメントへの相対リンクの使用例 - 通常、
-linkoffline
に相対パスを指定することはありません。-link
で同じことができるからです。-linkoffline
を使用する際、package-list
には通常ローカルのファイルを指定します。相対リンクを使用する際も、リンク先のファイルには通常ローカルのファイルを指定します。したがって、-linkoffline
の 2 つの引数に別々のパスを指定する必要はありません。2 つの引数が同一である場合は、-link
を使用できます。-link
の相対リンクの例を参照してください。
package-list
ファイルを手動で作成 -package-list
ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルを自分で作成し、packagelistLoc でそのパスを指定することができます。com.apipackage
が最初に生成され、com.spipackage
のパッケージリストが存在しないという前出の例を参照してください。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。また、package-list
ファイルが生成されない Javadoc 1.0 や 1.1 などで生成されたパッケージ向けにpackage-list
ファイルを作成するときにも、この方法を利用します。同様に、2 つの会社が未公開のpackage-list
ファイルを共有することもできるため、クロスリンクを設定したドキュメントを同時にリリースすることも可能です。複数のドキュメントへのリンク -
-linkoffline
は、参照先の生成ドキュメントごとに 1 つずつ指定します。次の例では、わかりやすくするためにオプションごとに行を分けています。
C:> javadoc -linkoffline
extdocURL1 packagelistLoc1\
extdocURL2 packagelistLoc2
-linkoffline\
...ドキュメントの更新 - 前述の
-linkoffline
オプションのもうひとつの用途は、プロジェクトに大量のパッケージが含まれていて、すでにツリー全体に対して javadoc の実行が完了している場合に、次の実行では、少量の変更を手早く加えたあと、ソースツリーのごく一部に対してだけ javadoc を再実行する場合に便利です。これは、ドキュメンテーションコメントに対してだけ変更を加え、宣言は変更しない場合にのみ正しく処理されるので、ハッキングのようなものです。ソースコードの宣言を追加、削除、または変更した場合は、索引、パッケージツリー、継承されるメンバーのリスト、「使用」ページなどの場所で、リンクが壊れることがあります。まず、今回の実行で使用する新しい生成先ディレクトリ (
update
) を作成します。元の生成先ディレクトリの名前がhtml
だとします。もっとも単純な例では、html
ディレクトリの親ディレクトリに移動 (cd) します。-linkoffline
の最初の引数にカレントディレクトリ "." を指定し、2 番目の引数にhtml
への相対パスを指定します。ここで、package-list
が検索されます。更新対照のパッケージのパッケージ名だけを指定してください。C:> javadoc -d update -linkoffline . html com.mypackageJavadoc ツールの実行が完了したら、生成されたクラスページをupdate\com\package
(概要、索引ではない) にコピーし、html\com\package
内の元のファイルを上書きします。- -linksource
- 各ソースファイル (行番号付き) の HTML バージョンを作成し、標準 HTML ドキュメントからソースファイルへのリンクを追加します。リンクは、ソースファイル内に宣言されているクラス、インタフェース、コンストラクタ、メソッド、フィールドに対して作成されます。デフォルトコンストラクタ、生成されたクラスに対しては作成されません。
このオプションは、
-public
、-package
、-protected
、-private
の各オプションとは関係なく、非公開のクラス、フィールド、非公開のメソッドの本体をはじめとする組み込まれたソースファイル内のすべての非公開実装の詳細を公開します。-private
オプションを指定しないかぎり、非公開のクラスやインタフェースの一部には、リンクを介してアクセスできないことがあります。各リンクは、その宣言内の識別子名の上に作成されます。たとえば、
Button
クラスのソースコードヘのリンクは、「Button」という語の上に作成されます。public class Button extends Component implements AccessibleButton クラスのgetLabel()
メソッドのソースコードへのリンクは、「getLabel」という語の上に作成されます。public String getLabel()- -group groupheading packagepattern
:
packagepattern:
...- 概要ページの複数のパッケージを、指定したグループに分けて、グループごとに表を作成します。各グループは、それぞれ別の
-group
オプションで指定します。これらのグループは、コマンド行で指定した順序でページに表示されます。各グループ内では、パッケージがアルファベット順に並べられます。指定した-group
オプションごとに、packagepattern 式のリストと一致するパッケージが、見出し groupheading を持つ 1 つの表にまとめて表示されます。
- groupheading には、任意のテキストを指定でき、空白を含めることができます。指定したテキストは、グループの表見出しになります。
- packagepattern には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (
*
) を指定できます。アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。ワイルドカードとして指定できるのは、アスタリスクだけです。1 つのグループには、コロン (:
) で区切って複数のパターンを含めることができます。注: パターンやパターンリスト内でアスタリスクを使う場合は、"java.lang*:java.util"
のように、パターンリストを引用符で囲む必要があります。
-group
オプションが指定されていない場合は、すべてのパッケージが、「パッケージ」という見出しの 1 つのグループに入れられます。ドキュメント化されるパッケージの中に、指定したグループのどのグループにも入らないパッケージがある場合、このようなパッケージは「その他のパッケージ」という見出しを持つ独立したグループに入れられます。たとえば、次のようにオプションを指定すると、ドキュメント化される 5 つのパッケージは、コアパッケージ、拡張機能パッケージ、およびその他のパッケージに分けられます。「java.lang*」では、最後のドットを指定していないことに注目してください。「java.lang.*」のようにドットを入れると、java.lang パッケージは除外されることになります。
C:> 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
- その他のパッケージ
java.new
- -nodeprecated
- 推奨されない API をドキュメントに生成しないようにします。このオプションを指定すると、-nodeprecatedlist オプションを指定した場合と同じ効果があることに加えて、ドキュメントのほかの部分全体でも、推奨されない API が生成されません。このオプションは、コードを記述しているとき、推奨されないコードによって気を散らされたくない場合に便利です。
- -nodeprecatedlist
- 推奨されない API のリストを含むファイル (deprecated-list.html)、およびナビゲーションバーのそのページへのリンクが生成されないようにします。ただし、ドキュメントのほかの部分では、推奨されない API が生成されます。このオプションは、推奨されない API がソースコードに含まれておらず、ナビゲーションバーをすっきりと見せたい場合に便利です。
- -nosince
- 生成ドキュメントから、@since タグに対応する「導入されたバージョン」 セクションを省略します。
- -notree
- 生成されるドキュメントからクラスおよびインタフェースの階層ページを省略します。これらのページには、ナビゲーションバーの「ツリー」ボタンからアクセスできます。デフォルトでは、階層が生成されます。
- -noindex
- 生成ドキュメントから、索引を省略します。デフォルトでは、索引が生成されます。
- -nohelp
- 出力の各ページの最上部と最下部にあるナビゲーションバーから「ヘルプ」リンクを省略します。
- -nonavbar
- 生成されるページの最上部と最下部に表示されるナビゲーションバー、ヘッダー、およびフッターを生成しないようにします。このオプションは、bottom オプションには影響を与えません。
-nonavbar
オプションは、印刷するためだけにファイルを PostScript または PDF に変換する場合など、内容だけが重要で、ナビゲーションの必要がない場合に便利です。- -helpfile path\filename
- 上部と下部のナビゲーションバーの「ヘルプ」リンクのリンク先となる代替ヘルプファイル path\filename のパスを指定します。このオプションが指定されていない場合、Javadoc ツールは、ハードコードされているヘルプファイル
help-doc.html
を自動的に作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。filename にはどんなファイル名でも指定でき、help-doc.html
には限定されません。Javadoc ツールは、このオプションでの指定に従って、ナビゲーションバーにあるリンクに調整を加えます。例を示します。C:> javadoc -helpfile C:\user\myhelp.html java.awt- -stylesheetfile path\filename
- 代替 HTML スタイルシートファイルのパスを指定します。このオプションが指定されていない場合、Javadoc ツールは、ハードコードされているスタイルシートファイル
stylesheet.css
を自動的に作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。filename にはどんなファイル名でも指定でき、stylesheet.css
には限定されません。例を示します。C:> javadoc -stylesheetfile C:\user\mystylesheet.css com.mypackage- -serialwarn
- @serial タグがない場合は、コンパイル時に警告を生成します。デフォルトでは、Javadoc 1.2.2 以降のバージョンでは、直列化の警告は生成されません1.2.2 より前の初期バージョンでは、警告が生成されます。このオプションを使用すると、直列化の警告が表示されるので、デフォルトの直列化可能フィールドと
writeExternal
メソッドを適切にドキュメント化するのに役立ちます。- -charset name
- このドキュメント用の HTML 文字セットを指定します。この名前は、IANA Registry で与えられた、推奨される MIME 名でなければなりません。例を示します。
C:> javadoc -charset "iso-8859-1" mypackage生成されるすべてのページの先頭に、次の行が挿入されます。<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">この META タグについては、HTML の標準 (4197265 および 4137321) を参照してください。-encoding および -docencoding も参照してください。
- -docencoding name
- 生成される HTML ファイルのエンコーディングを指定します。この名前は、IANA Registry で与えられた、推奨される MIME 名でなければなりません。このオプションを省略しながら -encoding を使用した場合、生成される HTML ファイルのエンコードは、-encoding によって決められます。例:
% javadoc -docencoding "ISO-8859-1" mypackage-encoding および -charset も参照してください。- -keywords
- HTML メタキーワードタグを、クラスごとに生成されるファイルに追加します。これらのタグは、メタタグを検索するサーチエンジンがページを見つける場合に役立ちます。インターネット全体を検索する多くのサーチエンジンは、ページがメタタグを誤用しているため、メタタグを調べません。一方、検索を自身の Web サイトに限定している企業では、サーチエンジンがメタタグを調べることによってメリットを得られます。
メタタグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同じであるため含まれません。たとえば、クラス String は次のキーワードで開始します。
<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"
- Javadoc ツールがドキュメンテーションコメント内の引数を 1 つ取る単純なカスタムブロックタグ
@
tagname を解釈できるようにします。これにより、Javadoc ツールはタグ名の「スペルチェック」を行うことができるので、ソースコード内のすべてのカスタムタグに-tag
オプションを組み込むことをお勧めします。今回の実行で出力されないタグは、X
を付けて無効にします。コロン (
:
) は常に区切り文字になります。tagname でコロンを使用するには、「タグ名でのコロンの使用」を参照してください。
-tag
オプションは、タグの見出し「taghead」を太字で出力します。その次の行には、このオプションの引数で指定したテキストが続きます。以下の例を参照してください。ブロックタグと同様、この引数のテキストにはインラインタグを含めることができます。このインラインタグも解釈されます。出力は、引数を 1 つ取る標準のタグ (@return
、@author
など) の出力とよく似ています。taghead を省略すると、tagname が見出しとして表示されます。タグの配置 - 引数の
Xaoptcmf
部分は、ソースコード内のタグを配置できる位置と、X
を使ってこのタグを無効にできるかどうかを特定します。タグの配置位置を制限しない場合はa
を指定します。それ以外の文字の組み合わせも可能です。シングルタグの例 - ソースコード内の任意の位置で使用で気るタグのタグオプションの例を示します。
-tag todo:a:"To Do:"@todo をコンストラクタ、メソッド、フィールドのみで使用する場合は、以下のオプションを使用します。-tag todo:cmf:"To Do:"上の例の最後のコロン (:
) は、パラメータ区切り子ですが、見出しテキストの一部になっています (以下の例を参照)。次の例のように、@todo
タグを含むソースコードでは、いずれかのタグオプションを使用します。@todo The documentation for this method needs work.この行は、次のような出力を生成します。タグ名にコロンを使用する - コロン (:) をバックスラッシュでエスケープすると、コロンをタグ名に使用することができます。このドキュメンテーションコメントの中では、次のように使用します。
- To Do:
- The documentation for this method needs work.
/** * @ejb:bean */でこのタグオプションを使用すると、-tag ejb\:bean:a:"EJB Bean:"タグ名のスペルチェック (タグの無効化) - ソースコード内に配置した一部のカスタムタグの出力を抑制したい場合があります。この場合も、ソースコード内にすべてのタグを配置し、出力を抑制しないタグを有効にし、出力を抑制するタグを無効にします。タグを無効にするには、X
を指定します。指定しないと、そのタグは有効になります。これにより、Javadoc ツールは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。未知のタグを検出した場合、Javadoc ツールは警告を出力します。すでに配置されている値に
X
を追加できます。こうしておけば、X
を削除するだけでタグを有効にすることができます。たとえば、@todo タグの出力を抑制したい場合、次のように指定します。-tag todo:Xcmf:"To Do:"さらに単純な指定方法もあります。-tag todo:X構文
-tag todo:X
は、@todo
が taglet で定義されている場合も有効です。タグの順序 -
-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:Xjavadoc がドキュメンテーションコメントを解析する際に検出されたタグのうち、標準タグでも
-tag
や-taglet
で渡されるタグでもないものは、未知のタグの見なされます。この場合、警告がスローされます。標準タグは、最初、デフォルトの順序でリスト内に内部的に格納されます。
-tag
オプションを使用すると、このリストに追加されるタグ、すなわち標準タグの位置がデフォルトの位置から移動します。つまり、標準タグに-tag
オプションを付けなければ、これらはデフォルトの位置に配置されたままになります。競合の回避 - 固有の名前空間を細かく分けるには、パッケージに使用されている
com.mycompany.todo
という名前のように、ドット (.) を区切り記号とする名前を使います。Sun は、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Sun が提供する同じ名前のタグの動作をオーバーライドします。つまり、ユーザーが@todo
という名前のタグまたはタグレットを作成している場合、Sun があとから同じ名前の標準タグを作成しても、そのタグまたはタグレットは元の動作を保持します。注釈 vs. Javadoc タグ - 一般に、追加する必要のあるマークアップが、ドキュメンテーションに影響を与えたりドキュメンテーションを生成したりするためのものである場合、そのマークアップは javadoc タグにすべきです。それ以外の場合は注釈にすべきです。「Comparing Annotations and Javadoc Tags」を参照してください。
-taglet オプションを使用して、より複雑なブロックタグやカスタムインラインタグを 作成することができます。
- -taglet class
- そのタグのドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。クラスの完全指定名を指定してください。このタグレットは、カスタムタグのテキスト引数の数も定義します。タグレットは、これらの引数を受け付け、処理し、出力を生成します。外部ドキュメントとサンプルタグレットについては、以下を参照してください。
タグレットは、ブロックタグまたはインラインタグで便利です。タグレットは任意の数の引数をとることができます。また、テキストを太字にする、箇条書きを作成する、テキストをファイルに書き出す、その他のプロセスを開始するなどのカスタム動作を実装できます。
タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガーするなどの副作用は得られます。
タグレットのパスを指定するには、
-tagletpath
オプションを使用します。以下は、生成されるページの「Parameter」と「Throws」の間に「To Do」タグレットを挿入する例です。-taglet com.sun.tools.doclets.ToDoTaglet -tagletpath /home/taglets -tag return -tag param -tag todo -tag throws -tag see
-tag
オプションの代わりに-taglet
オプションを使用することもできますが、読みやすさを考慮するなら、-tag
オプションを使用したほうがよいでしょう。- -tagletpath tagletpathlist
- taglet クラスファイル (.class) の検索パスを指定します。tagletpathlist には、コロン (
:
) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。- -docfilessubdirs
doc-files
ディレクトリの深いコピーを有効にします。つまり、コピー先には、サブディレクトリとすべてのコンテンツがコピーされます。たとえば、doc-files/example/images
ディレクトリとその中のファイルがコピーされます。ここでも、サブディレクトリを除外する指定が可能です。- -excludedocfilessubdir name1:name2...
- 所定の名前の
doc-files
サブディレクトリを除外します。これにより、SCCS とその他のソースコード制御サブディレクトリのコピーを防ぎます。- -noqualifier
all
| packagename1:packagename2:...- 出力されるクラス名の先頭のパッケージ名 (パッケージ修飾子) を省略します。
-noqualifier
の引数としてall
を指定した場合、すべてのパッケージ修飾子がすべて省略されます。削除する複数のパッケージ名をコロンで区切って、ワイルドカードとともに指定することもできます。クラスまたはインタフェース名が表示される位置からパッケージ名が削除されます。次の例では、すべてのパッケージ修飾子を省略します。
-noqualifier all次の例では、パッケージ修飾子 java.lang および java.io を省略します。-noqualifier java.lang:java.io次の例では、java で始まるパッケージ修飾子と com.sun というサブパッケージ (javax ではない) を省略します。-noqualifier java.*:com.sun.*パッケージ修飾子が上記の動作に従って表示される場合、名前は適切に短くされます。詳細は「名前の表示方法」を参照してください。この規則は、-noqualifier
を使用したかどうかにかかわらず有効です。- -notimestamp
- タイムスタンプが抑制されます。各ページ先頭近くにある、生成された HTML 内の HTML コメントでタイムスタンプが隠されます。Javadoc を 2 つのソースベースで実行し、それらに対して diff を実行するときにこのオプションを使用すると、タイムスタンプによって diff が発生しなくなるので便利です (このオプションを使用しないと、各ページで diff になります)。タイムスタンプには Javadoc のバージョン番号が含まれており、次のようになります。
<!-- Generated by javadoc (build 1.5.0-internal) on Tue Jun 22 09:57:24 PDT 2004 -->- -nocomment
- 主説明およびすべてのタグを含むコメント本文全体を抑制し、宣言だけを生成します。このオプションにより、元は異なる目的のためだったソースファイルを再利用し、新しいプロジェクトの早い段階でスケルトン HTML ドキュメントを作成できるようになりました。
javadoc
のコマンド行を短くしたり簡潔にしたりするために、javadoc
コマンドに対する引数 (-J
オプションを除く) が入った 1 つ以上のファイルを指定することができます。このことを利用すれば、どのオペレーティングシステム上でも、任意の長さの javadoc コマンドを作成できます。引数ファイルには、javadoc のオプションとソースファイル名を自由に組み合わせて記述できます。ファイル内の各引数は、スペースまたは改行で区切ります。ファイル名に空白が含まれている場合は、そのファイル名全体を二重引用符で囲み、円記号を二重にします (
"My Files\\Stuff.java"
)。引数ファイル内のファイル名は、現在のディレクトリから見た相対パスになります。引数ファイルの位置から見た相対パスではありません。引数ファイル内のファイル名リストでは、ワイルドカード (*) は使用できません。たとえば、
*.java
とは指定できません。引数ファイル内の引数で @ 文字を使用して、複数のファイルを再帰的に解釈することはサポートされていません。また、-J
オプションもサポートされていません。このオプションは起動ツールに渡されますが、起動ツールでは引数ファイルをサポートしていないからです。javadoc を実行するときに、各引数ファイルのパスとファイル名の先頭に @ 文字を付けて渡します。javadoc は、@ 文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。
引数ファイルを 1 つ指定する例
argfile
という名前の引数ファイルにすべての Javadoc 引数を格納し、次のように使用することができます。C:> javadoc @argfileこの引数ファイルには、次の例で示されている 2 つのファイルの内容を両方とも入れることができます。引数ファイルを 2 つ指定する例
Javadoc オプション用に 1 つ、ソースファイル名用に 1 つというように、2 つの引数ファイルを作成し、次のようにして使用することができます。なお、このあとのリストでは、行の継続文字を使用していません。以下の内容を含む
options
という名前のファイルを作成します。-d docs-filelist -use -splitindex -windowtitle 'Java 2 Platform v1.3 API Specification' -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform 5.0 API Specification' -header '<b>Java 2 Platform </b><br><font size="-1">5.0</font>' -bottom 'Copyright 1993-2000 Sun Microsystems, Inc. All Rights Reserved.' -group "Core Packages" "java.*" -overview \java\pubs\ws\1.5\src\share\classes\overview-core.html -sourcepath \java\pubs\ws\1.5\src\share\classes以下の内容を含む
packages
という名前のファイルを作成します。com.mypackage1 com.mypackage2 com.mypackage3そのあと、次のコマンドを使用して javadoc を実行します。C:> javadoc @options @packagesパス付きの引数ファイルの例
引数ファイルには、パスを指定できます。ただし、そのファイル内に指定されたファイル名は、現在の作業ディレクトリから見た相対パスになります。つまり、下の例の場合は、path1
やpath2
から見た相対パスではありません。C:> javadoc @path1\options @path2\packagesオプションの引数の例
次に、Javadoc オプションに対する引数だけを引数ファイルに格納する例を示します。ここでは、
-bottom
を例に取り上げます。そのオプションには、かなり長い引数を指定することがあるからです。まず、このオプションのテキスト引数になる次のような内容を含む、bottom
という名前のファイルを作成します。'<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>'そのあと、次のようにして Javadoc ツールを実行します。C:> javadoc -bottom @bottom @packagesまた、引数ファイルの先頭に-bottom
オプションを組み込んでおけば、次のようにして実行できます。C:> javadoc @bottom @packages
バージョン番号 - javadoc のバージョン番号を判別するには、javadoc -J-version を使用します。出力ストリームには標準ドックレットのバージョン番号が含まれます。-quiet
で無効にできます。公開プログラムインタフェース - Java 言語で記述されたプログラムから Javadoc ツールを起動するとき使用します。このインタフェースは
com.sun.tools.javadoc.Main
にあります (javadoc は再入可能)。詳細は、「標準ドックレット」を参照してください。ドックレットの実行 - 下記の説明は、標準 HTML ドックレットを呼び出すためのものです。カスタムドックレットを呼び出すには、-doclet および -docletpath オプションを使用します。特定のドックレットを実行した完全な例については、MIF Doclet のドキュメントを参照してください。
javadoc は、パッケージ全体に対して実行することも、個々のソースファイルに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。次の例では、ソースファイルはC:\home\src\java\awt\*.java
にあります。生成先ディレクトリはC:\home\html
です。1 つ以上のパッケージのドキュメント化
パッケージをドキュメント化するには、そのパッケージのソースファイル (*.java
) が、パッケージと同じ名前を持つディレクトリ内に存在していなければなりません。パッケージ名が複数の識別子で構成されている (java.awt.color
のように、各識別子はドットで区切られている) 場合は、後続の各識別子が下位のサブディレクトリに対応していなければなりません (java/awt/color
など)。1 つのパッケージのための複数のソースファイルを、異なる場所にある 2 つのディレクトリツリーに分けて格納することも可能です (src1/java/awt/color
とsrc2/java/awt/color
など)。ただし、その場合は、-sourcepath
によって、その両方の場所を指定しなければなりません。javadoc を実行するには、
cd
コマンドを使ってディレクトリを変更するか、または-sourcepath
オプションを使用します。以下の例では、両方の方法について説明します。Result: 上記のどのケースでも、パッケージ
- ケース 1 – 1 つ以上のパッケージからの起動を再帰的に実行 - この例では javadoc が任意のディレクトリから実行できるように、-sourcepath を使用し、再帰的処理のために -subpackages (1.4 の新オプション) を使用します。これは、
java
のサブパッケージ (java.net
およびjava.lang
をルートとするパッケージを除く) を処理します。ただし、java.lang
のサブパッケージであるjava.lang.ref
は除外されます。% javadoc -d \home\html -sourcepath \home\src -subpackages java -exclude java.net:java.langその他のパッケージツリーを巡回するには、
java:javax:org.xml.sax
のように、-subpackages
引数にその名前を追加します。- ケース 2 - ルートソースディレクトリに移ってから明示的なパッケージに対して実行 - 完全指定のパッケージ名の親ディレクトリに移ります。次に、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。
C:> cd C:\home\src\ C:> javadoc -d C:\home\html java.awt java.awt.event- ケース 3 - 任意のディレクトリから実行。ソースファイルは 1 つのディレクトリツリー内にある - このケースでは、現在のディレクトリがどこであってもかまいません。最上位パッケージの親ディレクトリを
-sourcepath
に指定し、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event- ケース 4 - 任意のディレクトリから実行。ソースファイルは複数のディレクトリツリー内にある - これはケース 3 と似ていますが、パッケージが複数のディレクトリツリーに存在します。それぞれのツリーのルートへのパスを
-sourcepath
に指定し (コロンで区切る)、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。1 つのパッケージのすべてのソースファイルが、1 つのルートディレクトリの下に存在しなければならない、ということはありません。ソースパスとして指定された場所のどこかで見つかれば十分です。C:> javadoc -d C:\home\html -sourcepath C:\home\src1;C:\home\src2 java.awt java.awt.eventjava.awt
とjava.awt.event
の public および protected のクラスとインタフェースについて、HTML 形式のドキュメントが生成され、指定された生成先ディレクトリ (\home\html
) に HTML ファイルが保存されます。2 つ以上のパッケージが生成されているので、ドキュメントは、パッケージのリスト、クラスのリスト、およびメインのクラスページという 3 つのフレームを持つことになります。1 つ以上のクラスのドキュメント化
また、1 つ以上のソースファイル (.java
) を渡して、Javadoc ツールを実行することもできます。javadoc は、次の 2 つのどちらかの方法で実行できます。1 つは、cd
コマンドでディレクトリを変更する方法、もう 1 つは.java
ファイルへのパスを完全指定する方法です。相対パスは、現在のディレクトリを起点とします。ソースファイル名を渡すときは、-sourcepath
オプションは無視されます。アスタリスク (*) のようなコマンド行ワイルドカードを使用すると、クラスのグループを指定できます。
- ケース 1 - ソースディレクトリに移る -
.java
ファイルのあるディレクトリに移ります。次に、ドキュメント化する 1 つ以上のソースファイルの名前を指定して javadoc を実行します。C:> cd C:\home\src\java\awt C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.javaこの例では、クラスButton
とCanvas
、および名前がGraphics
で始まるクラスについて、HTML 形式のドキュメントが生成されます。パッケージ名ではなくソースファイルが javadoc に引数として渡されているので、ドキュメントは、クラスのリストとメインページという 2 つのフレームを持つことになります。- ケース 2 - パッケージのルートディレクトリに移る - これは、同じルート内にある複数のサブパッケージの個々のソースファイルをドキュメント化する場合に便利です。パッケージのルートディレクトリに移り、各ソースファイルを、ルートからのパスとともに指定します。
C:> cd C:\home\src C:> javadoc -d \home\html java\awt\Button.java java\applet\Applet.javaこの例では、Button
クラスおよびApplet
クラスについて、HTML 形式のドキュメントが生成されます。- ケース 3 - 任意のディレクトリから - このケースでは、現在のディレクトリがどこであってもかまいません。ドキュメント化する
.java
ファイルへの絶対パス (または、現在のディレクトリからの相対パス) を指定して javadoc を実行します。C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.javaこの例では、クラスButton
と、名前がGraphics
で始まるクラスについて、HTML 形式のドキュメントが生成されます。パッケージとクラスのドキュメント化
パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に前述の 2 つの例を組み合わせた例を示します。sourcepath
は、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt C:\home\src\java\applet\Applet.javaこの例では、パッケージjava.awt
と、クラスApplet
について、HTML 形式のドキュメントが生成されます。Javadoc ツールは、Applet
のパッケージ名を、Applet.java
ソースファイル内のパッケージ宣言 (その宣言がある場合) から判別します。
Javadoc ツールには多くの便利なオプションがあり、その中にはほかのオプションよりも頻繁に使われるものがあります。ここで紹介するのは、Java プラットフォーム API に対して Javadoc ツールを実行するときに使用する実際のコマンドです。Java 2 Platform, Standard Edition, v1.2 に存在する、約 1500 個の public および protected クラスについてドキュメントを生成するために、180M バイトのメモリーを使用しました。同じ例を 2 回掲載します。最初の例はコマンド行から実行するもので、2 番目の例は Makefile から実行するものです。オプションの引数に絶対パスを使用しているため、任意のディレクトリからこの
javadoc
コマンドを実行できます。コマンド行の例
次のコマンド行の例は 900 文字を超えているため、DOS などのシェルには大きすぎます。この制限を回避するには、コマンド行引数ファイルを使用します。または、シェルスクリプトを記述します。C:> javadoc -sourcepath \java\jdk\src\share\classes ^ -overview \java\jdk\src\share\classes\overview.html ^ -d \java\jdk\build\api ^ -use ^ -splitIndex ^ -windowtitle 'Java 2 Platform 5.0 API Specification' ^ -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform 5.0 API Specification' ^ -header '<b>Java 2 Platform </b><br><font size="-1">5.0</font>' ^ -bottom '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' ^ -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" ^ -group "Extension Packages" "javax.*" ^ -J-Xmx180m ^ @packages上記のコマンドで、packages
は、処理対象のパッケージ名 (java.applet java.lang
など) が入っているファイルの名前です。各オプションの、単一引用符で囲まれた引数の内側には、改行文字を挿入できません。たとえば、この例をコピー&ペーストする場合は、-bottom
オプションから改行文字を削除してください。さらに、このあとの「注」も参照してください。Makefile の例
ここでは、GNU Makefile の例を示します。Windows の Makefile の例については、Windows の Makefile の作成方法を参照してください。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 2 Platform v1.2 API Specification' DOCTITLE = 'Java<sup><font size="-2">TM</font></sup> 2 Platform v1.2 API Specification' HEADER = '<b>Java 2 Platform </b><br><font size="-1">v1.2</font>' BOTTOM = '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"' GROUPEXT = '"Extension Packages" "javax.*"' SRCDIR = '/java/jdk/1.2/src/share/classes'Makefile の引数は、単一引用符で囲みます。
注
一般的なトラブルシューティング
- Javadoc FAQ - 一般的なバグおよびトラブルシューティングのヒントは、「Javadoc FAQ」 で参照できます。
- バグおよび制限事項 - バグの一部は、「Important Bug Fixes and Changes」 でも参照できます。
- バージョン番号 - 「バージョン番号」を参照してください。
- 有効なクラスだけをドキュメント化 - パッケージをドキュメント化するとき、Javadoc は、有効なクラス名で構成されているファイルのみを読み込みます。たとえば、ファイル名にハイフン「-」を含めることで、javadoc によるファイルの解析を防ぐことができます。
エラーと警告
エラーおよび警告メッセージには、ファイル名と宣言行 (ドキュメンテーションコメント内の特定の行ではない) の行番号が含まれます。
"error:cannot read:Class1.java"
Javadoc ツールはカレントディレクトリに Class1.java クラスをロードしようとしています。絶対パスまたは相対パスとともに表示されるクラス名は、この例の場合./Class1.java
と同じです。
CLASSPATH
- Javadoc がユーザークラスのファイルを探すときに使うパスを指定する環境変数です。この環境変数は、
-classpath
オプションによってオーバーライドされます。複数のディレクトリはセミコロンで区切ります。たとえば、次のとおりです。- .;C:\classes;C:\home\java\classes
JavadocTM は、Sun Microsystems, Inc の商標です (javadoc
コマンド自体には商標シンボルは不要)。
Copyright © 2002-2006 Sun Microsystems, Inc. All Rights Reserved. フィードバック |
![]() Java Software |