javadoc - Java API ドキュメントジェネレータ

Java ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている JavadocTM の例は、Sun Solaris を使用した場合のものです。

目次

リファレンスガイド 実行

リファレンスガイド

形式

javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]

引数を指定する順序は任意です。Javadoc ツールでの、処理対象の .java ファイルを決定する方法の詳細については、「ソースファイルの処理」を 参照してください。

options
このドキュメントで説明されているコマンド行オプションです。Javadoc オプションの標準的な使用法については、「使用例」を参照してください。
packagenames
スペースで区切られた一連のパッケージ名です。たとえば、java.lang java.lang.reflect java.awt のように指定します。ドキュメント化するパッケージを個別に指定する必要があります。ワイルドカードは使用できません。回帰には -subpackages を使用します。Javadoc ツールは、-sourcepath を使ってこれらのパッケージ名を検索します。「1 つ以上のパッケージのドキュメント化」の例を参照してください。
sourcefilenames
スペースで区切られた一連のソースファイル名です。 各ファイルは、パスで始まります。アスタリスク (*) などのワイルドカードを含めることができます。Javadoc ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、その拡張子を除いた名前が実際に有効なクラス名であるすべてのファイルです (「Identifiers」を 参照)。したがって、ハイフンを含む名前 (X-Buffer など) や、その他の無効な文字を含む名前を付けることによって、それらのファイルをドキュメント化の対象から除外できます。これは、テスト用ファイルとテンプレートファイルに便利です。ソースファイル名の前に指定したパスによって、 javadoc がそのファイルを検索する場所が決まります。Javadoc ツールは、これらのソースファイル名を検索するときに -sourcepath は使いません。相対パスはカレントディレクトリを起点とします。したがって、Button.java を渡すことは、./Button.java を渡すことと同じです。ソースファイル名を絶対パスとワイルドカードで指定すると、/home/src/java/awt/Graphics*.java のようになります。「1 つ以上のクラスのドキュメント化」の例を参照してくださ い。また、「パッケージとクラスのドキュメント化」の例のように、パッケージ名とソース ファイル名を混在させることもできます。
-subpackages pkg1:pkg2:...
ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。パッケージ名またはソース ファイル名を指定する必要はありません。
@argfiles
Javadoc オプション、パッケージ名、およびソースファイル名を任意の順序で並べたリストが含まれる 1 つ以上のファイルです。このファイルの中では、ワイルドカード (*) および -J オプションは指定できません。

説明

JavadocTM ツールは、一連の Java ソースファイルにある宣言およびドキュメンテーションコメントを解析し、デフォルトでは public クラス、protected クラス、入れ子にされたクラス (匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連の HTML ページを生成します。このツールを使用して、API (Application Programming Interface) ドキュメントまたは一連のソースファイルの実装ドキュメントを生成できます。

Javadoc ツールは、パッケージ全体、個々のソースファイル、またはそ の両方に対して実行できます。パッケージ全体をドキュメント化する場合は、-subpackages を使用して最上位ディレクトリから再帰的に処理していくか、パッケージ名の明示的なリストを渡します。個々のソースファイルをドキュメント化する場合は、 ソース (.java) ファイル名のリストを渡します。具体的な例は、こ のドキュメントの最後に紹介します。次に、Javadoc によるソースファイルの処理について説明します。

ソースファイルの処理

Javadoc ツールは、末尾に .java の付いたファイル以外に、ソー スファイルで説明する他のファイルも処理します。個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、.java ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソースファイル 名を明示的に指定しなくても、Javadoc ツールは 3 つの方法で実行できます。この方法は、(1) パッケージ名を渡す、(2) -subpackages を使用する、(3) ソースファイル名にワイルドカードを使用する (*.java) という方法です。これらの方法を使用する場合、Javadoc ツールは、.java ファイルが次のすべての要件を満たしている場合にかぎり、このファイルを処理します。

リンクの処理 - Javadoc ツールは、処理の実行中に、その実行でドキュメント化されるパッケージ、クラス、およびメンバの名前に対して、自動的に相互参照リンクを追加します。この ようなリンクは、次のような場所に追加されます。

コマンド行で指定しなかったクラスについての既存のテキスト (別に生成したテキスト) に対してハイパーリンクを追加するには、-link および -linkoffline オプションを利用できます。

その他の処理についての詳細 - Javadoc ツールは、実行するたびに 1 つの完全なドキュメントを作成します。ドキュメントを追加生成することはできません。つまり、Javadoc ツールの以前の実行結果を修正したり、その内容を直接組み入れたりすることはできません。ただし、前述のように、以前の実行結果に対してリンクを追加する ことはできます。

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

Javadoc ツールは、メソッド本体のない純粋なスタブファイルである .java ソースファイルに対しても、実行することができます。したがって、API の作成時には、実装を記述する前の設計の早い段階で、ドキュメンテーションコメントを記述して javadoc ツールを実行できます。

コンパイラに依存することによって、HTML 出力は、実際の実装に正確に対応します。実際の実装は、明示的なソースコードにではなく、暗黙のソースコードに依存する場合があります。たとえば、 Javadoc ツールは、.class ファイル内に存在するが、ソースコード内には存在しないデ フォルトコンストラクタ (Java 言語仕様のセクション 8.6.7) をドキュメント化します。

通常、Javadoc ツールでは、ソースファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。このため、デバッグやトラブルシューティング を完了する前にドキュメントを生成できます。たとえば、Java 言語仕様によると、抽象メソッドを含むクラスは、それ自体抽象として宣言されなければなりません。このエラーを検出すると、javac コンパイラは停止しますが、Javadoc ツールは警告を出さずに処理を続行します。Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。

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

Javadoc のドックレット

Javadoc ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。Javadoc ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み」ドックレットがあります。標準ドックレットは、HTML 形式の API ドキュメントを生成します。標準ドックレットを修正またはサブクラス化することや、HTML、XML、MIF、RTF などの好みの出力形式を生成する独自のドックレットを記述することも可能です。ドックレットとその使用法については、次の項目を参照してください。 -doclet コマンド行オプションでカスタムドックレットが指定されていない場合、Javadoc ツールは、デフォルトの標準ドックレットを使用します。javadoc ツールには、使用されているドックレットに関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらのほかに、いくつかのコマン ド行オプションが追加されます。どちらのオプションについても、このあとの「オプション」で説明します。

関連ドキュメントおよびドックレット

用語

「ドキュメンテーションコメント」、「doc コメント」、「主説明」、「タグ」、「ブロックタグ」、および「インラインタグ」の用語については、「ドキュメンテーションコメント」 で説明します。以下のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。
生成ドキュメント (generated document)
javadoc ツールが Java ソースコード内のドキュメンテーションコメントから生成したドキュメントのことです。デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。

名前
Java 言語で書かれたプログラム要素の名前、つまりパッケージ、クラス、インタフェース、フィールド、コンストラクタ、またはメソッドの名前のことです。名前 は、java.lang.String.equals(java.lang.Object) のように完全修飾することも、equals(Object) のように部分修飾することもできます。

ドキュメント化されるクラス (documented classes)
javadoc ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。ソースファイルをドキュメント化するには、このソースファイ ルが利用でき、そのソースファイル名またはパッケージ名を javadoc コマンドに渡す必要があります。また、それらのアクセス修飾子 (public、protected、package-private、または private) によるフィルタで除外されないようにする必要があります。ドキュメント化されるクラスは、javadoc ツールの出力に組み込まれるクラス、つまり「包含クラス」とも呼ばれます。

包含クラス
Javadoc ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。「ドキュメント化されるクラス」と同じです。

除外クラス (excluded classes)
Javadoc ツールの実行によって詳細なドキュメントが生成されないクラスおよびインタフェースのことです。

参照クラス (referenced classes)
ドキュメント化されるクラスおよびインタフェースの定義 (実装) またはドキュメンテーションコメントの中で明示的に参照されているクラスおよびインタフェースのことです。参照の例としては、戻り値の型、パラメータの 型、キャストの型、拡張されたクラス、実装されたインタフェース、インポートされたクラス、メソッド本体で使用されるクラス、@see、{@link}、 {@linkplain}、{@inheritDoc} タグなどがあります。この定義は 1.3 から変更されています。javadoc ツールを実行するときは、Javadoc のブートクラスパスおよびクラスパス内にあるすべての参照クラスをメモリにロードする必要があります。参照クラスが見つからない場合は、「クラスが見つか りません」という警告が表示されます。Javadoc ツールは、クラスの存在とそのメンバの完全指定の名前を判別するのに必要なすべての情報を、.class ファイルから引き出すことができます。

外部参照クラス (external referenced classes)
参照クラスのうち、javadoc ツールの実行中にドキュメントが生成されないクラスのことです。つまり、これらのクラスは、コマンド行で Javadoc ツールに渡されていません。生成ドキュメント内でこれらのクラスにリンクしている箇所は、「外部参照」または「外部リンク」と呼ばれます。たとえば、java.awt パッケージに対してだけ Javadoc ツールを実行した場合、Object などの java.lang 内のすべてのクラスが外部参照クラスになります。外部参照クラスにリンクするには、-link および -linkoffline オプションを使用します。外部参照クラスには、通常そのソースコメントを javadoc ツールの実行で利用できないという重要な特徴があります。この場合、それらのコメントを継 承することはできません。


ソースファイル

Javadoc ツールは、4 種類の異なるソースファイルから出力結果を生成します。そのファイルは、クラスの Java 言語ソースファイル (.java)、 パッケージコメントファイル、概要コメントファイル、およびその他の処理されないファイルです。この節では、ソースツリーに置かれたテスト用ファイルとテ ンプレートファイルも扱っていますが、これはドキュメント化する必要はありません。

クラスソースコードファイル

それぞれのクラスまたはインタフェース、およびそのメンバは、独自のドキュメンテーションコメントを持つことができ、それを .java ファイル内に保持します。ドキュメンテーションコメントの詳細は、「ドキュメンテー ションコメント」を参照してください。

パッケージコメントファイル

それぞれのパッケージは、独自のドキュメンテーションコメントを持つことができ、それを専用の「ソース」ファイルに保持します。その内容は、 Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、そのパッケージ全体に当てはまるドキュメントを記述します。

パッケージコメントファイルを作成するには、ファイル名を package.html にして、.java ファイルとともにソースツリー内のパッケージディレクトリに置く必要があります。Javadoc ツールは、この場所にあるこのファイル名を自動的に検索します。ファイル名は、どのパッケージについても同じです。詳細は、 package.html の例を参照してください。

パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に、HTML で記述された 1 つの大きなドキュメンテーションコメントです。ただし、ほかのコメントと異なる点が 1 つだけあります。それは、このドキュメンテーションコメントには、コメント区切り文字である /** と */、 および行頭のアスタリスクを含めてはならない、ということです。コメントを書く場合は、最初の文をパッケージの概要とし、<body> と最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージタグを含めるこ とはできますが、ほかのドキュメンテーションコメントと同様、{@link} 以外のすべてのタグは、説明のあとに置かなければなりません。パッケージコメントファイルに @see タグを追加する場合は、完全指定の名前を使用する必要があります。

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 オプションを使って概要コメントファイル名を指定します。このファイルは、パッケージコメントファイルと同じように処理されます。

その他の未処理のファイル

ソースには、Javadoc ツールによって生成先のディレクトリにコピーされる、その他の任意のファイルを含めることができます。一般に、このようなファイルには、グラフィックファ イル、サンプルの Java ソース (.java) およびクラス (.class) ファイル、内容が通常の Java ソースファイルのドキュメンテーションコメントの影響を受けない独立した HTML ファイルなどがあります。

未処理のファイルをソースに含めるには、それらのファイルを doc-files というディレクトリに置きます。このディレクトリは、ソースファイルがある任意のパッケージディレクトリの下に作成できます。このようなサブディレクトリ は、パッケージごとに 1 つ用意できます。イメージ、サンプルコード、ソースファイル、.class ファイル、アプレット、および HTML ファイルをこのディレクトリに格納できます。たとえば、ボタンのイメージ button.gif を java.awt.Button クラスのドキュメントに含める場合は、そのファイルを /home/user/src/java/awt/doc-files/ ディレクトリに置きます。doc-files ディレクトリを /home/user/src/java/doc-files に置くことはできません。これは、java はパッケージではなく、そのディレクトリそのものにソースファイルが入っていないからです。

これらの未処理のファイルへのリンクは、すべて明示的に記述する必要があります。これは、Javadoc ツールがそれらのファイルを見ずに、単にディレクトリとその内容を生成先にコピーするだけだからです。たとえば、Button.java のドキュメンテーションコメント内のリンクは、次のようになります。 

    /**
     * This button looks like this: 
     * <img src="doc-files/Button.gif">
     */

テスト用ファイルとテンプレートファイル

開発者によっては、テスト用ファイルとテンプレートファイルを、対応するソースファイルに近いソースツリーに格納しようと考える場合があります。つまり、 テスト用ファイルとテンプレートファイルをソースファイルと同じディレクトリまたはサブディレクトリに置くことになります。

個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、テスト用およびテンプレートファイルを慎重に除外して、これらのファイルの処理を回避できます。ただし、パッケージ名またはワイル ドカードを渡す場合は、特定のルールに従って、テスト用ファイルとテンプレートファイルの処理を確実に回避する必要があります。

テスト用ファイルとテンプレートファイルとは、テスト用ファイルが有効でコンパイル可能なソースファイルであるのに対し、テンプレートファイル はそうではなく末尾に「.java」が付けられている点で異なっています。

テスト用ファイル - 開発者は、所定のパッケージ用のコンパイルおよび実行可能なテスト用ファイルを、そのパッケージのソースファイルと「同じ」ディレクトリに置きたいと考え る場合があります。しかし、ソースファイルパッケージ以外のパッケージ (名前のないパッケージなど) にテスト用ファイルを所属させたいと考えることもあります。このため、テスト用ファイルにはパッケージ文がなかったり、ソースとは異なるパッケージ文が含 まれたりします。この場合、コマンド行で指定したパッケージ名を指定してソースをドキュメント化しているときに、テスト用ファイルによって警告やエラーが 発生します。このようなテスト用ファイルは、サブディレクトリに置く必要があります。たとえば、com.package1 のソースファイル用のテスト用ファイルを追加する場合、次のようにハイフンを含んだ無効なパッケージ名のサブディレクトリに、これらのテスト用ファイルを 置きます。 

    com/package1/test-files/
Javadoc ツールはテスト用ディレクトリをスキップし、警告は発生しません。

テスト用ファイルにドキュメンテーションコメントが含まれている場合、ワイルドカードを使用したテスト用のソースファイル名 (たとえば com/package1/test-files/*.java) を渡すことによって、Javadoc ツールをもう一度実行してテスト用ファイルのドキュメントを生成するように設定できます。

ソースファイル用テンプレート - テンプレートファイルは、たいてい末尾が「.java」である名前が付けられ、コンパイル可能ではありません。ソースディレクトリに格納したいソースファ イル用テンプレートがある場合、ダッシュを含んだ名前 (たとえば Buffer-Template.java)、またはそ の他の不正な Java 文字を含んだ名前を、テンプレートに付けることによって、テンプレートの処理を回避できます。これは、Javadoc ツールが、「.java」の接尾辞を取り除くと実際に有効なクラス名になる名前のソースファイル以外を処理しないためです。「identifiers」を 参照してください。


生成されるファイル

デフォルトでは、javadoc ツールは、HTML 形式のドキュメントを生成する標準ドックレットを使います。このドックレットは、以下の種類のファイルを生成します。それぞれの HTML ページは、個々のファイルに相当します。Javadoc が生成するファイルの名前には、クラスやインタフェースの名前にちなんだものと、そうでないもの (package-summary.html など) の 2 種類があります。後者のグループのファイル名には、前者のグループとファイル名が競合しないように、ハイフンが含まれています。

基本内容ページ

相互参照ページ

サポートファイル

HTML フレーム

Javadoc ツールは、下の図に示すように、2 〜 3 つの HTML フレームを生成します。パッケージが 1 つだけまたはパッケージがない場合には、パッケージのリストを省略することによって、最低限必要な数のフレームを作成します。つまり、単一のパッケージに 所属する単一のパッケージ名またはソースファイル (*.java) を引数として javadoc コマンドに渡した場合は、左側にクラスを一覧表示するフレーム (C) が 1 つだけ作成されます。Javadoc に複数のパッケージ名を渡した場合は、概要ページ (Detail) に加えて、すべてのパッケージを一覧表示する第 3 のフレーム (P) が作成されます。この概要ページのファイル名は、overview-summary.html です。したがって、このファイルは、2 つ以上のパッケージ名を渡した場合にだけ作成されます。「フレームなし」リンクをクリックするか、overview-summary.html を最初に表示すると、フレームを省略できます。

HTML フレームに慣れていない場合は、特定のフレームを印刷およびスクロールするには、そのフレームに「フォーカス」がなければならないことに注意してくださ い。フレームにフォーカスを与えるには、そのフレームをクリックします。このようにすると、多くのブラウザでは、矢印キーやページキーを使ってそのフレー ムをスクロールしたり、「印刷」メニューコマンドを使ってそのフレームを印刷したりできます。 

              ------------                  ------------
              |C| Detail |                  |P| Detail |
              | |        |                  | |        |
              | |        |                  |-|        |
              | |        |                  |C|        |
              | |        |                  | |        |
              | |        |                  | |        |
              ------------                  ------------
             javadoc *.java           javadoc java.lang java.awt
HTML フレームが必要かどうかによって、次のどちらかのファイルを開始ページとしてロードします。 生成されるファイルの構造

生成されるクラスファイルおよびインタフェースファイルは、Java ソースファイルおよびクラスファイルと同じディレクトリ階層に編成されます。1 つのサブパッケージにつき 1 つのディレクトリ、という構造になります。

たとえば、java.applet.Applet クラスに対して生成されるドキュメントは、java/applet/Applet.html に格納されます。生成先のディレクトリの名前が apidocs だとすると、java.applet パッケージのファイル構造は、その下に構築されます。前述のように、「frame」という語を名前に含むファイルは、すべて左上または左下のフレームに表 示されます。それ以外の HTML ファイルは、すべて右側のフレームに表示されます。

注 - 下の階層図で、ディレクトリは太字 (bold) で示してあります。アスタリスク (*) は、javadoc への引数がパッケージ名ではなくソースファイル名 (*.java) である場合に省略されるファイルおよびディレクトリを示しています。また、引数がソースファイル名の場合は、package-list は作成されますが、内容は空です。doc-files ディレクトリは、ソースツリー内に存在する場合にのみ、生成先に作成されます。 
apidocs                            最上位ディレクトリ
   index.html                       HTML フレームを設定する初期ページ
 * overview-summary.html            全パッケージのリスト。先頭に要約文がある
   overview-tree.html               全パッケージのクラス階層のリスト
   deprecated-list.html             全パッケージの推奨されない API のリスト
   constant-values.html             全パッケージの static フィールドの値のリスト
   serialized-form.html             全パッケージの直列化された形式のリスト
 * overview-frame.html              全パッケージのリスト。左上のフレームに表示される
   allclasses-frame.html            全パッケージの全クラスのリスト。左下のフレームに表示される
   help-doc.html                    これらのページの構成を示すユーザヘルプを表示する
   index-all.html                   -splitindex オプションなしで作成されたデフォルト索引
   index-files                    -splitindex オプションを指定して作成されたディレクトリ
       index-<number>.html          -splitindex オプションを指定して作成された索引ファイル
   package-list                     パッケージ名のリスト。外部参照を解決するためだけに使用される
   stylesheet.css                   フォント、色、配置を定義する HTML スタイルシート
   java                             パッケージディレクトリ
       applet                      サブパッケージディレクトリ
            Applet.html             Applet クラスのページ
            AppletContext.html      AppletContext インタフェースのページ
            AppletStub.html         AppletStub インタフェースのページ
            AudioClip.html          AudioClip インタフェースのページ
          * package-summary.html    このパッケージのクラスのリスト。先頭に要約文がある
          * package-frame.html      このパッケージのクラスのリスト。左下のフレームに表示される
          * package-tree.html       このパッケージのクラス階層のリスト
            package-use             このパッケージが使用されている場所のリスト
            doc-files              イメージやサンプルのファイルが格納されるディレクトリ
            class-use              API が使用されている場所のページを格納するディレクトリ
                Applet.html         Applet クラスを使用するページ
                AppletContext.html  AppletContext インタフェースを使用するページ
                AppletStub.html     AppletStub インタフェースを使用するページ
                AudioClip.html      AudioClip インタフェースを使用するページ
   src-html                        ソースコードディレクトリ
       java                         パッケージディレクトリ
           applet                  サブパッケージディレクトリ
                Applet.html         Applet ソースコードのページ
                AppletContext.html  AppletContext ソースコードのページ
                AppletStub.html     AppletStub ソースコードのページ
                AudioClip.html      AudioClip ソースコードのページ

生成される API 宣言

Javadoc ツールは、その API 項目について、それぞれのクラス、インタフェース、フィールド、コンストラクタ、およびメソッドの説明の最初に、宣言を生成します。たとえば、Boolean クラスの宣言は、次のようになります。

public final class Boolean
extends Object
implements Serializable

また、Boolean.valueOf メソッドの宣言は、次のようになります。

public static Boolean valueOf(String s)

Javadoc ツールは、修飾子 public、protected、private、abstract、final、static、transient、 および volatile を組み込むことができますが、synchronized と native を組み込むことができません。これら後者の 2 つの修飾子は、実装の詳細と見なされているため、API 仕様には含まれません。

API では、並行性のセマンティクスについて、キーワード synchronized に依存するのではなく、コメントによる主説明としてドキュメント化する必要があります。たとえば、「1 つの Enumeration を複数のスレッドから並行して使用することはできない」などのコメントを記述します。ドキュメントには、これらのセマンティクスを実現する方法を記述する べきではありません。たとえば、Hashtable はスレッドに対して安全である必要がありますが、「エクスポートされるすべてのメソッドを同期化すればそれを実現できる」のようには指定する根拠はありま せん。バケットレベルで内部的に同期化する権利を残しておく必要があります。そうすれば、より高度な並行性が提供されます。

ドキュメンテーションコメント

オリジナルの「ドキュメンテーションコメントの仕様」は、「関連項目」を参照してください。

ソースコードへのコメントの挿入

ソースコードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーションコメント (「doc comments」) を記述することができます。各パッケージにドキュメンテーションコ メントを作成できます。構文は若干異なりますが、概要にもドキュメンテーションコメント を作成できます。ドキュメンテーションコメントは、非公式に「Javadoc コメント」とも呼ばれています。ただし、これは商標の侵害に当たります。ドキュメンテーションコメントは、コメントの始まりを示す文字列 /** と、コメントの終わりを示す文字列 */ の間にある文字で構成されます。行の先頭のアスタリスクは、各行に記述できます。詳細は、以下で説明します。コメントのテ キストは、複数行にわたって記述できます。 

/**
 * This is the typical format of a simple documentation comment
 * that spans two lines.
 */
次のようにして 1 行に記述すると、スペースを節約できます。 
/** This comment takes up only one line. */
コメントの配置 - ドキュメンテーションコメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置かれているときにだけ認識されま す。クラスの例、メソッドの例、 およびフィールドの例を参照してください。メソッドの本体に置かれているドキュメンテーション コメントは無視されます。javadoc ツールでは、1 つの宣言文につき 1 つのドキュメンテーションコメントだけが認識されます。

よくある間違いは、クラスのコメントとクラスの宣言の間に import 文を置いてしまうことです。このような記述はしないでください。このようなクラスコメントは無視されます。 

   /**
    * This is the class comment for the class Whatever.
    */

    import com.sun;   // MISTAKE - Important not to put import statement here

    public class Whatever {
    }
ドキュメンテー ションコメントは主説明とそれに続くタグセクションから構成される - 開始区切り文字 /** の後ろからタグセクションまでが、主説明になります。タグセクションは、最初のブロックタグから始まります。最初のブロックタグは、行の先頭を示す (行頭のアスタリスク、空白、および区切り文字 /** は除く) 最初の @ 文字で指定されます。主説明を記述せず、タグセクションだけのコメントを記述することもできます。主説明は、タグセクション以降に続けることはできませ ん。タグの引数は、複数行にわたって記述できます。タグの数に制限はありません。何回も記述できるタグと、1 回しか記述できないタグがあります。たとえば、次の例の @see からタグセクションが始まります。 

/**
 * This sentence would hold the main description for this doc comment.
 * @see java.lang.Object
 */
ブロックタグとインラインタグ - 「タグ」は、Javadoc ツールが処理できる、ドキュメンテーションコメント内の特別なキーワードです。次の 2 種類のタグがあります。ブロックタグは @tag と記述し (「スタンドアロンタグ」とも呼ばれる)、インラインタグは {@tag} のように中括弧で囲んで記述します。ブロックタグが正しく解釈されるためには、行の先頭のアスタリスク、空白、区切り文字 (/**) を除いて、行の先頭に置かなければなりません。これは、テキスト内のそれ以外の位置で @ 文字を使用しても、タグの開始としては解釈されないことを意味しています。行の最初に @ 文字を使用してもタグとして解釈されないようにするには、HTML エンティティの &#064; を使用してください。それぞれのブロックタグには、対応付けられたテキストがあります。このテキストは、タグのあとから、次のタグの前、またはドキュメン テーションコメントの最後までの間に記述されたテキスト (タグやコメント区切り文字を除く) です。この関連テキストは複数行にわたって記述できます。インラインタグは、テキストを記述できる場所であればどこにでも置くことができ、正しく解釈され ます。次のコード例には、ブロックタグ @deprecated と、インラインタグ {@link} が含まれています。 

/**
 * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
 */

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

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

次に、ドキュメンテーションコメントを示します。 

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

行頭のアスタリスク - Javadoc は、ドキュメンテーションコメントを解析するときに、各行の先頭にあるアスタリスク (*) をすべて破棄します。また、最初のアスタリスク (*) より前の空白とタブも破棄します。バージョン 1.4 からは、行の先頭のアスタリスクを省略しても、先頭の空白文字は削除されなくなりました。このため、コード例を直接ドキュメンテーションコメントの <PRE> タグ内にペーストしても、インデントが保持されます。通常、ブラウザは、空白文字をタブよりも一律に解釈します。インデントは区切り文字 /** または <PRE> タグよりも左寄りになります。

最初の文 - 各ドキュメンテーションコメントの最初の文は、宣言されているエンティティに関する簡潔かつ完全な要約文である必要があります。この「最初の文」は、直後 にスペース、タブ、または改行が続く最初のピリオド (ロケールが英語に設定されている場合)、または最初のブ ロックタグがある位置で終わります。最初の文は、Javadoc ツールによって HTML ページの最初にあるメンバの概要の部分にコピーされます。

複数フィールドの宣言 - Java では、1 つの文で複数のフィールドを宣言できます。ただし、この文には、1 つのドキュメンテーションコメントしか記述できません。そのコメントが、すべてのフィールドに対してコピーされます。したがって、フィールドごとにドキュ メンテーションコメントを記述する必要がある場合は、各フィールドを別々の文で宣言しなければなりません。たとえば、次のドキュメンテーションコメント は、1 つの宣言として記述すると不適切です。この場合は、宣言を 2 つに分けることをお勧めします。 

/** 
 * The horizontal and vertical distances of point (x,y)
 */
public int x, y;      // Avoid this
上記のコードからは、次のようなドキュメントが生成されます。 
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 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラ スは、ドキュメンテーションコメントを継承しません。

ドキュメンテーションコメントを実際にコピーに利用するには、継承したメソッドのソースファイルが -sourcepath で指定したパスだけに置かれていることが必要になります。コマンド行で、クラスもパッケージも渡す必要はありません。この点は、クラスが ドキュメント化されるクラスでなければならなかった 1.3.x 以前のリリースと異なります。

クラスおよびインタフェースからの継承 - クラスおよびインタフェースから継承する次の 3 つの場合に、コメントの継承が行われます。

最初の 2 つのケース (メソッドをオーバーライドしている場合) では、Javadoc ツールは、コメントが継承されているかどうかにかかわらず、オーバーライドしているメソッドのドキュメント内に「オーバーライド」という小見出しを生成 し、オーバーライドされているメソッドへのリンクを書き込みます。

3 番目のケース (特定のクラスのメソッドがインタフェースのメソッドを実装している場合) では、Javadoc ツールは、実装しているメソッドのドキュメント内に「定義」という小見出しを生成し、実装されているメソッドへのリンクを書き込みます。これは、コメント が継承されているかどうかにかかわらず行われます。

メソッドのコメントを継承するためのアルゴリズム - あるメソッドにドキュメンテーションコメントが記述されていない場合、または {@inheritDoc} タグが記述されている場合、Javadoc ツールは、次のようなアルゴリズムを使用して適切なコメントを検索します。このアルゴリズムは、もっとも適切なドキュメンテーションコメントを検索できる ように設計されており、スーパークラスよりもインタフェースが優先されるようになっています。

  1. 直接に実装されている (または、拡張されている) インタフェースを、メソッドの宣言で implements (または extends) キーワードのあとに登場する順序で、1 つずつ調べる。このメソッドについて最初に見つかったドキュメンテーションコメントを採用する
  2. 手順 1 でドキュメンテーションコメントが見つからなかった場合は、直接実装されている (または、拡張されている) インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用する (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ)
  3. 手順 2 でドキュメンテーションコメントが見つからなかった場合で、このクラスが Object 以外のクラスである (インタフェースではない) 場合は、次のように処理する
    1. スーパークラスにこのメソッドについてのドキュメンテーションコメントが記述されていれば、そのコメントを採用する
    2. 手順 3a でドキュメンテーションコメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を適用する

ｊavadoc タグ

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

タグには 2 つのタイプがあります。

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

現時点で有効なタグは、次のとおりです。

タグ 導入された JDK/SDK のバージョン
@author 1.0
{@code} 1.5
{@docRoot} 1.3
@deprecated 1.0
@exception 1.0
{@inheritDoc} 1.4
{@link} 1.2
{@linkplain} 1.4
{@literal} 1.5
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
{@value} 1.4
@version 1.0

カスタムタグについては、-tag オプションを参照してください。

@author  name-text
-author オプションが使われている場合、生成ドキュメントに「著者」の項目を追加し、指定された name-text を書き込みます。1 つのドキュメンテーションコメントに複数の @author タグを含めることができます。1 つの @author タグに 1 つの名前を指定することも、1 つのタグに複数の名前を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (,) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではな く、各言語に対応した名前区切り文字を使う必要がある場合は、1 つのタグに複数の名前を指定できます。

詳細については、「タグを使用できる場所」および @author タグのドキュメントを参照してください。

@deprecated  deprecated-text
この API は動作し続けますが、この API を使用するべきではないことを示すコメントを追加します。Javadoc ツールは、deprecated-text を主説明の前に移動してイタリックにし、その前に警告文としてボールドの「推奨されな い」を追加します。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、お よびフィールドで有効です。

deprecated-text の最初の文では、少なくとも、その API が推奨されなくなった時期と、代替使用するべき API を読者に提示する必要があります。Javadoc ツールは、この最初の文だけを、概要セクションと索引にコピーします。そのあとの文では、その API が推奨されない理由を説明することもできます。また、代わりの API を指し示す {@link} タグ (Javadoc 1.2 以降の場合) を含める必要があります。次のように記述します。

詳細については、@deprecated タグのドキュメントを参照してください。

  • Javadoc 1.2 以降では、{@link} タグを使用します。これにより、必要な場所にインラインでリンクを作成できます。次に例を示します。 
    /**
     * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
     */
  • Javadoc 1.1 では、各 @deprecated タグに対して @see タグ (インラインにはできない) を記述するのが標準の形式です。

推奨されないタグについての詳細は、@deprecated タグのドキュメントを参照してください。

{@code  text}
<code>{@literal}</code> と同じです。

テキストを HTML マークアップまたは入れ子の Javadoc タグと解釈することなく、code フォントの text を表示します。このため、ドキュメンテーションコメントで、HTML の エンティティ (&lt; および &gt;) の代わりに、通常の角括弧 (< および >) を、たとえばパラメータタイプ (<Object>)、不等号 (3 < 4)、 または矢印 (<-) に使用できます。たとえば、次のドキュメンテーションコメントテキストを記述します。 

     {@code A<B>C}
これは、生成される HTML ページでも変わらずに表示されます。 
     A<B>C
特に、<B> が太字 (bold) と解釈されず、コードフォントに囲まれている点が重要です。

コードフォントを使用せずに同じ機能を実現しようとする場合は、{@literal} を使用します。

{@docRoot}
生成されるページから見た、生成ドキュメントの (生成先の) ルートディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むとき に便利です。通常は、各ページの下部から著作権のページにリンクします。

この {@docRoot} タグは、コマンド行からも、ドキュメンテーションコメントの中でも使用できます。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メ ソッド、およびフィールドで有効です。

  1. コマンド行では、ヘッダ、フッタ、またはボトムノートは次のように定義します。 
       javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
    注 - {@docRoot} をこのように利用する場合、一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする必要があります。たとえば、Inprise MAKE バージョン 5.2 を Windows 上で実行する場合は、「{{@docRoot}}」 のように、中括弧を二重にする必要があります。さらに、-bottom などのオプションに対する引数を、単一引用符ではなく、二重引用符で囲む必要があります。href 引数の値を囲む引用符は省略します。

  2. ドキュメンテーションコメントの中では、次のように使用します。 
       /**
        * 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

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

{@inheritDoc} 
「もっとも近い」継承可能なクラスまたは実装可能なインタフェー スのドキュメントを、このタグの位置の現在のドキュメンテーションコメントへ継承 (コピー) します。このため、上位の継承ツリーにより一般的なコメントを書き込み、コピー したテキストに継承できます。

このタグは、ドキュメンテーションコメントの次の位置でのみ有効です。

  • メソッドの主説明ブロック内。この場合、主説明は、上位階層の クラスまたはインタフェースからコピーされる
  • メソッドの @return、@param、@throws タグのテキスト引数内。この場合、タグテキストは、上位階層の対応するタグからコピーされる

継承階層でコメントを見つける方法に関する正確な説明について、「メ ソッドコメントの自動 コピー」を参照してください。このタグが見つからない場合、コメントは、この節で説明するルールに応じて、自動的に継承されるかどうかが決まりま す。

{@link  package.class#member  label}
表示テキスト label とのインラインリンクを挿入します。label は、参照クラスの指定されたパッケージ、クラス、またはメンバの名前のドキュメンテーションを指し示します。こ のタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メ ソッド、およびフィールドで有効です。

このタグは、@see タグとよく似ています。どちらのタグも、package.class#member および label の参照の仕方が同じで、有効な構文もまったく同じです。大きな違いは、{@link} は、リンクを「関連項目」セクションに置くのではなく、インラインリンクを生成するということです。また、インラインテキストのほかの部分と区別するため に、{@link} タグの最初と最後に中括弧を記述します。ラベルの中で「}」を使う必要がある場合は、HTML エンティティの「&#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.
{@link} を、ドキュメント化の対象にしていないクラスにまで拡張するには、-link オプションを使用します。

詳細については、{@link} タグのドキュメントを参照してください。

{@linkplain  package.class#member  label}
リンクのラベルがコードフォントではなくプレーンテキストで表示される点以外は {@link} と同じです。ラベルがプレーンテキストで記述されていると便利です。次の例を参照してください。 
     Refer to {@linkplain add() the overridden method}.
これは以下のように表示されます。
Refer to the overridden method.
{@literal  text}
テキストを HTML マークアップまたは入れ子の Javadoc タグと解釈することなく、text を表示します。このため、ドキュメンテーションコメントで、HTML の エンティティ (&lt; および &gt;) の代わりに、通常の角括弧 (< および >) を、たとえばパラメータタイプ (<Object>)、 不等号 (3 < 4)、または矢印 (<-) に使用できます。たとえば、次のドキュメンテーションコメントテキストを記述します。 
     {@literal A<B>C}
これは、生成される HTML ページでも変わらずにブラウザで表示されます。

     A<B>C

特に、<B> が太字 (bold) と解釈されず、コードフォントに囲まれていない点が重要です。

テキストをコードフォントで囲んで同じ機能を実現しようとする場合は、{@code} を使用します。

@param  parameter-name description
指定の parameter-name に指定の description が続くパラメータを、「パラメータ」セクションに追加します。ドキュメンテーションコメントを作成するときに、複数行に description を繰り返すことができます。このタグは、メソッド、コンストラクタ、またはクラスのドキュメンテーションコメントでのみ有効です。

parameter-name は、メソッドまたはコンストラクタでのパラメータの名前か、クラスのタイプパラメータの名前になります。次のように、角括弧でこのパラメータ名を囲んで、 使用するタイプパラメータを指定します。 

     /**
      * @param <E> Type of element stored in a list
      */
     public interface List<E> extends Collection<E> {
     }

詳細については、@param タグのドキュメントを参照してください。

@return  description
「戻り値」セクションを追加して、description のテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテー ションコメントでのみ有効です。

詳細については、@return タグのドキュメントを参照してください。

@see  reference
「関連項目」見出しを追加し、reference を指すリンクか、またはテキストエントリを書き込みます。1 つのドキュメンテーションコメントには、任意の数の @see タグを指定できます。すべての @see タグの内容は、同じ見出しの下にグループ化されます。@see タグには、次の 3 種類の形式があります。もっともよく使われるのは、3 番目の形式です。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およ びフィールドで有効です。パッケージ、クラス、またはメンバに対するインラインリンクを文中に挿入する方法は、{@link} を参照してください。

@see "string"
string のテキストエントリを追加します。リンクは生成されません。string は、書籍または URL ではアクセスできない情報の参照先です。Javadoc ツールは、最初の文字が二重引用符 (") かどうかを調べて、この形式をほかの 2 つの形式と区別します。次に例を示します。 
     @see "The Java Programming Language"
これは次のようなテキストを生成します。
See Also:
"The Java Programming Language"
@see <a href="URL#value">label</a>
URL#value で定義されているリンクを追加します。URL#value は、相対 URL または絶対 URL です。Javadoc ツールは、最初の文字が「より小さい」記号 (<) かどうかを調べて、この形式をほかの 2 つの形式と区別します。次に例を示します。 
     @see <a href="spec.html#section">Java Spec</a>
これは次のようなリンクを生成します。
See Also:
Java Spec
@see  package.class#member  label
指定された名前を持つ、参 照されている Java 言語のメンバについてのドキュメントを指すリンクを、表示テキスト label とともに追加します。label は省略可能です。label を省略すると、リンク先のメンバの名前が適切に短縮されて表示されます。「名前が表示される方法」を 参照してください。-noqualifier を使用して、この表示テキストからパッケージ名を広域的に削除します。表示テキストを、自動生成の表示テキストとは異なるテキストにする場合は、ラベルを 使用します。

バージョン 1.2 だけは、ラベルではなく、名前が <code> HTML タグ内に自動的に表示されます。1.2.2 からは、ラベルを使用するか、しないかにかかわらず、<code> は常に表示テキストを囲むかたちで、含まれます。

  • package.class#member には、参照されている任意の有効なプログラム要素の名 前を指定します。つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。ただし、メンバ名の前の 文字は、シャープ記号 (#) を使用します。class は、最上位か入れ子の任意のクラスまたはインタフェースを表します。member は、入れ子のクラスまたはインタフェースではなく、任意のコンストラクタ、メソッド、またはフィールドを表します。指定した名前が、ドキュメント化されて いるクラスに含まれている場合、Javadoc ツールは、その名前へのリンクを自動的に作成します。外部参照クラスへのリンクを作成するには、-link オプションを使います。参照クラスに属していない名前のドキュメントを参照するには、ほかの 2 つの形式の @see タグを使います。この引数については、このあとの「名前の指定」で詳しく説明します。

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

  • 空白文字は、package.class#member と label の間の区切り文字です。括弧の内側の空白文字はラベルの先頭とは解釈されないため、メソッドのパラメータ間に空白文字を入れてもかまいません。

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

 /**
  * @see String#equals(Object) equals
  */
標準ドックレットは、次のような HTML を生成します。 
<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 にはメソッドまたはコンストラクタを指定できます。

@see package.class#member の一般的な形式
現在のクラスのメンバを参照する
@see  #field
@see  #method(Type, Type,...)
@see  #method(Type argname, Type argname,...)
@see  #constructor(Type, Type,...)
@see  #constructor(Type argname, Type argname,...)

現在の、またはインポートされたパッケージの別のクラスを参照する
@see  Class#field
@see  Class#method(Type, Type,...)
@see  Class#method(Type argname, Type argname,...)
@see  Class#constructor(Type, Type,...)
@see  Class#constructor(Type argname, Type argname,...)
@see  Class.NestedClass
@see  Class

別のパッケージの要素を参照する (完全修飾)
@see  package.Class#field
@see  package.Class#method(Type, Type,...)
@see  package.Class#method(Type argname, Type argname,...)
@see  package.Class#constructor(Type, Type,...)
@see  package.Class#constructor(Type argname, Type argname,...)
@see  package.Class.NestedClass
@see  package.Class
@see  package

上の表に対する補足事項を以下に示します。

  • 最初の種類の形式 (パッケージとクラスを省略) の場合、Javadoc ツールは、現在のクラスの階層だけを検索します。つまり、現在のクラスかインタフェース、そのスーパークラスかスーパーインタフェース、または現在のクラ スかインタフェースを囲んでいるクラスかインタフェースからメンバを検索します (このあとの検索 手順 1 〜 3)。現在のパッケージのほかの部分や、ほかのパッケージは検索しません (検索手順 4 〜 5)。
  • メソッドまたはコンストラクタを指定するときに括弧を付けずに名前だけ (getValue など) を使用した場合、同じ名前のフィールドが存在しなければ、Javadoc ツールはそのメソッドに対して正しくリンクを作成します。ただし、括弧と引数を追加するように促す警告メッセージを出力します。このメソッドがオーバー ロードされている場合、Javadoc ツールは、検索で最初に見つかったメソッドにリンクします。結果は前もって特定できません。
  • 入れ子にされたクラスは、上記のどの形式の場合も、単に「inner」ではなく、「outer.inner」 として指定しなければなりません。
  • すでに述べたとおり、クラスとメンバを区切るために、ドット (.) ではなくシャープ記号 (#) を使用することに注意してください。このように指定すると、Javadoc ツールは、あいまいさを解決できます。ドットは、クラス、入れ子にされたクラス、パッケージ、およびサブパッケージを区切るためにも使用されます。ただ し、Javadoc ツールでは一般に許容範囲が広く、あいまいさがなければ、ドットでも正しく解析されます。その場合でも警告は表示されます。

@see の検索順序 - Javadoc ツールは、ソースファイル (.java)、パッケージファイル (package.html)、または概要ファイル (overview.html) の中に登場する @see タグを処理します。後者の 2 つのファイルでは、完全指定の名前を @see タグに指定しなければなりません。ソースファイルでは、完全指定の名前、または部分指定の名前を指定できます。

Javadoc ツールは、.java ファイル内で完全指定でない名前が記述された @see タグを見つけると、Java コンパイラと同じ順序で指定された名前を検索します。ただし、Javadoc ツールは、特定の名前空間のあいまいさを検出しません。これは、ソースコードにこれらのエラーが存在していないことを前提としているためです。この検索順 序は、Java 言語仕様第 2 版の第 6 章「Names」で正式に定義されています。Javadoc ツールは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてから名前を検索します。具体的には、次の順序で検索します。

  1. 現在のクラスまたはインタフェース
  2. 外側を囲んでいるクラスとインタフェース (もっとも近いものから検索)
  3. スーパークラスとスーパーインタフェース (もっとも近いものから検索)
  4. 現在のパッケージ
  5. インポートされているパッケージ、クラス、およびインタフェース (import 文の順序に従って検索)

Javadoc ツールは、各クラスについて手順 1 〜 3 を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にそのクラスを囲んでいるクラス E を検索し、その次に E のスーパークラスを検索し、さらにその次に E を囲んでいるクラスを検索します。 手 順 4 と 5 では、1 つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません。その順序は、個々のコンパイラによって異なります。手順 5 では、Javadoc ツールは、java.lang を検索します。このパッケージは、すべてのプログラムに自動的にインポートされるからです。

Javadoc ツールは、必ずしもサブクラスを検索するとは限りません。また、javadoc の実行中にほかのパッケージのドキュメントが生成される場合でも、ほかのパッケージを検索しません。たとえば、@see タグが java.awt.event.KeyEvent クラス内にあって、java.awt パッケージにある名前を参照している場合、Javadoc は、そのクラスがインポートしないかぎりそのパッケージを検索しません。

名前が表示される方法 - label を省略すると、package.class.member が表示されます。一般に、package.class.member は、現在のクラスおよびパッケージに応じて適切に短縮されます。「短縮される」とは、必要最小限の名前だけが表示されるということです。たとえば、String.toUpperCase() メソッドに、同じクラスのメンバへの参照とほかのクラスのメンバへの参照が含まれている場合、クラス名が表示されるのは後者のケースだけです (次の表を参照)。

パッケージ名を広域的に削除するには、-noqualifier を使用します。

参照の種類 String.toUpperCase() での例 表示される名前
@see タグが同じクラス、同じパッケージのメンバを参照している @see String#toLowerCase()
toLowerCase()
(パッケージおよびクラス名は省略)
@see タグが異なるクラス、同じパッケージのメンバを参照している @see Character#toLowerCase(char)
Character.toLowerCase(char)
(パッケージ名は省略し、クラス名を含む)
@see タグが異なるクラス、異なるパッケージのメンバを参照している @see java.io.File#exists()
java.io.File.exists()
(パッケージ名とクラス名を含む)

@see の例
右側のコメントは、@see タグが別のパッケージ (java.applet.Applet など) のクラス内にある場合に、名前がどのように表示されるかを示しています。 

                                           See also: 
@see java.lang.String                   //  String                           
@see java.lang.String The String class  //  The String class                 
@see String                             //  String                           
@see String#equals(Object)              //  String.equals(Object)            
@see String#equals                      //  String.equals(java.lang.Object)   
@see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)      
@see Character#MAX_RADIX                //  Character.MAX_RADIX              
@see <a href="spec.html">Java Spec</a>  //  Java Spec            
@see "The Java Programming Language"    //  "The Java Programming Language"
@see を、ドキュメント化の対象にしていないクラスにまで拡張するには、-link オプションを使用します。

詳細については、@see タグのドキュメントを参照してください。

@serial  field-description | include | exclude
デフォルトの直列化可能フィールドのドキュメンテーションコメントで使用します。

field-description (省略可能) では、フィールドの意味を説明し、取り得る値のリストを示す必要があります。必要に応じて、複数の行に渡って説明を記述できます。標準ドックレットは、こ の情報を、直列化された形式のページに追加します。

クラスを直列化したあとしばらくしてから直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。

include および exclude 引数は、直列化された形式のページにクラスまたはパッケージを含めるか除外するかを示します。これらの引数には、次のような効果があります。

  • Serializable を実装している public または protected クラスは、通常はそのページに含められます。ただし、そのクラスまたはそのクラスが属するパッケージが @serial exclude で指定されていると、そのページから除外されます。
  • Serializable を実装している private または package private クラスは、通常はそのページから除外されます。ただし、そのクラスまたはそのクラスが属するパッケージが @serial include で指定されていると、そのページに含められます。

例: javax.swing パッケージは、@serial exclude で指定されています (package.html 内)。public クラス java.security.BasicPermission は、@serial exclude で指定されています。package private クラス java.util.PropertyPermissionCollection は、@serial include で指定されています。

クラスレベルで指定された @serial タグは、パッケージレベルで指定された @serial タグをオーバーライドします。

これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の第 1.6 節「クラスの直列化可能なフィールド およびデータの文書化」を参照してください。また、「直 列化の FAQ」も参照してください。この FAQ には、「-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。直列化形式仕様にクラスを含める場合には、Sun の仕様も参照してください。

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

@serialData  data-description
data-description は、直列化された形式でのデータの型と順序を説明するテキストです。このデータには、特に、writeObject メソッドによって書き込まれる省略可能なデータ、および Externalizable.writeExternal メソッドによって書き込まれるすべてのデータ (基底クラスを含む) が含まれます。

@serialData タグは、writeObject、readObject、writeExternal、readExternal、writeReplace、 および readResolve メソッドのドキュメンテーションコメントで使用できます。

@since  since-text
生成ドキュメントに「導入されたバージョン」見出しを追加し、指定された since-text を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、 インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、since-text に示されたソフトウェアリリース以降、存在していることを意味します。次に例を示します。 
    @since 1.4
Java プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。

@throws  class-name  description
@throws タグと @exception タグは同義です。生成ドキュメントに「例外」小見出しを追加して、class-name と description テキストを書き込みます。class-name は、そのメソッドからスローされる可能性のある例外の名前です。このタグは、メソッドまたはコンストラクタのドキュメンテーションコメントでのみ有効で す。このクラスが完全指定の名前で記述されていない場合、Javadoc ツールは、検索順序に 従ってクラスを探します。複数の @throws タグは、同じまたは異なる例外について、所与のドキュメンテーションコメントで使用できます。

チェックされる例外をすべて確実にドキュメント化するため、throws 節の例外に対して @throws タグが存在しない場合、Javadoc ツールは、@throws タグでドキュメント化されたかのように、その例外を HTML 出力 (説明なし) に自動的に追加します。

オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、@throws ドキュメンテーションをそのメソッドからサブクラスにコピーします。同じことは、インタフェースメソッドから実装メソッドへコピーする場合にも当てはまり ます。@throws にドキュメンテーションを継承させるには、{@inheritDoc} を使用できます。

詳細については、@throws タグのドキュメントを参照してください。

{@value  package.class#field}
{@value} が static フィールドのドキュメンテーションコメントで使用される場合 (引数なし)、その定数値が表示されます。 
    /**
     * The value of this constant is {@value}.
     */
    public static final String SCRIPT_START = "<script>"
任意のドキュメンテーションコメントで引数 package.class#field とともに使用すると、指定の定数値が表示されます。 

    /**
     * Evaluates the script starting with {@value #SCRIPT_START}.
     */
    public String evalScript(String script) {
    }
引数 package.class#field は、@see 引数と 同じ形式になりますが、メンバは static フィールドに属していなければなりません。

これらの定数値は、定数フィールド値の ページにも表示される値です。

@version  version-text
-version オプションが使われている場合、生成ドキュメントに「バージョン」小見出しを追加して、指定された version-text を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のバージョン番号を保持するように意図されています。これに対し、@since は、このコードが導入されたバージョン番号を保持します。version-text には、特別な内部構造はありません。バージョンタグを使用できる場所を調べるには、「タグを使用できる場所」を 参照してください。

1 つのドキュメンテーションコメントに複数の @version タグを含めることができます。必要に応じて、@version タグごとに 1 つのバージョン番号を指定することも、タグごとに複数のバージョン番号を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (,) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではな く、各言語に対応した名前区切り文字を使う必要がある場合は、1 つのタグに複数の名前を指定できます。

詳細については、@version タグのドキュメントを参照してください。


タグを使用できる場所

ここでは、タグを使用できる場所について説明します。@see、@since、@deprecated、{@link}、{@linkplain}、 および {@docroot} のタグは、すべてのドキュメンテーションコメントで使用できます。


概要のドキュメンテーションタグ

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

注 - バージョン 1.2 では、概要ドキュメント内の {@link} タグにバグがあります。テキストは正しく表示されますが、リンクが設定されません。現在のところ、{@docRoot} タグは、概要ドキュメント内では動作しません。

概要タグ
@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}

パッケージドキュメンテーションタグ

パッケージタグは、パッケージのドキュメンテーションコメントで使用できるタグです。このドキュメンテーションコメントは、package.html という名前のソースファイル内にあります。ここで使用できる @serial タグは、include または exclude 引数を指定したものだけです。

パッケージタグ
@see
@since
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}

クラスおよびインタフェースドキュメンテーションタグ

以下に、クラスまたはインタフェースのドキュメンテーションコメントで使用できるタグを示します。ここで使用できる @serial タグは、include または exclude 引数を指定したものだけです。

クラスおよびインタフェースタグ
@see
@since
@deprecated
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}

次にクラスコメントの例を示します。

/**
 * A class representing a window on the screen.
 * For example:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  Sami Shaio
 * @version %I%, %G%
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
   ...
}

フィールドドキュメンテーションタグ

以下に、フィールドのドキュメンテーションコメントで使用できるタグを示します。

フィールドタグ
@see
@since
@deprecated
@serial
@serialField
{@link}
{@linkplain}
{@docRoot}
{@value}

次にフィールドコメントの例を示します。

    /**
     * The X-coordinate of the component.
     *
     * @see #getLocation()
     */
    int x = 1263732;

コンストラクタおよびメソッドドキュメンテーションタグ

次に、コンストラクタまたはメソッドのドキュメンテーションコメント内で使用できるタグを示します。ただし、@return はコンストラクタ内では使用できず、{@inheritDoc} にはある制約があります。@serialData タグは、特定の直列化されたメソッドのドキュメンテーションコメントでのみ使用できます。

メソッドおよびコンストラクタタグ
@see
@since
@deprecated
@param
@return
@throws (@exception)
@serialData
{@link}
{@linkplain}
{@inheritDoc}
{@docRoot}

次にメソッドのドキュメンテーションコメントの例を示します。

    /**
     * Returns the character at the specified index. An index 
     * ranges from <code>0</code> to <code>length() - 1</code>.
     *
     * @param     index  the index of the desired character.
     * @return    the desired character.
     * @exception StringIndexOutOfRangeException 
     *              if the index is not in the range <code>0</code> 
     *              to <code>length()-1</code>.
     * @see       java.lang.Character#charValue()
     */
    public char charAt(int index) {
       ...
    }

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

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

-1.1
-author
-bootclasspath
-bottom
-breakiterator
-charset
-classpath
-d
-docencoding
-docfilessubdirs
-doclet
-docletpath
-doctitle
-encoding
-exclude
-excludedocfilessubdir
-extdirs
-footer
-group
 -header
-help
-helpfile
-J
-keywords
-link
-linkoffline
-linksource
-locale
-nocomment
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-noqualifier
-nosince
-notimestamp
-notree
-overview
-package
 -private
-protected
-public
-quiet
-serialwarn
-source
-sourcepath
-splitindex
-stylesheetfile
-subpackages
-tag
-taglet
-tagletpath
-title
-use
-verbose
-version
-windowtitle
イタリックで示されたオプションは、Javadoc の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、イタリックでないオプションを提供します。

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 に複数のパッケージ名を渡した場合だけです。詳細は、「HTML フレーム」を参照してください。

概要ページのタイトルは、-doctitle によって設定されます。

-public
public クラスおよびメンバだけを表示します。

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

-package
package、protected、および public のクラスとメンバだけを表示します。

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

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

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

たとえば、MIF ドックレットを呼び出すには、次のように指定します。 

    -doclet com.sun.tools.doclets.mif.MIFDoclet

特定のドックレットを実行した完全な例については、「Running the MIF Doclet」を参照してください。

-docletpath  classpathlist
-doclet オプションで指定されているドックレット開始クラスファイル、およびそれに依存する jar ファイルへのパスを指定します。開始クラスファイルが jar ファイル内にある場合、以下の例のように jar ファイルのパスが指定されます。絶対パスまたは現在のディレクトリからの相対パスを指定できます。classpathlist には、複数のパスまたは JAR ファイルを含めることができます。その場合、各パスまたは JAR ファイルを、Solaris の場合にはコロン (:)、Windows の場合にはセミコロン (;) で区切ります。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。

jar ファイルへのパスの例には、ドックレット開始クラスファイルが含まれています。jar ファイル名が含まれている点に注目してください。 

   -docletpath /home/user/mifdoclet/lib/mifdoclet.jar
ドックレット開始クラスファイルのパスの例クラスファイル名が省略されている点に注目してください。 
   -docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/
特定のドックレットを実行した完全な例については、「Running the MIF Doclet」を参照してください。

-1.1
この機能は、Javadoc 1.4 では削除されました。代替機能はありません。このオプションは、Javadoc 1.1 によって生成されるのと同じ外見と機能を持つドキュメントを作成するためのものでした。入れ子のクラスはサポートされていません。このオプションが必要な 場合は、Javadoc 1.2 または 1.3 を使用してください。

-source release
受け付けるソースコードのバージョンを指定します。ｒｅｌｅａｓｅ には次の値を指定できます。
1.5 Javadoc は、JDK 1.5 で導入された総称および他の言語機能を含んだコードを受け付けます。-source フラグを指定しないと、コンパイラはデフォルトとして 1.5 の動作をします。
1.4 Javadoc は、JDK 1.4 で導入された、アサーションを含むコードを受け付けます。
1.3 Javadoc は、JDK 1.3 以降に導入されたアサーション、総称、または他の言語機能をサポートしません。

javac でコードをコンパイルするときに使用した値に対応する release の値を使用します。

-sourcepath  sourcepathlist
javadoc コマンドにパッケージ名または -subpackages を渡すときに、ソースファイル (.java) を検索するためのパスを指定します。sourcepathlist には、コロン (:) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使って、ドキュメント化されるソースファイルの位置だけでなく、 それ自体はドキュメント化されないがドキュメント化されるソースファイルから継承されたコメントを持つソースファイルの位置も確認できます。

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

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

  /home/user/src/com/mypackage/*.java
この場合、次のようにして sourcepath を /home/user/src、つまり com/mypackage を含むディレクトリに指定し、それからパッケージ名 com.mypackage を指定します。 
  % javadoc -sourcepath /home/user/src/ com.mypackage
この指定方法は、「ソースパスの値とパッケージ名を連結して、ドットをスラッシュ「/」に変えると、パッケージのフルパス (/home/user/src/com/mypackage) になる」と覚えれば簡単です。

2 つのソースパスを設定するには、次のようにします。 

  % javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage

-classpath  classpathlist
Javadoc が参照クラス (.class ファイル) を検索するパスを指定します。参照クラスとは、ドキュメント化されるクラスとそれらのクラスによって参照されるすべてのクラスのことです。classpathlist には、コロン (:) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。classpathlist を指定するときは、クラスパスのドキュメントにある指示に従ってください。

-sourcepath が省略されている場合、Javadoc ツールは、-classpath を使って、クラスファイルだけでなくソースファイルも検索します (下位互換性のため)。したがって、ソースファイルとクラスファイルを別々のパスから検索する必要がある場合は、-sourcepath と -classpath の両方を使います。

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

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

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

-subpackages  package1:package2:...
ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソースコー ドに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。各 package 引数は、任意の最上位サブパッケージ (javaなど) または完全指定のパッケージ (javax.swing など) になります。ソースファイルを含める必要はありません。引数は、コロンで区切られます (すべてのオペレーティングシステム)。ワイルドカードは不要です (使用不可)。パッケージの検索場所を指定するには、-sourcepath を使用します。このオプションは、「ソースファイルの処理」で説明したとおり、ソースツリーにあるがパッケー ジには属していないソースファイルを処理しないので役立ちます。

次に例を示します。 

  % javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
このコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。

-exclude とともに -subpackages を使用すると、特定のパッケージを除外できます。

-exclude  packagename1:packagename2:...
指定されたパッケージとそのサブパッケージを -subpackages によって作成されたリストから無条