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

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

目次

リファレンスガイド 実行

リファレンスガイド

形式

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 言語仕様によると、抽象メソッドを含むクラスは、それ自体抽象として宣言されなければなりません。 このエラーを検出すると、javac コンパイラは停止しますが、Javadoc ツールは警告を出さずに処理を続行します。 Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。 ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。

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

Javadoc のドックレット

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

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

用語

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 ツールは、クラスの Java 言語ソースファイル (.java)、パッケージコメントファイル、概要コメントファイル、およびその他の未処理のファイル、という 4 種類の「ソース」ファイルから出力を生成します。

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

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

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

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

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

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

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

概要コメントファイル

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

概要コメントファイルを作成する場合は、ファイルに任意の名前を付け、任意の場所に置くことができます。ただし、通常は、ファイル名を overview.html にして、ソースツリーの最上位レベルに置きます。 異なるパッケージのセットに対して javadoc を複数回実行する場合は、同じ 1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。 たとえば、java.applet パッケージのソースファイルが C:\user\src\java\applet ディレクトリに含まれているとすると、C:\user\src\overview.html に概要コメントファイルを作成することができます。

概要コメントファイルの内容は、前述のパッケージコメントファイルと同様、HTML で記述された 1 つの大きなドキュメンテーションコメントです。 詳細は、前述の説明を参照してください。 要点を繰り返すと、このコメントを記述する場合は、最初の文をアプリケーションまたはパッケージセットの要約とし、<body> と最初の文の間にタイトルその他のテキストを含めないようにします。 概要タグを含めることができます。どのドキュメンテーションコメントについても、インラインタグ ({@link} など) 以外のすべてのタグは、説明のあとに置く必要があります。 @see タグを追加する場合は、完全指定の名前を使用しなければなりません。

Javadoc ツールの実行時に、-overview オプションを使って概要コメントファイル名を指定します。 このファイルは、パッケージコメントファイルと同じように処理されます。

その他の未処理ファイル

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

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

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

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

生成されるファイル

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

基本内容ページ

相互参照ページ

サポートファイル

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 フレームが必要かどうかによって、次のどちらかのファイルを開始ページとしてロードします。 生成されるファイルの構造

生成されるクラスファイルおよびインタフェースファイルは、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 コメント) を記述することができます。 各パッケージにドキュメンテーションコメントを作成できます。構文は若干異なりますが、概要にもドキュメンテーションコメントを作成できます。 このコメントは、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} が含まれる場合、対応する説明またはタグがその位置にコピーされます。

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

コメントの継承は、次の 3 つのケースで起こります。

最初の 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 つのタイプがあります。

今後のリリースで導入されるタグについては、「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>'
    注 - {@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 とのインラインリンクを挿入します。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} と同じです。 ラベルがプレーンテキストで記述されていると便利です。次の例を参照してください。 
     {@linkplain add() the overridden method} を参照してください。
これは以下のように表示されます。
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 も参照してください。この FAQ には、「-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。

@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 パッケージのソースツリーが C:\src\classes\java\lang\ の場合、概要ファイルは C:\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 C:\user\mifdoclet\lib\mifdoclet.jar
ドックレット開始クラスファイルのパスの例。クラスファイル名が省略されている点に注目してください。 
   -docletpath C:\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 という名前のパッケージをドキュメント化する場合に、そのソースファイルが次の場所にあるとします。 

C:\user\src\com\mypackage\*.java
この場合は、sourcepath に C:\user\src (com\mypackage を含むディレクトリ) を指定してから、パッケージ名 com.mypackage を指定します。次のようなコマンドになります。 
  C:> javadoc -sourcepath C:\user\src com.mypackage
この方法は、ソースパスの値とパッケージ名を連結して、ドットを「\」(円記号) に変えると、パッケージのフルパス (C:\user\src\com\mypackage) になることを理解すると簡単です。 C:\user\src\com\mypackage.

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

  C:> javadoc -sourcepath C:\user1\src;C:\user2\src com.mypackage

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

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

たとえば、com.mypackage をドキュメント化する場合に、そのソースファイルがディレクトリ C:\user\src\com\mypackage にあり、このパッケージが C:\user\lib にあるライブラリに依存しているときは、次のように指定します。 

  C:> javadoc -classpath \user\lib -sourcepath \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 は、省略可能です。これは、初期メモリのサイズを設定するだけのオプションで、必要なメモリの最小サイズがわかっている場合に便利です。 
   C:> javadoc -J-Xmx32m -J-Xms32m com.mypackage
使用している javadoc のバージョンを確認するには、次のように java の「-version」オプションを呼び出します。 

   C:> 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 パッケージのドキュメントを生成し、結果を C:\user\doc\ ディレクトリに保存します。 

  C:> javadoc -d \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 の値を使います。 

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

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

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

  C:> 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でなければなりません。

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

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

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

-linkoffline と -link の選択 - 現在実行中の javadoc の外部にある API ドキュメントにリンクするとき、いずれかのオプションを使用します。
次のような場合は、-link オプションを使用します。

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

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

  C:> javadoc -link http://java.sun.com/j2se/1.4/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 パッケージをドキュメント化します。 
  C:> 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 を使用した場合、ハイパーリンク <A HREF> が作成されるのは、そのクラスが import 文か宣言のどちらかで参照されている場合にかぎられます。 メソッドの本体で参照されているだけでは不十分です。 回避策としては、その参照クラスの明示的な (ワイルドカードを使用しない) import 文を組み込むという方法がありました。
現在では、@see または {@link} で -link を使って参照するだけで、参照クラスをロードし、その参照クラスへのリンクを有効にできるようになっています。 以前に回避策として追加した import 文は削除できます。この import 文には、次の例のようにコメントを付加することを推奨していました。 
   import java.lang.SecurityManager; // workaround to force @see/@link hyperlink

パッケージリスト - -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/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 で修正されました。

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

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

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

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

C:> javadoc -linkoffline extdocURL1 packagelistLoc1 \
          -linkoffline extdocURL2 packagelistLoc2 \
          ...

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

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

  C:> javadoc -d update -linkoffline . html com.mypackage
Javadoc ツールの実行が完了したら、生成されたクラスページを update\com\package (概要、索引ではない) にコピーし、html\com\package 内の元のファイルを上書きします。

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

このオプションは、-public、-package、-protected、-private の各オプションとは関係なく、private クラス、private フィールド、および private メソッドの本体をはじめとする組み込まれたソースファイル内のすべての 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 パッケージは除外されることになります。 

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

-charset  name
このドキュメント用の HTML 文字セットを指定します。 例を示します。 
  C:> 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"
javadoc がドキュメンテーションコメント内の引数を 1 つ取る単純なカスタムスタンドアロン タグ @tagname を解釈できるようにします。 これにより、Javadoc ツールはタグ名の「スペルチェック」を行うことができるので、ソースコード内のすべてのカスタムタグのために -tag オプションを含めることをお勧めします。今回の実行で出力されないタグは、X を付けて無効にします。

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

タグの配置 - 引数の 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 ツールは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。 未知のタグを検出した場合、Javadoc ツールは警告を出力します。

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

    -tag todo:Xcmf:"To Do:"
さらに単純な指定方法もあります。 
    -tag todo:X

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

タグの順序 - -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 オプションを使用します。 以下は、生成されるページの「パラメータ」と「例外」の間に「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 ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。

-subpackages  package1:package2:...
ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。 このオプションは、ソースコードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。 各パッケージは最上位パッケージ (java) または完全指定のサブパッケージ名 (javax.swing) になります。ソースファイルを含める必要はありません。 ワイルドカードは不要、または使用不可です。 パッケージの検索場所を指定するには、-sourcepath を使用します。 例を示します。 
  C:> javadoc -d docs -sourcepath C:\user\src -subpackages java:javax.swing
このコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。

サブパッケージを除外することもできます。

-exclude  packagename1:packagename2:...
指定されたパッケージとそのサブパッケージを -subpackages によって作成されたリストから無条件に除外します。 過去の -subpackages オプションの指定によって組み込まれたパッケージ、または将来組み込まれるパッケージも除外の対象となります。 例を示します。 
   C:> javadoc -sourcepath C:\user\src -subpackages java -exclude java.net:java.lang
このうち、java.io、java.util、java.math は組み込まれますが、java.net と java.lang 以下のパッケージは除外されます。 ただし、java.lang のサブパッケージ java.lang.ref は除外されません。

-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 引数を格納し、次のように使用することができます。 
  C:> 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-2009 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 を実行します。 
  C:> javadoc @options @packages

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

引数ファイルには、パスを指定できます。ただし、そのファイル内に指定されたファイル名は、現在の作業ディレクトリから見た相対パスになります。つまり、下の例の場合は、path1 や path2 から見た相対パスではありません。 
  C:> 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-2009 Sun
Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.
All Rights Reserved.</font>'
そのあと、次のようにして Javadoc ツールを実行します。 
  C:> javadoc -bottom @bottom @packages
また、引数ファイルの先頭に -bottom オプションを組み込んでおけば、次のようにして実行できます。 
  C:> javadoc @bottom @packages

実行


Javadoc の実行

バージョン番号 - javadoc のバージョン番号を判別するには、javadoc -J-version を使用します。 出力ストリームには標準ドックレットのバージョン番号が含まれます。 -quiet で無効にできます。

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


簡単な例

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

1 つ以上のパッケージのドキュメント化

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

javadoc を実行するには、cd コマンドを使ってディレクトリを変更するか、または -sourcepath オプションを使用します。 以下の例では、両方の方法について説明します。

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

1 つ以上のクラスのドキュメント化

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

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

パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。 次に前述の 2 つの例を組み合わせた例を示します。 sourcepath は、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。 
  C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt C:\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 などのシェルには大きすぎます。 この制限を回避するには、コマンド行引数ファイルを使用します。または、シェルスクリプトを記述します。 
C:> 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 の引数は、単一引用符で囲みます。

注


トラブルシューティング

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

エラーと警告

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

環境

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

関連項目

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

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

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

 Sun
Java ソフトウェア