Java ソースファイルから API ドキュメンテーションの HTML ページを生成します。
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]引数の順は任意です。
options- このドキュメントで指定されているコマンド行オプションです。javadoc のオプションの一般的な使用法については、「使用例」を参照してください。
packagenamesjava.lang java.lang.reflect java.awtなどの、スペースで区切られた連続したパッケージ名です。ドキュメント化するパッケージごとに別個に指定する必要があります。Javadoc は、-sourcepathを使ってこれらのパッケージ名を検索します。Javadoc は、サブパッケージを再帰的に処理することはありません。アスタリスク (*) などのワイルドカードは使うことができません。「1 つ以上のパッケージのドキュメント化」の例を参照してください。sourcefiles- スペースで区切られた一連のソースファイル名です。 各ファイルは、パスで始まります。 アスタリスク (*) などのワイルドカードを含めることができます。ソースファイル名の前に指定したパスによって、javadoc の検索先が決まります。Javadoc では、ソースファイル名を検索するときに
-sourcepathは使用されません。たとえば、Button.javaを渡した場合は、./Button.javaが検索されます。フルパスをソースファイル名に指定した場合は、C:\src\java\awt\Graphics*.javaのようになります。「1 つ以上のクラスのドキュメント化」の例を参照してください。また、「パッケージとクラスのドキュメント化」の例のように、パッケージ名とソースファイルを組み合わせることもできます。@files- 複数のパッケージ名およびソースファイルを任意の順序で各行に 1 つずつ含んだ 1 つ以上のファイルです。
JavadocTM は、一連の Java ソースファイルの宣言およびドキュメンテーションコメントを解析し、デフォルトでは public クラスと protected クラス、内部クラス、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連の HTML ページを生成します。Javadoc は、パッケージ全体、個々のソースファイル、またはその両方に対して実行できます。javadoc をパッケージ全体に対して実行する場合は、一連のパッケージ名を
javadocに引数として渡します。個々のクラスに対して javadoc を実行する場合は、一連のソース (.java) ファイル名を渡します。具体的な例は、このページの最後で示します。Javadoc は、実行するたびに 1 つのドキュメントを作成します。 追加生成することはできません。 つまり、Javadoc の以前の実行結果を修正したり、「直接」組み込んだりすることはできません。ただし、以前の実行結果にリンクすることはできます。
実装上の理由から、Javadoc は実行に java コンパイラを必要とし、java コンパイラに依存しています。Javadoc は
javacの一部を呼び出して、宣言をコンパイルし、メンバの実装は無視します。Javadoc は、クラス階層を含むクラスの豊富な内部表現、および「使用」関係を構築し、そこから HTML を生成します。Javadoc は、ソースコードのドキュメンテーションコメントから、ユーザの提供するドキュメンテーションも取得します。Javadoc は、メソッド本体のない純粋なスタブファイルである
.javaソースファイル上で実行されます。つまり、API の作成時には、実装を記述する前の設計の早い段階でドキュメンテーションコメントを記述し、Javadoc を実行できます。コンパイラに依存することによって、HTML 出力が、実際の実装に正確に対応することが保証されます。 実際の実装は、明示的でなく暗黙的にソースコードに依存している場合があります。たとえば、Javadoc は、
.classファイル内には存在するが、ソースコード内には存在しないデフォルトコンストラクタ (Java 言語仕様のセクション 8.6.7) をドキュメント化します。Javadoc がドキュメンテーション用の内部構造を構築するときは、参照するクラスをすべてロードします。このため、ブートストラップクラス、拡張機能、またはユーザクラスにかかわらず、Javadoc は、参照するクラスをすべて見つけられなければなりません。詳細は、「クラスの検索方法」を参照してください。一般的に、作成するクラスは、拡張機能としてロードされるか、Javadoc のクラスパス内にある必要があります。
Javadoc のドックレット
Javadoc の出力の内容と形式は、ドックレットを使ってカスタマイズできます。Javadoc には、標準ドックレットと呼ばれるデフォルトの「組み込み型」ドックレットがあり、これによって HTML 形式の API ドキュメンテーションを生成します。標準ドックレットの修正やサブクラス化を行なったり、HTML、XML、MIF、RTF などの好みの出力形式を生成する独自のドックレットを記述することも可能です。ドックレットとその使用法については、次を参照してください。 -doclet コマンド行オプションでカスタムドックレットが指定されていない場合、javadoc は、デフォルトの標準ドックレットを使用します。javadoc ツールには、どのドックレットが使われているかには関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらのほかに、いくつかのコマンド行オプションが追加されます。どちらのオプションについても、後述の「オプション」で説明します。関連ドキュメント
- Javadoc に施された機能強化 - Javadoc 1.3 で追加された改良点の詳細
- Javadoc FAQ - 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法
- How to Write Doc Comments for Javadoc - ドキュメンテーションコメントの記述方法の詳細
- Requirements for Writing API Specifications - Java 2 Platform 仕様を記述する際に使用する標準要件 - ソースファイルのドキュメンテーションコメント形式または他の形式で API 仕様を記述する場合に役立ちます。検証可能なアサーションを満たすパッケージ、クラス、インタフェース、フィールドおよびメソッドの各要件を定めています。
用語
いくつかの用語には、Javadoc のコンテキストで特定の意味があります。
- 生成されるドキュメント
- javadoc ツールが Java ソースコード内の doc コメントから生成したドキュメントのことです。デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。
- 名前
- Java 言語での名前、つまりパッケージ、クラス、インタフェース、フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、
java.lang.String.equals(java.lang.Object)のように完全修飾することも、equals(Object)のように部分修飾することもできます。- ドキュメント化されるクラス
- javadoc の実行によって完全なドキュメンテーションが生成されるクラスとインタフェースです。ドキュメント化するには、ソースファイルが使用可能でなければならず、ソースファイル名またはパッケージ名のどちらかを javadoc コマンドに渡さなければなりません。ドキュメント化されるクラスは、javadoc の実行で組み込まれるクラス、つまり「組み込みクラス」とも呼ばれます。
- 参照されるクラス
- ドキュメント化されるクラスとインタフェースの定義 (実装) の中で明示的に参照されているクラスとインタフェースです。参照の例としては、戻り値の型、パラメータの型、キャストの型、拡張されたクラス、実装されたインタフェース、インポートされたクラス、メソッド本体で使用されるクラスなどがあります。doc コメントの中で (@see タグなどで) 参照されているクラスは、参照されるクラスとは呼びません。javadoc を実行すると、javadoc のブートクラスパスおよびクラスパス内で参照されているクラスのすべてがメモリにロードされます。参照されているクラスが見つからなかった場合は、[クラスが見つかりません] という警告が表示されます。javadoc は、クラスの存在とそのメンバの完全修飾名を決定するのに十分な情報を、.class ファイルから引き出すことができます。
- 外部参照クラス
- 参照されるクラスのうち、javadoc を実行してもドキュメンテーションが生成されないクラスです。言い換えると、これらのクラスは javadoc の実行の外部に存在するクラスです。これらのクラスに対する、ドキュメンテーション内での名前のリンクは、「外部参照」または「外部リンク」と呼ばれます。たとえば、
java.awtパッケージに対してだけ javadoc を実行した場合、Object などのjava.lang内のすべてのクラスは、外部参照クラスになります。外部参照クラスには、-linkオプションを使ってリンクすることができます。外部参照クラスの重要な属性として、そのソースコメントが Javadoc の実行で利用できないことがあります。このため、これらのコメントを継承することはできません。
Javadoc は、クラス用の Java 言語ソースファイル (.java)、パッケージコメントファイル、概要コメントファイル、およびその他処理されていないファイルの 4 種類の異なる「ソース」ファイルからなる出力を生成します。クラスソースコードファイル
各クラスまたはインタフェース、およびそのメンバは、独自のドキュメンテーションコメントを持つことができ、.javaファイルに保持します。ドキュメンテーションコメントの詳細は、「ドキュメンテーションコメント」を参照してください。パッケージコメントファイル
各パッケージは、独自のドキュメンテーションコメントを持つことができ、「ソース」ファイルに保持します。Javadoc は、生成するパッケージの要約ページにこのコメントをマージします。通常、このコメントには、パッケージ全体に適用されるドキュメンテーションを含めます。 パッケージコメントファイルを作成するには、ファイル名を
package.htmlにして.javaファイルとともにソースツリー内のパッケージディレクトリに置く必要があります。Javadoc は、この場所でこのファイル名を自動的に検索します。ファイル名は、どのパッケージでも同一です。パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に、HTML で記述された 1 つの大きなドキュメンテーションコメントですが、ほかのコメントと異なる点が 1 つだけあります。それは、このドキュメンテーションコメントには
/**と*/、および行頭のアスタリスクのコメント区切り文字を含めてはならないことです。コメントを書く場合は、最初の文をパッケージの要約にし、<body>と最初の文の間にタイトルまたはその他のテキストを含めてはなりません。パッケージタグを含めることはできますが、ほかのドキュメンテーションコメントと同様、{@link}以外のタグは、説明のあとに置かなければなりません。パッケージコメントファイルに@seeタグを追加する場合は、完全指定の名前を使用する必要があります。Javadoc は、実行時にこのファイルを自動的に検索します。 このファイルを見つけると、Javadoc は次の処理を行います。
<body>タグと</body>タグとの間にあるすべての内容を処理するためにコピーする- 存在するすべてのパッケージタグを処理する
- パッケージの要約など、Javadoc が生成するパッケージ要約ページの最後に、処理されたテキストを挿入する
- パッケージの要約ページの先頭に、パッケージコメントの最初の文をコピーする。また、概要の要約など、概要ページのパッケージのリストに、パッケージ名およびこの最初の文を追加する。文の末尾は、クラスやメンバの記述の最初の文の最後に適用されるのと同じ規則によって特定される
概要コメントファイル
ドキュメント化する各アプリケーションまたはパッケージのセットは、独自の概要ドキュメンテーションコメントを持つことができ、それは「ソース」ファイルに保持されます。 Javadoc は、生成する概要ページにこのコメントをマージします。通常、このコメントには、アプリケーションまたはパッケージのセット全体に当てはまるドキュメンテーションを含めます。概要コメントファイルを作成する場合、ファイルに好きな名前を付けて、好きな場所に置くことができますが、通常はファイル名を
overview.htmlにして、ソースツリーの一番上の階層に置きます。異なるパッケージのセットに対して javadoc を複数回実行したい場合には、1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。たとえば、java.appletパッケージのソースファイルがC:\user\src\java\appletディレクトリに含まれているとすると、C:\user\src\overview.htmlに概要コメントファイルを作成することができます。概要コメントファイルの内容は、前に述べたパッケージコメントファイルと同様、HTML で記述された 1 つの大きなドキュメンテーションコメントです。詳細は、前述の説明を参照してください。繰り返しますが、このコメントを書く場合は、最初の文をアプリケーションまたはパッケージのセットの要約にし、
<body>と最初の文の間にタイトルまたはその他のテキストを含めてはなりません。概要タグを含めることはできます。 どのドキュメンテーションコメントについても、インラインタグ ({@link}など) 以外のタグは、説明のあとに置く必要があります。@seeタグを追加する場合は、完全指定の名前を使用する必要があります。Javadoc の実行時に、-overview オプションを使って概要コメントファイル名を指定します。ファイルは、パッケージコメントファイルと同じように処理されます。
<body>タグと</body>タグとの間にあるすべての内容を処理するためにコピーする- 存在するすべての概要タグを処理する
- 概要の要約に示されるように、Javadoc が生成する概要ページの最後に、処理されたテキストを挿入する
- 概要ページの先頭に、概要コメントの最初の文をコピーする
その他の処理されないファイル
ソースには、Javadoc でコピー先のディレクトリにコピーする、その他の任意のファイルを含めることができます。一般に、このようなファイルには、グラフィックファイル、Java ソース (.java) およびクラス (.class) 例のファイル、内容が通常の Java ソースファイルのドキュメンテーションコメントの影響を受けない独立した HTML ファイルなどがあります。処理されないファイルを含めるには、それらのファイルを
doc-filesというディレクトリに置きます。 このディレクトリは、任意のパッケージディレクトリの下に作成できます。パッケージごとにこのようなサブディレクトリを 1 つ持つことができます。イメージ、コード例、ソースファイル、.class ファイル、アプレット、および HTML ファイルをこのディレクトリに格納できます。たとえば、ボタンの画像button.gifをjava.awt.Buttonクラスドキュメンテーションに含めたい場合は、そのファイルを/home/user/src/java/awt/doc-files/ディレクトリに置きます。 これらの処理されないファイルへのリンクはすべて明示的に記述する必要があります。 これは、Javadoc がファイルを見ずに、単にディレクトリとその内容物を生成先にコピーするだけだからです。たとえば、Button.javaドキュメンテーションコメント内のリンクは、次のようになります。/** * This button looks like this: * <img src="doc-files/Button.gif"> */
デフォルトでは、javadoc は、HTML 形式のドキュメンテーションを生成する標準ドックレットを使います。このドックレットは、以下の種類のファイルを生成します。以下の各 HTML「ページ」は、それぞれ別のファイルに対応します。javadoc が生成するファイルの名前には、クラスやインタフェースの名前にちなんだものと、そうでないもの (package-summary.htmlなど) の 2 種類があります。後者のグループには、前者のグループの名前とファイル名が競合しないように、ハイフンが含まれています。基本内容ページ
- ドキュメント化する各クラスまたは各インタフェースに対し、1 つのクラスページまたはインタフェースページ (classname
.html)- ドキュメント化する各パッケージに対し、1 つのパッケージページ (
package-summary.html)。Javadoc によって、ソースツリーのパッケージディレクトリ内のpackage.htmlというファイル内のすべての HTML テキストが含められる。- パッケージのセット全体に対して 1 つの概要ページ (
overview-summary.html)。これは、生成されるドキュメントの先頭ページになる。Javadoc によって、-overviewオプションで指定されたファイル内のすべての HTML テキストが含められる。このファイルは、javadoc に複数のパッケージ名を渡した場合にだけ作成される。詳細は、「HTML フレーム」を参照してください。相互参照ページ
- パッケージのセット全体に対して 1 つのクラス階層ページ (
overview-tree.html)。これを表示するには、ナビゲーションバーの [概要] をクリックしてから、[階層ツリー] をクリックする- 各パッケージに対して 1 つのクラス階層ページ (
package-tree.html)。特定のパッケージ、クラス、またはインタフェースのページを表示し、[階層ツリー] をクリックすると、そのパッケージの階層が表示される- 各パッケージに対して 1 つの [使用] ページ (
package-use.html)と、各クラスおよびインタフェースに対して別に 1 つの [使用] ページ (class-use/classname.html)。このページは、特定のクラス、インタフェース、またはパッケージのなんらかの部分を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドを記述する。クラスまたはインタフェース A を例にして考えると、その [使用] ページには、A のサブクラス、A として宣言されたフィールド、A を返すメソッド、A 型のパラメータを持つメソッドおよびコンストラクタが表示される。このページには、パッケージ、クラス、またはインタフェースに移動してから、ナビゲーションバーの [使用] リンクをクリックすることによってアクセスできる- 非推奨 API ページ (
deprecated-list.html)。推奨されない名前すべての一覧が含まれている(非推奨名は、通常は改良された API が存在するために使用が推奨されていない API の名前で、たいていはそれに置き換わる名前が提示されている。非推奨 API は、将来の実装では削除される可能性がある)- 直列化形式ページ (
serialized-form.html)。 直列化可能クラスおよび外部化可能クラスの情報用。これらの各クラスには、直列化フィールドおよびメソッドに関する説明がある。これらの情報は、API を使う開発者ではなく、再実装者に必要な情報である。ナビゲーションバーにリンクがない場合、任意の直列化されたクラスに移動して、クラスの [関連項目] セクション内の [直列化された形式] をクリックするとこの情報を取得できる。標準ドックレットは自動的に直列化形式ページを生成する。これには、public または非 public のすべての Serializable を実装するクラスが含まれ、さらに、readObjectメソッドとwriteObjectメソッド、直列化フィールド、および@serialタグ、@serialFieldタグ、@serialDataタグからの doc コメントが含まれる。標準ドックレットは次のようにして直列化形式ページとのリンクを生成する。直列化形式に属する各クラスについて、クラスページの [関連項目] 見出しの下に [直列化された形式] リンクが追加される。このリンクは、クラスレベル (メンバではない) で生成される。直列化クラスは public にも private にもなり得る。public および private クラスの完全に直列化された形式を生成するには、javadoc を-privateオプションを付けて実行します (将来のバージョンではこの要件が不要になることが期待されます)。- 索引 (
index-*.html)。 すべてのクラス名、インタフェース名、コンストラクタ名、フィールド名、およびメソッド名をアルファベット順に並べてある。索引は、Unicode を扱えるように国際化されており、1 つのファイルとして生成するか、または先頭文字 (英語の場合 A から Z) ごとに別のファイルとして生成できるサポートファイル
- ヘルプページ (
help-doc.html)。 ナビゲーションバーおよび上記のページについて説明する。-helpfileを使って、デフォルトのヘルプファイルに代わる独自のカスタムヘルプファイルを提供することもできる- 1 つの index.html ファイル。表示用 の HTML フレームを作成する。このファイルは、フレーム付きの最初のページを表示する場合にロードする。このファイル自体は、テキスト内容を含まない
- 複数のフレームファイル (
*-frame.html)。 パッケージ、クラス、およびインタフェースの一覧を含む。 HTML フレームを表示するときに使われる- パッケージリストファイル (
package-list)。-linkオプションおよび-linkofflineオプションで使われる。これは、HTML ファイルではなくテキストファイルのため、リンクではアクセスできない- スタイルシートファイル (
stylesheet.css)。 生成されるページ上の限られた色数、フォントファミリ、フォントサイズ、フォントのスタイルおよび配置を制御する- doc-files ディレクトリ。 出力先ディレクトリにコピーするイメージ、コード例、ソースコードなどのファイルをすべて格納する。これらのファイルは Javadoc では処理されない。 ファイルの javadoc タグは無視される。このディレクトリは、ソースツリー以外では生成されない
Javadoc は、下の図に示すように、2 つか 3 つの HTML フレームを生成します。ソースファイル (*.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 のリスト 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 インタフェースを使用するページ
Javadoc は、各クラス、インタフェース、フィールド、コンストラクタ、およびメソッドの説明の開始時に、シグニチャーを生成します。このシグニチャーは、該当する API 項目の宣言となります。たとえば、Booleanクラスのシグニチャーは、次のようになります。
public final class Boolean
extends Object
implements Serializableまた、
Boolean.valueOfメソッドのシグニチャーは、次のようになります。
public static Boolean valueOf(String s)Javadoc には、修飾子
public、protected、private、abstract、fi nal、static、transient、およびvolatileを含めることができますが、synchronizedやnativeを含めることはできません。これら後者の 2 つの修飾子は、実装の詳細とみなされているため、API 仕様には含まれません。API では、キーワード
synchronizedに依存せずに、コメントの説明で並行セマンティクスをドキュメント化する必要があります。 たとえば、「複数のスレッドが 1 つのEnumerationを並行して使用することはできない」などとコメントを記述します。ドキュメントには、これらのセマンティクスの実行方法を記述すべきではありません。別の例が示すように、Hashtableはスレッドに対して安全でなければならないため、エクスポートされたメソッドすべてを同期化することでこれを実現するように指定する理由はありません。バケットレベルで内部的に同期化する権利を予約しておく必要があります。 これにより、より高度な並行性の提供が可能になります。
ソースコードへのコメントの挿入
ソースコードの任意のエンティティ (クラス、インタフェース、メソッド、コンストラクタ、またはフィールド) の宣言の前には、ドキュメンテーションコメントを入れることができます。このコメントは、Javadoc コメントとも呼ばれます。doc コメントは、コメントの始まりを示す文字列/**とコメントの終わりを示す文字列*/との間にある文字で構成されます。テキストは、複数行にわたって記述できます。
/** * This is the typical format of a simple documentation comment. */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 { }コメントはタグの後の記述 - 開始区切り文字/**の後ろからタグセクションまでが、記述です。先頭の文字が@の行以降がタグセクションです (先行するアスタリスク、空白、およびコメント区切り文字は無視される)。コメントは、タグセクション以降には記述できません。タグセクションの数に制限はありません。 ただし、タグセクションによっては、複数回記述できないものがあります。次の例の@seeは、タグセクションの開始として有効です。
/** * This is a doc comment. * @see java.lang.Object */標準タグおよびインラインタグ - 「タグ」は、Javadoc が処理可能なドキュメンテーションコメントの中で、特別なキーワードです。Javadoc には、標準タグ (@tagで表される) とインラインタグ ({@tag}のように中括弧で囲まれる) があります。標準タグが正常に解釈されるためには、先行するアスタリスク、空白、コメント区切り文字 (/**) を除いて、行の最初におく必要があります。これは、それ以外の場所に@文字を使用しても、タグの開始として解釈されないことを意味します。行の最初に@文字を使用しても解釈されないようにする場合は、HTML エンティティ@を使用してください。各標準タグは、関連テキストを保持します。このテキストは、タグの後から、次のタグの前またはドキュメンテーションコメントの最後までの任意のテキストです。インラインタグは、テキストを 配置可能な場所であればどこにでも配置および解釈が可能です。次のコード例には、標準タグ@deprecatedおよびインラインタグ{@link}が含まれます。
/** * @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>を示します。次に doc コメントを示します。
/** * This is a <b>doc</b> comment. * @see java.lang.Object */行頭のアスタリスク - javadoc は、doc コメントを解析するときに、各行の先頭にある文字アスタリスク (
*) をすべて破棄します。 また、最初のアスタリスク (*) より前の空白とタブも破棄します。行頭のアスタリスクを省略した場合は、行頭のすべての空白が削除されます。このため、<pre>タグを使ってコード例をインデントするときなど、行頭に空白が必要な場合は、行頭のアスタリスクは省略しないでください。行頭のアスタリスクがないと、行頭の空白が削除されるため、生成されるドキュメント内でインデントが失われます。最初の文 - 各 doc コメントの最初の文は、宣言されているエンティティに関する簡潔かつ完全な要約文である必要があります。この文は、後に空白、タブ、または行末記号が続く最初のピリオドに遭遇した時点、あるいは最初のタグに遭遇した時点で終了します。最初の文は、Javadoc によって HTML ページ上部のメンバの概要の部分にコピーされます。
複数のフィールドによる宣言 - Java では、1 つの文で複数のフィールドを宣言できます。 ただし、この文には複数のドキュメンテーションコメントを記述することはできません。 このコメントは、すべてのフィールドにコピーされます。このため、フィールドごとにドキュメンテーションコメントを記述する場合は、個別の文に各フィールドを宣言する必要があります。たとえば、次のドキュメンテーションコメントは、1 つの宣言として記述されていますが、適切ではありません。 宣言を 2 つに分けることをお勧めします。
このコードから次のドキュメンテーションが生成されます。/** * The horizontal and vertical distances of point (x,y) */ public int x, y; // Avoid this見出しタグはなるべく使用しない - メンバに対してドキュメンテーションコメントを記述する場合は、<H1> and <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)
メソッドコメントの自動的な再利用 - 簡単に「継承コメント」とも呼ばれます。クラスまたはインタフェースの
m1()メソッドにドキュメンテーションコメントおよびタグがない場合は、Javadoc では、そのメソッドがオーバーライドまたは実装したm2()メソッドの、コメントとタグが代わりに使用されます(ある場合)。メソッドm2()は、ドキュメント化されたクラスのメンバでなければならず、かつ外部参照クラスのメンバであってはなりません。この現象は、次の 3 つの場合に発生します。
- クラスのメソッドがスーパークラスのメソッドをオーバーライドしたとき
- インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドしたとき
- クラスのメソッドがインタフェースのメソッドを実装したとき
最初の 2 つの場合、
m()メソッドが別のメソッドをオーバーライドしているときは、Javadoc ではm()のドキュメントに [オーバーライド] が小見出しとして生成され、オーバーライドしたメソッドにリンクが作成されます。3 つ目の場合、特定のクラスのメソッド
m()がインタフェースのメソッドを実装しているときは、Javadoc ではm()のドキュメントに [定義] が小見出しとして生成され、実装したメソッドにリンクが作成されます。検索は次のように行われます。クラス C のメソッドの場合は、クラス C によって実装されるすべてのインタフェースが再帰的に検索されてから、C のすべてのスーパークラスが検索されます。 インタフェース I のメソッドの場合は、そのすべてのスーパーインタフェースが再帰的に検索されます。どちらの場合も、最初に検出されたコメントがコピーされます。
Javadoc の仕様 - ドキュメンテーションコメントの仕様については、Java 言語仕様 (James Gosling、Bill Joy、Guy Steele 共著) の Chapter 18「Documentation Comments」を参照してください。
javadoc は、Java doc コメント内に埋め込まれた特殊なタグを解析します。これらの特殊な doc タグを使うと、書式の整った完全な API ドキュメンテーションをソースコードから自動的に生成できます。タグは、単価記号 (@) で始まり、大文字小文字が区別されます。 これらのタグは、以下に示すとおりに、大文字と小文字を区別して入力する必要があります。タグは、行の先頭 (ただし先行する空白と省略可能なアスタリスクは除く) から始めなければなりません。慣習上、同じ名前のタグは 1 個所にまとめて記述します。たとえば、@seeタグが複数ある場合は、すべてを 1 個所にまとめて記述します。今後のリリースで導入されるタグについては、「Proposed Javadoc Tags」を参照してください。
現時点で有効なタグを以下に示します。
タグ 導入された JDK/SDK のバージョン @author1.0 {@docRoot}1.3 @deprecated1.0 @exception1.0 {@link}1.2 @param1.0 @return1.0 @see1.0 @serial1.2 @serialData1.2 @serialField1.2 @since1.1 @throws1.2 @version1.0
@authorname-text- -author オプションが使われている場合、生成されるドキュメントに、指定された name-text を持つ Author エントリを追加します。1 つの doc コメントに複数の
@authorタグを含めることができます。@authorタグごとに 1 つ、またはタグごとに複数の名前を指定できます。前者の場合は、Javadoc は、名前と名前の間にコンマ (,) とスペースを挿入します。後者の場合、テキスト全体が解析されることなく生成されるドキュメントに単にコピーされます。このため、コンマ以外の現地仕様の名前区切り文字を使う場合は、1 行に複数の名前を指定します。{@docRoot}- 生成された任意のページを起点とした、生成されるドキュメントの (生成先) ルートディレクトリへの相対パスを表します。このタグは、著作権ページまたは会社のロゴなど、生成されるすべてのページから参照するファイルを取り込むときに使います。通常は、各ページの下部から著作権ページにリンクします。
この
{@docRoot}タグは、コマンド行および doc コメントで使うことができます。
このタグが必要な理由は、生成されるドキュメントが、サブパッケージと同じ階層のディレクトリに格納されるためです。たとえば、次のように指定します。
- コマンド行では、次のようにヘッダ、フッタ、または下部を定義します。
javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'- doc コメントには次のように記述します。
/** * See the <a href="{@docRoot}/copyright.html">Copyright</a>. */<a href="{@docRoot}/copyright.html">次のように解決されます。<a href="../../copyright.html"> for java/lang/Object.javaおよび<a href="../../../copyright.html"> for java/lang/ref/Reference.java@deprecateddeprecated-text- この API は (動作はするが) 使用すべきでないことを示すコメントを追加します。Javadoc は、deprecated-text を説明の前に移動してイタリックにし、その前にボールドの警告「推奨されません。」を追加します。
deprecated-text の最初の文では、少なくともユーザにどのようなときにその API が推奨されないか、およびそれに代わる API を提示する必要があります。Javadoc は、この最初の文だけを要約セクションと索引にコピーします。あとに続く文で、なぜその API が推奨されないかを説明することもできます。代わりの API を指し示す
{@link}タグ (Javadoc 1.2 以降の場合) を含める必要があります。
- Javadoc 1.2 以降では、
{@link}タグを使用してください。これにより、必要な場所にインラインでリンクが作成されます。例を示します。/** * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */- Javadoc 1.1 では、各
@deprecatedタグに@seeタグ (インラインにできない) を作成するのが標準の形式です。推奨されないタグについての詳細は、@deprecated タグのドキュメントを参照してください。
@exceptionclass-name description@exceptionタグは、@throwsと同義です。{@linkpackage.class#member label}- 表示テキスト label とのインラインリンクを挿入します。 label は、参照先の、Java 言語で記述された名前のドキュメンテーションを指し示します。このタグの package.class
#member と label の構文は、後述する@seeタグと同じですが、関連項目セクションにリンクを置くのではなく、インラインリンクを生成する点が異なります。インラインテキストのほかの部分と区別するため、このタグの開始と終了には中括弧を使います。ラベルの中で「}」を使う必要がある場合は、HTML のエンティティ表記法の } を使います。1 つの行で使える {@link} タグの数に制限はありません。このタグは、ドキュメンテーションコメントの説明部分、または @deprecated、@return、@param などの任意のタグのテキスト部分で使うことができます。
たとえば、次のコメントでは
getComponentAt(int, int)メソッドを参照しています。Use the {@link #getComponentAt(int, int) getComponentAt} method.標準ドックレットでは、このコメントから次の HTML が生成されます (このコメントが同じパッケージの別のクラスを参照していると仮定した場合)。Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.この HTML は Web ページ上で次のように表示されます。Use the getComponentAt method.@paramparameter-namedescription- Parameters セクションにパラメータを追加します。説明は次の行に続けて記述できます。
@returndescription- description で指定されたテキストを持つ戻り値セクションを追加します。テキストでは、戻り値の型と取り得る値の範囲について記述する必要があります。
@seereference- reference を指すリンクまたはテキストエントリを持つ [関連項目] 見出しを追加します。1 つの doc コメントには、任意の数の
@seeタグを指定できます。@seeタグは、同一の見出しにグループ化されます。@seeタグには、次の 3 つの形式があります。 通常は、3 番目の形式が使われます。
@see"string" 注 - この形式は、バージョン 1.2 では使用できません (引用符で囲まれたテキストが出力されない) が、1.2.2 では使用できます。- 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 は、小なり括弧 (
<) が先頭にあるものを探して、そのリンクをその他の場合と区別します。例を示します。@see <a href="spec.html#section">Java Spec</a>これは次のようなリンクを生成します。
- 関連項目:
- Java Spec
@seepackage.class#member label- 参照されるドキュメンテーションへのリンクを追加します。 このドキュメンテーションの名前は、Java 言語で記述されている必要があり、label 表示テキストも指定できます。label は省略可能です。 label を省略した場合は、該当する名前が適切に短縮されて表示テキストとして代わりに表示されます。 「名前の表示方法」を参照してください。ラベルは、表示テキストを短縮する場合や、該当する名前と異なる表示テキストを指定する場合に使います。
バージョン 1.2 だけは、ラベルではなく、名前が <code> HTML タグ内に自動的に表示されます。1.2.2 からは、ラベルを使用するか、しないかにかかわらず、<code> は常に表示テキストを囲むかたちで、含まれます。
- package.class
#member には、参照される任意の名前、つまり、Java 言語で記述された有効な名前を持つパッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドを指定します。 ただし、メンバ名の前のドットは、ハッシュ文字 (#) で置き換えます。指定した名前が、ドキュメント化されるクラスにある場合、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>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 にはメソッドまたはコンストラクタを指定できます。
@seepackage.class#member の一般的な形式現在のクラスのメンバを参照する
@see#field
@see#method(Type, Type,...)@see#method(Type argname, Type argname,...)
現在の、またはインポートされたパッケージの別のクラスを参照する
@seeClass#field
@seeClass#method(Type, Type,...)@seeClass#method(Type argname, Type argname,...)@seeClass
別のパッケージを参照する (完全指定)
@seepackage.Class#field
@seepackage.Class#method(Type, Type,...)@seepackage.Class#method(Type argname, Type argname,...)@seepackage.Class
@seepackage上の表に対する注を以下に示します。
- クラスまたはパッケージを省いた最初の形式のセットでは、Javadoc は現在のクラス階層だけで検索を行います。Javadoc は、現在のクラスかインタフェースのメンバ、スーパークラスかスーパーインタフェースの 1 つ、または親クラスかインタフェースの 1 つ (検索手順 1 〜 3) を検索します。現在のパッケージのほかの部分やほかのパッケージ (検索手順 4 〜 5) は検索しません。
- メソッドまたはコンストラクタが、
getValueのように括弧を付けずに名前として入力され、かつ同じ名前のフィールドがない場合は、Javadoc は正確にリンクを作成しますが、括弧と引数を追加するように促す警告メッセージを出力します。このメソッドをオーバーロードした場合、Javadoc は、指定されたメソッドではなく、検索で見つかった最初のメソッドにリンクします。- 内部クラスは、どの形式の場合でも、単に inner という形ではなく、outer
.inner という形で指定しなければなりません。- すでに述べたとおり、クラスとメンバを区切るのに、ドット (
.) ではなくハッシュ文字 (#) が使われていることに注意してください。ドットは、クラス、内部クラス、パッケージ、およびサブパッケージを区切るのにも使われますが、javadoc では、クラスとメンバを区切るのにハッシュ文字を使うことで、あいまいさを排除しています。ただし、一般に、あいまいにならない限りドットは許容され、適切に構文解析されます。 ただし、その場合でも警告は表示されます。@see の検索順序 - Javadoc は、ソースファイル (.java)、パッケージファイル (package.html)、または概要ファイル (overview.html) 内で使われる
@seeタグを処理します。あとの 2 つのファイルでは、@seeを使って指定する名前を完全修飾する必要があります。ソースファイルでは、完全修飾名と部分修飾名のどちらを指定することもできます。Javadoc が、完全修飾されていない
.javaファイルで@seeタグを見つけた場合、指定された名前を Java コンパイラと同じ順序で検索します。 ただし、javadoc は、一部のネームスペースのあいまいさは検出しません。 これは、javadoc が、ソースコードにこれらのエラーが存在していないことを前提として動作するためです。検索順序は、Java 言語仕様の第 6 章「Names」で正式に定義され、内部クラス仕様で修正されています。Javadoc は、関連付けおよびインポートが行われたすべてのクラスとパッケージから名前を検索します。具体的には、検索は次の順序で行われます。
- 現在のクラスまたはインタフェース
- 名前を囲むクラスとインタフェース。 もっとも近いものを最初に検索
- スーパークラスとスーパーインタフェース。 もっとも近いものを最初に検索
- 現在のパッケージ
- インポートされるパッケージ、クラス、およびインタフェース。 import 文の順序に従って検索
javadoc は、一致する名前が見つかるまで、各クラスについて手順 1 〜 3 を繰り返して検索を続けます。つまり、現在のクラスとそのクラスを囲むクラス E を検索したあと、E のスーパークラスを検索し、最後に E を囲むクラスを検索します。 手順 4 と 5 では、javadoc は、1 つのパッケージ内でのクラスまたはインタフェースの検索を、なんらかの決まった順序で行うわけではありません。この検索順序はコンパイラに依存します。手順 5 では、javadoc は、java.lang を検索します。 これは、java.lang がすべてのプログラムによって自動的にインポートされるためです。
javadoc は、必ずしもサブクラスを検索するわけではなく、Javadoc の実行中にほかのパッケージのドキュメンテーションが生成される場合でも、ほかのパッケージの検索は行いません。たとえば、
@seeタグがjava.awt.event.KeyEventクラスにあって、java.awtパッケージにある名前を参照する場合、javadoc は、そのクラスがインポートしない限りそのパッケージを検索しません。名前の表示方法 - label が省略された場合は、package.class.member が表示されます。通常、package.class.member は、現在のクラスおよびパッケージに応じて適切に短くされます。「短くされる」とは、Javadoc が必要最小限の名前を表示するということです。たとえば、
String.toUpperCase()メソッドに、そのクラスのメンバへの参照とほかのクラスのメンバへの参照が含まれている場合は、ほかのクラスの名前だけが表示されます。
参照の型 例 表示 @seeタグが同じクラスのメンバを参照する@see String#toLowerCase()
toLowerCase()
(クラス名を省略)@seeタグが別のクラスのメンバを参照する@see Character#toLowerCase(char)
Character.toLowerCase(char)
(クラス名を含む)@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"@sincesince-text- 生成されるドキュメントに、指定された since-text を持つ [導入されたバージョン] 見出しを追加します。このテキストには、特別な内部構造はありません。このタグは、特定の変更または機能が、since-text によって指定されたソフトウェアのリリース以来、継続して存在することを意味します。例を示します。
@since 1.3@serialfield-description- デフォルトの直列化可能フィールドの doc コメントで使用します。
任意の field-description は、フィールドの意味を説明し、取り得る値のリストを表示する必要があります。必要な場合には、複数の行にまたがって説明を記述することができます。標準ドックレットでは、この情報を直列化形式ページに追加します。
@sinceタグは、Serializableクラスの初期バージョン以来追加されている各直列化フィールドに対して追加する必要があります。これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の 1.6 節「クラスの直列化可能なフィールドおよびデータの文書化」を参照してください。また、直列化の FAQ も参照してください。 「javadoc 標準ドックレットでは、@serial または @serialData タグ、あるいはその両方がないという警告がなぜ頻繁に通知されるのか」および「javadoc を -private スイッチを指定しないで実行した場合に、private フィールドに @serial タグがないという警告が javadoc から通知されるのはなぜか」といった質問に対する回答が掲載されています。
@serialFieldfield-name field-type field-descriptionSerializableクラスのserialPersistentFieldsメンバのObjectStreamFieldコンポーネントをドキュメント化します。各ObjectStreamFieldコンポーネントに対して@serialFieldタグを 1 つ使う必要があります。@serialDatadata-description- data-description は、データの型と順序を直列化形式でドキュメント化します。このデータには、特に
writeObjectメソッドによって書き込まれる任意指定のデータ、およびExternalizable.writeExternalメソッドによって書き込まれるすべてのデータ (基底クラスを含む) が含まれます。
@serialDataタグは、writeObject、readObject、writeExternal、およびreadExternalの各メソッドの doc コメントで使用できます。@throwsclass-name description@throwsタグと@exceptionタグは同義です。生成されるドキュメンテーションに、class-name および description テキストを持つ [例外] 小見出しを追加します。class-name は、該当するメソッドによってスローされる可能性のある例外の名前です。このクラスが完全修飾されていない場合、javadoc は検索順序に従ってクラスを探します。@versionversion-text- -version オプションが使われている場合、生成されるドキュメンテーションに、指定された version-text を持つ [バージョン] 小見出しを追加します。このテキストには、特別な内部構造はありません。1 つの doc コメントに含めることのできる
@versionタグは 1 つ以下です。通常、バージョンは、該当するクラスまたはメンバを含むソフトウェア (Java 2 SDK など) のバージョンを指します。
以下では、タグを使用できる場所について説明します。@see、@link、@since、@deprecatedの 4 つのタグは、すべての doc コメントで使用できます。概要ドキュメンテーションタグ
概要タグは、概要ページのドキュメンテーションコメント (通常はoverview.htmlという名前のソースファイル内にある) で使用できるタグです。ほかのドキュメンテーションコメントと同様に、これらのタグは、説明のあとで使う必要があります。注 - バージョン 1.2 では、概要ドキュメント内の
{@link}タグにバグがあります。 テキストは適切に表示されますが、リンクが設定されません。
概要タグ
@see{@link}@since
パッケージドキュメンテーションタグ
パッケージタグは、パッケージのドキュメンテーションコメント (package.html) と言う名前のソースファイルに存在) で使用できるタグです。
パッケージタグ
@see{@link}@since@deprecated
クラスおよびインタフェースドキュメンテーションタグ
次に示すのは、クラスまたはインタフェースのドキュメンテーションコメントで使用できるタグです。
クラスおよびインタフェースタグ
@see{@link}@since@deprecated@author@version次は、クラスコメントの例です。
/** * A class representing a window on the screen. * For example: * <pre> * Window win = new Window(parent); * win.show(); * </pre> * * @author Sami Shaio * @version %I%, %G% * @see java.awt.BaseWindow * @see java.awt.Button */ class Window extends BaseWindow { ... }
フィールドドキュメンテーションタグ
次に示すのは、フィールドのドキュメンテーションコメントで使用できるタグです。
フィールドタグ
@see{@link}@since@deprecated@serial@serialField次は、フィールドコメントの例です。
/** * The X-coordinate of the component. * * @see #getLocation() */ int x = 1263732;
コンストラクタおよびメソッドドキュメンテーションタグ
次に示すのは、コンストラクタまたはメソッドのドキュメンテーションコメントで使用できるタグです。
メソッドおよびコンストラクタタグ
@see{@link}@since@deprecated@param@return@throws(@exception)@serialData次はメソッドの doc コメントの例です。
/** * 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コマンドを短く簡潔にするために、ファイルの各行に 1 つのソースファイル名またはパッケージ名が記述されたファイルを 1 つまたは複数指定することができます。Javadoc の実行時に、ファイル名をファイルのリストとして指定するには、ファイル名の前に「@」文字を付けて渡します。javadoc は、「@」文字で始まる引数に遭遇すると、そのファイルに記述されたファイル名がコマンド行に書かれていたかのように処理を行います。たとえば、
packagesというファイル内に、すべてのパッケージ名を列挙できます。ファイルは、次のようになります。
com.mypackage1 com.mypackage2 com.mypackage3次のコマンドを使って、javadoc を実行できます。C:> javadoc -d apidocs @packages
javadoc ツールは、ドックレットを使って出力を決定します。javadoc は、-doclet オプションでカスタムドックレットが指定されている場合以外は、デフォルトの標準ドックレットを使います。javadoc には、任意のドックレットとともに使用できるコマンド行オプションがあります。 これらのオプションについては、後述の「javadoc のオプション」で説明します。標準ドックレットでは、このほかに、いくつかの追加のコマンド行オプションが提供されます。 これらのオプションについては、後述の「標準ドックレットが提供するオプション」で説明します。どのオプション名も大文字と小文字を区別しません。 ただし、オプションの引数では大文字と小文字が区別されることがあります。オプションを以下に示します。
-1.1
-author
-bootclasspath
-bottom
-charset
-classpath
-d
-docencoding
-doclet
-docletpath
-doctitle
-encoding
-extdirs
-footer
-group
-header
-help
-helpfile
-J
-link
-linkoffline
-locale
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-nosince
-notree
-overview
-package
-private
-protected
-public
-serialwarn
-sourcepath
-splitindex
-stylesheetfile
-title
-use
-verbose
-version
-windowtitle
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 フレーム」を参照してください。
- -public
- public なクラスとメンバだけを表示します。
- -protected
- protected および public なクラスとメンバだけを表示します。これはデフォルトの動作です。
- -package
- パッケージ、および protected と public なクラスとメンバだけを表示します。
- -private
- すべてのクラスとメンバを表示します。
- -help
- オンラインヘルプを表示します。 javadoc とドックレットのコマンド行オプションの一覧が表示されます。
- -doclet class
- ドキュメンテーションの生成に使うドックレットを起動するためのクラスファイルを指定します。ドックレットでは、出力の内容と形式を定義します。
-docletオプションが使われていない場合、javadoc は標準ドックレットを使ってデフォルトの HTML 形式を生成します。このクラスには、start(Root)メソッドが含まれていなければなりません。この起動クラスへのパスは、-docletpathオプションによって定義されます。- -docletpath classpathlist
-docletオプションで指定されているドックレットクラスファイルへのパスを指定します。classpathlist には、複数のパスを含めることができます。 その場合、各パスを Solaris の場合にはコロン (:)、Windows の場合にはセミコロン (;) で区切ります。目的のドックレットが検索パス内にある場合は、このオプションは不要です。- -1.1
- Javadoc 1.1 によって生成されるドキュメンテーションの外観および機能を持つドキュメンテーションを生成します。生成されるページの背景は灰色になり、ヘッダにはイメージが使われ、表ではなく丸印を使ったリストが使われます。 また、生成先ディレクトリは平坦な構造になり、継承された API は含まれなくなり、HTML フレームは使われず、内部クラスはサポートされません。また、このオプションでは、索引をアルファベットごとに自動的に分類し、別々のファイルに格納します。このような外観を持つ出力を得たい場合、このオプションを使うと、javadoc 1.1 に存在していたいくつかのバグを回避できる利点があります。
-1.1オプションとは同時に使用できないオプションがあります。使用可能な他のオプションを見つけるには、次のようにコマンド入力します。C:> javadoc -1.1 -helpこのリスト内の-footerオプションの機能は、このページの別の場所で説明する-bottomオプションと同じです。-title オプションの機能は、-doctitleオプションと同じです。- -sourcepath sourcepathlist
javadocコマンドにパッケージ名を渡す際に、ソースファイル (.java) 検索用のパスを指定します。-sourcepathオプションは、javadoc コマンドにパッケージ名を渡すときにだけ使用できます。javadocコマンドに渡される.javaファイルは検索しません。.javaファイルを検索するには、そのディレクトリに cd によって移動するか、各ファイルの先頭にパスを追加します (「1 つ以上のクラスのドキュメント化」を参照)。-sourcepathが省略された場合は、javadoc はクラスパスを使ってソースファイルを検索します (-classpath を参照)。したがって、デフォルトの -sourcepath はクラスパスの値です。-classpath を省略してパッケージ名を 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) になることを理解すると簡単です。- -classpath classpathlist
- javadoc が参照されるクラス (
.class) を検索するパスを指定します。 参照されるクラスとは、ドキュメント化されるクラスとそれらのクラスによって参照される任意のクラスのことです。javadoc は、指定されたパス以下のすべてのサブディレクトリで検索を行います。classpathlist には、パス間をセミコロンで区切って複数のパスを含めることができます。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を使ってユーザクラスを検索する方法についての詳細は、「クラスの検索方法」を参照してください。- -bootclasspath classpathlist
- ブートクラスが存在するパスを指定します。ブートクラスとは、Java コアクラスのことです。ブートクラスパスは、javadoc がソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、「javac と javadoc がクラスを検索する方法」を参照してください。classpathlist 内の複数のクラスパスリストは、セミコロン (;) で区切ります。
- -extdirs dirlist
- 拡張機能クラスが存在するディレクトリを指定します。拡張機能クラスは、Java 拡張機能機構を使うすべてのクラスです。拡張機能ディレクトリ (extdirs) は、javadoc がソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、上の
-classpathを参照してください。dirlist 内の複数のディレクトリは、セミコロン (;) で区切ります。- -verbose
- javadoc の実行中に詳細なメッセージを表示します。冗長オプションを指定しない場合は、ソースファイルのロード時、ドキュメンテーションの生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時にメッセージが表示されます。冗長オプションを指定した場合は、各 java ソースファイルの解析に要したミリ秒数などの追加メッセージを表示します。
- -locale language_country_variant
-localeオプションは、標準ドックレットが提供するオプションすべて、または他の任意のドックレットの提供するオプションすべてより前 (左側) に指定する必要があります。そうしないと、ナビゲーションバーが英語で表示されます。このオプションは、唯一、指定する順序に依存するコマンド行オプションです。en_US(英語、米国)、en_US_WIN(Windows で使われる英語) などを指定します。ロケールを指定すると、javadoc は指定されたロケールのリソースファイルを選択してメッセージ (ナビゲーションバー、リストと表の見出し、ヘルプファイルの目次、stylesheet.css のコメントなどの文字列) に使います。また、アルファベット順にソートされるリストのソート順、および最初の文の末尾を決定する文の区切り文字も、指定したロケールによって決まります。このオプションは、ドキュメント化されるクラスのソースファイル内で指定されている doc コメントテキストのロケールを決定するものではありません。
- -encoding name
- ソースファイルのエンコーディング名 (
EUCJIS/SJISなど) を指定します。このオプションが指定されていない場合は、プラットフォームのデフォルトコンバータが使われます。- -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 には、絶対ディレクトリまたは現在の作業ディレクトリからの相対ディレクトリを指定できます。たとえば、次の例は、
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.3" com.mypackage- -footer footer
- -footer footer 各出力ファイルの下部に配置するフッタテキストを指定します。フッタは、下部ナビゲーションバーの右側に配置されます。 footer には、HTML タグと空白を含めることができますが、これらを含める場合は全体を引用符で囲まなければなりません。footer の中で引用符を使う場合は、引用符をエスケープする必要があります。
- -bottom text
- 各出力ファイルの最下部に配置するテキストを指定します。このテキストは、下部ナビゲーションバーの下のページの最下部に配置されます。text には、HTML タグと空白を含めることができますが、これらを含める場合は全体を引用符で囲まなければなりません。text の中で引用符を使う場合は、引用符をエスケープする必要があります。
- -link extdocURL
- javadoc により生成された既存の外部参照クラスのドキュメンテーションへのリンクを作成します。引数 extdocURL は、リンクを設定する外部ドキュメントの URL です。絶対 URL または 相対 URL のどちらかを指定できます。 相対 URL は生成先ディレクトリ (
-dで指定) の相対位置となります。言い換えると、このオプションを使うと、コードによって参照されていても、現在の javadoc の実行ではドキュメント化されないクラスにリンクできるようになります。リンクが有効なページに移動するようにするには、それらの HTML ページがどこにあるかを調べ、その場所を extdocURL に指定する必要があります。このオプションを使うと、たとえばサードパーティのドキュメンテーションから
http://java.sun.comのjava.*ドキュメンテーションにリンクすることができます。さらに、一連のパッケージに対して javadoc を実行したあと、これらのパッケージのサブセットに対してもう一度 javadoc を実行することで、一連のパッケージ全体のリンクを維持することもできます。3 回目の使用は、ドキュメントの更新用の「ハッキング」としての使用です。つまり、パッケージのセット全体に javadoc を実行してから、更新されたファイルをオリジナルのセットに挿入できるように、変更したパッケージの一部のセットだけに javadoc を実行します。この方法は時間を節約するために使われますが、扱いが難しいことがあります。 サブセットに対して API の追加または削除を行なった場合は、索引内のリンクが失われたり、壊れたりします。
-linkオプションの使用法は、次のとおりです。
- 現在実行中の javadoc によって生成されるドキュメンテーション内の API だけを対象にリンクを作成する場合は、
-linkオプションを省略します。ただし、-linkオプションがない場合、javadoc はドキュメントが存在するかどうか、また存在する場所を判別できないため、ドキュメントに外部参照のためのリンクを作成しません。
- javadoc で、外部参照クラスの、extdocURL にあるドキュメンテーションへのリンクも作成する場合は、
-linkオプションを指定します。URL が World Wide Web 上にある場合、javadoc がパッケージリストにアクセスするには、ドキュメンテーションの生成時に Web 接続が可能な状態になっていなければなりません。Web 接続が不可能な場合は、代わりに
-linkofflineを使用できます。パッケージリスト -
-linkオプションでは、javadoc によって生成されたpackage-listという名前のファイルが、このオプションで指定する URL に存在している必要があります。package-listファイルは、その場所でドキュメント化されているパッケージの名前のリストを含む単純なテキストファイルです。javadoc がどのようにパッケージリストを使用するかについては、以下で説明します。たとえば、Java 2 プラットフォーム v1.3 API のパッケージリストは
http://java.sun.com/products/jdk/1.3/docs/api/package-listにあり、次のようになっています。java.applet java.awt java.awt.color java.awt.datatransfer java.awt.dnd java.awt.event java.awt.font etc.
-linkオプションを指定せずに javadoc を実行する場合、ドキュメンテーションの生成時に外部参照クラスに属する名前を見つけると、javadoc は、その名前をリンクを持たない形で出力します。一方、-linkオプションが指定されている場合、javadoc は、指定された extdocURL のpackage-listファイルから、該当する名前のパッケージを探します。パッケージ名が見つかった場合は、その URL を名前の前に付けます。すべてのリンクが正しく機能するためには、外部参照のドキュメンテーションのすべてが、指定された URL に存在していなければなりません。javadoc は、package-list が存在するかどうかを調べるだけで、指定された URL に目的のページが存在するかどうかはチェックしません。
javadoc 指定された引数がパッケージではなくソースファイルである場合は、
package-listファイルは作成されますが、ファイルの内容は空になります。例 - たとえば、次のコマンドにより、Javadoc は、指定された URL で
package-listファイルを検索し、そのファイル内のパッケージ名を読み込んでから、これらの外部パッケージ内の API へのリンクを追加する際に、この指定された URL を使います。C:> javadoc -link http://java.sun.com/products/jdk/1.3/docs/api com.mypackage複数のリンク - 複数の-linkオプションを提供して、外部で生成されたドキュメントに任意数のリンクを設定できます。 既知のバグ - Javadoc 1.2 には、複数の -link コマンドを提供できないというバグがあります。これは 1.2.2 で修正されました。リンクする外部ドキュメントごとに別のリンクオプションを指定します。
C:> javadoc -linkextdocURL1-linkextdocURL2...-linkextdocURLncom.mypackageextdocURL1、extdocURL2、... extdocURLn は、それぞれ外部ドキュメントのルートを指し、各ルートには、
package-listという名前のファイルが含まれています。クロスリンク - まだ生成されていない 2 つ以上のドキュメントをクロスリンクする場合は、「ブートストラッピング」が必要になることに注意してください。言い換えると、どのドキュメントの
package-listも存在していない場合、最初のドキュメントに対して javadoc を実行した時点では、2 番目のドキュメントのpackage-listはまだ存在していません。したがって、外部リンクを作成するには、2 番目のドキュメントを生成したあと、最初のドキュメントを生成し直す必要があります。この場合、最初に行うドキュメント生成の目的は、そのドキュメントの
package-listを作成することです。 パッケージ名をすべて把握している場合は、package-list を手動で作成することもできます。次に、2 番目のドキュメントとその外部リンクを生成します。javadoc は、必要な外部のpackage-listファイルが存在しない場合は、警告を表示します。ドキュメントの更新 -
-linkオプションの 3 回目の使用は、プロジェクトで多数のパッケージを使い、すでにツリー全体に対して javadoc を実行してある場合に、次の実行では、すばやく細かい変更を行なってから、ソースツリーの一部に対してだけ javadoc を実行し直したい場合に便利です。これは、変更がドキュメンテーションコメントに対してであり、シグニチャーに対してではない場合にだけ正常に処理されるので、ハッキングのようなものです。ソースコードに対してシグニチャーを追加、削除または変更した場合は、索引、パッケージツリー、継承されるメンバのリスト、[使用] ページなどの場所で壊れたリンクが表示されます。まず、この部分的な新規実行用の実行先ディレクトリを作成し、
-linkおよび-dに同じ相対パスを設定します。オリジナルのドキュメントがhtmlという名前のディレクトリにある場合は、次のようになります。C:> javadoc -d update -link . html com.mypackagejavadoc の実行が終了したら、update内に生成されたファイルで、html内の元のファイルを上書きします。内容説明:一般に、javadoc を実行すると、シグニチャー、
@seeタグ、{@link}タグ、要約、階層、概要、および索引など、生成されたページの至る所に名前のリンクが生成される可能性があります。これらのリンクの一部は現在の実行で生成されるページに置かれますが、別のリンクは現在の実行では生成されないページに将来的には置かれています。- -linkoffline extdocURL packagelistLoc
- このオプションは、
-linkオプションを変えたものです。どちらも、外部参照クラスのドキュメントへのリンクを作成します。javadoc の実行時に、外部ドキュメントのpackage-listファイルが、extdocURL (オフライン) に存在せず、別の packageListLoc (ローカル) に存在する場合、-linkの代わりにこのオプションを指定する必要があります。これは、javadoc を実行中のシェルが extdocURL への Web アクセスがない場合に発生することがあります。このため、WWW 上でのみ extdocURL にアクセス可能な場合、-linkofflineを設定することにより、ドキュメンテーションの生成時に Web に接続するという制約がなくなります。例を示します。javadoc を実行するときに、複数の
-linkofflineオプションを指定できます。1.2.2 より前は、複数のオプションを指定することはできませんでした。引数を次に示します。
- extdocURL は、javadoc によって生成された、外部ドキュメンテーションのルートの URL です。この場所には、相対 URL または絶対 URL を指定できます。 相対 URL の場合、生成先ディレクトリ (
-dで指定) の相対位置で指定します。
- packagelistLoc は、外部ドキュメンテーションの
package-listファイルを含むディレクトリに対する位置を示します。これは、URL (http: または file:) とファイルパスのどちらでもかまいません。 また、絶対パスと相対パスのどちらでも指定できます。相対パスの場合は、javadoc が実行されるカレントディレクトリの相対パスになります。package-listファイル名を含めてはなりません。たとえば、
http://java.sun.com/products/jdk/1.3/docs/apiにあるjava.langパッケージにリンクを設定するが、シェルから Web にアクセスできない場合、http://java.sun.com/products/jdk/1.3/docs/api/package-listのpackage-listファイルにアクセスして、ローカルディレクトリに保存し、packagelistLoc でこのローカルコピーをポイントします。
package-listファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合、このファイルを手動で独自に作成し、packagelistLoc でそのパスを指定します。この方法は、パッケージ名はわかっているもののまだ公開されていない、新しい外部ドキュメンテーションにリンクするドキュメンテーションを生成する必要がある場合に便利です。Javadoc 1.0 や 1.1 などの初期バージョンで生成されたドキュメンテーションへのリンクを設定するためのpackage-listファイルを作成する方法もあります。 これらの初期バージョンではpackage-listファイルは生成されませんでした。2 つの企業が未公開の
package-listファイルを共有することも可能であるため、クロスリンクが設定されているドキュメンテーションを同時にリリースすることも可能です。次に示すように、このオプションを使うには、外部参照クラスの javadoc 生成ドキュメンテーションの場所を示す extdocURL1 と、このドキュメンテーションの
package-listファイルの場所を示す packagelistLoc1 を指定します。-linkofflineは、参照先の各生成ドキュメント 1 回ずつインクルードします。 次の例では、わかりやすくするためにオプションごとに行を分けています。
% javadoc -linkofflineextdocURL1packagelistLoc1\extdocURL2
-linkofflinepackagelistLoc2\
...たとえば、次のコマンドは、
package-listファイル (2 番目の引数で場所を指定) にあるパッケージのドキュメントを指すリンク (最初の引数で指定) を追加します。C:> javadoc -linkoffline http://java.sun.com/products/jdk/1.3/docs/api/jdk/1.3/docs/api/ ...- -group groupheading packagepattern
:packagepattern:...- 概要ページの複数のパッケージを指定のグループに分け、グループ単位で表を作成します。各グループは、それぞれ別の
-groupオプションで指定します。これらのグループは、コマンド行で指定した順序でページに表示されます。パッケージは、1 つのグループ内ではアルファベット順に並べられます。 各-groupオプションでは、packagepattern 式のリストに一致するパッケージが、見出し groupheading を持つ 1 つの表にまとめて表示されます。
- groupheading には任意のテキストを指定でき、空白を含めることができます。指定したテキストは、グループの表見出しになります。
- packagepattern には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (
*) を指定できます。アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。ワイルドカードとして許容されるのは、アスタリスクだけです。1 つのグループには、セミコロン (;) で区切った複数のパターンを含めることができます。注: パターンやパターンリスト内でアスタリスクを使う場合は、"java.lang*:java.util"のように、パターンリストを引用符で囲む必要があります。
-groupオプションが 1 つも指定されていない場合は、すべてのパッケージが、[パッケージ] という見出しを持つ 1 つのグループに入れられます。ドキュメント化されるパッケージの中に、指定したグループのどのグループにも入らないパッケージがある場合、このようなパッケージは [その他のパッケージ] という見出しを持つ独立したグループに入れられます。たとえば、次のようにオプションを指定すると、ドキュメント化される 4 つのパッケージは、コアパッケージ、拡張機能パッケージ、およびその他のパッケージに分かれます。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この結果、次のようなグループ化が行われます。
- Core Packages
java.langjava.lang.reflectjava.util- Extension Packages
javax.servlet- Other Packages
java.new- -nodeprecated
- 推奨されない API をドキュメンテーションに生成することを禁止します。これは、-nodeprecatedlist オプションを指定した場合の動作に加えて、ドキュメンテーションのほかの部分を通じて、推奨されない API を生成しないことと同じです。このオプションは、コードを記述していて、推奨されないコードを無視したい場合に便利です。
- -nodeprecatedlist
- 推奨されない API のリストを含むファイル (deprecated-list.html) の生成を禁止します。 また、このページへのリンクをナビゲーションバーに生成することを禁止します。ただし、ドキュメントのほかの部分では、推奨されない API の生成を続行します。このオプションは、推奨されない API がソースコードに含まれておらず、ナビゲーションバーをすっきりと見せたい場合に便利です。
- -nosince
- 生成されるドキュメントから、@since タグに関連した "Since" セクションを省略します。
- -notree
- 生成されるドキュメントからクラスおよびインタフェース階層を省略します。デフォルトでは、階層が作成されます。
- -noindex
- 生成されるドキュメントから索引を省略します。デフォルトでは、索引が作成されます。
- -nohelp
- 各出力ページの最上部と最下部のナビゲーションバーから [ヘルプ] リンクを省略します。
- -nonavbar
- 生成されるページの最上部と最下部に表示されるナビゲーションバー、ヘッダ、およびフッタの生成を禁止します。このオプションは、bottom オプションには影響しません。
-nonavbarオプションは、印刷するためだけにファイルを PostScript または PDF に変換する場合など、内容だけが重要でナビゲーションの必要性がない場合に便利です。- -helpfile path\filename
- 上部と下部のナビゲーションバーの [ヘルプ] リンクのリンク先となる代替ヘルプファイル path\filename のパスを指定します。このオプションが指定されていない場合、javadoc は、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 文字セットを指定します。例を示します。
% javadoc -charset "iso-8859-1" mypackage生成されるすべてのページの先頭に、次の行が挿入されます。<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">この META タグについては、HTML の標準 (4197265 および 4137321) を参照してください。- -docencoding name
- 生成される HTML ファイルのエンコーディングを指定します。
javadoc は、パッケージ全体に対して実行することも、個々のクラスに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。 次の例では、ソースファイルはC:\home\src\java\awt\*javaにあります。生成先ディレクトリはC:\home\htmlです。1 つ以上のパッケージのドキュメント化
パッケージをドキュメント化するには、そのパッケージのソースファイル (*.java) が、パッケージと同じ名前を持つディレクトリ内に存在していなければなりません。パッケージ名が、(ドットで区切られた) いくつかの識別子から構成されている場合は、各識別子がそれぞれ別のディレクトリを表します。したがって、すべてのjava.awtクラスは、java\awt\という名前のディレクトリに存在していなければなりません。javadoc は、次の 2 つのどちらかの方法で実行できます。 1 つは、(cdによって) ディレクトリを変更する方法、もう 1 つは-sourcepathオプションを使う方法です。パッケージのグループを指定する場合は、ワイルドカードは使用できません。
どちらのケースでも、パッケージ
- ケース 1 - パッケージディレクトリの変更 - 完全修飾パッケージの親ディレクトリに移動します。次に、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。
C:> cd C:\home\src\ C:> javadoc -d C:\home\html java.awt java.awt.event- ケース 2 - すべてのディレクトリから - このケースでは、現在のディレクトリがどのディレクトリでも問題はありません。完全修飾パッケージの親ディレクトリを
-sourcepathに指定し、ドキュメント化する 1 つ以上のパッケージの名前を指定して javadoc を実行します。C:> javadoc -d C:\home\html -sourcepath C:\home\src 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 - ソースディレクトリの変更 - ファイルのあるディレクトリに移動します。次に、ドキュメント化する 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 を実行するために使う効果的なコマンドです。ここでは、180M バイトのメモリを使用して、Java 2 Platform, Standard Edition, v1.2 に存在する、約 1500 の public および protected クラスのドキュメントを生成します。この例を 2 つの方法で示します。 最初の例はコマンド行で実行し、次の例は Makefile から実行します。オプションの引数に絶対パスを使用しているため、任意のディレクトリからこの Javadoc コマンドを実行できます。
コマンド行の例
次のコマンド行の例は 900 文字を超えているため、DOS などのシェルには大きすぎます。このコマンドを実行する代わりに、シェルスクリプトを記述することもできます。% 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 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>' \ -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \ -group "Extension Packages" "javax.*" \ -J-Xmx180m \ @filelistfilelistは、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 の引数は、単一引用符で囲みます。
注
CLASSPATH- 環境変数は、javadoc がユーザクラスファイルを探すときに使う、パスを指定します。環境変数は、
-classpathオプションによってオーバーライドされます。ディレクトリはセミコロンで分割します。 たとえば、次のとおりです。- .;C:\classes;C:\home\java\classes
現在のところ、Javadoc のエラーメッセージに関するドキュメントは存在しません。 トラブルシューティングに関するヒントは、Javadoc FAQ を参照してください。
JavadocTM は Sun Microsystems, Inc の商標です。(javadoc コマンド本体には商標シンボルは必要ありません。)