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

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

目次

リファレンスガイド 実行

リファレンスガイド

形式

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」という拡張子で終わり、その拡張子を除いた名前が実際に有効なクラス名であるすべてのファイルです (「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 ページを生成します。

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

注 - Javadoc ツールにパッケージ名を渡すと、現在のところ、指定したパッケージディレクトリにあるすべての .java クラスが処理されます。.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 言語仕様によると、抽象メソッドを含むクラスはそれ自体を抽象と宣言しなければなりません。 このエラーを検出すると、ｊavac コンパイラの場合は、このエラーで停止しますが、Javadoc ツールは警告を出さずに処理を進めます。 Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。 ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。

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

Javadoc のドックレット

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

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

  • Javadoc に施された機能強化 - Javadoc 1.4 で追加された改良点の詳細
  • Javadoc FAQ - 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法
  • Javadoc のドキュメンテーションを作成するには - Sun で一般的なドキュメンテーションコメントの記述方法の詳細
  • API 仕様を生成するための要件 - Java 2 プラットフォーム仕様を記述する際に使用された標準要件。 この情報は、ソースファイルのドキュメンテーションコメント形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも役立ちます。 検証可能なアサーションを満たすパッケージ、クラス、インタフェース、フィールド、およびメソッドについての要件を定めています。
  • ドキュメンテーションコメントの仕様 - ドキュメンテーションコメントのオリジナル仕様については、『Java Language Specification』 (James Gosling、Bill Joy、Guy Steele 共著) の初版の第 18 章「Documentation Comments」を参照してください。 この章は、第 2 版では削除されました。
  • DocCheck ドックレット - ソースファイル内の doc コメントを検査し、みつかったエラーや不規則な箇所を一覧にしたレポートを生成します。 これは Sun Doc チェックユーティリティの一部です。
  • MIF ドックレット - MIF、FrameMaker、および PDF 形式での API ドキュメンDの生成を自動化します。 MIF は Adobe FrameMaker の互換形式です。

用語

Javadoc ツールに関する文脈では、特定の意味を持つ用語がいくつかあります。
生成ドキュメント (generated document)
javadoc ツールが Java ソースコード内のドキュメンテーションコメントから生成したドキュメントのことです。 デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。

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

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

包含クラス (included classes)
対応するソースファイル名またはパッケージ名が 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 ツールは次の処理を行います。

  • <body> タグと </body> タグの間にあるすべての内容を処理のためにコピーする
  • パッケージタグがあれば、すべて処理する
  • 生成したパッケージの概要ページの最後に、処理したテキストを挿入する (例: パッケージの概要)
  • パッケージの概要ページの先頭に、パッケージコメントの最初の文をコピーする。 さらに、概要ページのパッケージリストに、パッケージ名とパッケージコメントの最初の文を追加する (例: 概要の要約)。 文の末尾は、クラスやメンバの説明の最初の文の末尾と同じ規則によって判断される

概要コメントファイル

ドキュメント化する各アプリケーションまたはパッケージセットは、独自の概要ドキュメンテーションコメントを持つことができ、それは専用の「ソース」ファイルに保持されます。その内容は、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 ツールによって生成先のディレクトリにコピーされる、その他の任意のファイルを含めることができます。 一般に、このようなファイルには、グラフィックファイル、サンプルの 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 ページは、個々のファイルに相当します。 以下の各 HTML「ページ」は、それぞれ別のファイルに対応します。 javadoc が生成するファイルの名前には、クラスやインタフェースの名前にちなんだものと、そうでないもの (package-summary.html など) の 2 種類があります。 後者のグループのファイル名には、前者のグループとファイル名が競合しないように、ハイフンが含まれています。

基本内容ページ

  • ドキュメント化するクラスまたはインタフェースごとに 1 つのクラスページまたはインタフェースページ (クラス名.html)
  • ドキュメント化するパッケージごとに 1 つのパッケージページ (package-summary.html)。 Javadoc ツールは、ソースツリーのパッケージディレクトリ内の package.html というファイルで提供されたHTML テキストを組み入れます。
  • パッケージセット全体に対して 1 つの概要ページ (overview-summary.html)。 これは、生成ドキュメントの先頭ページになります。 Javadoc ツールは、-overview オプションで指定されたファイルで提供された HTML テキストを組み入れます。 このページのファイルは、javadoc に複数のパッケージ名を渡した場合にだけ作成されます。 詳細は、「HTML フレーム」を参照してください。

相互参照ページ

  • パッケージのセット全体に対して 1 つのクラス階層ページ (overview-tree.html)。 このページを表示するには、ナビゲーションバーの [概要] をクリックしてから、[階層ツリー] をクリックします。
  • パッケージごとに 1 つのクラス階層ページ (package-tree.html)。特定のパッケージ、クラス、またはインタフェースのページを表示してから、[階層ツリー] をクリックすると、そのパッケージのクラス階層が表示されます。
  • パッケージごとに 1 つの [使用] ページ (package-use.html)と、クラスおよびインタフェースごとに 1 つずつの [使用] ページ (class-use/クラス名.html)。 このページには、特定のクラス、インタフェース、またはパッケージの一部を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。 クラスまたはインタフェース A を例にして考えると、その [使用] ページには、A のサブクラス、A として宣言されたフィールド、A を返すメソッド、A 型のパラメータを持つメソッドおよびコンストラクタが表示されます。このページを表示するには、まず、パッケージ、クラス、またはインタフェースのページに移動してから、ナビゲーションバーの [使用] リンクをクリックします。
  • 非推奨 API ページ (deprecated-list.html)。推奨されないすべての名前が一覧表示されます。 非推奨名は、一般に改良された API が存在するために使用が推奨されていない API の名前であり、通常、それに置き換わる名前が提示されています。 非推奨 API は、将来の実装では削除される可能性があります。
  • A定数フィールド値ページ (constant-values.html) 。static フィールドの値が表示されます。
  • 直列化された形式のページ (serialized-form.html)。直列化が可能なクラスと外部化が可能クラスについての情報が表示されます。 これらの各クラスには、直列化フィールドおよびメソッドに関する説明があります。 これらの情報は、API を使う開発者ではなく、再実装を行う開発者に必要な情報です。 ナビゲーションバーにこのページへのリンクはありませんが、直列化されたクラスに移動して、そのクラスの説明にある [関連項目] セクションで [直列化された形式] をクリックすると、この情報を取得できます。 標準ドックレットは、直列化された形式のページを自動的に生成します。 ここには、Serializable を実装する public または非 public のクラスが組み込まれており、さらに、readObject メソッド、writeObject メソッド、直列化されたフィールド、および @serial タグ、@serialField タグ、@serialData タグからのドキュメンテーションコメントが組み込まれています。 直列化が可能な public クラスを除外するには、そのクラスまたはそのクラスが属するパッケージを @serial exclude タグで指定します。直列化が可能な package private クラスを含めるには、そのクラスまたはそのクラスが属するパッケージを @serial include タグで指定します。 1.4 では、-private オプションを指定せずに javadoc を実行することで、public クラスおよび private クラスに完全な直列化形式を生成することができます。
  • 索引 (index-*.html)。すべてのクラス名、インタフェース名、コンストラクタ名、フィールド名、およびメソッド名が、アルファベット順に並んでいます。 索引は、Unicode を扱えるように国際化されています。1 つのファイルとして生成することも、先頭文字 (英語の場合 A 〜 Z) ごとに別々のファイルとして生成することもできます。

サポートファイル

  • ヘルプページ (help-doc.html)。ナビゲーションバーや前述の各ページに関する説明が記載されています。 -helpfile を使うと、デフォルトのヘルプファイルに代わる独自のカスタムヘルプファイルを提供することもできます。
  • 表示用の HTML フレームを作成する 1 つの index.html ファイル。 このファイルは、フレーム付きの先頭ページを表示する場合にロードします。 このファイル自体には、テキスト内容は含まれていません。
  • 複数のフレームファイル (*-frame.html)。パッケージ、クラス、およびインタフェースのリストが含まれています。HTML フレームを表示するときに使用されます。
  • パッケージリストファイル (package-list)。-link オプションおよび -linkoffline オプションで使用されます。 これは、HTML ファイルではなくテキストファイルであり、どのリンクからもアクセスできません。
  • スタイルシートファイル (stylesheet.css)。生成されるページ上のいくつかの要素について、色、フォントファミリ、フォントサイズ、フォントのスタイル、および配置を制御します。
  • doc-files ディレクトリ。生成先ディレクトリにコピーするイメージ、サンプルコード、ソースコードなどのファイルがすべて格納されます。 これらのファイルは、Javadoc ツールによって処理されないため、ファイル内に ｊavadoc タグがあっても無視されます。 このディレクトリは、ソースツリーの中にある場合にのみ生成されます。

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 インタフェースを使用するページ
   src-html                         ソースコードディレクトリ
       java                             パッケージディレクトリ
           applet                       サブパッケージディレクトリ
                Applet.html         アプレットソースコードのページ
                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 コメント) を記述することができます。 各パッケージにドキュメンテーションコメントを作成できます。構文は若干異なりますが、概要にもドキュメンテーションコメントを作成できます。 ドキュメンテーションコメントは、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 is a doc comment.
 * @see java.lang.Object
 */
スタンドアロンタグとインラインタグ - 「タグ」は、Javadoc ツールが処理できる、ドキュメンテーションコメント内の特別なキーワードです。 Javadoc ツールには、スタンドアロンタグ (@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 ページの最初にあるメンバの概要の部分にコピーされます。 文の区切りの判別する方法を将来のリリースでどのように変更されるかについては、-breakiterator を参照してください。

複数フィールドの宣言 - 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 ツールには、クラスおよびインタフェース内のメソッドのコメントを自動的に再利用する、つまり「継承」する機能があります。 メソッドコメントに記述や@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 以外のクラスである (インタフェースではない) 場合は、次のように処理する
    1. スーパークラスにこのメソッドについてのドキュメンテーションコメントが記述されていれば、そのコメントを採用する
    2. 手順 3a でドキュメンテーションコメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を適用する

ｊavadoc タグ

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

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

  • スタンドアロンタグ - 説明に続くタグセクション内にのみ記述可能。 中括弧で区切らない (@tag)
  • インラインタグ - コメントの説明内またはスタンドアロンタグの任意の場所に記述可能。 中括弧で区切られる ({@tag}
今後のリリースで導入されるタグについては、「Proposed Javadoc Tags」を参照してください。

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

タグ 導入された JDK/SDK のバージョン
@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 を書き込みます。 1 つのドキュメンテーションコメントに複数の @author タグを含めることができます。 1 つの @author タグに 1 つの名前を指定することも、1 つのタグに複数の名前を指定することもできます。 前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (,) とスペースが挿入されます。 後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。 したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。

@deprecated  deprecated-text
この API は動作し続けますが、この 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} タグは、コマンド行からも、ドキュメンテーションコメントの中でも使用できます。

  1. コマンド行では、ヘッダ、フッタ、または下部テキストは次のように定義します。 
       javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
    注 - Makefile の中で {@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">      (java/lang/Object.java の場合)
および 
  <a href="../../../copyright.html">   (java/lang/ref/Reference.java の場合)

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

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

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

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

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

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

1 つの文の中で使用できる {@link} タグの数に制限はありません。 このタグは、ドキュメンテーションコメントの説明部分、または @deprecated、@return、@param などの任意のタグのテキスト部分で使うことができます。

たとえば、次のコメントでは、getComponentAt(int, int) メソッドを参照しています。 

      {@link #getComponentAt(int, int) getComponentAt} メソッドを使用します。
標準ドックレットでは、上記のコメントから次の HTML が生成されます (このコメントが同じパッケージの別のクラスを参照している場合)。 
      <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> メソッドを使用します。
この HTML は、Web ページ上では次のように表示されます。 
      getComponentAt メソッドを使用します。
{@link} を、ドキュメント化の対象にしていないクラスにまで拡張するには、-link オプションを使用します。

{@linkplain  package.class#member  label}
リンクのラベルがコードフォントではなくプレーンテキストで表示されている点以外は、{@link} と同じです。 ラベルがプレーンテキストで記述されている場合に便利です。次の例を参照してください。 例: 
     Refer to {@linkplain add() the overridden method}
これは以下のように表示されます。
Refer to the overridden method.
@param  parameter-name description
[パラメータ] セクションにパラメータを追加します。 説明は、次の行に続けて記述してもかまいません。

@return description
[戻り値] セクションを追加して、description のテキストを書き込みます。 このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。

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

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

バージョン 1.2 だけは、名前だけが HTML の <code> タグで自動的に囲まれて表示され、ラベルはそのタグで囲まれません。バージョン 1.2.2 以降では、ラベルを使用するかどうかにかかわらず、表示テキストは常に <code> で囲まれて表示されます。

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

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

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

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

 /**
  * @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 package.class#member の一般的な形式
現在のクラスのメンバを参照する
@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 ツールは、現在のクラスの階層だけを検索します。 つまり、現在のクラスかインタフェース、そのスーパークラスかスーパーインタフェース、または現在のクラスかインタフェースを囲んでいるクラスかインタフェースからメンバを検索します (このあとの検索手順 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() メソッドに、同じクラスのメンバへの参照とほかのクラスのメンバへの参照が含まれている場合、クラス名が表示されるのは後者のケースだけです (次の表を参照)。

参照の種類 例 表示される名前
@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
デフォルトの直列化可能フィールドのドキュメンテーションコメントで使用します。

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 も参照してください。「-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 メソッドのドキュメンテーションコメントで使用できます。

@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 つのドキュメンテーションコメントに含めることのできる @version タグは、1 つまでです。 バージョンとは、通常、このクラスまたはメンバを含むソフトウェア (Java 2 SDK など) のバージョンのことです。


タグを使用できる場所

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


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

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

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

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

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

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

パッケージタグ
@see
@since
@deprecated
@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;

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

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

メソッドおよびコンストラクタタグ
@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
-link
-linkoffline
-linksource
-locale
-nocomment
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-noqualifier
-nosince
-notree
-overview
-package
 -private
-protected
-public
-quiet
-serialwarn
-source
-sourcepath
-splitindex
-stylesheetfile
-subpackages
-tag
-taglet
-tagletpath
-title
-use
-verbose
-version
-windowtitle

Javadoc オプション

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

filename と path には、それぞれ任意の名前と場所を指定できますが、通常は、overview.html という名前を付けて、ソースツリー内の最上位のパッケージディレクトリがあるディレクトリに配置します。 この場所に配置すると、-sourcepath によってこのファイルが指し示されるので、パッケージをドキュメント化する際に path が不要になります。 たとえば、java.lang パッケージのソースツリーが /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

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

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

   -docletpath /home/user/mifdoclet/lib/mifdoclet.jar
ドックレット開始クラスファイルのパスの例 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 ファイルを検索するには、そのファイルのあるディレクトリに 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 を使ってユーザクラスを検索する方法についての詳細は、「クラスの検索方法」を参照してください。

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

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

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

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

-locale  language_country_variant
重要 - -locale オプションは、標準ドックレットが提供するすべてのオプション、またはその他の任意のドックレットの提供するすべてのオプションより前 (左側) に指定する必要があります。 そうしないと、ナビゲーションバーが英語で表示されます。 このコマンド行オプションだけは、指定する順序に依存します。
Javadoc がドキュメントを生成するときに使うロケールを指定します。 引数には、java.util.Locale のドキュメントで説明されているロケールの名前を指定します。たとえば、en_US (英語、米国)、en_US_WIN (Windows で使われる英語) などを指定します。

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

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

-Jflag
javadoc を実行する実行時システム java に、flag を直接渡します。 J と flag の間に空白を入れてはなりません。 たとえば、生成ドキュメントを処理するためにシステムで 32M バイトのメモリを確保しておく必要がある場合は、Java の -Xmx オプションを次のように呼び出します。-Xms は、省略可能です。これは、初期メモリのサイズを設定するだけのオプションで、必要なメモリの最小サイズがわかっている場合に便利です。 
   % javadoc -J-Xmx32m -J-Xms32m com.mypackage
使用している javadoc のバージョンを確認するには、次のように java の「-version」オプションを呼び出します。 

   % 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/ ディレクトリに保存します。 

  % 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 ツールのバージョンを確認するには、-J-version オプションを使用します。

-author
生成ドキュメントに、@author のテキストを組み込みます。

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

-windowtitle  title
HTML の <title> タグに配置するタイトルを指定します。 指定したタイトルは、ウィンドウのタイトルや、このページに対して作成されたブラウザのブックマーク (お気に入り) に表示されます。 このタイトルには HTML タグを含めないでください。タイトルに HTML タグが含まれていると、ブラウザがタグを正しく解釈できません。 title の中で引用符を使う場合は、引用符をエスケープする必要があります。 -windowtitle が省略されている場合、Javadoc ツールは、このオプションの代わりに -doctitle の値を使います。 

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

  % javadoc -doctitle "Java<sup><font size=¥"-2¥">TM</font></sup>" com.mypackage
-title  title
このオプションは、現在は存在しません。Javadoc 1.2 のベータ版にだけ存在しました。 このオプションは、-doctitle という名前に変更されました。 名前を変更した理由は、このオプションが、ウィンドウのタイトルではなくドキュメントのタイトルを定義することを明確にするためです。

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

  % javadoc -header "<b>Java 2 Platform </b><br>v1.4" com.mypackage

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

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

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

  • extdocURL は、javaoc によって生成され、リンク先として指定する外部ドキュメントがあるディレクトリの絶対 URL または相対 URL です。 あとで例を示します。 このディレクトリ内にpackage-list ファイルは存在していなければなりません。存在しない場合は、-linkoffline を使用します。 Javadoc ツールは package-list ファイルからパッケージ名を読み取り、それを URL のパッケージにリンクします。 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 に接続し、読み取りを行うことがシェルによっ許可されていない場合)。 このような状況は、リンク先のドキュメントがファイアウォールの向こう側にある場合に発生します。

外部 docs への絶対リンクを使用例 - java.lang、java.io、および他の Java 2 Platform パッケージ (http://java.sun.com/j2se/1.4/docs/api) にリンクしたい場合があります。次のコマンドは、com.mypackageパッケージのドキュメントと Java 2 ぷラットフォームパッケージへのリンクを生成します。 生成されたドキュメントには、たとえばクラスツリー内の 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 パッケージドキュメントはすでに生成され、docs が現在のディレクトリ内にある場合、次のように実行することで、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 つのパッケージ群の間にクロスリンクを作成できます。

参照クラスのバグ修正 - 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 2 Platform v1.4 API のパッケージリストは http://java.sun.com/j2se/1.4/docs/api/package-list にあり、次のような内容で始まっています。 

  java.applet
  java.awt
  java.awt.color
  java.awt.datatransfer
  java.awt.dnd
  java.awt.event
  java.awt.font
  など ...

-link オプションを指定せずに javadoc を実行した場合、ドキュメントの生成時に外部参照クラスに属する名前を見つけると、javadoc はその名前をリンクを持たない形で出力します。 一方、-link オプションを指定した場合は、指定した extdocURL にある package-list ファイルから該当するパッケージ名が検索されます。 パッケージ名が見つかると、その extdocURL が名前の前に付加されます。

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

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

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

   % 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 番目のドキュメントとその外部リンクを生成します。 必要な外部の package-list ファイルが存在しない場合、Javadoc ツールは警告を表示します。

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

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

さらに、もう1 つの用途として、ドキュメントを更新するための「ハッキング」としての使用も可能です。 パッケージのセット全体に対して javadoc を実行したあと、変更した一部のパッケージだけに対して javadoc を実行します。こうして、更新されたファイルを、オリジナルのファイルセットに挿入できるようにします。 例をあとで示します。

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

  • extdocURL は、javaoc によって生成され、リンク先として指定する外部ドキュメントがあるディレクトリの絶対 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 Platform パッケージ (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 プラットフォーム API へのリンクを含む、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 つずつ指定します。次の例では、わかりやすくするためにオプションごとに行を分けています。

% javadoc -linkoffline extdocURL1 packagelistLoc1 ¥
          -linkoffline extdocURL2 packagelistLoc2 ¥
          ...

ドキュメントの更新 - 前述の -linkoffline オプションのもう 1 つの用途は、プロジェクトに大量のパッケージが含まれていて、すでにツリー全体に対して javadoc の実行が完了している場合に、次の実行では、少量の変更を手早く加えたあと、ソースツリーのごく一部に対してだけ javadoc を再実行する場合に便利です。 これは、ドキュメンテーションコメントに対してだけ変更を加え、宣言は変更しない場合にのみ正しく処理されるので、ハッキングのようなものです。 ソースコードの宣言を追加、削除、または変更した場合は、索引、パッケージツリー、継承されるメンバのリスト、[使用] ページなどの場所で、リンクが壊れることがあります。

まず、この一部に対する実行で新しい生成先ディレクトリを作成します (更新という)。 元の生成先ディレクトリ名は html とします。 もっとも簡単な例として、html の親 (上位) ディレクトリに移動します。 現在のディレクトリ「.」に、-linkoffline の最初の引数を設定します。次に、2 番目の引数を html への相対パスに設定します。この引数は、元のディレクトリでみつかった package-list を、更新するパッケージのパッケージ名でのみ渡します。 

  % javadoc -d update -linkoffline . html com.mypackage
Javadoc ツールの終了後、update/com/package 内の生成されたクラスのページをコピーし (概要や索引を除く)、html/com/package 内の元のファイルに上書きします。

-linksource 
各ソースファイル (行番号付き) の HTML バージョンを作成し、標準の HTML ドキュメントからのリンクを追加します。 リンクは、ソースファイルで宣言されているクラス、インタフェース、コンストラクタ、メソッド、フィールドについて作成されます。 それ以外の場合は、リンクは作成されません (デフォルトのコンストラクタや生成されたクラスなど)。

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

各リンクは宣言で使用された識別子が名前として表示されます。 たとえば、Button クラスのソースコードへのリンクは、Button となります。 

    public class Button
    extends Component
    implements Accessible
そして、Button クラスの getLabel() メソッドのソースコードへのリンクは、getLabel となります。 
    public String getLabel()

-group  groupheading  packagepattern:packagepattern:...
概要ページの複数のパッケージを、指定したグループに分けて、グループごとに表を作成します。 各グループは、それぞれ別の -group オプションで指定します。 これらのグループは、コマンド行で指定した順序でページに表示されます。各グループ内では、パッケージがアルファベット順に並べられます。 指定した -group オプションごとに、packagepattern 式のリストと一致するパッケージが、見出し groupheading を持つ 1 つの表にまとめて表示されます。

  • groupheading には、任意のテキストを指定でき、空白を含めることができます。 指定したテキストは、グループの表見出しになります。

  • packagepattern には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (*) を指定できます。 アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。 ワイルドカードとして指定できるのは、アスタリスクだけです。 1 つのグループには、コロン (:) で区切って複数のパターンを含めることができます。
注: パターンやパターンリスト内でアスタリスクを使う場合は、"java.lang*:java.util" のように、パターンリストを引用符で囲む必要があります。

-group オプションが指定されていない場合は、すべてのパッケージが、「パッケージ」という見出しの 1 つのグループに入れられます。 ドキュメント化されるパッケージの中に、指定したグループのどのグループにも入らないパッケージがある場合、このようなパッケージは「その他のパッケージ」という見出しを持つ独立したグループに入れられます。

たとえば、次のようにオプションを指定すると、ドキュメント化される 5 つのパッケージは、コアパッケージ、拡張機能パッケージ、およびその他のパッケージに分けられます。 「java.lang*」では、最後のドットを指定していないことに注目してください。「java.lang.*」のようにドットを入れると、java.lang パッケージは除外されることになります。 

  %  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
その他のパッケージ
java.new

-nodeprecated
非推奨 API をドキュメントに生成しないようにします。 このオプションを指定すると、-nodeprecatedlist オプションを指定した場合と同じ効果があることに加えて、ドキュメントのほかの部分全体でも、非推奨 API が生成されません。 このオプションは、コードを記述しているとき、非推奨コードに気を取られたくない場合に便利です。

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

-nosince
生成ドキュメントから、@since タグに対応する「導入されたバージョン」 セクションを省略します。

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

-noindex
生成ドキュメントから、索引を省略します。 デフォルトでは、索引が生成されます。

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

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

-helpfile  path/filename
上部と下部のナビゲーションバーの [ヘルプ] リンクのリンク先となる代替ヘルプファイル path/filename のパスを指定します。 このオプションが指定されていない場合、Javadoc ツールは、Javadoc ツールに固定的に組み込まれているヘルプファイル help-doc.html を自動的に作成します。 このオプションを使うと、そのデフォルトの動作をオーバーライドできます。 filename にはどんなファイル名でも指定でき、help-doc.html には限定されません。Javadoc ツールは、このオプションでの指定に従って、ナビゲーションバーにあるリンクに調整を加えます。 例を示します。 
  % javadoc -helpfile /home/user/myhelp.html java.awt
-stylesheetfile  path/filename
代替 HTML スタイルシートファイルのパスを指定します。 このオプションが指定されていない場合、Javadoc ツールは、Javadoc ツールに固定的に組み込まれているスタイルシートファイル stylesheet.css を自動的に作成します。 このオプションを使うと、そのデフォルトの動作をオーバーライドできます。 filename にはどんなファイル名でも指定でき、stylesheet.css には限定されません。 例を示します。 
  % javadoc -stylesheetfile /home/user/mystylesheet.css com.mypackage
-serialwarn
@serial タグがない場合は、コンパイル時に警告を生成します。 デフォルトでは、Javadoc 1.2.2 以降のバージョンは、直列化の警告は生成されません (1.2.2 より前の初期バージョンでは、警告が生成されます。) このオプションを使用すると、直列化の警告が表示されるので、デフォルトの直列化可能フィールドと writeExternal メソッドを適切にドキュメント化するのに役立ちます。

-charset  name
このドキュメント用の HTML 文字セットを指定します。 例を示します。 
  % javadoc -charset "iso-8859-1" mypackage
上のコマンドでは、生成されるすべてのページの先頭に、次の行が挿入されます。 
   <META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
この META タグについては、HTML の規格 (4197265 および 4137321) を参照してください。

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

-source  1.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 が doc コメントを解析する際に、検出されたタグのうち、標準タグでも、-tag や -taglet で渡されるタグでもないものは、そのタグを不明なタグとして認識し、警告がスローされます。

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

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

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

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

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

タグレットで指定できるのは、タグが表示される場所と形式だけです。 他の決定はすべてドックレットによって行います。 したがって、タグレットは「含まれるクラスのリストからクラス名を削除する」といったことはできません。 ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガするなどの副作用は得られます。

タグレットへのパスを指定するには、 -tagletpath オプションを使用します。 生成されたページの「パラメータ」と「例外」の間に「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) を探すための検索パスを指定します。 telepathist には、コロン (:) で区切って複数のパスを含めることができます。 Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。

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

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

-exclude  packagename1:packagename2:...
-subpackages で作成されたリストから、指定されたパッケージとそのサブパッケージを無条件で除外します。 それらのパッケージが前後の -subpackages オプションに含まれてしまう場合でも、除外処理を行います。 例を示します。 
  % javadoc -sourcepath /home/user/src -subpackages 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 ディレクトリとその中のファイルがコピーされます。 サブディレクトリを除外するためのオプションもあります。

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

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

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

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

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

    -noqualifier java.*:com.sun.*
パッケージ修飾子が上記の動作にしたがって表示される場合、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 という名前のファイルを作成します。 

'<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit a
bug or feature</a><br><br>Java is a trademark or registered trademark of
Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-2000 Sun
Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.
All Rights Reserved.</font>'
そのあと、次のようにして javadoc ツールを実行します。 
  % javadoc -bottom @bottom @packages
また、引数ファイルの先頭に -bottom オプションを組み込んでおけば、次のようにして実行できます。 
  % javadoc @bottom @packages

実行


Javadoc の実行

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

プログラムから利用できる public インタフェース - Java 言語で書かれたプログラム内から Javadoc ツールを呼び出します。 このインタフェースは com.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 を実行します。 
      % cd /home/src/
  % 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 つ以上のクラスのドキュメント化

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

  • ケース 1 - ソースディレクトリに移る - .java ファイルのあるディレクトリに移ります。 次に、ドキュメント化する 1 つ以上のソースファイルの名前を指定して javadoc を実行します。 
      % cd /home/src/java/awt
  % javadoc -d /home/html Button.java Canvas.java Graphics*.java
    この例では、Button と Canvas クラス、および名前が Graphics で始まるクラスについて、HTML 形式のドキュメントが生成されます。 パッケージ名ではなくソースファイルが javadoc に引数として渡されているので、ドキュメントは、クラスのリストとメインページという 2 つのフレームを持つことになります。

  • ケース 2 - パッケージのルートディレクトリに移る - これは、同じルート内にある複数のサブパッケージの個々のソースファイルをドキュメント化する場合に便利です。 パッケージのルートディレクトリに移り、各ソースファイルを、ルートからのパスとともに指定します。 
      % cd /home/src/
  % javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
    この例では、Button クラスおよび Applet クラスについて、HTML 形式のドキュメントが生成されます。

  • ケース 3 - 任意のディレクトリから - このケースでは、現在のディレクトリがどこであってもかまいません。 ドキュメント化する .java ファイルへの絶対パス (または、現在のディレクトリからの相対パス) を指定して javadoc を実行します。 
      % javadoc -d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java
    この例では、Button クラスと、名前が Graphics で始まるクラスについて、HTML 形式のドキュメントが生成されます。

パッケージとクラスのドキュメント化

パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。 次に前述の 2 つの例を組み合わせた例を示します。 sourcepath は、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。 
  % javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java
この例では、java.awt パッケージと、Applet クラスについて、HTML 形式のドキュメントが生成されます。 javadoc ツールは、Applet のパッケージ名を、Applet.java ソースファイル内のパッケージ宣言 (その宣言がある場合) から判別します。

使用例

Javadoc ツールには多くの便利なオプションがあり、その中にはほかのオプションよりも頻繁に使われるものがあります。 ここで紹介するのは、Java プラットフォーム API に対して javadoc ツールを実行するときに使用する実際のコマンドです。 Java 2 Platform, Standard Edition, v1.2 に存在する、約 1500 個の public および protected クラスに対してドキュメントを生成するために、180M バイトのメモリを使用しました。

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

コマンド行の例

次のコマンド行の例は 900 文字を超えているため、DOS などのシェルには大きすぎます。 この制限を回避するには、コマンド行引数ファイルを使用します。または、シェルスクリプトを記述します。 
% javadoc -sourcepath /java/jdk/src/share/classes            ¥
    -overview /java/jdk/src/share/classes/overview.html      ¥
    -d /java/jdk/build/api                                   ¥
    -use                                                     ¥
    -splitIndex                                              ¥
    -windowtitle 'Java 2 Platform v1.2 API Specification'    ¥
    -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform v1.2 API Specification' ¥
    -header '<b>Java 2 Platform </b><br><font size="-1">v1.2</font>' ¥
    -bottom '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit
a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems,
Inc. in the US and other countries.<br>Copyright 1993-1999 Sun Microsystems, Inc.
901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' ¥
    -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" ¥
    -group "Extension Packages" "javax.*"                    ¥
    -J-Xmx180m                                               ¥
    @packages
上記のコマンドで、packages は、処理対象のパッケージ名 (java.applet java.lang など) が入っているファイルの名前です。 各オプションの、単一引用符で囲まれた引数の内側には、改行文字を挿入できません。 たとえば、この例をコピー＆ペーストする場合は、-bottom オプションから改行文字を削除してください。 さらに、このあとの「注」も参照してください。

Makefile の例

ここでは、GNU Makefile の例を示します。 Windows の Makefile の例については、Windows の Makefile の作成方法を参照してください。 
javadoc -sourcepath $(SRCDIR)              ¥   /* Sets path for source files     */
        -overview $(SRCDIR)/overview.html  ¥   /* Sets file for overview text    */
        -d /java/jdk/build/api             ¥   /* Sets destination directory     */
        -use                               ¥   /* Adds "Use" files               */
        -splitIndex                        ¥   /* Splits index A-Z               */
        -windowtitle $(WINDOWTITLE)        ¥   /* Adds a window title            */
        -doctitle $(DOCTITLE)              ¥   /* Adds a doc title               */
        -header $(HEADER)                  ¥   /* Adds running header text       */
        -bottom $(BOTTOM)                  ¥   /* Adds text at bottom            */
        -group $(GROUPCORE)                ¥   /* 1st subhead on overview page   */
        -group $(GROUPEXT)                 ¥   /* 2nd subhead on overview page   */
        -J-Xmx180m                         ¥   /* Sets memory to 180MB           */
        java.lang java.lang.reflect        ¥   /* Sets packages to document      */
        java.util java.io java.net         ¥
        java.applet

WINDOWTITLE = 'Java 2 Platform v1.2 API Specification'
DOCTITLE = 'Java<sup><font size="-2">TM</font></sup> 2 Platform v1.2 API Specification'
HEADER = '<b>Java 2 Platform </b><br><font size="-1">v1.2</font>'
BOTTOM = '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit
    a bug or feature</a><br><br>Java is a trademark or registered trademark
    of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-1999
    Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.
    All Rights Reserved.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
GROUPEXT  = '"Extension Packages" "javax.*"'
SRCDIR = '/java/jdk/1.2/src/share/classes'

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

注

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

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

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

トラブルシューティング

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

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

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

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

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

エラーと警告

エラーメッセージおよび警告メッセージには、ファイル名、宣言行に対する行番号が含まれますが、doc コメントの特定の行に対する行番号は含まれません。
  • "エラー: Class1.java を読み込めません" - Javadoc ツールは現在のディレクトリの Class1.java クラスを読み込もうとしています。 クラス名は、絶対パスまたは相対パスで表示されます。この場合、./Class1.java と同じです。

環境

CLASSPATH
Javadoc がユーザクラスのファイルを探すときに使うパスを指定する環境変数です。 この環境変数は、-classpath オプションによってオーバーライドされます。 ディレクトリは、次のようにコロンで区切ります。 
.:/home/classes:/usr/local/java/classes

関連項目

コメントの送付先: javadoc-tool@sun.com

JavadocTM は、Sun Microsystems, Inc の商標です (javadoc コマンド自体には商標シンボルは不要)。

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java ソフトウェア