javadoc(1)

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

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

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

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

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

sourcefilenames
    スペースで区切られた一連のファイル名です。パス、および アスタリスク (*) などのワイルドカードを含めることができます。 javadoc ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、 その拡張子を除いた名前が実際に有効なクラス名であるすべてのファイルです。 したがって、ハイフンを含む名前 (X-Buffer など) や、 その他の無効な文字を含む名前を付けることによって、 それらのファイルをドキュメント化の対象から除外できます。 これは、テスト用のファイルや、テンプレートから生成されたファイルの場合に便利です。 javadoc ツールは、ソースファイル名の前に指定されたパスを使用して、 ソースファイル名を探します。この場合、 -sourcepath は使用しません。たとえば、 Button.java を渡すことは ./Button.java と指定することと同じです。完全パスを付けたソースファイル名の 例は「 /home/src/java/awt/Graphics*.java 」のようになります。「1 つ以上のクラスのドキュメント化」の例を 参照してください。また、「パッケージとクラスのドキュメント化」の 例のように、パッケージ名とソースファイル名を組み合わせることもできます。

-subpackages pkg1:pkg2:...
    指定されたパッケージ内のソースファイルからドキュメントを生成し、 再帰的にサブパッケージを処理します。 パッケージ名または ソールファイル名を指定するための代替手段です。

@argfiles
    Javadoc オプション、パッケージ名、およびソースファイル名を 任意の順序で並べたリストが含まれる 1 つ以上のファイルです。 このファイルの中では、ワイルドカード (*) および -J オプションは指定できません。

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

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

    注) javadoc ツールにパッケージ名を渡すと、現在のリリースでは指定された パッケージディレクトリ内のすべての .java クラスが処理されます。これは、 .java ファイルがコード例である場合や指定されたパッケージの実際の メンバではないその他のクラスである場合も同様です。 javadoc ツールは、パッケージ宣言用の各 .java ファイルを解析しません。将来のリリースでは、この解析を追加 する可能性があります。

実行時に、 javadoc ツールはその実行の一部として記述されているパッケージ、クラス、 およびメンバの名称にクロスリファレンスリンクを自動的に 追加します。リンクは、次の箇所に現われます。

•   宣言 (戻り値の型、引数の型、フィールドの型)

•   @see タグから生成される [関連項目] のセクション

•   {@link} タグから生成されるインラインテキスト

•   @throws タグから生成される例外の名称

•   インタフェースのメンバに対する [定義] リンクと、クラスのメンバに対する [オーバーライド] リンク

•   パッケージ、クラス、およびメンバを記述した一覧表

•   パッケージとクラスの継承ツリー

•   索引

-link と -linkoffline オプションを使用して、 コマンド行に含まれていない、個別に生成されるクラスの既存のテキストに ハイパーリンクを追加できます。

javadoc ツールは、実行のたびにひとつの完全なドキュメントを生成します。javadoc は、 追加生成を行えません。つまり、以前に実行した javadoc の結果を変更したり、 それらを直接取り込むことはできません。しかし、前述のようにほかの 実行の結果にリンクすることは可能です。

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

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

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

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

javadoc ツールがドキュメント用の内部構造を構築するときは、参照する クラスをすべてロードします。このため、ブートストラップクラス、 拡張機能、またはユーザクラスにかかわらず、 javadoc ツールは、参照するクラスをすべて検出できなければなりません。 一般的に、作成する クラスは、拡張機能としてロードされるか、 javadoc ツールのクラスパス内にある必要があります。

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

•   javadoc に施された機能強化

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

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

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

•   Javadoc に施された機能強化 - Javadoc 1.4 で追加された改良点の詳細

•   Javadoc FAQ - 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法

•   Javadoc のドキュメンテーションを作成するには - Sun で 一般的なドキュメンテーションコメントの記述方法の詳細

•   API 仕様を記述するための要件 - Java 2 プラットフォーム仕様を記述する際に 使用された標準要件。 この情報は、ソースファイルのドキュメンテーションコメント 形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも 役立ちます。 検証可能なアサーションを満たすパッケージ、クラス、 インタフェース、フィールド、およびメソッドについての要件を定めています。

•   ドキュメンテーションコメントの仕様 - ドキュメンテーションコメントの オリジナル仕様については、『Java Language Specification』 (James Gosling、Bill Joy、Guy Steele 共著) の初版の 第 18 章「Documentation Comments」を参照してください。 この章は、第 2 版では削除されました。

•   DocCheck ドックレット - ソースファイル内のドキュメンテーションコメントを検査し、 見つかったエラーや不規則な箇所を一覧にしたレポートを生成します。 これは Sun Doc チェックユーティリティの一部です。

•   MIF ドックレット - MIF、FrameMaker、および PDF 形式での API ドキュメントの 生成を自動化します。 MIF は Adobe FrameMaker の互換形式です。

  用語
いくつかの用語には、 javadoc ツールのコンテキストで特定の意味があります。

生成されるドキュメント
    javadoc ツールが Java ソースコード内の doc コメントから生成したドキュメント のことです。デフォルトの生成ドキュメントは HTML 形式で、標準 ドックレットによって作成されます。

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

ドキュメント化されるクラス
    javadoc の実行によって完全なドキュメントが生成されるクラスと インタフェースです。ドキュメント化するには、ソースファイルが 使用可能でなければならず、ソースファイル名またはパッケージ名の どちらかを javadoc コマンドに渡さなければなりません。ドキュメント化されるクラスは、 javadoc の実行で組み込まれるクラス、つまり「組み込みクラス」とも呼ばれます。

含まれるクラス
    対応するソースファイル名またはパッケージ名が javadoc コマンドに 渡されるクラスおよびインタフェースのことです。

除外されるクラス
    javadoc コマンドにソースファイル名またはパッケージ名が 渡されないクラスとインタフェースです。

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

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

  ソースファイル
javadoc ツールは、Java 言語ソースファイル (.java)、パッケージコメントファイル、 概要コメントファイル、およびその他の処理されないファイルの 4 種類の 「ソース」ファイルを基にして、出力を生成します。

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

  パッケージコメントファイル
各パッケージは、独自のドキュメンテーションコメントを 持つことができ、「ソース」ファイルに保持します。 javadoc ツールは、生成するパッケージの要約ページにこのコメントをマージします。 通常、このコメントには、パッケージ全体に適用される ドキュメントを含めます。

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

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

javadoc ツールは、実行時にこのファイルを自動的に検索します。このファイルを 見つけると、 javadoc ツールは次の処理を行います。

•   <body> タグと </body> タグの間にあるすべての内容を処理のためにコピーする

•   存在するパッケージタグを処理する

•   パッケージの要約などの Javadoc が生成するパッケージ要約ページの 最後に、処理されたテキストを挿入する

•   パッケージのコメントにある最初の文を、パッケージの要約ページの先頭に コピーする。また、概要の要約などの概要ページのパッケージリストにも、 この最初の文とパッケージ名を追加する。文の末尾は、クラスやメンバの 記述の最初の文に適用されるのと同じ規則によって特定される

  概要コメントファイル
ドキュメント化する各アプリケーションまたはパッケージのセットは、 独自の概要ドキュメンテーションコメントを持つことができ、それは 「ソース」ファイルに保持されます。 javadoc ツールは、生成する概要ページにこのコメントをマージします。通常、この コメントには、アプリケーションまたはパッケージのセット全体に 当てはまるドキュメントを含めます。

概要コメントファイルを作成する場合、ファイルに好きな名前を付けて、 好きな場所に置くことができますが、通常はファイル名を overview.html にして、ソースツリーの一番上の階層に置きます。異なるパッケージの セットに対して javadoc を複数回実行したい場合には、1 つのソースファイルのセットに対して 複数の概要コメントファイルを作成できます。たとえば、 java.applet パッケージのソースファイルが /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/ ディレクトリに置きます。 doc-files ディレクトリを /home/user/src/java/doc-files に置くことはできません。これは、 java はパッケージではなく、そのディレクトリそのものにソースファイルが 入っていないからです。

これらの処理されないファイルへのリンクは すべて明示的に記述する必要があります。これは、 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 は、将来の実装では 削除される可能性がある)

•   定数フィールド値ページ (constant-values.html) 。 static フィールドの値が表示される。

•   直列化形式ページ (serialized-form.html)。直列化可能クラス および外部化可能クラスの情報用。これらの各クラスには、直列化 フィールドおよびメソッドに関する説明がある。これらの情報は、API を 使う開発者ではなく、再実装者に必要な情報である。ナビゲーションバーに リンクがない場合、任意の直列化されたクラスに移動して、 クラスの [関連項目] セクション内の [直列化された形式] をクリック するとこの情報を取得できる 標準ドックレットは、直列化された形式のページを自動的に生成する。 ここには、Serializable を実装する public または非 public の クラスが組み込まれており、さらに、 readObject メソッド、 writeObject メソッド、直列化されたフィールド、 および @serial タグ、@serialField タグ、@serialData タグからの ドキュメンテーションコメントが組み込まれている。 直列化が可能な public クラスを除外するには、 そのクラスまたはそのクラスが属するパッケージを @serial exclude タグで 指定する。直列化が可能な package private クラスを含めるには、 そのクラスまたはそのクラスが属するパッケージを @serial include タグで 指定する。 1.4 では、 -private オプションを指定せずに javadoc を実行することで、public クラスおよび private クラスに完全な直列化形式を生成することができる。

•   索引 (index-*.html)。すべてのクラス名、 インタフェース名、コンストラクタ名、フィールド名、およびメソッド名を アルファベット順に並べてある。索引は、Unicode を扱えるように 国際化されており、1 つのファイルとして生成するか、または先頭 文字 (英語の場合 A から Z) ごとに別のファイルとして生成できる

  サポートファイル

•   ヘルプページ (help-doc.html)。ナビゲーションバーおよび 上記のページについて説明する。 -helpfile を使って、デフォルトの ヘルプファイルに置き換わる独自のカスタムヘルプファイルを提供する こともできる

•   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 のリスト
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 インタフェースを使用するページ
AudioClip.html | AudioClip インタフェースを使用するページ
src-html |  | ソースコードディレクトリ
 | java |  | パッケージディレクトリ
 |  | applet | サブパッケージディレクトリ
 |  |  | Applet.html | アプレットソースコードのページ
 |  |  | AppletContext.html AppletContext ソースコードのページ
 |  |  | AppletStub.html AppletStub ソースコードのページ
 |  |  | AudioClip.html AudioClip ソースコードのページ

  生成される API 宣言
javadoc ツールは、各クラス、インタフェース、フィールド、コンストラクタ、 およびメソッドの説明の初めで宣言を生成します。 この宣言は、その API 項目の宣言です。たとえば、 ブール型クラスの宣言は次のようになります。

    public final class Boolean
    extends Object
    implements Serializable

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

    public static Boolean valueOf(String s)

javadoc ツールは修飾子 public 、 protected 、 private 、 abstract 、 final 、 static 、 transient 、 および volatile を組み込むことができますが、 synchronized と native は組み込むことができません。 synchronized と native修飾子 は実装の詳細と見なされ、API 仕様の一部とは見なされません。

キーワード synchronized に依存するよりも、「複数のスレッドによって単一の Enumeration を並行して使用してはならない」というように、並行処理のセマンティックスを コメント説明の中でドキュメント化するべきです。ドキュメントでは、 これらのセマンティックスの達成方法を説明すべきではありません。別の 例を挙げると、 Hashtable はスレッドに対して安全でなければなりませんが、エクスポートされるその メソッドすべてを同期させることによってこれを実現すると明記する必要 はないということです。バケットレベルで内部的に同期をとる権限を留保して、 より高度な並行性を提供すべきです。

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

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

    /**
    * This is the typical format of a simple documentation comment.
    * that spans two lines.
    */

次のように、コメントは 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 {
    }

コメントの説明のあとにタグが続く - コメントの開始区切り文字である /** のあとからタグセクションまでが説明になります。 タグセクションは、 先頭文字が @ である行から始まります (行の先頭のアスタリスクおよび空白文字 は除く)。 説明を記述せず、コメントだけのタグを記述することもできます。 説明は、タグセクション以降に続けることはできません。 タグの引数は複数の行にまたがって記述できます。 タグの数に 制限はありません。何回も記述できるタグと、1 回しか記述できない タグがあります。 次の例の @see からタグセクションが始まります。

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

標準タグとインラインタグ: タグは、javadoc ツールが処理できる、 doc コメント内の特別なキーワードです。javadoc ツールには、@tag として現れる 標準タグと、中括弧内に {@tag} として現れるインラインタグがあります。解釈 させるためには、先頭のアスタリスク、空白、コメント区切り文字 (/**) を 除いては標準タグが行の先頭であるように配置する必要があります。つ まり、ユーザはテキスト内の任意の位置で @ 文字を使用でき、 この文字はタグの始めとは解釈されません。@ 文字で行を開 始してこれが解釈されないようにしたい場合は、HTML エンティティの &#064; を使用してください。各スタンドアロンタグには関連するテキストがあり ます。これは、そのタグの後から次のタグの直前まで、または doc コメント の最後までの任意のテキストです。関連付けられたテキストは、 複数行にまたがって記述できます。 インラインタグは、そのテキストが許 可される位置にはどこでも指定でき、解釈の対象となります。次の例は、 標準タグ @deprecated とインラインタグ {@link} が含まれています。

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

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

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

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

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

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

最初の文 - 各 doc コメントの最初の文は、宣言されている エンティティに関する簡潔かつ完全 な説明を含む要約文でなければなりません。 この文は、空白、タブ、または行末記 号が続いている最初のピリオド、あるいは最初のスタンドアロンタグで終了します。 javadoc ツールは、HTML ページの最初にあるメンバ要約に、この最初の文をコピーします。 文の区切りを判別する方法が将来のリリースでどのように 変更されるかについては、-breakiterator を参照してください。

複数フィールドの宣言 - 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 ツールには、クラスおよびインタフェース内のメソッドのコメントを 自動的に再利用する、つまり「継承」する機能があります。 メソッドコメントに記述や @return、@param、@see、@throws と いったタグがない場合、 javadoc ツールは、そのメソッドがオーバーライドまたは実装している メソッドのコメントとタグ (存在する場合) を代わりにコピーします。 その際のアルゴリズムは、以下のとおりです。

つまり、特定のパラメータの @param タグが見つからない場合、 そのパラメータのコメントがコピーされます。 特定の例外の @throws タグが 見つからない場合、その例外が宣言されている場合に限り、 その @throws タグがコピーされます。

この動作は、バージョン 1.3 以前とは対照的です。 以前のバージョンでは、説明やタグが存在すれば、 コメントは一切継承されませんでした。

また、説明または任意のタグにインラインタグ {@inheritDoc} が含まれる場合、対応する説明またはタグが その位置にコピーされます。

オーバーライドされているメソッドは、ドキュメント化される クラスのメンバでなければならず、かつ、外部参照クラスの メンバであってはなりません。そうでないと、コピーする ドキュメンテーションコメントを実際には取得できません。

コメントの継承は次の場合に行われます。

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

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

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

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

1.  直接に実装されている (または、拡張されている) インタフェースを、 メソッドの宣言で implements (または extends) キーワードのあとに 登場する順序で、1 つずつ調べる。 このメソッドについて 最初に見つかったドキュメンテーションコメントを採用する

2.  手順 1 でドキュメンテーションコメントが見つからなかった場合は、 直接実装されている (または、拡張されている) インタフェースの それぞれに対して、このアルゴリズム全体を再帰的に適用する
     (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ)

3.  手順 2 でドキュメンテーションコメントが見つからなかった場合で、 このクラスが Object 以外のクラスである (インタフェースではない) 場合は、 次のように処理する

    a. スーパークラスにこのメソッドについてのドキュメンテーションコメントが
    記述されていれば、そのコメントを採用する
    b. 手順 3a でドキュメンテーションコメントが見つからなかった場合は、
    スーパークラスに対して、このアルゴリズム全体を適用する

  javadoc のタグ

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

タグは次の 2 種類あります。

• スタンドアロンタグ - 説明のあとのタグセクションだけに 置くことができます。 このタグは、@tag のように中括弧で囲みません。

• インラインタグ - コメントの説明内またはスタンドアロンタグの コメント中の任意の場所に置くことができます。 インラインタグは、{@tag} の ように中括弧で囲みます。

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

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

タグ | 導入された JDK
 | のバージョン
@author | 1.0
{@docRoot} | 1.3
@deprecated | 1.0
@exception | 1.0
{@inheritDoc} | 1.4
{@link} | 1.2
{@linkplain} | 1.4
@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 を持つ Author エントリを追加します。 1 つの doc コメントに複数の @author タグを含めることができます。 @author タグごとに 1 つ、またはタグごとに複数の名前を 指定できます。前者の場合は、 javadoc ツールは、名前と名前の間にコンマ (,) とスペースを挿入します。 後者の場合、テキスト全体が 解析されることなく生成されるドキュメントにコピーされるだけです。 このため、コンマ以外 の現地仕様の名前区切り文字を使う場合は、1 行に複数の名前を指定します。

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

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

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

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

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

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

        注 - Makefile の中で {@docRoot}をこのように利用する場合、 一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする 必要があります。 たとえば、Inprise MAKE バージョン 5.2 を Windows 上で実行する場合は、{{@docRoot}} のように、 中括弧を二重にする必要があります。さらに、-bottom などの オプションに対する引数を、単一引用符ではなく、 二重引用符で囲む必要があります。href 引数の値を囲む引用符は省略します。

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

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

    {@inheritDoc}
        最も近いスーパークラスから現在の ドキュメンテーションコメントに、 ドキュメントを継承します。 この機能により、コメントは継承ツリーの 上位に移動し、開発者はコピーしたテキストに 記述を追加することができます。 コメントの継承もあわせて参照してください。

    このタグは次の 2 つの位置に配置できます。

    •   コメント本文 (最初のスタンドアロンタグの前)。ここで、 スーパークラスからコメント全体をコピーします。

    •   スタンドアロンタグのテキスト引数内。ここで、スーパークラスからタグの テキストをコピーします。

    {@link " package.class#member label" }
        参照クラスの、指定された名前を持つパッケージ、クラス、 またはメンバについてのドキュメントを指すインラインリンクを、表示テキスト label とともに挿入します。

        このタグは、 @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 オプションを使用します。

    {@linkplain " package.class#member label"}
        リンクのラベルがコードフォントではなくプレーンテキストで 表示されている点以外は、 {@link} と同じです。 ラベルがプレーンテキストで 記述されている場合に便利です。次の例を参照してください。

    Refer to {@linkplain add() the overridden method}.

    これは以下のように表示されます。

    Refer to the overridden method.

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

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

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

    @see string
        string のテキストエントリを追加します。 リンクは生成されません。string は、書籍、または URL ではアクセスできない情報の参照先です。 javadoc ツールは、最初の文字が二重引用符 (") かどうかを調べて、 上の 2 つの形式とこの形式とを区 別します。次に例を示します。

             @see "The Java Programming Language"

        これは次のようなテキストを生成します。

             関連項目:
                  "The Java Programming Language"

    @see <a href="URL#value">label</a>
        URL#value で定義されたとおりにリンクを追加します。 URL#value は、相対 URL または絶対 URL です。 javadoc ツールは、最初の文字として、小なり括弧 (<) を探すことで、 このリンクをその他の場合と区別します。

             @see <a href="spec.html#section">Java Spec</a>

        これは次のようなリンクを生成します。

            関連項目:
                  Java Spec

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

        バージョン 1.2 では、ラベルではなく、名前だけが HTML タグ <code> に囲まれて自動的に表示されます。バージョン 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」第 2 版の第 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"

    @see を、ドキュメント化の対象にしていないクラスにまで拡張するには、
        -link オプションを使用します。

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

        @since 1.4

    Java プラットフォームのソースコードの場合、このタグは、 Java プラットフォーム API 仕様のバージョンを示します。 その変更や機能がリファレンス実装に追加された時期を 示すとは限りません。

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

        省略可能な field-description は、 フィールドの doc コメントを拡張します。 この説明では、フィールドの意味および 取り得る値のリストを指定しなければなりません。 必要な場合には、複数の行にまたがって説明を記述することができます。 標準ドックレットは、この情報を、直列化された形式のページに追加します。

        include と exclude 引数は、直列化された形式のページにクラスまたはパッケージを含めるべきか、 あるいはこれらの引数を除くべきかを指定します。 これらは、次のように動作します。

        •   Serializable を実装する public クラスまたは protected クラスは、 そのクラス (またはそのパッケージ) が @serial exclude とマークされていない限り含められます。

        •   Serializable を実装する private クラスまたは package-private クラスは、 そのクラス (またはそのパッケージ) が @serial include とマークされていない限り除かれます。

        例: javax.swing パッケージは、(package.html 内で) @serial exclude とマークされます。public クラスである java.sercurity.BasicPermission は、 @serial exclude とマークされます。package-private クラスである java.util.PropertyPermissionCollection は、 @serial include とマークされます。

        クラスレベルのタグ @serial は、パッケージレベルの @serial をオーバーライドします。

        これらのタグの使用法についての詳細と 使用例は、「Java オブジェクト直列化仕様」 の 1.6 節 「クラスの直列化可能なフィールドおよびデータの文書化」を 参照してください。 また、「直列化の FAQ」も参照してください。ここには、「 -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 ツールは検索順序に従ってクラスを探します。 スーパークラスまたはインタフェース内にドキュメント化されている @throws タグのコメントは、（1） サブクラスの throws 節で宣言されている 例外と （2） すべての実行時の例外に継承されます。 こうした例外が存在しない場合、ドキュメントを 強制的に継承させるには、{@inheritDoc} を使用します。

    {@value}
        static フィールドのコメント内で使用すると、定数の値を表示します。 これらは、「定数フィールド値」ページで表示される値です。

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

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

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

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

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

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

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

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

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

次は、クラスコメントの例です。

    /**
    * A class representing a window on the screen.
    * For example:
    * <pre>
    *    Window win = new Window(parent);
    *    win.show();
    * </pre>
    *
    * @author  Sami Shaio
    * @version 1.12, 05/12/00
    * @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;

  コンストラクタおよびメソッドドキュメントタグ
次に、コンストラクタまたはメソッドの ドキュメンテーションコメント内で 表示できるタグを示します。 ただし、{@inheritDoc} は コンストラクタ内では表示できません。

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

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

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

    -1.1 | -header | -package
    -author | -help | -private
    -bootclasspath | -helpfile | -protected
    -bottom | -J | -public
    -charset | -link | -quiet
    -classpath | -linkoffline | -serialwarn
    -d | -linksource | -source
    -docencoding | -locale | -sourcepath
    -doclet | -nodeprecated | -splitindex
    -docletpath | -nodeprecatedlist | -stylesheetfile
    -doctitle | -nohelp | -subpackages
    -encoding | -noindex | -tag
    -exclude | -nonavbar | -taglet
    -excludedocfilessubdir | -noqualifier | -tagletpath
    -extdirs | -nosince | -title
    -footer | -notree | -use
    -group |  | -overview | -verbose
     |  |  | -windowtitle

  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 フレーム」 節を参照してください。

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

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

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

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

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

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

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

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

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

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

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

    -docletpath /home/user/mifdoclet/lib/mifdoclet.jar

次はドックレットの開始クラスファイルのパスの例です。 クラスファイル名が省略されていることに注意してください。

    -docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/

-1.1
    この機能は、javadoc 1.4 から削除されました。代替の機能は 存在しません。このオプションは、javadoc 1.1 で生成される ドキュメントの外観と機能 (サポートされなくなった、入れ子になったクラスを 含む) を備えたドキュメントを作成するためのものでした。 このオプションが必要であれば、代わ りに javadoc 1.2 または 1.3 を使用してください。

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

-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
    2 つのソースパスを指定するには、次のようにします。

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

-classpath classpathlist
    javadoc が参照されるクラスの検索を行うパスを指定します。 参照されるクラス (.class) とは、 ドキュメント化されるクラスとそれらのクラスによって 参照される任意のクラスのことです。 javadoc は、指定されたパス以下のすべてのサブディレクトリで 検索を行います。 classpathlist には、パス間をコロン (:) で区切って複数のパスを 含めることができます。 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 ソースファイルの解析に要したミリ秒数などの 追加メッセージを表示します。

-quiet
    エラーメッセージ以外、および警告メッセージ以外の メッセージを除外し、 エラーメッセージおよび警告メッセージだけを 表示して見つけやすくします。 また、バージョン文字列の表示も抑制します。

-locale language_country_variant
    重要: -locale オプションは、標準ドックレットやその他のドックレット によって提供されるオプションよりも前に (左側に) 指定する必要があります。そうでなければ、ナビゲーションバーは 英語で表示されます。順序に依存するコマンド行オプションは、 このオプションのみです。

    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 バイトを 確保する必要がある場合は、Java の -Xmx オプションを次のように呼び出します。

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

使用している javadoc のバージョンを確認するには、 次のように java の「-version」オプションを呼び出します。

    example% javadoc -J-version
    java version "1.2"
    Classic VM (build JDK-1.2-V, green threads, sunwjit)

(標準ドックレットのバージョン番号は出力ストリームに表示されます。)

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

-d directory
    生成された HTML ファイルを保存するディレクトリを 指定します (d は「生成先 (destination)」の意味)。このオプションを 省略すると、生成されたファイルは現在のディレクトリに保存されます。 値 directory には、絶対ディレクトリまたは現在の作業 ディレクトリからの相対ディレクトリを指定できます。 1.4 では、javadoc の実行時に 自動的に生成先ディレクトリが作成されます。

たとえば、 次の例は、com.mypackage パッケージのドキュメントを生成し、 結果を /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 テキストを含めます。このテキストは、デフォルトでは省略されます。 使用している javadoc ツールのバージョンを確認するには、 オプションを使用します。

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

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

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

    example% javadoc -windowtitle "Java 2 Platform" com.mypackage

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

    example% javadoc -doctitle "Java<sup><font size=
    			TM</font></sup>" com.mypackage

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

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

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

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

-link extdocURL
    javadoc ツールにより生成された既存の 外部参照クラスのドキュメンテーションへのリンクを作成します。 引数は 1 つです。

•   extdocURL は、javadoc によって生成され、リンク先として指定する 外部ドキュメントがあるディレクトリの絶対 URL または相対 URL です。 あとで例を示します。 このディレクトリ内に package-list ファイルが存在して いなければなりません。存在しない場合は、-linkoffline を使用します。 javadoc ツールは package-list ファイルからパッケージ名を読み取り、それを extdocURL のパッケージにリンクします。 javadoc ツールを実行すると、 extdocURL 値は作成された <A HREF> リンクにそのままコピーされます。 したがって、 extdocURL はファイルではなく、 extdocURL の URL である必要があります。

ドキュメントを任意の Web サイト上のドキュメントにリンクするには extdocURL の絶対リンクを、相対ロケーションだけを指定するには 相対リンクを使用できます。 相対リンクを使用する場合、 生成先ディレクトリ (-d で指定) からの相対パスを、 リンク先パッケージがあるディレクトリに渡す必要があります。

通常、絶対リンクを指定する場合は、http: リンクを使用します。 ただし、Web サーバをもたないファイルシステムに リンクする場合は、file: リンクを使用できます。 ただし、この方法は、生成されたドキュメントに アクセスしようとする すべてのユーザが同じファイルシステムを共有している 場合以外は使用しないでください。

    javadoc 実行時に複数の -link オプションを指定して、 複数のドキュメントへのリンクを作成することもできます。

    -linkoffline または -link の選択 - 現在実行中の javadoc の外部にある API ドキュメントにリンクするとき、 どちらかのオプションを使用します。

    -link を使用する場合: • 外部 API ドキュメントへの相対パスを使用している • 外部 API ドキュメントへの絶対 URL を使用している
     (プログラムがその URL に接続し、読み取りを行うことが シェルによって許可されている場合)

    -linkoffline を使用する場合: • 外部 API ドキュメントへの絶対 URL を使用している (プログラムがその URL に接続し、読み取りを行うことが シェルによって許可されていない場合)。このような状況は、 リンク先のドキュメントがファイアウォールの 向こう側にある場合に発生します。

    外部ドキュメントへの絶対リンクの使用例 - java.lang、java.io、および他の Java 2 プラットフォームパッケージ (http://java.sun.com/j2se/1.4/docs/api) に リンクしたい場合があります。次のコマンドは、 Java 2 プラットフォームパッケージへのリンクを持つ com.mypackage パッケージのドキュメントを生成します。 生成されたドキュメントには、たとえばクラスツリー内の Object クラスへのリンクが含まれています (-sourcepath や -d などの他のオプションは表示されません)。

        % javadoc -link http://java.sun.com/j2se/1.4/docs/api com.mypackage

    外部 ドキュメントへの相対リンクの使用例 - javadoc ツールの異なる実行で生成されたドキュメントを持つ 2 つのパッケージがあり、それらが別々の 相対パスをもっているとします。 この例では、2 つのパッケージを com.apipackage (API)、com.spipackage (SPI - Service Provide Interface) とします。 ドキュメントの置き場所は docs/api/com/apipackage および docs/spi/com/spipackage です。 API パッケージドキュメントはすでに生成され、ドキュメントが現在の ディレクトリ内にある場合、次のように実行することで、 API ドキュメントにリンクした SPI パッケージをドキュメント化できます。

        % javadoc -d ./spi -link ../api com.spipackage

    -link 引数が生成先ディレクトリの相対パス (docs/spi) で あることに注意してください。

    詳細 - -link オプションを使うと、コードからは参照されていても、 Javadoc の現在の実行ではドキュメント化されないクラスにリンク できるようになります。 リンクから有効なページに 移動できるようにするには、それらの HTML ページが ある場所を調べ、その場所を extdocURL に指定する必要があります。 このオプションを使うと、たとえば、サードパーティのドキュメントから、 http://java.sun.com にある java.* のドキュメントにリンクすることができます。

    今回の実行で javadoc によって生成されるドキュメント内の API だけを対象にリンクを作成する場合は、 -link オプションを省略します。 -link オプションが 指定されていない場合、 javadoc ツールは、外部参照されたドキュメントへのリンクを 作成しません。これは、そのドキュメントが 存在するかどうか、あるいは存在していてもどこに 存在しているのかを判別できないからです。

    このオプションは、生成ドキュメント内の複数の場所に リンクを作成できます。

    また、このオプションを使うと、複数のパッケージ群の 間にクロスリンクを作成することもできます。 つまり、ある一式のパッケージに対して javadoc を実行したあと、別の一式のパッケージに 対して javadoc を実行し、 これら 2 つのパッケージ群の間に クロスリンクを作成できます。 3 番目の使い方は、ドキュメントを 更新するための「ハック」用です。 つまり、まず、パッケージ全体に javadoc を実行して、次に、変更されたパッケージだけに javadoc をもう一度実行します。すると、 更新されたファイルだけをオリジナルの パッケージに挿入し直すことになります。

    参照クラスのバグ修正 - 1.4 では、次のバグが修正されました。

        1.2 および 1.3 でのリンクに関するバグ
        - @see または {@link} で 除外クラスを参照し、
        -link を使用した場合、実際にハイパーリンクが
        作成されるのは、そのクラスが import 文か宣言の
        どちらかで参照されている場合に限られます。
        メソッドの本体で参照されているだけでは不十分です。
        対策としては、その参照クラスの import 文を明示的に
        (またはワイルドカードを使用して) 追加します。

    @see または -link を使った {@link} 参照により、 参照クラスを読み込み、リンクを作成できるようになりました。 以前に回避策として追加した import 文は削除できます。 この import 文には、次の例のように コメントを追加することを推奨していました。

        import java.lang.SecurityManager; // workaround to force @see/@link\
        										hyperlink

    パッケージリスト: -link オプションでは、javadoc ツールによって生成された package-list という名前のファイルが、このオプションで指定する URL に存在している 必要があります。 package-list ファイルは、その場所でドキュメント化されているパッケージの 名前のリストを含む単純なテキストファイルです。 前の例では、 javadoc ツールは、指定された URL にある package-list という名前のファイルを探し、パッケージ名を読み込んで、 その URL にあるそれらのパッケージへのリンクを作成しました。

    たとえば、Java プラットフォーム v1.4 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 ツールは、指定された extdocURL の場所にある package-list ファイルから、該当する名前のパッケージを探します。パッケージ名が 見つかった場合は、その extdocURL を名前の前に付けます。

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

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

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

        example% javadoc -link extdocURL1 -link extdocURL2 ... \
           -link extdocURLn com.mypackage

    extdocURL1、 extdocURL2、... extdocURLn は、それぞれ外部ドキュメントの ルートを指し、各ルートには、 package-list という名前のファイルが含まれています。

    クロスリンク - まだ生成されていない 2 つ以上のドキュメントを クロスリンクする場合は、「ブートストラッピング」が必要になることに 注意してください。言い換えると、どのドキュメントの package-list も存在していない場合、最初のドキュメントに対して javadoc ツールを実行した時点では、2 番目のドキュメントの package-list はまだ存在していません。したがって、外部リンクを作成するには、 2 番目のドキュメントを 生成したあと、最初のドキュメントを生成し直す必要があります。

    この場合、最初に行うドキュメント生成の目的は、 package-list を作成することです。パッケージ名をすべて把握している場合は、 package-list を手動で作成することもできます。次に、2 番目のドキュメントと その外部リンクを生成します。 javadoc ツールは、必要な外部の package-list ファイルが存在しない場合は、警告を表示します。

    -linkoffline extdocURL  packagelistLoc
        このオプションは、 -link オプションを変えたものです。どちらも、javadoc で 生成された外部参照クラスのドキュメントへのリンクを作成します。 Javadoc ツールが「オフライン」で、Web 上のドキュメントに リンクする場合は、Web 接続経由ではドキュメントに アクセスできないため、 -linkoffline オプションを使用します。

    つまり、外部ドキュメントの package-list ファイルがアクセスできない、または extdocURL ロケーションに存在しないが、 packageListLoc で指定できる別のロケーション (通常はローカル) に存在している場合には、 -linkoffline を使用するということです。 したがって、 extdocURL に WWW 上でしかアクセスできない場合は、 -linkoffline を指定することにより、ドキュメントの生成時に javadoc ツールが Web に接続できなければならないという制約がなくなります。 例をあとで示します。

    -linkoffline オプションには 2 つの引数があります。1 つは <a href> リンクに埋め込む文字列、もう 1 つは package-list: の検索場所を示します。

        •   extdocURL は、javadoc によって生成され、リンク先として指定する 外部ドキュメントがあるディレクトリの絶対 URL または相対 URL です。 相対リンクの場合、 生成先ディレクトリ (-d で指定) からの相対パスを、 リンク先パッケージのルートに渡す必要があります。 詳細は、 -link オプションの extdocURL を参照してください。

        •   packagelistLoc には、外部ドキュメントの package-list ファイルが入っているディレクトリのパスまたは URL を指定します。 URL (http: または file:) またはファイルパスを指定できます。 また、絶対パスと相対パスのどちらでもかまいません。 相対パスの場合は、javadoc が実行される現在の ディレクトリからの相対パスとして指定します。 package-list というファイル名は含めないでください。

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

        外部ドキュメントへの絶対リンクを使った例 - java.lang 、 java.io 、およびその他の Java 2 プラットフォームパッケージ (http://java.sun.com/j2se/1.4/docs/api) にリンクしたくても、Web にアクセスできない 場合について考えてみます。 package-list ファイルをブラウザで開き (http://java.sun.com/j2se/1.4/docs/api/package-list)、 ローカルディレクトリに保存します。次に、2 番目の引数 packagelistLoc でそのローカルコピーを指定します。 このとき、 パッケージリストファイルは現在のディレクトリ 「.」に保存されています。 次のコマンドは、 Java 2 プラットフォームパッケージへのリンクを含む、 com.mypackage パッケージのドキュメントを生成します。 生成されたドキュメントには、たとえばクラスツリー内の Object クラスへのリンクが含まれています (-sourcepath などの他の必要なオプションは表示されません)。

            % javadoc -linkoffline http://java.sun.com/j2se/1.4/docs/api . com.mypackage

        外部ドキュメントへの相対リンクを使った例 - -linkoffline を相対パスで指定するのはあまり一般的ではありません。通常は、 -link で十分だからです。 -linkoffline を使用している場合、 package-list ファイルは通常ローカルで、相対リンクを使用している場合は、 リンク先のファイルもローカルであるのが普通です。 そのため、 -linkoffline に 2 つの異なる引数のパスを 与える必要はありません。 2 つの引数が同じである場合、 -link を使用できます。 -link の相対リンクの使用例を参照してください。

        package-list ファイルの手動作成 - package-list ファイルがまだ存在しなくても、ドキュメントのリンク先の パッケージ名がわかっている場合は、 このファイルのコピーを自分で作成し、 packagelistLoc でそのパスを指定することができます。 com.apipackage が最初に作成されたときに com.spipackage のパッケージリストが存在しなかった、 以前の場合がその例です。 この方法は、パッケージ名はわかっているものの、 まだ公開されていない、新しい外部ドキュメントにリンクする ドキュメントを生成する場合に便利です。 また、Javadoc 1.0 または 1.1 では package-list ファイルが 生成されないため、この方法で、これらのバージョンで 生成されたパッケージの package-list ファイルを生成できます。 2 つの会社が未公開の package-list ファイルを 共有することもできるため、クロスリンクを設定した ドキュメントを同時にリリースすることも可能です。

        複数のドキュメントにリンク - -linkoffline は、参照先の生成ドキュメントごとに 1 つずつ指定します。 次の例では、わかりやすくするために オプションごとに行を分けています。

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

        ドキュメントの更新: -linkoffline オプションのもう 1 つの用途は、プロジェクトで多数のパッケージを使い、 すでにツリー全体に対して javadoc を実行してある場合に、次の実行では、すばやく細かい 変更を行なってから、ソース ツリーの一部に対してだけ javadoc を実行し直したい場合に便利です。これは、 変更がドキュメンテーションコメントに対し てであり、シグニチャに対してではない場合にだけ正常に 処理されるので、ハッキング のようなものです。ソースコードに対してシグニチャを追加、 削除または変更した場合は、索引、パッケージツリー、 継承されるメンバのリスト、[使用] ページなどの場所 で壊れたリンクが表示されます。

        まず、新しい実行のため、新規の 生成先ディレクトリ (update) を作成します。 -linkoffline の 1 番目の引数に現在のディレクトリ「.」を 設定し、2 番目の引数に package-list を検索する場所であるオリジナルの ドキュメントへの相対パス (html) を設定します。

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

        javadoc の実行が終了したとき、 update 内に生成されたファイル (概要や索引ではない) で、 html 内にあるオリジナルのファイルを上書きコピーします。

        -linksource
            各ソースファイル (行番号付き) の HTML バージョンを 作成し、標準の HTML ドキュメントからのリンクを追加します。 このオプションにより、含まれるソースファイル内の すべての private 実装の詳細が開示されます。 開示されるものには、private クラス、private フィールド、 および private メソッドの本文 (-public、-package、-protected、-private といった オプションにかかわらず) が含まれます。 -private オプションを指定していない場合は、 すべての private クラスまたはインタフェースが リンクを介してアクセスできるわけではありません。

        -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 がソースコードに 含まれておらず、ナビゲーションバーを すっきりと見せたい場合に便利です。

        -nosince
            生成されるドキュメントから、 @since タグに関連した「Since」セクションを削除します。

        -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 -helpfile /home/doc/myhelp.html 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 ファイルのエンコーディングを指定します。

        -source1.4
            Javadoc で J2SE v 1.4 のソースコードに存在するアサーションを 処理できるようにするために必要です。 このオプションは、javac -source 1.4 を使用して コンパイルするコードをドキュメント化します。

        -tag tagname:Xaoptcmf:taghead
            1 つの引数をもつ簡単なカスタムスタンドアロンタグである、ドキュメンテーションコメント内の @tagname を javadoc で 解釈できるようにします。 したがって、Javadoc ツールはタグ名をスペルチェックできます。 ソースコードに存在するすべてのカスタムタグに -tag オプションを付け、現在の実行で出力されていないものを 無効化 (Xを使用) しておくことが重要です。

        -tag オプションはタグの見出しである taghead を 太字で出力し、そのあとに 1 つの引数からの テキストを出力します。その例はこのあとで表示します。 他のスタンドアロンタグと同様に、 この引数のテキストにインラインタグを含め、 解釈させることができます。 出力結果は、@return や @author といった標準の 1 つの引数をもつタグと似ています。

        タグの配置 - 引数の Xaoptcmf 部分は、ソースコードのどこに タグの配置が許可されているか、 またタグを無効に (X を使用) できるかどうかを判断します。 タグの配置を全体に許可する場合は a、 それ以外の場合については、 その他の文字を組み合わせて指定できます。

            X (タグの無効化)
            a (全部)
            o (概要)
            p (パッケージ)
            t (タイプ、つまりクラスおよびインタフェース)
            c (コンストラクタ)
            m (メソッド)
            f (フィールド)

        シングルタグの例 - ソースコードの任意の場所で使用できる タグのタグオプションの例を示します。

            -tag todo:a:"To Do:"

        コンストラクタ、メソッド、およびフィールドだけで @todo を 使用させるには、次のようにします。

            -tag todo:cmf:"To Do:"

        上記では、末尾のコロン (:) がパラメータの 区切り記号ではなく、表示のとおり、 見出しテキストの一部であることに注意してください。 次のように、@todo タグを含むソースコードに どちらかのタグオプションを使用します。

            @todo The documentation for this method needs work.

        この行は次のように出力されます。

            To Do:
            	The documentation for this method needs work.

                タグ名のスペルチェック (タグの無効化) -
                開発者は、ソースコードの中で出力できないカスタムタグを
                使用することがあります。 その場合、ソースタグに存在する
                すべてのタグをリストし、出力するタグを有効化し、
                出力しないタグを無効化することが重要です。
                X を使用するとタグを無効化でき、これがない場合は
                タグが有効となります。 この文字の存在によって、
                Javadoc
                ツールは、検出したタグが未知のタグで、
                おそらく綴り間違いであると判断できます。
                この場合、警告メッセージが表示されます。

                すでに存在する、配置を指定する引数の値に X を追加した場合、
                タグを有効にしたいときに X を削除できます。
                たとえば、@todo が出力しないタグの場合、次のようにします。

                    -tag todo:Xcmf:"To Do:"

                または、次のようにより簡単にすることもできます。

                    -tag todo:X

                -tag todo:X の構文は、@todo がタグレットで 定義されている場合も有効です。

                タグの順序 - -tag (および -taglet) オプションの順序に従って タグが出力されます。 カスタムタグと標準タグを 混在させることができます。 標準タグのタグオプションは、 順序を決定するためだけのプレースホルダです。 これらは標準タグ名だけを使用します (標準タグの小見出しは変更できません)。 これを次の例に示します。

                -tag がない場合、-taglet の場所によってその順序が決まります。 この 2 つが両方ある場合は、コマンド行の最後に使用された方が 順序を決定します (これは、タグとタグレットが、 コマンド行で使用された順に処理されるためです)。 たとえば、-taglet と -tag が両方とも todo という 名前である場合、コマンド行の最後で使用された 方が順序を決定します。

                タグの完全なセットの例 - この例では、出力の Parameters と Throws の間に ToDo を挿入します。 「X」を使用して、@example が ソースコード内の今回の実行で出力されないタグで あることを指定できます。 @argfile を使用すると、 次のように行の継続文字なしで、 引数ファイルの異なる行にタグを配置できます。

                    -tag param
                    -tag return
                    -tag todo:a:"To Do:"
                    -tag throws
                    -tag see
                    -tag example:X

                javadoc がドキュメンテーションコメントを解析する際に、 検出されたタグのうち、標準タグでもなく、 -tag や -taglet で渡されるタグでもないものは、 不明なタグとして認識し、警告がスローされます。

                標準タグは、最初、デフォルトの順序で リスト内部的に格納されます。 -tag オプションを使用すると、このタグがリストに追加されます。 標準タグはデフォルトの位置から移動します。 そのため、標準タグで -tag オプションが省略されると、 デフォルトの位置に配置されたままになります。

                競合の回避 - 固有のネームスペースを細かく分けるには、 パッケージに使用されている com.mycompany.todo という名前のように、ドット (.) を区切り記号とする名前を使います。 Sun は今後もドットを含まない標準タグを作成します。 ユーザが作成したタグは、Sun が定義した同じ 名前のタグの動作をオーバーライドします。 つまり、ユーザが @todo という名前のタグまたは タグレットを作成していた場合、そのあとで Sun が 同じ名前の標準タグを作成しても、ユーザが定義した 動作はそのまま維持されます。

                -taglet オプションを使用して、より複雑な スタンドアロンタグやカスタムインラインタグを 作成することができます。

                -taglet " class"
                    タグのドキュメントの生成に使うタグレットを起動するための クラスファイルを指定します。 クラスの完全修飾名を指定してください。 このタグレットは、カスタムタグが持っているテキスト引数の 数も定義します。 タグレットはこれらの引数を受け取り、 処理し、出力を生成します。 タグレットの例の詳細については、 タグレットの概要を参照してください。

                タグレットはスタンドアロンタグまたはインラインタグに 使用すると便利です。 タグレットでは任意の 数の引数を持つことができ、カスタムの動作を実装できます。 たとえば、テキストを太字にしたり、箇条書き形式にしたり、 テキストをファイルに書き出したり、 他のプロセスを起動したりすることができるのです。

                タグレットへのパスを指定するには、 -tagletpath オプションを使用します。 生成されたページの Parameters と Throws の間に To Do タグレットを挿入する例を示します。

                    -taglet com.sun.tools.doclets.ToDoTaglet
                    -tagletpath /home/taglets
                    -tag return
                    -tag param
                    -tag todo
                    -tag throws
                    -tag see

                -taglet オプションを -tag オプションの代わりに使用することもできますが、 その結果、読みにくくなります。

                -tagletpath " tagletpathlist"
                    taglet クラスファイル (.class) を探すための検索パスを指定します。 tagletpathlist には、コロン (:) で 区切って複数のパスを含めることができます。 Javadoc ツールは、指定されたパス以下のすべての サブディレクトリを検索します。

                -subpackages " package1:package2:..."
                    指定されたパッケージ内のソースファイルから ドキュメントを生成し、再帰的にサブパッケージを処理します。 このオプションは、ソースコードに新しいサブパッケージを 追加するのを自動化するのに便利です。 各パッケージはトップレベルのパッケージ (java) または 完全修飾されたサブパッケージ (javax.swing) であり、 ソースファイルを含む必要はありません。 ワイルドカードは不要で、かつ許可されていません。 パッケージの検索場所を指定するには、 -sourcepath を使用します。 例を示します。

                    % javadoc -d docs -sourcepath /home/user/src \
                    		-subackages java:javax.swing

                このコマンドにより、java および javax.swing という名前のパッケージと、そのすべてのサブパッケージのドキュメントを生成します。

                また、サブパッケージを処理するとき、サブパッケージを 除外するためのオプションもあります。

                -exclude " packagename1:packagename2:..."
                    -subpackages で作成されたリストから、指定されたパッケージと そのサブパッケージを無条件で除外します。 それらのパッケージが前後の -subpackages オプションに含まれている場合でも、除外処理を行います。 例を示します。

                    % javadoc -sourcepath /home/user/src -sourcepath java\
                    		-exclude java.net:java.lang

                これは java.io 、 java.util 、 java.math を含みますが、 java.net および java.lang にルートをもつパッケージを除外します。 これによって java.lang.ref ( java.lang のサブパッケージ) が 除外されることに注意してください。

                -breakiterator
                    文のブレーク反復子を使って、 最初の文の終わりを判断できます。 次のメジャーリリースでは、最初の文の終点を判断する アルゴリズムを変更する予定です。 -breakiterator オプションはこの新しい アルゴリズムを使用します。 次回のメジャーリリースへの移行がスムーズに行えるよう、 バージョン 1.4 の実行時には常にこのオプションを 使用することをお勧めします。

                1.2 および 1.3 では、 java.text.BreakIterator クラスを使用して英語以外の全言語の 文の終点を判別していました。 そのため、-breakiterator オプションは英文でのみ有効です。 英文にはピリオドのあとに空白文字が来るという固有の アルゴリズムがあります。 -breakiterator を使用しないと、 最初の文の終点は 1.2 および 1.3 から変更されず、 差異がある場所を表示する警告が表示されます。

                アルゴリズムの違いにより、英語では次のようになります。

                •   古いアルゴリズム - ピリオドのあとの空白文字または 段落レベルの HTML タグ (<P>など) の位置で停止

                •   新しいアルゴリズム - 次の単語が大文字で始まる場合、 ピリオド、疑問符、感嘆符と空白文字の位置で停止。 このアルゴリズムでは、ほとんどの省略記号が 処理されます（「Serial no. is valid」は処理されるが、 「Mr. Smith」は処理されない）。 HTML タグや、 数字または記号で始まる文では停止しません。

                -docfilessubdirs
                    doc-files ディレクトリを、下の階層を含めてコピー できるようにします。 つまり、サブディレクトリとすべての コンテンツが、生成先ディレクトリに再帰的にコピーされます。 たとえば、 doc-files/example/images ディレクトリとその中のファイルがコピーされます。 サブディレクトリを除外するためのオプションもあります。

                -excludedocfilessubdirs " name1:name2:..."
                    doc-files のサブディレクトリで、指定された 名前のものを除外します。 このオプションを使用すると、 SCCS およびその他のソースコード管理の サブディレクトリをコピーしないようにできます。

                -noqualifier " all | packagename1:packagename2:..."
                    修飾パッケージ名を、出力のクラス名の前から削除します。 -noqualifier の引数は all (すべてのパッケージ修飾子を削除)、 またはコロンで区切られたパッケージリストの いずれかで、修飾子として削除されます。 ワイルドカードも使用できます。 パッケージ名はクラス名またはインタフェース名が 表示されたところから削除されます。

                次の例では、すべてのパッケージ修飾子を省略します。

                    -noqualifier all

                次の例では、パッケージ修飾子 java.lang および java.io を省略します。

                    -noqualifier java.lang:java.io

                次の例では、java および com.sun から 始まる (javax を除く) サブパッケージのパッケージ修飾子を削除します。

                    -noqualifier java.*:com.sun.*

                パッケージ修飾子が上記の動作に従って 表示される場合、1.3 での次の動作も有効であり、 さらに修飾子を削除します。 p.C クラスのページでは、 p パッケージに所属するクラスのパッケージ 修飾子を削除します。 この規則は、 -noqualifier が 使用されているかどうかにかかわらず存在します。

                -nocomment
                    記述およびすべてのタグを含むコメント 本文全体を抑制し、宣言だけを生成します。 このオプションにより、元は異なる目的のためだった ソースファイルを再利用し、 新しいプロジェクトのためのスケルトンを 作成できるようになりました。

  コマンド行引数ファイル
javadoc のコマンド行を短くしたり簡潔にしたりするために、 javadoc コマンドに対する引数 (-J オプションを除く) が 入った 1 つ以上のファイルを指定することができます。 このことを利用すれば、どのオペレーティングシステム 上でも、任意の長さの javadoc コマンドを作成できます。

引数ファイルには、Javadoc オプション、ソースファイル名、 およびパッケージ名を自由に組み合わせて記述できます。 また、Javadoc オプションに対する引数だけを記述してもかまいません。 ファイル内の各引数は、空白文字または改行で区切ります。 引数ファイル内のファイル名は、 現在のディレクトリから見た相対パスになります。 引数ファイルの位置から見た相対パスではありません。 引数ファイル内のファイル名リストでは、 ワイルドカード (*) は使用できません。 たとえば、*.java とは指定できません。 引数ファイル内の引数で @ 文字を使用して、 複数のファイルを再帰的に解釈することはサポートされていません。 また、-J オプションもサポートされていません。 このオプションは起動ツールに渡されますが、 起動ツールでは引数ファイルをサポートしていないからです。

javadoc を実行するときに、各引数ファイルのパスとファイル名の 先頭に @ 文字を付けて渡します。 javadoc は、@ 文字で始まる引数を見つけると、 そのファイルの内容を展開して引数リストに挿入します。

引数ファイルを 1 つ指定する例

argfile という名前の引数ファイルにすべての Javadoc 引数を格納し、次のように使用することができます。

    % javadoc @argfile

この引数ファイルには、次の例で示されている 2 つのファイルの内容を両方とも入れることができます。

引数ファイルを 2 つ指定する例

Javadoc オプション用に 1 つ、パッケージ名またはソースファイル名用に 1 つというように、2 つの引数ファイルを作成し、 次のようにして使用することができます。 なお、このあとのリストでは、行の継続文字を使用していません。

以下の内容を含む options という名前のファイルを作成します。

    -d docs-filelist
    -use
    -splitindex
    -windowtitle 'Java 2 Platform v1.3 API Specification'
    -doctitle 'Java<sup><font size="-2">TM</font></sup> 2\
    		Platform v1.4 API Specification'
    -header '<b>Java 2 Platform </b><br><font size="-1">v1.4</font>'
    -bottom 'Copyright 1993-2000 Sun Microsystems, Inc. All Rights Reserved.'
    -group "Core Packages" "java.*"
    -overview /java/pubs/ws/1.3/src/share/classes/overview-core.html
    -sourcepath /java/pubs/ws/1.3/src/share/classes

以下の内容を含む packages という名前のファイルを作成します。

    com.mypackage1
    com.mypackage2
    com.mypackage3

そのあと、次のコマンドを使用して javadoc を実行します。

    % javadoc @options @packages

パス付きの引数ファイルの例

引数ファイルには、パスを指定できます。 ただし、そのファイル内に指定されたファイル名は、 現在の作業ディレクトリから見た相対パスになります。 つまり、下の例の場合は、path1 や path2 から見た相対パスではありません。

    % javadoc @path1/options @path2/packages

オプションの引数の例

次に、javadoc オプションに対する引数だけを引数ファイルに 格納する例を示します。 ここでは、-bottom オプションを 例に取り上げます。そのオプションには、 かなり長い引数を指定することがあるからです。 まず、このオプションのテキスト引数になる 次のような内容を含む、bottom という名前の ファイルを作成します。

Submit a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>'

そのあと、次のようにして javadoc ツールを実行します。

    % javadoc -bottom @bottom @packages

また、引数ファイルの先頭に -bottom オプションを組み込んでおけば、 次のようにして実行できます。

    % javadoc @bottom @packages

RUNNING

  Javadoc の実行
バージョン番号 -

javadoc のバージョン番号は javadoc-J-version を使用することで確認できます。 標準ドックレットのバージョン番号は出力ストリームに 表示されます。 これは -quiet オプションでオフにできます。

プログラムから利用できる public インタフェース -

Java 言語で書かれたプログラム内から javadoc ツールを呼び出します。 このインタフェースは om.sun.tools.javadoc.Main (javadoc は再入) にあります。 詳細は、「標準ドックレット」 を参照してください。

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

  1 つ以上のパッケージのドキュメント化
パッケージをドキュメント化するには、その パッケージのソースファイル (*.java) が、パッケージと同じ名前を持つディレクトリ 内に存在していなければなりません。 パッケージ名が複数の識別子で構成されている (java.awt.color のように、各識別子はドットで 区切られている) 場合は、後続の各識別子が下位の サブディレクトリに対応して いなければなりません (java/awt/color など)。 1 つのパッケージのための複数のソースファイルを、 異なる場所にある 2 つのディレクトリツリーに分けて 格納することも可能です
 ( src1/java/awt/color と src2/java/awt/color など)。 ただし、その場合は、-sourcepath によって、 その両方の場所を指定しなければなりません。

javadoc を実行するには、cd コマンドを使って ディレクトリを変更するか、 または -sourcepath オプションを使用します。 それぞれの例を次に示します。

•   ケース 1 - 1 つ以上のパッケージからの起動を再帰的に実行 - この例では javadoc が任意のディレクトリから実行できるように、 -sourcepath を使用します。 これは、java のサブパッケージ ( java.net および java.lang をルートとするパッケージを除く) を処理します。 これによって java.lang.ref( java.lang のサブパッケージ) が 除外されることに注意してください。

    % javadoc -d /home/html -sourcepath /home/src\
    		-subpackages java -exclude java.net:java.lang

他のパッケージツリーを処理するには、 java:javax:org.xml.sax のように、その名前を -subpackages 引数に追加します。

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

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

•   ケース 3 ・任意のディレクトリから実行。ソースファイルは 1 つのディレクトリツリー内にある - このケースでは、現在のディレクトリがどこであってもかまいません。 トップレベルのパッケージの親ディレクトリを -sourcepath に指定し、ドキュメント化する 1 つ以上のパッケージ名を指定して、 javadoc を実行します。

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

•   ケース 4 ・任意のディレクトリから実行。ソースファイルは複数のディレクトリツリー内にある - これはケース 3 と似ていますが、パッケージが複数のディレクトリツリーに 存在します。 各ツリーのルートへのパスを -sourcepath に指定し (コロンで区切る)、ドキュメント化する 1 つ以上の パッケージ名を指定して、javadoc を実行します。 1 つのパッケージのすべてのソースファイルが、 1 つのルートディレクトリの下に存在しなければならない、 ということはありません。ソースパスとして指定された場所の どこかで見つかれば十分です。

    % javadoc -d /home/html -sourcepath\
            /home/src1:/home/src2 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 ツールを実行するために使う効果的なコマンドです。 ここでは 180M バイトのメモリを使用して、 Java 2 Platform, Standard Edition, v1.2 に 存在する、約 1500 個の public および protected クラスについてドキュメントを生成します。

同じ例を 2 回掲載します。最初の例はコマンド行から 実行するもので、2 番目の例は Makefile から 実行するものです。 オプションの引数に絶対パスを 使用しているため、任意のディレクトリからこの javadoc コマンドを実行できます。

  コマンド行の例
次のコマンド行の例は 900 文字を超えているため、 DOS などのシェルには大きすぎます。 この制限を回避するには、コマンド行 引数ファイルを使用します。 または、シェルスクリプトを記述します。

    example% javadoc -sourcepath /jdk/src/share/classes	.if n .ta 28n
    -overview /java/jdk/src/share/classes/overview.html -d /jdk/build/api	-use	-splitIndex	-windowtitle 'Java 2 Platform v1.2 API Specification' -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 \
    	Platform v1.2 API Specification ' -header '<b>Java 2 Platform </b><br><font size="-1">v1.2</font>' -bottom '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi"> \
    	Submit a bug or feature</a><br><br>Java is a trademark or registered \
    	trademark of Sun Microsystems,Inc. in the US and other countries.<br> \
    	Copyright 1993-1999 Sun Microsystems, Inc.
          901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. \
    	All Rights Reserved.</font>'
    -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" -group "Extension Packages" "javax.*" .if n .ta 37
    -J-Xmx180m	@packages

    上記のコマンドで、packages は、 処理対象のパッケージ名 ( java.applett java.langなど)が 入っているファイルの名前です。 各オプションの、 単一引用符で囲まれた引数の内側には、 改行文字を挿入できません。 たとえば、 この例をコピー＆ペーストする場合は、 -bottom オプションから改行文字を削除してください。 さらに、このあとの「注」も参照してください。

  Makefile の例
ここでは、GNU Makefile の例を示します。 Windows の Makefile の例については、 Windows の Makefile の作成方法を参照してください。

    example% javadoc -sourcepath /jdk/src/share/classes	/* Sets path for
    	source files  */
    -overview $ (SRCDIR)/overview.html /* Sets path for overview text */
    -d /jdk/build/api	/* Sets destination directory */
    -use	/* Adds "Use" files      */
    -splitIndex	/* Splits index A-Z      */
    -windowtitle $(WINDOWTITLE)	/* Adds a window title   */
    -doctitle $(DOCTITLE)	/* Adds a doc title      */
    -header $(HEADER)	/* Adds running header text       */
    -bottom $(BOTTOM)	/* Adds text at bottom            */
    -group $(GROUPCORE)	/* 1st subhead on overview page */
    -group $(GROUPEXT)	/* 2nd subhead on overview page  */
    -J-Xmx180m	/* Sets memory to 180MB     */
    java.lang java.lang.reflect	/* Sets packages to document  */
    java.util java.io java.net	java.applet
    WINDOWTITLE = 'Java 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-1998 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'

    Makefile の引数は、単一引用符で囲みます。

  注

•   -windowtitle オプションを省略すると、 Javadoc ツールによってドキュメントタイトルが ウィンドウタイトルにコピーされます。 -windowtitle のテキストは、基本的に -doctitle と同じです。ただし、HTML タグは使用しません。 HTML タグは、ウィンドウタイトルにそのままの テキストとして表示されてしまいます。

•   この例のように -footer オプションを省略すると、 Javadoc ツールによってヘッダテキストが フッタにコピーされます。

この例では必要ありませんが、
    -classpath および -link も重要なオプションです。

トラブルシューティング

  一般的なトラブルシューティング

•   Javadoc FAQ - よく問題となるバグや トラブルシューティングの ヒントは Javadoc FAQ にあります。

•   バグおよび制限事項 - また、バグの一部は、 「Important Bug Fixes and Changes」でも参照できます。

•   バージョン番号 - バージョン番号を参照してください。

•   有効なクラスだけをドキュメント化 - javadoc がパッケージをドキュメント化するとき、 有効なクラス名で構成されているファイルだけを 読み込むようになりました。 ファイル名にハイフン (-) などを含めることで、 javadoc がファイルを解析しないようにできます。

  エラーと警告
エラーメッセージおよび警告メッセージには、 ファイル名と宣言行に対する行番号が 含まれますが、doc コメントの特定の 行に対する行番号は含まれません。

•   "error: cannot read: Class1.java" - Javadoc ツールは現在のディレクトリの Class1.java クラスを読み込もうとしています。 クラス名は、絶対パスまたは相対パスで表示されます。 この場合、./Class1.java と同じです。

環境

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

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

関連項目

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

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

The Javadoc Home Page @
    http://java.sun.com/products/jdk/javadoc/index.html

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

Setting the Class Path

How Javac and Javadoc Find Classes