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

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

目次

• 概要
• 説明
  • ソースファイルの処理
  • Javadoc のドックレット
  • 関連ドキュメント
  • 用語
• ソースファイル
  • クラスソースコードファイル
  • パッケージコメントファイル
  • 概要コメントファイル
  • その他の未処理のファイル
  • テスト用ファイルとテンプレートファイル
• 生成されるファイル
  • 生成される API 宣言
• ドキュメンテーションコメント
  • ソースコードへのコメントの挿入
  • メソッドコメントの自動コピー
• ｊavadoc タグ (@tag)
  • タグを使用できる場所
• オプション (-option)
  • Javadoc オプション
  • 標準ドックレットが提供するオプション
• コマンド行引数ファイル

• Javadoc の実行
• 簡単な例
  • 1 つ以上のパッケージのドキュメント化
  • 1 つ以上のクラスのドキュメント化
  • パッケージとクラスのドキュメント化
• 使用例
  • コマンド行の例
  • Makefile の例
• トラブルシューティング
  • 一般的なトラブルシューティング
  • エラーと警告
• 環境
  • CLASSPATH
• トラブルシューティング
• 関連項目

リファレンスガイド

形式

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

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

options

このドキュメントで説明されているコマンド行オプションです。Javadoc オプションの標準的な使用法については、「使用例」を参照してください。

packagenames

スペースで区切られた一連のパッケージ名です。たとえば、java.lang java.lang.reflect java.awt のように指定します。ドキュメント化するパッケージを個別に指定する必要があります。ワイルドカードは使用できません。回帰には -subpackages を使用します。Javadoc ツールは、-sourcepath を使ってこれらのパッケージ名を検索します。「1 つ以上のパッケージのドキュメント化」の例を参照してください。

sourcefilenames

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

-subpackages pkg1:pkg2:...

ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。パッケージ名またはソース ファイル名を指定する必要はありません。

@argfiles

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

説明

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

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

ソースファイルの処理

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

• 名前から .java の接尾辞を取り除くと、実際に有効なクラス名になっている (有効な文字については、「Identifiers」を 参照)
• ソースツリーのルートから相対的なディレクトリパスが、区切り文字をドットに変換すると、実際に有効なパッケージ名になっている
• パッケージ文には有効なパッケージ名が含まれる (前項目で指定)

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

• 宣言 (戻り値の型、引数の型、フィールドの型)
• @see タグから生成された「関連項目」セクション
• {@link} タグから生成されたインラインテキスト
• @throws タグから生成された例外の名前
• インタフェースのメンバに対する「定義」リンクと、クラスのメン バに対する「オーバーライド」リンク
• パッケージ、クラス、およびメンバを列挙している概要テーブル
• パッケージおよびクラスの継承ツリー
• 索引

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

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

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

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

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

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

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

Javadoc のドックレット

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

• Javadoc のドックレット
• -doclet コマンド行オプション

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

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

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

用語

「ドキュメンテーションコメント」、「doc コメント」、「主説明」、「タグ」、「ブロックタグ」、および「インラインタグ」の用語については、「ドキュメンテーションコメント」 で説明します。以下のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。

生成ドキュメント (generated document)

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

名前

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

ドキュメント化されるクラス (documented classes)

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

包含クラス

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

除外クラス (excluded classes)

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

参照クラス (referenced classes)

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

外部参照クラス (external referenced classes)

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

ソースファイル

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

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

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

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

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

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

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

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

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

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

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

    com/package1/test-files/

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

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

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

生成されるファイル

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

基本内容ページ

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

相互参照ページ

• パッケージのセット全体に対して 1 つのクラス階層ページ (overview-tree.html)。 このページを表示するには、ナビゲーションバーの「概要」をクリックしてから、「階層ツリー」をクリックします。
• パッケージごとに 1 つのクラス階層ページ (package-tree.html)。特定 のパッケージ、クラス、またはインタフェースのページを表示してから、「階層ツリー」をクリックすると、そのパッケージのクラス階層が表示されます。
• パッケージごとに 1 つの「使用」ページ (package-use.html)と、ク ラスおよびインタフェースごとに 1 つずつの「使用」ページ (class-use/classname.html)。 このページには、特定のクラス、インタフェース、またはパッケージの一部を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドに ついて記述されます。クラスまたはインタフェース A を例にして考えると、その「使用」ページには、A のサブクラス、A として宣言されたフィールド、A を返すメソッド、A 型のパラメータを持つメソッドおよびコンストラクタが表示されます。このページを表示するには、まず、パッケージ、クラス、またはインタフェースのページ に移動してから、ナビゲーションバーの「使用」リンクをクリックします。
• 非推奨 API ページ (deprecated-list.html)。推奨されないすべて の名前が一覧表示されます。非推奨名は、一般に改良された API が存在するために使用が推奨されていない API の名前であり、通常、それに置き換わる名前が提示されています。非推奨 API は、将来の実装では削除される可能性があります。
• 定数フィールド値ページ (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 フレームを生成します。パッケージが 1 つだけまたはパッケージがない場合には、パッケージのリストを省略することによって、最低限必要な数のフレームを作成します。つまり、単一のパッケージに 所属する単一のパッケージ名またはソースファイル (*.java) を引数として javadoc コマンドに渡した場合は、左側にクラスを一覧表示するフレーム (C) が 1 つだけ作成されます。Javadoc に複数のパッケージ名を渡した場合は、概要ページ (Detail) に加えて、すべてのパッケージを一覧表示する第 3 のフレーム (P) が作成されます。この概要ページのファイル名は、overview-summary.html です。したがって、このファイルは、2 つ以上のパッケージ名を渡した場合にだけ作成されます。「フレームなし」リンクをクリックするか、overview-summary.html を最初に表示すると、フレームを省略できます。

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

              ------------                  ------------
              |C| Detail |                  |P| Detail |
              | |        |                  | |        |
              | |        |                  |-|        |
              | |        |                  |C|        |
              | |        |                  | |        |
              | |        |                  | |        |
              ------------                  ------------
             javadoc *.java           javadoc java.lang java.awt

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

• 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         Applet ソースコードのページ
                AppletContext.html  AppletContext ソースコードのページ
                AppletStub.html     AppletStub ソースコードのページ
                AudioClip.html      AudioClip ソースコードのページ

生成される API 宣言

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

public final class Boolean
extends Object
implements Serializable

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

public static Boolean valueOf(String s)

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

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

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

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

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

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

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

次のようにして 1 行に記述すると、スペースを節約できます。

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

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

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

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

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

    public class Whatever {
    }

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

/**
 * This sentence would hold the main description for this doc comment.
 * @see java.lang.Object
 */

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

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

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

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

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

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

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

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

上記のコードからは、次のようなドキュメントが生成されます。

public int x

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

public int y

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

見出しタグはなるべく使用しない - メンバに対してドキュメンテーションコメントを記述するときには、<H1> や <H2> などの HTML 見出しタグは、なるべく使わないでください。Javadoc ツールは、完全に構造化されたドキュメントを作成するので、このような構造化タグが使われていると、生成ドキュメントの形式が悪影響を受けることがありま す。ただし、クラスやパッケージのコメントでは、これらの見出しタグを使って独自の構造を組み立ててかまいません。

メソッドコメントの自動コピー

Javadoc ツールには、次の 2 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラ スは、ドキュメンテーションコメントを継承しません。

• 自動的にコメントを継承して、見つからないテキストを埋める - 主説明または、@return、@param、@throws タグが、メソッドコメントで見つからないる場合、Javadoc ツールは、オーバーライドしたメソッドまたは実装している場合はそのメソッドから、対応する主説明およびタグコメントを、次のアルゴリズムに従ってコピー します。

  厳密には、特定のパラメータの @param タグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。特定の例外の @throws タグが見つからない場合、その例外が宣言されている場合にかぎり、その @throws タグがコピーされます。

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

• {@inheritDoc} タグを持つコメントを明示的に継承する - インラインタグ {@inheritDoc} を、メソッドの主説明、または @return、@param、@throws タグコメントに挿入します。継承した対応する主説明またはタグコメントは、その箇所にコピーされます。

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

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

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

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

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

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

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

ｊavadoc タグ

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

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

• ブロックタグ - 主説明に続くタグセクション内にのみ記述可能。 ブロックタグの形式は @tag
• インラインタグ - 主説明内またはブロックタグのコ メント内に記述可能。中括弧で囲まれる ({@tag})

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

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

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

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

@author  name-text

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

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

@deprecated  deprecated-text

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

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

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

• Javadoc 1.2 以降では、{@link} タグを使用します。これにより、必要な場所にインラインでリンクを作成できます。次に例を示します。

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

• Javadoc 1.1 では、各 @deprecated タグに対して @see タグ (インラインにはできない) を記述するのが標準の形式です。

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

{@code  text}

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

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

     {@code A<B>C}
      

これは、生成される HTML ページでも変わらずに表示されます。

     A<B>C
      

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

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

{@docRoot}

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

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

1. コマンド行では、ヘッダ、フッタ、またはボトムノートは次のように定義します。

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

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

2. ドキュメンテーションコメントの中では、次のように使用します。

      /**
       * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
       */
   

このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。次に例を示します。

  <a href="{@docRoot}/copyright.html">

次のように解決されます。

  <a href="../../copyright.html">      for java/lang/Object.java

および

  <a href="../../../copyright.html">   for java/lang/ref/Reference.java

@exception  class-name  description

@exception タグは、@throws タグと同義です。

{@inheritDoc} 

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

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

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

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

{@link  package.class#member  label}

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

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

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

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

Use the {@link #getComponentAt(int, int) getComponentAt} method.

標準ドックレットでは、上記のコメントから次の HTML が生成されます (このコメントが同じパッケージの別のクラスを参照している場合)。

Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.

この HTML は、Web ページ上では次のように表示されます。

Use the getComponentAt method.

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

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

{@linkplain  package.class#member  label}

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

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

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

Refer to the overridden method.

{@literal  text}

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

     {@literal A<B>C}
      

これは、生成される HTML ページでも変わらずにブラウザで表示されます。

     A<B>C

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

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

@param  parameter-name description

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

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

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

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

@return  description

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

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

@see  reference

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

@see "string"

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

     @see "The Java Programming Language"

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

See Also:

"The Java Programming Language"

@see <a href="URL#value">label</a>

URL#value で定義されているリンクを追加します。URL#value は、相対 URL または絶対 URL です。Javadoc ツールは、最初の文字が「より小さい」記号 (<) かどうかを調べて、この形式をほかの 2 つの形式と区別します。次に例を示します。

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

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

See Also:

Java Spec

@see  package.class#member  label

指定された名前を持つ、参 照されている Java 言語のメンバについてのドキュメントを指すリンクを、表示テキスト label とともに追加します。label は省略可能です。label を省略すると、リンク先のメンバの名前が適切に短縮されて表示されます。「名前が表示される方法」を 参照してください。-noqualifier を使用して、この表示テキストからパッケージ名を広域的に削除します。表示テキストを、自動生成の表示テキストとは異なるテキストにする場合は、ラベルを 使用します。

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

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

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

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

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

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

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

<dl>
<dt><b>See Also:</b>
<dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
</dl>

これは、ブラウザでは次のように表示され、ラベルがリンクテキストになります。

関連項目:

equals

名前の指定 - このタグに指定する package.class#member という名前は、java.lang.String#toUpperCase() のように完全指定することも、String#toUpperCase() や #toUpperCase() のように部分的に指定することもできます。名前が完全指定されていない場合、Javadoc ツールは、Java コンパイラの通常の検索順序でその名前を検索します。詳細は、このあとの「@see の検索順序」を 参照してください。名前には、メソッドの複数の引数の間など、括弧の内側であれば空白を含めることができます。

「部分的に指定」した短い名前を指定することの利点は、入力する文字数が減ることや、ソースコードが読みやすくなることです。 次の表に、さまざまな形式の名前を示します。この表の中で、Class にはクラスまたはインタフェースを、Type にはクラス、インタフェース、配列、または基本データ型を、そして method にはメソッドまたはコンストラクタを指定できます。

@see package.class#member の一般的な形式

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

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

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

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

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

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

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

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

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

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

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

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

                                           See also: 
@see java.lang.String                   //  String                           
@see java.lang.String The String class  //  The String class                 
@see String                             //  String                           
@see String#equals(Object)              //  String.equals(Object)            
@see String#equals                      //  String.equals(java.lang.Object)   
@see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)      
@see Character#MAX_RADIX                //  Character.MAX_RADIX              
@see <a href="spec.html">Java Spec</a>  //  Java Spec            
@see "The Java Programming Language"    //  "The Java Programming Language"         

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

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

@serial  field-description | include | exclude

デフォルトの直列化可能フィールドのドキュメンテーションコメントで使用します。

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

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

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

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

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

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

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

@serialField  field-name  field-type  field-description

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

@serialData  data-description

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

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

@since  since-text

生成ドキュメントに「導入されたバージョン」見出しを追加し、指定された since-text を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、 インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、since-text に示されたソフトウェアリリース以降、存在していることを意味します。次に例を示します。

    @since 1.4

Java プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。

@throws  class-name  description

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

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

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

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

{@value  package.class#field}

{@value} が static フィールドのドキュメンテーションコメントで使用される場合 (引数なし)、その定数値が表示されます。

    /**
     * The value of this constant is {@value}.
     */
    public static final String SCRIPT_START = "<script>"

任意のドキュメンテーションコメントで引数 package.class#field とともに使用すると、指定の定数値が表示されます。

    /**
     * Evaluates the script starting with {@value #SCRIPT_START}.
     */
    public String evalScript(String script) {
    }

引数 package.class#field は、@see 引数と 同じ形式になりますが、メンバは static フィールドに属していなければなりません。

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

@version  version-text

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

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

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

タグを使用できる場所

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-1.1 -author -bootclasspath -bottom -breakiterator -charset -classpath -d -docencoding -docfilessubdirs -doclet -docletpath -doctitle -encoding -exclude -excludedocfilessubdir -extdirs -footer -group

-header -help -helpfile -J -keywords -link -linkoffline -linksource -locale -nocomment -nodeprecated -nodeprecatedlist -nohelp -noindex -nonavbar -noqualifier -nosince -notimestamp -notree -overview -package

-private -protected -public -quiet -serialwarn -source -sourcepath -splitindex -stylesheetfile -subpackages -tag -taglet -tagletpath -title -use -verbose -version -windowtitle

イタリックで示されたオプションは、Javadoc の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、イタリックでないオプションを提供します。

Javadoc オプション

-overview  path/filename

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

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

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

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

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

-public

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

-protected

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

-package

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

-private

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

-help

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

-doclet  class

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

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

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

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

-docletpath  classpathlist

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

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

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

ドックレット開始クラスファイルのパスの例クラスファイル名が省略されている点に注目してください。

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

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

-1.1

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

-source release

受け付けるソースコードのバージョンを指定します。ｒｅｌｅａｓｅ には次の値を指定できます。

1.5	Javadoc は、JDK 1.5 で導入された汎用機能および他の言語機能を含んだコードを受け付けます。-source フラグを指定しないと、コンパイラはデフォルトとして 1.5 の動作をします。
1.4	Javadoc は、JDK 1.4 で導入された、アサーションを含むコードを受け付けます。
1.3	Javadoc は、JDK 1.3 以降に導入されたアサーション、汎用機能、または他の言語機能をサポートしません。

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

-sourcepath  sourcepathlist

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

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

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

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

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

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

この指定方法は、「ソースパスの値とパッケージ名を連結して、ドットをスラッシュ「/」に変えると、パッケージのフルパス (/home/user/src/com/mypackage) になる」と覚えれば簡単です。

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

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

-classpath  classpathlist

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

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

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

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

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

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

-subpackages  package1:package2:...

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

次に例を示します。

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

このコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。

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

-exclude  packagename1:packagename2:...

指定されたパッケージとそのサブパッケージを -subpackages によって作成されたリストから無条件に除外します。過去の -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 のサブパッケージである java.lang.ref は除外されます。

-bootclasspath  classpathlist

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

-extdirs  dirlist

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

-verbose

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

-quiet

エラーメッセージまたは警告メッセージ以外のメッセージを抑制し、警告とエラーだけが表示されるようにして、これらを特定しやすくしま す。バージョン文字列も抑制します。

-breakiterator 

英語言語というロケール固有のアルゴリズムではなく、java.text.BreakIterator の国際化された文境界を使用して、英文の最初の文の終わりを判断します (他のすべてのロケールはすでに BreakIterator を使用)。「最初の文」とは、パッケージ、クラス、またはメンバの主説明での最初の文のことです。この文は、パッケージ、クラス、またはメンバの要約にコ ピーされ、アルファベット順のインデックスにコピーされます。

JDK 1.2 以降、BreakIterator クラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、1.2 以降では、-breakiterator オプションは英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。

• 英文のデフォルトの文区切りアルゴリズム - 空白または HTML ブロックタグ (<P> など) が続くピリオドで停止する
• breakiterator 文区切りアルゴリズム - 一般に、次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止する。このアルゴリズムでは、ほとんどの省略表記が処理される (「The serial no. is valid」は処理されるが「Mr. Smith」は処理されない)。HTML タグや、数字または記号で始まる文では停止しない。HTML タグに埋め込まれている場合でも、「../filename」の最後のピリオドで停止する

注: 1.5.0 からは、1.4.x に設けられていた breakiterator 警告メッセージを削除し、デフォルトの文区切りアルゴリズムを変更していません。つまり、-breakiterator オプションは、1.5.0 ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャーリリース」(1.5.0) でデフォルトを変更するという、以前の目的とは逆になっています。つまり、ソースコードを変更せず、1.4.x での breakiterator 警告を除去していない場合でも、1.5.0 からは何もする必要がなく、警告は消滅しています。この逆戻りの理由は、breakiterator をデフォルトにするメリットよりも、デフォルトにするために必要となる、互換性のないソースの変更の方が負担が大きかったためです。これに費やした作業や 混乱が無駄になり残念です。

-locale  language_country_variant

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

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

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

-encoding  name

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

-docencoding および -charset も参照してください。

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

  extdocURL への絶対リンクを使用すると、ユーザのドキュメントを任意の Web サイト上のドキュメントにリンクできます。相対位置へリンクするだけでよい場合は相対リンクを使用できます。相対リンクを使用する場合、-d を使って、生成先ディレクトリからリンクされるパッケージのあるディレクトリの相対パスを指定する必要があります。

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

  すべての場合、すべてのオペレーティングシステムで、絶対 URL と相対 URL、 「http:」ベースと「file:」ベースにかかわらず、スラッシュを区切り文字として使用します (URL Memo で指定)。

  http: ベースの絶対リンク:

  -link http://<host>/<directory>/<directory>/.../<name>

  file: ベースの絶対リンク:

  -link file://<host>/<directory>/<directory>/.../<name>

  相対リンク:

  -link <directory>/<directory>/.../<name>

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

-linkoffline と -link の選択-
次のような場合は、-link オプションを使用します。

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

次のような場合は、-linkoffline オプションを使用します。

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

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

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

外部ドキュメントへの相対リンクの使用例 - 2 つのパッケージがあり、そのドキュメントが Javadoc ツールを複数回実行した結果生成されたものであるとします。さらに、これらのドキュメントが相対パスで分割されているとします。この例の場合、2 つのパッケージは、API である com.apipackage とSPI (サービスプロバイダインタフェース) である com.spipackage です。ドキュメントの格納先は 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 つのパッケージ群の間にクロスリンクを作成できます。

クラスの参照方法 - 外部参照クラスへのリンクを、テキストラベルだけではなく実際に表示するには、次の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照 するだけでは十分ではありません。import 文または宣言で参照する必要があります。次に、クラス java.io.File を参照する方法の例を示します。

• すべての種類の import 文の場合: ワイルドカードによるインポート、名前による明示的なインポート、または java.lang.* に対する自動的なインポート。たとえば、次のようにすれば十分です。
  import java.io.*;
  1.3.x および 1.2.x では、名前による明示的なインポートだけです。ワイルドカードによるインポート文も、自動インポート java.lang.* も使用できません。

• 宣言の場合:
  void foo(File f) {}
  この参照を使用し、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースのリターンタイプまたはパラメータタイプに置くか、 implements、extends 文または throws 文に置きます。

この結果、-link オプションを使用しても、この制限のために誤って表示されない多くのリンクが多数発生する可能性があります。テキストはハイパーテキストリンクが付けられ ずに表示されます。これらのリンクが表示する警告から、このリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するためのもっとも安 全な方法は上で説明したとおり、当該のクラスをインポートすることです。

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

たとえば、Java 2 Platform v1.4 API のパッケージリストは http://java.sun.com/j2se/1.4.2/docs/api/package-list にあり、次のような内容で始まっています。

  java.applet  
  java.awt
  java.awt.color
  java.awt.datatransfer
  java.awt.dnd
  java.awt.event
  java.awt.font
  etc.

-link オプションを指定せずに javadoc を実行した場合、外部参照クラスに属する名前を見つけると、javadoc はその名前をリンクを持たない形で出力します。一方、-link オプションを指定した場合は、指定した 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 に接続できなければならないという制約がなくなります。

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

-linkoffline オプションは引数を 2 つ取ります。最初の引数は <a href> リンクに組み込まれる文字列を指定する引数、2 番目の引数は 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 より前は、複数のオプションを指定することはできませんでした。

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

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

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

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

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

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

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

まず、今回の実行で使用する新しい生成先ディレクトリ (update) を作成します。元の生成先ディレクトリの名前が html だとします。もっとも単純な例では、html ディレクトリの親ディレクトリに移動 (cd) します。-linkoffline の最初の引数にカレントディレクトリ「.」を指定し、2 番目の引数に html への相対パスを指定します。ここで、package-list が検索されます。更新対照のパッケージのパッケージ名だけを指定してください。

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

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

-linksource 

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

このオプションは、-public、-package、-protected、-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
      

この結果、次のようなグループ化が行われます。

コアパッケージ

java.lang

java.lang.reflect

java.util

拡張機能パッケージ

javax.servlet

その他のパッケージ

java.new

-nodeprecated

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

-nodeprecatedlist

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

-nosince

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

-notree

生成ドキュメントから、クラスおよびインタフェースの階層ページを省略します。これらのページは、ナビゲーションバーの「Tree」ボタ ンを使用すると表示されます。デフォルトでは、階層が生成されます。

-noindex

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

-nohelp

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

-nonavbar

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

-helpfile  path/filename

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

  % javadoc -helpfile /home/user/myhelp.html java.awt
      

-stylesheetfile  path/filename

代替 HTML スタイルシートファイルのパスを指定します。このオプションが指定されていない場合、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 文字セットを指定します。この名前は、IANA Registry で与えられた、推奨される MIME 名でなければなりません。次に例を示します。

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

生成されるすべてのページの先頭に、次の行が挿入されます。

   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

この META タグについては、HTML の標準 (4197265 および 4137321) を参照してください。

-encoding および -docencoding も参照してください。

-docencoding  name

生成される HTML ファイルのエンコーディングを指定します。この名前は、IANA Registry で与えられた、推奨される MIME 名でなければなりません。このオプションを省略しながら -encoding を使用した場合、生成される HTML ファイルのエンコードは、-encoding によって決められます。次に例を示します。

  % javadoc -docencoding "ISO-8859-1" mypackage
      

-encoding および -charset も参照してください。

-keywords

HTML メタキーワードタグを、クラスごとに生成されるファイルに追加します。これらのタグは、メタタグを検索するサーチエンジンがページを見つける場合に役立ち ます。インターネット全体を検索する多くのサーチエンジンは、ページがメタタグを誤用しているため、メタタグを調べません。一方、検索を自身の Web サイトに限定している企業では、サーチエンジンがメタタグを調べることによってメリットを得られます。

メタタグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同 じであるため含まれません。たとえば、クラス String は次のキーワードで開始します。

     <META NAME="keywords" CONTENT="java.lang.String class">
     <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
     <META NAME="keywords" CONTENT="length()">
     <META NAME="keywords" CONTENT="charAt()">

-tag  tagname:Xaoptcmf:"taghead"

Javadoc ツールがドキュメンテーションコメント内の引数を 1 つ取る単純なカスタムブ ロックタグ @tagname を解釈できるようにします。これにより、Javadoc ツールはタグ名の「スペルチェック」を行うことができるので、ソースコード 内のすべてのカスタムタグに -tag オプションを組み込むことをお勧めします。今回の実行で出力されないタグは、X を付けて無効にします。

コロン (:) は常に区切り文字になります。tagname でコロンを使用するには、「タグ名でのコロンの使用」を参照してください。

-tag オプションは、タグの見出し「taghead」を太字で出力します。その次の行には、このオプションの引数で指定したテキストが続きます。以下の例を参照してください。ブロックタグと同様、この引数のテキストにはインラインタグを含めることがで きます。このインラインタグも解釈されます。出力は、引数を 1 つ取る標準のタグ (@return、@author など) の出力とよく似ています。taghead を省略すると、tagname が見出しとして表示されます。

タグの配置 - 引数の 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.

タグ名でのコロンの使用 - コロンは、バックスラッシュでエスケープすると、タグ名内で使用できます。 次のドキュメンテーションコメントを例にとります。

    /**
     * @ejb:bean
     */

次のタグオプションを使用します。

    -tag ejb\\:bean:a:"EJB Bean:"

タグ名のスペルチェック (タグの無効化) - ソースコード内に配置した一部のカスタムタグの出力を抑制したい場合があります。この場合も、ソースコード内にすべてのタグを配置し、出力を抑制しないタ グを有効にし、出力を抑制するタグを無効にします。タグを無効にするには、X を指定します。指定しないと、そのタグは有効になります。これにより、Javadoc ツールは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。未知のタグを検出した場合、Javadoc ツールは警告を出力します。

すでに配置されている値に X を追加できます。こうしておけば、X を削除するだけでタグを有効にすることができます。たとえば、@todo タグの出力を抑制したい場合、次のように指定します。

    -tag todo:Xcmf:"To Do:"

さらに単純な指定方法もあります。

    -tag todo:X

構文 -tag todo:X は、@todo が taglet で定義されている場合も有効です。

タグの順序 - -tag (および -taglet) オプションの順序によって、その出力順序が決定します。カスタムタグと標準タグを組み合わせて使用することもできます。標準タグのタグオプションは、順序 を決定するためだけのプレースホルダです。これらは標準タグ名のみを使用します。(標準タグの小見出しは変更できない。)これについては、以下の例で説明 します。

-tag がない場合、-taglet の位置によってその順序が決定します。タグが両方とも存在する場合、コマンド行の最後にあるほうがその順序を決定します。これは、タグやタグレットがコマ ンド行に指定された順番に処理されるためです。たとえば、-taglet と -tag の両方が todo という名前を持っている場合、コマンド行の最後にあるほうが順序を決定します。

タグの完全セットの例 - この例では、出力の「Parameters」と「Throws」の間に「To Do」を挿入します。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 オプションを使用します。以下は、生成されるページの「Parameter」と「Throws」の間に「To Do」タグレットを挿入する例です。

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

-tag オプションの代わりに -taglet オプションを使用することもできますが、読みやすさを考慮するなら、-tag オプションを使用したほうがよいでしょう。

-tagletpath  tagletpathlist

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

-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.*

上の動作によりパッケージ修飾子が表示されますが、名前は適宜短くなります。「名前が表示される方法」を 参照してください。この規則は、-noqualifier を使用したかどうかにかかわらず有効です。

-notimestamp 

タイムスタンプを抑制します。タイムスタンプは、生成される HTML の各ページの最上部近くにある HTML コメントの中に隠されます。このオプションを使用すれば、タイムスタンプによる diff が発生しなくなるため、2 つのソースベースで Javadoc を実行し、これらのソースベースを区別したいときに役立ちます (このオプションを使用しない場合は、ページごとに diff が発生する)。タイムスタンプには Javadoc バージョン番号が含まれ、この時点では、次のように表示されます。

     <!-- Generated by javadoc (build 1.5.0-internal) on Tue Jun 22 09:57:24 PDT 2004 -->

-nocomment 

主説明すべてのタグを含むコメント本体を抑制し、宣言のみを生成しま す。このオプションを使用すると、異なった目的で作成されたソースファイルを再利用し、新しいプロジェクトの初期段階でスケルトン HTML ドキュメントを生成できます。

コマンド行引数ファイル

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 で無効にできます。

公開プログラムインタフェース - Java 言語で記述されたプログラムから Javadoc ツールを起動するとき使用します。このインタフェースは com.sun.tools.javadoc.Main にあります (javadoc は再入可能)。詳細は、「標 準ドックレッ ト」を参照してください。

ドックレットの実行 - 下記の説明は、標準 HTML ドックレットを呼び出すためのものです。カスタムドックレットを呼び出すには、-doclet および -docletpath オプションを使用します。特定のドックレットを実行した完全な例については、「Running the MIF Doclet」を参照してください。

簡単な例

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 を使用し、再帰できるように -subpackages (新しい 1.4 オプション) を使用します。java.net および java.lang 以下のパッケージを除く java ディレクトリのサブパッケージを巡回します。ただし、java.lang のサブパッケージである java.lang.ref は除外されます。

    % 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 - 単一のディレクトリツリーの明示的なパッケージに対して任意のディレクトリから実行 - このケースでは、カレントディレクトリがどこであってもかまいません。最上位パッケージの親ディレクトリを -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 によるファイルの解析を防ぐことができます。

エラーと警告

エラーおよび警告メッセージには、ファイル名と宣言行 (ドキュメンテーションコメント内の特定の行ではない) の行番号が含まれます。

• "error:cannot read:Class1.java" Javadoc ツールはカレントディレクトリに Class1.java クラスをロードしようとしています。絶対パスまたは相対パスとともに表示されるクラス名は、この例の場合 ./Class1.java と同じです。

環境

CLASSPATH

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

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

関連項目

• javac
• java
• jdb
• javah
• javap
• Javadoc のホームページ
• How to Write Doc Comments for Javadoc
• クラスパスの設定
• javac と javadoc がクラスを検索する方法 (tools.jar)

コメントの送付先 (電子メールアドレス):

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

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

Java ソフトウェア