javadoc(1)

名前
javadoc - Java API ドキュメンテーションジェネレータ

形式
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

パラメータ
パラメータの順序は任意です。

options
    このドキュメントで指定されているコマンド行オプションです。 javadoc のオプションの一般的な使用法については、「使用例」を参照してください。

packagenames
    java.lang java.lang.reflect java.awt などの、スペースで区切られた 一連のパッケージ名です。ドキュメント化するパッケージごとに別個に 指定する必要があります。 javadoc はこれらのパッケージ名を探すとき、 -sourcepath を使用します。 javadoc は、サブパッケージを再帰的に処理することはありません。 アスタリスク (*) などのワイルドカードは使うことができません。 「1 つ以上のパッケージのドキュメント化」の 例を参照してください。

sourcefiles
    スペースで区切られた一連のファイル名です。パス、および アスタリスク (*) などのワイルドカードを含めることができます。 javadoc は、ソースファイル名の前にあるパスを使用して、 ソースファイル名を探します。 -sourcepath は使用しません。たとえば、 Button.java を渡すことは ./Button.java と指定することと同じです。完全パスを付けたソースファイル名の 例は「 /home/src/java/awt/Graphics*.java 」のようになります。「1 つ以上のクラスのドキュメント化」の例を 参照してください。また、「パッケージとクラスのドキュメント化」の 例のように、パッケージ名とソースファイルを組み合わせることもできます。

@files
    複数の packagenames および sourcefiles を任意の順に含む、1 つ以上のファイル名です。

機能説明
javadoc は、一連の Java ソースファイルの宣言およびドキュメンテーション コメントを解析し、デフォルトでは public クラスと protected クラス、 内部クラス、インタフェース、コンストラクタ、メソッド、および フィールドについて説明した一連の HTML ページを生成します。

javadoc は、パッケージ全体、個々のソースファイル、またはその両方に対して 実行できます。 javadoc をパッケージ全体に対して実行する場合は、一連の パッケージ名を javadoc に引数として渡します。個々の クラスに対して javadoc を実行する場合は、一連の ソース (.java) ファイル名を渡します。具体的な例は、 このページの最後で示します。

実装上の理由から、 javadoc は実行に java コンパイラを必要とし、java コンパイラに依存しています。 javadoc は javac の一部を呼び出して、宣言をコンパイルし、メンバの実装は無視します。 javadoc は、クラス階層を含むクラスの豊富な内部表現、および「使用」関係を 構築し、そこから HTML を生成します。 javadoc は、ソースコードのドキュメンテーションコメントから、ユーザの 提供するドキュメンテーションも取得します。

javadoc は、メソッド本体のない純粋なスタブファイルである .java ソースファイル上で実行されます。つまり、API の作成時には、コードを 記述する前の設計の早い段階でドキュメンテーションコメントを記述し、 javadoc を実行できます。

コンパイラに依存することによって、HTML 出力が、実際の実装に正確に対応 することが保証されます。実際の実装は、明示的でなく暗黙的に ソースコードに依存している場合があります。たとえば、 javadoc は、 .class ファイル内には存在するが、ソースコード内には存在しない デフォルトコンストラクタ (「Java Language Specification」の項 8.6.7) をドキュメント化します。

javadoc がドキュメンテーション用の内部構造を構築するときは、参照する クラスをすべてロードします。このため、ブートストラップクラス、 拡張機能、またはユーザクラスにかかわらず、 javadoc は、参照するクラスをすべて見つけられなければなりません。 詳細は、「クラスの検索方法」を参照してください。一般的に、作成する クラスは、拡張機能としてロードされるか、 javadoc のクラスパス内にある必要があります。

  Javadoc ドックレット
javadoc の出力の内容と形式は、ドックレットを使ってカスタマイズできます。 javadoc には、標準ドックレットと呼ばれるデフォルトの「組み込み型」 ドックレットがあり、これによって HTML 形式の API ドキュメンテーションを生成します。標準ドックレット の修正やサブクラス化を行なったり、HTML、XML、MIF、RTF などの好みの 出力形式を生成する独自のドックレットを記述することも可能です。 ドックレットとその使用法については、次を参照してください。

•   javadoc に施された機能強化

•   -doclet コマンド行オプション

-doclet コマンド行オプションでカスタムドックレットが指定されていない場合、 javadoc は、デフォルトの標準ドックレットを使用します。 javadoc ツールには、どのドックレットが使われているかには関係なく使用できる コマンド行オプションがあります。標準ドックレットでは、これらの ほかに、いくつかのコマンド行オプションが追加されます。どちらの オプションについても、後述の「オプション」で説明します。

  用語
いくつかの用語には、 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 は、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 パッケージのソースファイルが /home/user/src/java/applet ディレクトリに含まれているとすると、 /home/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 に 2 つ以上のパッケージ名を渡した 場合だけであることに注意する。詳細は、以下の「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 を 使う開発者ではなく、再実装者に必要な情報である。ナビゲーションバーに リンクがない場合、任意の直列化されたクラスに移動して、 クラスの [関連項目] セクション内の [直列化された形式] をクリック するとこの情報を取得できる

•   インデックス (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 ファイルのディレクトリ。 javadoc はこのようなファイルを処理しない。つまり、このようなファイル内の javadoc タグはすべて無視される。ソースツリーに存在しない限り、この ディレクトリは生成されない

  HTML フレーム
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.awt

HTML フレームが必要かどうかによって、次のどちらかのファイルを 開始ページとしてロードします。

•   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 | このパッケージが使われる場所
files | イメージとサンプルファイルがあるディレクトリ
class-use | API を使用するページがあるディレクトリ
Applet.html | Applet クラスを使用するページ
AppletContext.html | AppletContext インタフェースを使用するページ
AppletStub.html | AppletStub インタフェースを使用するページ
AudioClip.html | AudioClip インタフェースを使用するページ

  ドキュメンテーションコメント: ソースコードへのコメント

ソースコードの任意のエンティティ (クラス、インタフェース、 メソッド、コンストラクタ、 またはフィールド) の宣言の前には、ドキュメンテーションコメントを 入れることができます。このコメントは、 javadoc コメントとも呼ばれています。doc コメントは、コメントを 開始する文字 /** から、コメントを終了する文字 */ までの間の 文字です。コメントは複数行にまたがることができます。

    /**
    * This is the typical format of a simple documentation comment.
    */

次のように、コメントは 1 行にまとめることもできます。

    /** This comment takes up only one line. */

ドキュメンテーションコメントが認識されるのは、クラス、 インタフェース、コンストラクタ、メソッド、またはフィールド 宣言の前に置かれた場合だけです (クラス、メソッド、およびフィールドの 例を参照)。メソッドの本体に置かれたドキュメンテーション コメントは無視されます。 javadoc ツールは、宣言文ごとに 1 つのドキュメンテーションコメントだけを 認識します。

よく発生する間違いは、重要な文をクラスコメントとクラス宣言の間に 入れてしまうことです。 javadoc はクラスコメントを無視するため、注意してください。

    /**
    * This is the class comment for the class Whatever.
    */
    import com.sun;   // MISTAKE - Important not to put statements here
    public class Whatever {
    }

コメントは、説明とそれに続くタグから構成されています。 説明は開始区切り文字 /** から始まり、タグ付き段落まで続きます。タグ付き段落は行頭の @ 文字から始まります。この文字よりも前にあるアスタリスクおよび空白は すべて無視 されます。タグ付き段落が始まった後では、説明は継続できません。 タグの数は 任意です。いくつかの種類のタグは繰り返すことができますが、 できないものもあります。 次の @see はタグ付き段落を開始します。

     /**
     * This is a doc comment.
     * @see java.lang.Object
     */

コメントは HTML で記述します。テキストは HTML で 記述しなければなりません。 これは、HTML のエンティティを使う必要があること、 および HTML タグを使用できること を意味します。HTML は、使用するブラウザがサポートする 任意のバージョンを使うことが できます。標準ドックレットは、階層式スタイルシートと フレームを含むほかの部分 (ドキュメンテーションコメント 以外) は、HTML 3.2 に準拠したコードを生成するように記述 されています (フレームセット対応のため、生成される各 ファイルは、「HTML 4.0」で始まる)。

たとえば、より小さい (<) およびより大きい (>) という 記号は、 &lt; と &gt; と記述する必要があります。同様に、アンパサンド (&) は、 &amp; と記述する必要があります。次の例で は、ボールドの HTML タグ <b> を示します。

次に doc コメントを示します。

    /**
    * This is a <b>doc</b> comment.
    * @see java.lang.Object
    */

javadoc は、doc コメントを解析するときに、各行の先頭にある 文字アスタリスク (*) をすべて破棄し ます。また、最初のアスタリスク (*) より前の空白と タブも破棄します。したがって、 行頭の空白をそのままにしておきたい場合は、 先頭のアスタリスクを省略してはな りません。たとえば、 <pre> タグを使って、サンプルコードをインデントする場合などです。

各 doc コメントの最初の文は、宣言されている エンティティに関する簡潔かつ完全 な説明を含む要約文でなければなりません。 この文は、空白、タブ、または行末記 号が続いている最初のピリオド、あるいは最初のタグで終了します。 javadoc は、HTML ページの最初にあるメンバ要約に、この最初の文をコピーします。

java では、単一の文で複数のフィールドを宣言できます。 しかし、この文のドキュメンテ ーションコメントは 1 つだけで、このコメントが すべてのフィールドにコピーされます。 したがって、フィールドごとに個々の ドキュメンテーションコメントを付けたい場合は、 各フィールドを異なる文で宣言しなければなりません。 たとえば、次のドキュメンテー ションコメントは単一の宣言としては意味を成さず、 2 つの宣言として処理するべき です。

    /**
    * The horizontal and vertical distances of point (x,y)
    */
    public int x, y;      // Avoid this

javadoc は、上記コードから次のドキュメンテーションを生成します。

    public int x
    The horizontal and vertical distances of point (x,y).
    public int y
    The horizontal and vertical distances of point (x,y).

ヘッダタグを使用するときは注意してください。 メンバ用のドキュメンテーションコ メントを書くときは、 <H1> や <H2> などの HTML ヘッダタグを使用しないでください。これは、 javadoc が全ドキュメントを構造化して生成するため、 これらの構造化タグを使用すると、 ドキュメントの書式が乱れる可能性があるためです。 しかし、クラスやパッケージの コメントでは、これらのヘッダタグを使用して構造化を指示してください。

メソッドのコメントの自動再利用は、コメントの継承とも呼びます。 クラスまたはインタフェースのメソッドがドキュメンテーションコメント またはタグを持たない場合、 javadoc は、以前オーバーライドまたは実装したメソッドがあれば、そのメソッドから コメントまたはタグを再利用します。次の場合に、これを行います。

•   クラスのメソッドがスーパークラスのメソッドをオーバーライドした
•   インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドした
•   クラスのメソッドがインタフェースのメソッドを実装した

最初の 2 つの場合、メソッド m() が別のメソッドをオーバーライドすると、 javadoc は m() のドキュメンテーションに「オーバーライド」という サブヘッダを作成し、また、オーバーライドするメソッドへのリンクも作成します。

3 つ目の場合、特定のクラスのメソッド m() がインタフェースの メソッドを実装すると、 javadoc は m() のドキュメンテーションに「定義」という サブヘッダを作成し、また、実装するメソッドへのリンクも作成します。

検索する方法は、クラス C のメソッドの場合、 javadoc はクラス C が実装するすべてのインタフェースを再帰的に検索し、 次に C のスーパークラスすべてを検索します。インタフェース I のメソッドの場合、 javadoc は I のスーパーインタフェースすべてを再帰的に検索します。 どちらの場合も、最初に検索したコメントをコピーします。

ドキュメンテーションコメントの仕様については、「Java Language Specification」 (James Gosling、Bill Joy、Guy Steele 共著) の第 18 章「Documentation Comments」を 参照してください。

  javadoc のタグ

javadoc は、 javadoc コメント内に埋め込まれた特殊なタグを解析します。これらの 特殊な doc タグを使うと、 書式の整った完全な API ドキュメンテーションをソース コードから自動的に生成できます。 タグは、単価記号 (@) で始まり、大文字小文字が 区別されます。これらのタグは、 以下に示すとおりに、大文字と小文字を区別して入力する 必要があります。タグは、行 の先頭 (ただし先行する空白と省略可能なアスタリスクは除く) から 始めなければなり ません。慣習上、同じ名前のタグは 1 個所にまとめて記述します。 たとえば、 @see タグが複数ある場合は、すべてを 1 個所にまとめて記述します。

今後のリリースで導入されるタグについては、 「Proposed Javadoc Tags」を参照してください。

現時点で有効なタグを以下に示します。

タグ | 導入された JDK
 | のバージョン
@author | 1.0
{@docRoot} | 1.3
@deprecated | 1.0
@exception | 1.0
{@link} | 1.2
@param | 1.0
@return | 1.0
@see | 1.0
@serial | 1.2
@serialData | 1.2
@serialField | 1.2
@since | 1.1
@throws | 1.2
@version | 1.0

@author name-text
    -author オプションが使われている場合、 生成されるドキュメントに、指定された name-text を持つ Author エントリを追加します。 1 つの doc コメントに複数の @author タグを含めることができます。 @author タグごとに 1 つ、またはタグごとに複数の名前を 指定できます。前者の場合は、 javadoc は、名前と名前の間にコンマ (,) とスペースを挿入します。 後者の場合、テキスト全体が 解析されることなく生成されるドキュメントにコピーされます。 このため、コンマ以外 の現地仕様の名前区切り文字を使う場合は、1 行に複数の名前を指定します。

{@docRoot}
    生成された任意のページを起点とした、ドキュメントの (出力先) ルートディレクトリの相対パスを表します。このタグは、著作権ページ または会社のロゴなど、生成されるすべてのページから参照するファイル を取り込むときに使います。通常は、各ページの最下部から著作権 ページにリンクします。

    この {@docRoot} タグは、コマンド行および doc コメントで使うことができます。

    1.  コマンド行では、次のようにヘッダ (header)、フッタ (footer)、またはページの最下部 (bottom)を定義します。

        javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'

    2.  doc コメントには次のように記述します。

        /**
        * 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 の場合

@deprecated deprecated-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 タグ」 を参照してください。

@exception class-name description
    @exception タグは、 @throws と同義です。

{@link name label}
    指定された名前を指すインラインリンクを挿入します。 このタグの name と label の構文 は、後述する @see タグと同じですが、関連項目セクションにリンクを置くのではなく、 インラインリンクを生成 する点が異なります。インラインテキストのほかの部分と 区別するため、このタグの開始と 終了には大括弧を使います。ラベルの中で「}」を 使う必要がある場合は、HTML のエン ティティ表記法の &#125; を使います。

    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.

@param parameter-name description
    Parameters セクションにパラメータを追加します。 説明は次の行に続けて記述できます。

@return description
    description で指定されたテキストを持つ戻り値 セクションを追加します。テキストでは、 戻り値の型と取り得る値の範囲について記述する必要があります。

@see reference
    reference を指すリンクまたはテキストエントリを 持つ [関連項目] 見出しを追加します。 doc コメントには任意の数の @see タグを含めることができ、これらのタグはすべて 同じ見出しの下にまとめられます。 @see タグには次の 3 つの形式があります。3 番目がもっとも一般的な形式です。

@see string
    注: この形式は JDK 1.2 では使用できません。 この形式では、引用されたテキストが 表示されません。 ただし、JDK 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

@see package.class#member label
    Java 言語で指定された名前のドキュメンテーションを指す、 表示テキスト label を持つ リンクを追加します。label は省略可能です。label を省略した場合は、 該当する名前が 適切に短くされて (「名前の表示方法」を参照)、 表示テキストとして代わりに表示されます。ラベルは、表示 テキストを短縮する場合や、該当する名前と異なる 表示テキストを指定する場合に使 います。

    JDK 1.2 では、ラベルではなく、名前だけが <code> HTML タグに囲まれて自動的に表示されます。JDK 1.2.2 以降は、 <code> は常に、ラベルが使用されているかどうかにかかわらず、 表示可能なテキストを囲みます。

    •   package.class#member には、Java 言語で有効な任意の名前、つまりパッケージ、 クラス、インタフェース、 コンストラクタ、メソッド、またはフィールドの名前を指定します 。ただし、メンバ名の前の ドットは、ハッシュ文字 (#) で置き換えます。 指定した名前が、ドキュメント化されるクラス にある場合、 javadoc は該当する名前へのリンクを自動的に作成します。 外部参照クラスへのリンクを作成する には、 -link オプションを使います。参照されるクラスに属していない名前の ドキュメンテーションを参 照するには、ほかの 2 つの形式の @see タグを使います。1 番目の引数については、「名前の指定」 で 詳しく説明します。

    •   label は省略可能なテキストで、 リンクのラベルとして表示されます。label には空白を含 めることができます。label を省略した場合は、 package.class.member が、現在のクラスおよびパッケージに応じて 適切に短くされて表示されます。「名前の表示方法」を参照してください。

    •   空白文字は package.class#member と label の間の区切り文字です。括弧内の空白文字は、 ラベルの開始を意味しないため、 メソッドのパラメータ間のデリミタとして使うことができます。

    この例では、Character クラスの @see タグが String クラスの equals メソッドを参照しています。 タグには、名前 String#equals(Object) とラベル equals の 両方の引数が含まれています。

          /**
          * @see String#equals(Object) equals
          */

    標準ドックレットは、次のような HTML を生成します。

        <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 #field
    @see #method(Type, Type,...)
    @see #method(Type argname, Type argname,...)
    現在の、またはインポートされたパッケージの別のクラスを参照する
    @see Class#field
    @see Class#method(Type, Type,...)
    @see Class#method(Type argname, Type argname,...)
    @see Class
    別のパッケージを参照する (完全修飾)
    @see package.Class#field
    @see package.Class#method(Type, Type,...)
    @see package.Class#method(Type argname, Type argname,...)
    @see package.Class
    @see package

    上の表に対する注を以下に示します。

    •   クラスまたはパッケージを省いた最初の形式のセットでは、 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 Language Specification」の第 6 章「Names」で 正式に定義され、 内部クラス仕様で修正されています。具体的には、 検索は次の順序で行われます。

    1.  現在のクラスまたはインタフェース
    2.  名前を囲むクラスとインタフェース。もっとも近いものを最初に検索
    3.  スーパークラスとスーパーインタフェース。もっとも近いものを最初に検索
    4.  現在のパッケージ
    5.  インポートされるパッケージ、クラス、 およびインタフェース。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"

@since since-text
    生成されるドキュメントに、指定された since-text を持つ [導入されたバージョン] 見出しを追加します。このテキストには、 特別な内部構造はありません。このタグは、 特定の変更または機能が、since-text によって 指定されたソフトウェアのリリース以来、 継続して存在することを意味します。たとえば、次のとおりです。

    @since JDK1.1

@serial field-description
    デフォルトの直列化可能フィールドの doc コメントで使用します。

    省略可能な field-description は、 フィールドの doc コメントを拡張します。 この説明では、フィールドの意味および 取り得る値のリストを指定しなければなりません。 必要な場合には、複数の行にまたがって説明を記述することができます。

    @since タグは、Serializable クラスの初期バージョン以来 追加されている各直列化フィールド に対して追加する必要があります。

    -private クラスの直列化された形式を取得するには、 -private オプションを使います。したがって、public および private クラスの 両方の直列化された 形式を生成するには、 javadoc でこの -private オプションを使います。

    これらのタグの使用法についての詳細と 使用例は、「Java オブジェクト直列化仕様」 の 1.6 節 「クラスの直列化可能なフィールドおよびデータの文書化」を 参照してください。 また、「Serialization FAQ」も参照してください。ここには、「なぜ javadoc 標準 doclet は @serial タグと @serialData タグがない場合について頻繁に警告を出すのか」と「 javadoc を -private スイッチで実行していない場合、なぜ javadoc は private フィールドの @serial タグがないことについて警告を出すのか」という質問とその回答があります。

@serialField field-name  field-type  field-description
    Serializable クラスの serialPersistentFields メンバの ObjectStreamField コンポーネント をドキュメント化します。各 ObjectStreamField コンポーネントに対して @serialField タグを 1 つ使う必要があります。

@serialData data-description
    data-description は、データのシーケンスと型、特に writeObject メソッドによって書き込ま れる任意指定のデータ、および Externalizable.writeExternal メソッド によって書き込まれ るすべてのデータのシーケンスと型をドキュメント化します。

    @serialData タグは、writeObject、readObject、writeExternal、および readExternal の各メソッドの doc コメントで使用できます。

@throws class-name  description
    @throws タグと @exception タグは同義です。生成されるドキュメン テーションに、 class-name および description テキストを持つ [例外] 小見出しを追加します。 class-name は、該当するメソッドによって スローされる可能性のある例外の名前です。このクラスが完全 修飾されていない場合、 javadoc は検索順序に従ってクラスを探します。

@version version-text
    -version オプションが使われている場合、生成されるドキュメンテーションに、 指定された version-text を持つ [バージョン] 小見出しを追加します。 このテキストには、特別な 内部構造はありません。1 つの doc コメントに含めることのできる @version タグは 1 つ以下です。通常、バージョンは、該当するクラスまたは メンバを含むソフト ウェア (JDK など) のバージョンを指します。

  タグを使用できる場所
以下では、タグを使用できる場所について説明します。@see、@link、@since、および @deprecated の 4 つのタグは、すべての doc コメントで使用できます。

  概要ドキュメンテーションタグ
概要タグは、概要ページのドキュメンテーション コメント (通常は overview.html という名前のソースファイル内にある) で使用できるタグです。 ほかのドキュメンテーション コメントと同様に、これらのタグは、説明のあとで使う必要があります。

注: JDK 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 1.12, 05/12/00
    * @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.my.package1
    com.my.package2
    com.my.package3

次のコマンドを使って、 javadoc を実行できます。

    example% javadoc -d apidocs @packages

オプション
javadoc ツールは、ドックレットを使って出力を決定します。 javadoc は、 -doclet オプションでカスタムドックレットが指定されている場合以外は、 デフォルトの標準ドック レットを使います。 javadoc には、任意のドックレットとともに使用できるコマンド行 オプションがあります。これらのオプ ションについては、後述の「javadoc のオプション」で説明します。 標準ドックレットでは、こ のほかに、いくつかの追加のコマンド行オプションが提供されます。 これらのオプションに ついては、後述の「標準ドックレットが提供するオプション」で 説明します。どのオプション 名も大文字と小文字を区別しません。ただし、オプションの引数では 大文字と小文字が区 別されることがあります。

オプションを以下に示します。

    -1.1 | -header | -package
    -author | -help | -private
    -bootclasspath | -helpfile | -protected
    -bottom | -J | -public
    -charset | -link | -serialwarn
    -classpath | -linkoffline | -sourcepath
    -d | -locale | -splitindex
    -docencoding | -nodeprecated | -stylesheetfile
    -doclet | -nodeprecatedlist | -title
    -docletpath | -nohelp | -use
    -doctitle | -noindex | -verbose
    -encoding | -nonavbar | -version
    -extdirs | -notree | -windowtitle
    -footer | -overview
    -group

  Javadoc のオプション

-overview path/filename
    javadoc に対して、 path/filename で指定された「ソース」ファイルから 概要ドキュメント用のテキスト を取得し、概要ページ (overview-summary.html) に配置することを 指示します。 path/filename は、 -sourcepath への相対パスです。

    filename と path には、それぞれ任意の名前と場所を指定できますが、通常は、 overview.html という名前を付けて、ソースツリー内の最上位の パッケージディレクトリを含むディレクトリ に配置します。この場所では、 -sourcepath がこのファイルを指すので、パッケージを ドキュメント化する際に path が必要ありません。 たとえば、java.lang パッケージのソースツリーが /src/classes/java/lang/ の場合、概要ファイルを /src/classes/overview.html に配置できます。「使用例」を参照してください。

    path/filename で指定するファイルについては、 「概要コメントファイル」を参照してください。

    概要ページが作成されるのは、 javadoc に 2 つ以上のパッケージ名を渡した場合だけです。 詳細は、「HTML フレーム」 節を参照してください。

-public
    public なクラスとメンバだけを表示します。

-protected
    protected および public なクラスとメンバだけを表示します。 これはデフォルトの動作です。

-package
    パッケージ、および protected と public な クラスとメンバだけを表示します。

-private
    すべてのクラスとメンバを表示します。

-help
    オンラインヘルプを表示します。 javadoc とドックレットのコマンド行オプションの一覧が表示されます。

-doclet class
    ドキュメンテーションの生成に使う ドックレットを起動するためのクラスファイルを指定します。 ドックレットでは、出力の内容と形式を定義します。 -doclet オプションが使われていない場合、 javadoc は標準ドックレットを使ってデフォルトの HTML 形式を生成します。 このクラスには、 start(Root) メソッドが含まれていなければなりません。 この起動クラスへのパスは、 -docletpath オプションによって定義されます。

-docletpath classpathlist
    -doclet オプションで指定されているドックレットクラス ファイルへのパスを指定します。 目的のドックレットが検索パス内にある場合は、 このオプションは不要です。

-1.1
    javadoc 1.1 によって生成されるドキュメンテーションの 外観および機能を持つドキュメンテーション を生成します。生成されるページの背景は灰色になり、 ヘッダにはイメージが使われ、 表ではなく丸印を使ったリストが使われます。また、 生成先ディレクトリは平坦な構造になり、 継承された API は含まれなくなり、 HTML フレームは使われず、内部クラスはサポート されません。また、このオプションでは、 インデックスをアルファベットごとに自動的に分類 し、別々のファイルに格納します。このような 外観を持つ出力を得たい場合、このオプション を使うと、 javadoc 1.1 に存在していたいくつかのバグを回避できる利点があります。

    -1.1 オプションとは同時に使用できないオプションがあります。 使用可能な他のオプションを 見つけるには、次のようにコマンド入力します。

        example% javadoc -1.1 -help

    このリスト内の -footer オプションの機能は、このページの別の場所で説明する -bottom オプションと同じです。 -title オプションの機能は、 -doctitle オプションと同じです。

-sourcepath sourcepathlist
    javadoc コマンドにパッケージ名を渡す際に、 ソースファイル (.java) 検索用のパスを指定します。 -sourcepath オプションは、 javadoc コマンドを使ってパッケージ名を指定するときにだけ使用でき、 javadoc コマンドに渡される .java ファイルは検索できないことに注意してください。 .java ファイルを検索するには、 そのディレクトリに移動するか、 各ファイルの前にそのパスを付けます (「1 つ以上 のパッケージのドキュメント化」を参照)。 -sourcepath が省略された場合は、 javadoc はクラスパスを使ってソースファイルを検索します ( -classpath を参照)。 したがって、 -sourcepath のデフォルトは -classpath の値です。 -classpath を省略してパッケージ名を javadoc に渡した場合、 javadoc は、ソースファイルの現在のディレクトリ (およびサブディレクトリ) を 検索します。

    sourcepathlist では、ドキュメント化するパッケージ名の ソースツリーのルートディレクトリを 設定します。たとえば、ソースファイルが次の 場所にある com.mypackage という名前のパッケージをドキュメント化するとします。

        /home/user/src/com/mypackage/*.java

    この場合、次のようにしてソースパスを /home/user/src 、つまり com.mypackage を含むディレクトリに指定し、それからパッケージ名 com.mypackage を指定します。

        example% javadoc -sourcepath /home/user/src/ com.mypackage

    これは、ソースパスの値とパッケージ名をつなげて、 ドットをスラッシュ (/) に変えると、以下のパッケージのフルパス になることに注目すると覚えやすいでしょう。

        /home/user/src/com/mypackage

-classpath classpathlist
    javadoc が参照されるクラスの検索を行うパスを指定します。 参照されるクラス (.class) とは、 ドキュメント化されるクラスとそれらのクラスによって 参照される任意のクラスのことです。 javadoc は、指定されたパス以下のすべてのサブディレクトリで 検索を行います。クラスパスリストに は、パス間をコロンで区切って複数のパスを 含めることができます。 classpathlist の指定 については、クラスパスのドキュメントを参照してください。

    -sourcepath を省略した場合は、 javadoc は、クラスファイル (下位互換用) とともに、 -classpath を使ってソースファイルを検索します。このため、 異なるパス内のソースファイルおよびクラスファイルを検索する場合は、 -sourcepath と -classpath の両方を使います。

    たとえば、 com.mypackage をドキュメント化したい場合に、パッケージのクラスがディレクトリ /home/user/src/com/mypackage にあり、このパッケージが /home/user/lib 内のライブラリを使う場合は、次のように指定します。

        example% javadoc -classpath /home/user/lib -sourcepath \
                       /home/user/src com.mypackage

    ほかのツールと同様に、 -classpath を指定しない場合は、CLASSPATH 環境変数が 設定されていれば、 javadoc はこの環境変数を使います。 どちらも設定されていない場合 は、 javadoc は現在のディレクトリでクラスを検索します。

    javadoc が拡張機能クラスおよびブートストラップクラスと通信する際に、 -classpath を使ってユーザクラスを検索する方法についての 詳細は、「クラスの検索方法」を 参照してください。

-bootclasspath classpathlist
    ブートクラスが存在するパスを指定します。 ブートクラスとは、Java コアクラスのことです。 bootclasspath は、 javadoc がソースファイルとクラスファイルを探すときに 使う検索パスの一部です。詳細は、 「Javac と Javadoc がクラスを検索する方法」 を 参照してください。 classpathlist 内の複数の クラスパスリストは、コロン (:) で区切ります。

-extdirs dirlist
    拡張機能クラスが存在するディレクトリを指定します。 拡張機能クラスは、Java 拡張機能 機構を使うすべてのクラスです。拡張機能ディレクトリ ( extdirs ) は、 javadoc がソースファイルとクラスファイルを探すときに使う検索パスの一部です。 詳細は、上の -classpath を参照してください。 dirlist 内の複数のディレクトリは、 コロン (:) で区切ります。

-verbose
    javadoc の実行中に詳細なメッセージを表示します。冗長オプションを 指定しない場合は、ソースファイルのロード時、ドキュメンテーションの 生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時に メッセージが表示されます。冗長オプションを指定した場合は、 各 java ソースファイルの解析に要したミリ秒数などの 追加メッセージを表示します。

-locale language_country_variant
    javadoc がドキュメンテーションを生成するときに使うロケールを指定します。 引数には、java.util.Locale のドキュメンテーションで説明されている ロケールを指定します。 たとえば、en_US (英語、米国)、en_US_WIN (Windows で使われる英語) などを 指定します。

    ロケールを指定すると、 javadoc は指定されたロケールのリソースファイルを選択して メッセージ (ナビゲーションバー、リストと表の見出し、 ヘルプファイルの目次、 stylesheet.css のコメントなどの文字列) に 使います。また、アルファベット順にソートされるリストのソート順、 および最初の文の末尾を決定する文の区切り文字も、 指定したロケールによって決まります。このオプションは、 ドキュメント化されるクラスのソースファイル内で 指定されている doc コメントテキストの ロケールを決定するものではありません。

-encoding name
    ソースファイルのエンコーディング名 (EUCJIS/SJIS など) を指定します。 このオプションが指定されていない場合は、プラットフォームの デフォルトコンバータが使われます。

-Jflag
    javadoc を実行する実行システム java に flag を直接渡します。J と flag の間に 空白を入れることはできません。たとえば、生成される ドキュメンテーションを処理するために、システムで 32M バイトを 確保する必要がある場合は、次のようにします。

    example% javadoc -J-Xmx32m -J-Xms32m com.mypackage

  標準ドックレットが提供するオプション

-d directory
    生成された HTML ファイルを保存するディレクトリを 指定します (d は「生成先 (destination)」の意味)。このオプションを 省略すると、生成されたファイルは現在のディレクトリに保存されます。 値 directory には、絶対ディレクトリまたは現在の作業 ディレクトリからの相対ディレクトリを指定できます。たとえば、 次の例は、com.mypackage パッケージのドキュメンテーションを生成し、 結果を /home/user/doc/ ディレクトリに保存します。

    example% javadoc -d /home/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 テキストを含めます。このテキストは、デフォルトでは省略されます。

-author
    生成されるドキュメントに @author テキストを含めます。

-splitindex
    インデックスファイルをアルファベットごとに複数のファイルに分割し、 文字ごとに 1 つのファイルと、アルファベット以外の文字で始まる インデックスエントリ用のファイルを 1 つ作成します。

-windowtitle title
    HTML の <title> タグで使うタイトルを指定します。指定したタイトルは、 ウィンドウタイトルと、該当するページに対して作成されたブラウザの ブックマーク (よくアクセスする場所) に表示されます。 タイトルには HTML タグを含めないでください。タイトルに HTML タグが 含まれていると、ブラウザによるタグの解釈が不適切になる 可能性があります。 title の中で引用符を使う場合は、引用符を エスケープする必要があります。 -windowtitle が省略されている場合、 javadoc はこのオプションの代わりに -doctitle の値を使います。

-doctitle title
    概要ファイルの最上部近くに配置するタイトルを指定します。 タイトルは中央揃えされ、レベル 1 の見出しとして上部 ナビゲーションバーのすぐ下に置かれます。 title には、HTML タグと 空白を含めることができますが、これらを含める場合は全体を引用符で囲 まなければなりません。 title の中で引用符を使う場合は、引用符をエスケープする必要があります。

-title title
    このオプションは、現在は存在しません。 javadoc 1.2 のベータ版にだけ存在しました。このオプションは、 ウィンドウタイトルではなくドキュメントタイトルを定義することを 明確にするため、 -doctitle に名前が変更されました。

-header header
    各出力ファイルの上部に配置するヘッダテキストを指定します。ヘッダは、 上部ナビゲーションバーの右側に配置されます。 header には、HTML タグと 空白を含めることができますが、これらを含める場合は全体を引用符で 囲まなければなりません。header の中で引用符を使う場合は、引用符を エスケープする必要があります。

-footer footer
    各出力ファイルの下部に配置するフッタテキストを指定します。フッタは、 下部ナビゲーションバーの右側に配置されます。 footer には、HTML タグと 空白を含めることができますが、これらを含める場合は全体を引用符で 囲まなければなりません。 footer の中で引用符を使う場合は、引用符をエスケープする必要があります。

-bottom text
    各出力ファイルの最下部に配置するテキストを指定します。 このテキストは、下部ナビゲーションバーの下のページの最下部に 配置されます。 text には、HTML タグと空白を含めることができますが、 これらを含める場合は全体を引用符で囲まなければなりません。 text の中で引用符を使う場合は、引用符をエスケープする必要があります。

-link docURL
    javadoc により生成された既存の外部参照クラスの ドキュメンテーションへのリンクを作成します。引数 docURL は、リンクを設定する、javadoc で生成した外部ドキュメントの URLです。 この場所は、相対 URL または絶対 URL で指定できます。

    言い換えると、このオプションを使うと、コードによって 参照されていても、現在の javadoc の実行ではドキュメント化されないクラスにリンクできるようになります。 リンクが有効なページを参照するようにするには、それらの HTML ページ がどこにあるかを調べ、その場所を docURL に指定する必要があります。 このオプションを使うと、たとえば Sun 以外のドキュメンテーション から http://java.sun.com の java.* にリンクすることができます。また、一連のパッケージに対して javadoc を実行したあと、別の一連のパッケージに対して javadoc を実行することで、両方のパッケージの間にクロスリンクを 作成することもできます。さらに、 一連のパッケージに対して javadoc を実行したあと、これらのパッケージのサブセットに対してもう一度 javadoc を実行することで、一連のパッケージ全体のリンクを維持すること もできます。3 回目の使用は、ドキュメントの更新用の「ハッキング」 としての使用です。つまり、パッケージのセット全体に javadoc を実行してから、更新されたファイルをオリジナルのセットに 挿入できるように、変更したパッケージの一部のセットだけに javadoc を実行します。この方法は時間を節約するために使われますが、 扱いが難しいことがあります。サブセットに対して API の追加または 削除を行なった場合は、インデックス内のリンクが失われたり、 壊れたりします。

    -link オプションの使用法は、次のとおりです。

    •   現在実行中の javadoc によって生成されるドキュメンテーション内の API だけを対象に リンクを作成する場合は、 -link オプションを省略します。ただし、 -link オプションがない場合、 javadoc はドキュメントが存在するかどうか、また存在する場所を 判別できないため、ドキュメントに外部参照のためのリンクを作成しません。

    •   外部参照クラスを対象に、 docURL で指定された場所にある ドキュメンテーションへのリンクも作成する場合は、 -link オプションを指定します。

    URL が World Wide Web 上にある場合、 javadoc がパッケージリストにアクセスするには、ドキュメンテーションの 生成時に Web 接続が可能な状態になっていなければなりません。Web 接続 が不可能な場合は、代わりに -linkoffline を使用できます。

    パッケージリスト: -link オプションでは、javadoc によって生成された package-list という名前のファイルが、このオプションで指定する URL に存在している 必要があります。 package-list ファイルは、その場所でドキュメント化されているパッケージの 名前のリストを含む単純なテキストファイルです。 javadoc がどのようにパッケージリストを使用するかについては、 以下で説明します。

    たとえば、Java プラットフォーム 1.2 API のパッケージリストは以下にあり、

        http://java.sun.com/products/jdk/1.2/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 オプションが指定されている場合、 javadoc は、指定された docURL の場所にある package-list ファイルから、該当する名前のパッケージを探します。パッケージ名が 見つかった場合は、その URL を名前の前に付けます。指定された URL が 相対 URL で、 -d オプションの生成先ディレクトリが相対パスである場合、 javadoc は URL に生成先ディレクトリの相対パスを付加し、生成先ディレクトリを 起点としてリンクが動作するようにします。

    すべてのリンクが正しく機能するためには、外部参照の ドキュメンテーションのすべてが、指定された URL に 存在していなければなりません。 javadoc は、 package-list が存在するかどうかを調べるだけで、指定された URL に 目的のページが存在するかどうかはチェックしません。

    javadoc に与えられた引数がパッケージではなくソースファイルである場合は、 package-list ファイルは作成されますが、ファイルの内容は空になります。

    たとえば、次のコマンドにより、 javadoc は、指定された URL で package-list ファイルを検索し、そのファイル内のパッケージ名を読み込んでから、 これらの外部パッケージ内の API へのリンクを追加する際に、 この指定された URL を使います。

        example% javadoc -link \
           http://java.sun.com/products/jdk/1.2/docs/api com.mypackage

    複数のリンク: 複数の -link オプションを提供して、外部で生成されたドキュメントに任意数のリンクを設定できます。 既知のバグ —Javadoc 1.2 には、複数の -link コマンドを提供できないというバグがあります。このバグは、 将来のリリースでは修正される予定です。

    リンクする外部ドキュメントごとに別のリンクオプションを指定します。

        example% javadoc -link docURL1 -link docURL2 ... \
           -link docURLn com.mypackage

    docURL1、 docURL2、... docURLn は、それぞれ外部ドキュメントの ルートを指し、各ルートには、 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 という名前のディレクトリにある場合は、次のようになります。

        example% javadoc -d update -linkoffline . html com.mypackage

    javadoc の実行が終了したら、update 内に生成されたファイルで、html 内の 元のファイルを上書きします。

    内容説明: 一般に、 javadoc を実行すると、シグニチャー、 @see タグ、{@link} タグ、要約、階層、概要、およびインデックスなど、 生成されるページ全体を通じて表示される名前のリンクが潜在的には 生成されています。これらのリンクの 一部は現在の実行で生成されるページに置かれますが、 別のリンクは現在の実行では 生成されないページに潜在的には置かれています。

-linkoffline docURL  packagelistURL
    このオプションは、外部参照クラスの名前を対象として、 ドキュメンテーションへのリンクを作成します。

    •   docURL は、javadoc によって生成された、 リンク先の外部ドキュメンテーションの ルートの場所の URL です。この場所には、相対 URL または絶対 URL を指定できます。

    •   packagelistURL は、リンク先の外部ドキュメンテーションの package-list ファイルを含むディレクトリの URL です。このファイルは、 必要に応じて手動で作成する こともできます。

    javadoc の実行時に複数の -linkoffline オプションを指定できます。( javadoc 1.2.2 より前のバージョンでは、1 つしか指定できませんでした。)

    このオプションは、 -link オプションの変種です。 -linkoffline オプションは、 javadoc の実行時に、 docURL で指定された場所に package-list ファイルが存在しない場合に使用できます。生成される ドキュメントのリンク先のパッケー ジ名と、該当するドキュメントが存在する場所がわかっている場合は、 このオプションを 使うと、該当する場所に package-list ファイルがまだ実際には存在していなくても、 外部リンクを持つドキュメンテーションを 生成できます。このオプションを使えば、 package-list のコピーを独自に用意することで、適切な リンクを持ったドキュメンテーションを生成で きます。

    この方法は、パッケージ名はわかっているもののまだ 公開されていない、新しい外部 ドキュメンテーションをリンク先に持つ ドキュメンテーションを生成する必要がある場合に 便利です。この方法を使えば、2 つの 企業がそれぞれのドキュメンテーションを同時に リリースできます。また、 package-list が存在しない外部ドキュメンテーション ( javadoc 1.0、1.1、および 1.2 Beta3 までで 作成されたドキュメンテーションなど) にリンクしたドキュ メンテーションを生成することもできます。

    このオプションを指定する場合は、javadoc を 実行する時点で、ドキュメンテーションの U RL にアクセスできるようになっている必要はありません。 したがって、URL が World Wide Web 上にある場合は、Web 接続を行わなくても ドキュメンテーションを生成できます。

    次に示すように、このオプションを使うには、 javadoc によって生成された、外部参照クラス のドキュメンテーションの場所を示す docURL1 と、このドキュメンテーションの package-list ファイルの場所を示す packagelistURL1 を指定します。両者が同じ場所にある場合は、 -linkoffline ではなく、 -link を使用できます。 -linkoffline は、参照先の生成されたドキュメントごとに指定します。 (わかりやすくするため、2 行で示します)

        example% javadoc	-linkoffline docURL1 packagelistURL1 \
        	-linkoffline docURL2 packagelistURL2 \
        	...

    たとえば、次のコマンドは、第 1 引数として渡された URL を 使ってリンクを追加し、 第 2 引数で渡された package-list ファイルを検索します。

        example% javadoc -linkoffline \
              http://java.sun.com/products/jdk/1.2/docs/api \
                    /jdk/1.2/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 パッケージは含まれないことになります。

        example% 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.lang
          java.lang.reflect
          java.util
        Extension Packages
          javax.servlet
        Other Packages
          java.new

-nodeprecated
    推奨されない API をドキュメンテーションに生成することを禁止します。 これは、 -nodeprecatedlist オプションを指定した場合の動作に加えて、 ドキュメンテーションのほかの部分を通じて、 推奨されない API を生成しないことと同じです。 このオプションは、コードを記述していて、 推奨されないコードを無視したい場合に便利です。

-nodeprecatedlist
    推奨されない API のリストを含む ファイル (deprecated-list.html) の生成を禁止 します。また、このページへのリンクを ナビゲーションバーに生成することを禁止します。 ただし、ドキュメントのほかの部分では、 推奨されない API の生成を続行します。この オプションは、推奨されない API がソースコードに 含まれておらず、ナビゲーションバーを すっきりと見せたい場合に便利です。

-notree
    生成されるドキュメントからクラスおよびインタフェース 階層を省略します。 デフォルトでは、階層が作成されます。

-noindex
    生成されるドキュメントからインデックスを省略します。 デフォルトでは、 インデックスが作成されます。

-nohelp
    各出力ページの最上部と最下部の ナビゲーションバーから [ヘルプ] リンクを 省略します。

-nonavbar
    生成されるページの最上部と最下部に表示される ナビゲーションバー、ヘッダ、 およびフッタの生成を禁止します。 このオプションは、bottom オプションには影響しません。 -nonavbar オプションは、印刷するためだけに ファイルを PostScript または PDF に変換する 場合など、内容だけが重要でナビゲーションの 必要性がない場合に便利です。

-helpfile path/filename
    上部と下部のナビゲーションバーの [ヘルプ] リンクの リンク先となる代替ヘルプファイル path/filename のパスを指定します。このオプションが指定されていない場合、 javadoc は、javadoc にハードコードされているヘルプファイル help-doc.html を自動的に作成します。このオプションを使えば、 デフォルトの設定をオーバーライドでき ます。ファイル名にはどのような 名前も指定でき、help-doc.html には限定されま せん。 javadoc は、それに従って、ナビゲーションバーにある リンクに調整を加えます。 次に例を示します。

        example% javadoc -helpfile /home/doc/myhelp.html java.awt

-stylesheetfile path/filename
    代替 HTML スタイルシートファイルのパスを指定します。 このオプションが指定されてい ない場合、 javadoc は、内部的にハードコードされている スタイルシートファイル stylesheet.css を自動的に作成します。このオプションを使えば、 デフォルトの設定をオーバーライドできます。 filename にはどんなファイル名でも指定でき、 stylesheet.css には限定されません。 次に例を示します。

        example% javadoc -stylesheetfile \
                    /home/doc/mystylesheet.css java.awt

-serialwarn
    @serial タグがない場合、コンパイル時に警告を生成します。デフォルトでは、 javadoc 1.2.2 (およびそれ以降) は @serial の警告を生成しません。 (これは、以前のバージョンとは逆です。) @serial の警告を生成するには、 このオプションを使用してください。このオプションは、デフォルトの 直列化可能なフィールドと writeExternal メソッドを正しく ドキュメント化するのに役立ちます。

-charset name
    このドキュメント用の HTML 文字セットを指定します。 たとえば次の指定は、

        % javadoc -charset "iso-8859-1" mypackage

    次の行を、生成される各ページの先頭に挿入します。

    <META http-equiv="Content-Type" content="text/html; charset=iso-885 9-1">

    この META タグについては、HTML 標準 (4197265 と 4137321) で 説明されています。

-docencoding name
    出力される HTML ファイルのエンコーディングを指定します。

例
javadoc は、パッケージ全体に対して実行することも、 個々のクラスに対して実行することも できます。各パッケージ名は、それぞれの パッケージ名に対応するディレクトリ名を 持ちます。次の例では、ソースファイルは /home/src/java/awt/*java にあります。生成先ディレクトリは /home/html です。

  1 つ以上のパッケージのドキュメント化
パッケージをドキュメント化するには、その パッケージのソースファイル (*.java) が、パッケージと同じ名前を持つディレクトリ 内に存在していなければなりません。 パッケージ名が、(ドットで区切られた) いくつかの 識別子から構成されている場合は、 各識別子がそれぞれ別のディレクトリを表わします。 したがって、すべての java.awt クラス は、 java/awt/ という名前のディレクトリに存在していなければなりません。 javadoc は、次の 2 つのどちらかの方法で実行できます。 1 つは、(cd によって) ディレクトリを 変更する方法、もう 1 つは -sourcepath オプションを使う方法です。パッケージの グループを指定する場合は、ワイルドカードは 使用できません。

•   ケース 1 ソースディレクトリへの移動: 完全修飾パッケージの親ディレクトリに移動します。次に、ドキュメント化 する 1 つ以上のパッケージ名を指定して javadoc を実行します。

    example% cd /home/src/
    example% javadoc -d /home/html java.awt java.awt.event

•   ケース 2 すべてのディレクトリから: このケースでは、現在のディレクトリがどのディレクトリでも問題はありません。 完全修飾パッケージの親ディレクトリを -sourcepath に指定し、ドキュメント化する 1 つ以上のパッケージの名前を指定して javadoc を実行します。
    example% javadoc -d /home/html -sourcepath /home/src \
               java.awt java.awt.event

どちらのケースでも、パッケージ java.awt と java.awt.event の public および protected なクラスとインタフェースを対象に、HTML 形式の ドキュメンテーションが生成され、指定 された生成先ディレクトリ (/home/html) に HTML ファイルが 保存されます。2 つ 以上のパッケージが生成されるので、ドキュメントは、 パッケージのリスト、クラスのリスト、 およびメインページの 3 つのフレームを持つことになります。

  1 つ以上のクラスのドキュメント化
javadoc を実行する 2 番目の方法は、1 つ以上のソースファイル ( .java ) を渡すことです。 javadoc は、次の 2 つのどちらかの方法で実行できます。 1 つは、(cd によって) ディレクトリを 変更する方法、もう 1 つは .java ファイルへのパスを完全指定する方法です。 相対パスは、現在のディレクトリからの相対パスです。 ソースファイルを渡した場合、 -sourcepath オプションは無視されます。 アスタリスク (*) の ようなコマンド行ワイルドカードを使用すると、 クラスのグループを指定できます。

•   ケース 1 ソースディレクトリへの移動: .java ファイルのあるディレクトリに移動します。 次に、ドキュメント化する 1 つ以上の ソースファイルの名前を指定して javadoc を実行します。

    example% cd /home/src/java/awt
    example% javadoc -d /home/html Button.java Canvas.java \
                   Graphics*.java

    この例では、クラス Button と Canvas、 および先頭が Graphics で始まるクラスの HTML 形式のドキュメンテーションが生成されます。 javadoc の引数として渡されているのは、 パッケージ名ではなくソースファイルなので、 ドキュメントは、クラスのリストと メインページの 2 つのフレームを持つことになります。

•   ケース 2 パッケージのルートディレクトリへの移動: これは、同じルート内にある複数のサブパッケージのソースファイルを個々に ドキュメント化する場合に便利です。パッケージの ルートディレクトリに移動し、各ソースファイルを ルートからのパスで指定します。

    example% cd /home/src/
    example% javadoc -d /home/html java/awt/Button.java \
                     java/applet/Applet.java

    この例では、Button クラスおよび Applet クラス 用の HTML 形式のドキュメンテーション が生成されます。

•   ケース 3 すべてのディレクトリから: このケースでは、現在のディレクトリがどの ディレクトリでも問題はありません。 ドキュメント化する .java ファイルへの絶対パスまたは 相対パスを指定して javadoc を実行します。

    example% javadoc -d /home/html /home/src/java/awt/Button.java \
                   /home/src/java/awt/Graphics*.java

    この例では、クラス Button および先頭が Graphics で始まるクラスの HTML 形式 のドキュメンテーションが生成されます。

  パッケージとクラスのドキュメント化
パッケージ全体と個々のクラスを同時にドキュメント 化できます。次に示すのは、上に示 した 2 つの例を組み合わせた例です。 -sourcepath は、パッケージへのパスに対しては使用できますが、 個々のクラスのパスに対しては使用 できません。

    example% javadoc -d /home/html -sourcepath /home/src java.awt \
                   /home/src/java/applet/Applet.java

この例では、パッケージ java.awt とクラス Applet の HTML 形式のドキュメンテーションが 生成されます。 javadoc は、Applet のパッケージ名を、 Applet.java ソースファイル内のパッケージの宣言 (宣言がある場合) から決定します。

  使用例
javadoc には、多くの便利なオプションがあり、 その中のいくつかは、ほかのオプションよりもよく 使われます。以下は、makefile 変数を使って Java プラット フォーム API 上で javadoc を実行するために使う効果的なコマンドです。ただし、 ドキュメント化されるパッケージの すべてがリストされているわけではありません。

    example% javadoc -sourcepath /jdk/src/share/classes	/* Path for
    	source files  */
    -d /jdk/build/api	/* 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)	/* Core heading for overview page */
    -group $(GROUPEXT)	/* Ext heading for overview page  */
    -overview $ (SCRDIR) /overview.html	/* For overview text     */
    -J-Xmx180m	/* For 180MB memory      */
    java.lang java.lang.reflect	/* Packages to document  */
    java.util java.io java.net	java.applet
    WINDOWTITLE = 'Java Platform 1.2 Final API Specification'
    DOCTITLE = 'Java<sup><font size="-2">TM</font></sup> Platform 1.2 \
                     Final API Specification'
    HEADER = '<b>Java Platform 1.2</b><br><font size="-1">Final</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-2001 Sun Microsystems, Inc. 901 San \
                  Antonio Road,<br>Palo Alto, California, 94303, U.S.A.\
                  </font>'
    GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"
    GROUPEXT  = '"Extension Packages" "javax.*"'
    SRCDIR = '/java/jdk/1.2/src/share/classes'

    -windowtitle オプションを省略した場合は、 javadoc は、ウィンドウタイトルにドキュメントタイトルをコピーします。 ドキュメントタイトルに HTML タグが含まれていない場合は、 -windowtitle オプションは必要ありません (このタグはそのままのテキストとして ウィンドウのタイ トルに表示されます)。

    この例のように -footer オプションを省略した場合は、 javadoc は、ヘッダテキストをフッタにコピーします。

    この例では必要なかったオプションで、重要なオプションには -classpath と -link があります。

環境変数

CLASSPATH
    環境変数は、 javadoc がユーザクラスファイルを探すときに使う、パスを指定します。環境変数は、 -classpath オプションによってオーバーライドされます。ディレクトリは コロンで分割します。たとえば、 次のとおりです。

    .:/home/classes:/usr/local/java/classes

関連項目

javac(1)、 java(1)、 jdb(1)、 javah(1)、 javap(1)

次については、 java.sun.com を参照または検索してください。

Javadoc ホームページ @
    http://java.sun.com/products/jdk/javadoc/index.html

Javadoc に施された機能強化 @
    http://java.sun.com/j2se/1.3/ja/docs/ja/tooldocs/javadoc/index.html (http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/index.html ：英語版)

Javadoc FAQ @
    http://java.sun.com/products/jdk/javadoc/faq.html

How to Write Doc Comments for Javadoc @
    http://java.sun.com/products/jdk/javadoc/writingdoccomments.html

クラスを検索する方法 @
    http://java.sun.com/products/j2se/1.3/ja/docs/ja/tooldocs/findingclasses.html#srcfiles (http://java.sun.com/products/j2se/1.3/docs/tooldocs/findingclasses.html#srcfiles ：英語版)