javadoc - Java API ドキュメンテーションジェネレータ

Java ソースファイルから API ドキュメンテーションの HTML ページを生成します。

目次

形式

javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
引数の順は任意です。
options
このドキュメントで指定されているコマンド行オプションです。javadoc のオプションの一般的な使用法については、「使用例」を参照してください。
packagenames
java.lang java.lang.reflect java.awt などの、スペースで区切られた連続したパッケージ名です。ドキュメント化するパッケージごとに別個に指定する必要があります。Javadoc は、-sourcepath を使ってこれらのパッケージ名を検索します。Javadoc は、サブパッケージを再帰的に処理することはありません。アスタリスク (*) などのワイルドカードは使うことができません。「1 つ以上のパッケージのドキュメント化」の例を参照してください。
sourcefiles
スペースで区切られた一連のソースファイル名です。 各ファイルは、パスで始まります。 アスタリスク (*) などのワイルドカードを含めることができます。ソースファイル名の前に指定したパスによって、javadoc の検索先が決まります。Javadoc では、ソースファイル名を検索するときに -sourcepath は使用されません。たとえば、Button.java を渡した場合は、./Button.java が検索されます。フルパスをソースファイル名に指定した場合は、/home/src/java/awt/Graphics*.java のようになります。「1 つ以上のクラスのドキュメント化」の例を参照してください。また、「パッケージとクラスのドキュメント化」の例のように、パッケージ名とソースファイルを組み合わせることもできます。
@files
複数のパッケージ名およびソースファイルを任意の順序で各行に 1 つずつ含んだ 1 つ以上のファイルです。

解説

JavadocTM は、一連の Java ソースファイルの宣言およびドキュメンテーションコメントを解析し、デフォルトでは public クラスと protected クラス、内部クラス、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連の HTML ページを生成します。

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

Javadoc は、実行するたびに 1 つのドキュメントを作成します。 追加生成することはできません。 つまり、Javadoc の以前の実行結果を修正したり、「直接」組み込んだりすることはできません。ただし、以前の実行結果にリンクすることはできます。

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

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

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

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

Javadoc のドックレット

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

関連ドキュメント

用語

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

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

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

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

外部参照クラス
参照されるクラスのうち、javadoc を実行してもドキュメンテーションが生成されないクラスです。言い換えると、これらのクラスは javadoc の実行の外部に存在するクラスです。これらのクラスに対する、ドキュメンテーション内での名前のリンクは、「外部参照」または「外部リンク」と呼ばれます。たとえば、java.awt パッケージに対してだけ javadoc を実行した場合、Object などの java.lang 内のすべてのクラスは、外部参照クラスになります。外部参照クラスには、-link オプションを使ってリンクすることができます。外部参照クラスの重要な属性として、そのソースコメントが Javadoc の実行で利用できないことがあります。このため、これらのコメントを継承することはできません。


ソースファイル

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

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

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

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

各パッケージは、独自のドキュメンテーションコメントを持つことができ、「ソース」ファイルに保持します。Javadoc は、生成するパッケージの要約ページにこのコメントをマージします。

通常、このコメントには、パッケージ全体に適用されるドキュメンテーションを含めます。 パッケージコメントファイルを作成するには、ファイル名を package.html にして .java ファイルとともにソースツリー内のパッケージディレクトリに置く必要があります。Javadoc は、この場所でこのファイル名を自動的に検索します。ファイル名は、どのパッケージでも同一です。

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

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

概要コメントファイル

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

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

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

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

その他の処理されないファイル

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

処理されないファイルを含めるには、それらのファイルを doc-files というディレクトリに置きます。 このディレクトリは、任意のパッケージディレクトリの下に作成できます。パッケージごとにこのようなサブディレクトリを 1 つ持つことができます。イメージ、コード例、ソースファイル、.class ファイル、アプレット、および HTML ファイルをこのディレクトリに格納できます。たとえば、ボタンの画像 button.gif を java.awt.Button クラスドキュメンテーションに含めたい場合は、そのファイルを /home/user/src/java/awt/doc-files/ ディレクトリに置きます。 これらの処理されないファイルへのリンクはすべて明示的に記述する必要があります。 これは、Javadoc がファイルを見ずに、単にディレクトリとその内容物を生成先にコピーするだけだからです。たとえば、Button.java ドキュメンテーションコメント内のリンクは、次のようになります。 

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

生成されるファイル

デフォルトでは、javadoc は、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 のリスト
   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 インタフェースを使用するページ

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、fi nal、static、transient、および volatile を含めることができますが、synchronized や native を含めることはできません。これら後者の 2 つの修飾子は、実装の詳細とみなされているため、API 仕様には含まれません。

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

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

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

ソースコードの任意のエンティティ (クラス、インタフェース、メソッド、コンストラクタ、またはフィールド) の宣言の前には、ドキュメンテーションコメントを入れることができます。このコメントは、Javadoc コメントとも呼ばれます。doc コメントは、コメントの始まりを示す文字列 /** とコメントの終わりを示す文字列 */ との間にある文字で構成されます。テキストは、複数行にわたって記述できます。 

/**
 * This is the typical format of a simple documentation comment.
 */
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 {
    }
コメントはタグの後の記述 - 開始区切り文字 /** の後ろからタグセクションまでが、記述です。先頭の文字が @ の行以降がタグセクションです (先行するアスタリスク、空白、およびコメント区切り文字は無視される)。コメントは、タグセクション以降には記述できません。タグセクションの数に制限はありません。 ただし、タグセクションによっては、複数回記述できないものがあります。次の例の @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 は、使用するブラウザがサポートする任意のバージョンを使うことができます。階層式スタイルシートとフレームを含むほかの部分 (ドキュメンテーションコメント以外) は、HTML 3.2 に準拠したコードを生成する、標準ドックレットで記述してあります。(フレームセット対応のため、生成される各ファイルは、「HTML 4.0」で始まる)。

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

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

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

行頭のアスタリスク - javadoc は、doc コメントを解析するときに、各行の先頭にある文字アスタリスク (*) をすべて破棄します。 また、最初のアスタリスク (*) より前の空白とタブも破棄します。行頭のアスタリスクを省略した場合は、行頭のすべての空白が削除されます。このため、<pre> タグを使ってコード例をインデントするときなど、行頭に空白が必要な場合は、行頭のアスタリスクは省略しないでください。行頭のアスタリスクがないと、行頭の空白が削除されるため、生成されるドキュメント内でインデントが失われます。

最初の文 - 各 doc コメントの最初の文は、宣言されているエンティティに関する簡潔かつ完全な要約文である必要があります。この文は、後に空白、タブ、または行末記号が続く最初のピリオドに遭遇した時点、あるいは最初のタグに遭遇した時点で終了します。最初の文は、Javadoc によって HTML ページ上部のメンバの概要の部分にコピーされます。

複数のフィールドによる宣言 - Java では、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> and <H2> などの HTML 見出しタグを使わないでください。 javadoc は、完全な構造化ドキュメントを作成するため、構造化タグがあると、生成ドキュメントのフォーマットを妨害する可能性があります。ただし、クラスおよびパッケージコメントに使用すると、独自の構成にすることができます。

メソッドコメントの自動的な再利用 - 簡単に「継承コメント」とも呼ばれます。クラスまたはインタフェースの m1() メソッドにドキュメンテーションコメントおよびタグがない場合は、Javadoc では、そのメソッドがオーバーライドまたは実装した m2() メソッドの、コメントとタグが代わりに使用されます(ある場合)。メソッド m2() は、ドキュメント化されたクラスのメンバでなければならず、かつ外部参照クラスのメンバであってはなりません。この現象は、次の 3 つの場合に発生します。

最初の 2 つの場合、m() メソッドが別のメソッドをオーバーライドしているときは、Javadoc では m() のドキュメントに [オーバーライド] が小見出しとして生成され、オーバーライドしたメソッドにリンクが作成されます。

3 つ目の場合、特定のクラスのメソッド m() がインタフェースのメソッドを実装しているときは、Javadoc では m() のドキュメントに [定義] が小見出しとして生成され、実装したメソッドにリンクが作成されます。

検索は次のように行われます。クラス C のメソッドの場合は、クラス C によって実装されるすべてのインタフェースが再帰的に検索されてから、C のすべてのスーパークラスが検索されます。 インタフェース I のメソッドの場合は、そのすべてのスーパーインタフェースが再帰的に検索されます。どちらの場合も、最初に検出されたコメントがコピーされます。

Javadoc の仕様 - ドキュメンテーションコメントの仕様については、Java 言語仕様 (James Gosling、Bill Joy、Guy Steele 共著) の Chapter 18「Documentation Comments」を参照してください。


javadoc のタグ

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

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

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

タグ 導入された JDK/SDK のバージョン
@author 1.0
{@docRoot} 1.3
@deprecated 1.0
@exception 1.0
{@link} 1.2
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
@version 1.0
@author  name-text
-author オプションが使われている場合、生成されるドキュメントに、指定された name-text を持つ Author エントリを追加します。1 つの doc コメントに複数の @author タグを含めることができます。@author タグごとに 1 つ、またはタグごとに複数の名前を指定できます。前者の場合は、Javadoc は、名前と名前の間にコンマ (,) とスペースを挿入します。後者の場合、テキスト全体が解析されることなく生成されるドキュメントに単にコピーされます。このため、コンマ以外の現地仕様の名前区切り文字を使う場合は、1 行に複数の名前を指定します。

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

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

  1. コマンド行では、次のようにヘッダ、フッタ、または下部を定義します。 
       javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
  2. doc コメントには次のように記述します。 
       /**
    * 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

@deprecated  deprecated-text
この API は (動作はするが) 使用すべきでないことを示すコメントを追加します。Javadoc は、deprecated-text を説明の前に移動してイタリックにし、その前にボールドの警告「推奨されません。」を追加します。

deprecated-text の最初の文では、少なくともユーザにどのようなときにその API が推奨されないか、およびそれに代わる API を提示する必要があります。Javadoc は、この最初の文だけを要約セクションと索引にコピーします。あとに続く文で、なぜその API が推奨されないかを説明することもできます。代わりの API を指し示す {@link} タグ (Javadoc 1.2 以降の場合) を含める必要があります。

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

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

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

{@link  package.class#member  label}
表示テキスト label とのインラインリンクを挿入します。 label は、参照先の、Java 言語で記述された名前のドキュメンテーションを指し示します。このタグの package.class#member と label の構文は、後述する @see タグと同じですが、関連項目セクションにリンクを置くのではなく、インラインリンクを生成する点が異なります。インラインテキストのほかの部分と区別するため、このタグの開始と終了には中括弧を使います。ラベルの中で「}」を使う必要がある場合は、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.
@param  parameter-name description
Parameters セクションにパラメータを追加します。説明は次の行に続けて記述できます。

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

@see  reference
reference を指すリンクまたはテキストエントリを持つ [関連項目] 見出しを追加します。1 つの doc コメントには、任意の数の @see タグを指定できます。 @see タグは、同一の見出しにグループ化されます。@see タグには、次の 3 つの形式があります。 通常は、3 番目の形式が使われます。

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

バージョン 1.2 だけは、ラベルではなく、名前が <code> HTML タグ内に自動的に表示されます。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>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 Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class

別のパッケージを参照する (完全指定)
@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class
@see package

上の表に対する注を以下に示します。

  • クラスまたはパッケージを省いた最初の形式のセットでは、Javadoc は現在のクラス階層だけで検索を行います。Javadoc は、現在のクラスかインタフェースのメンバ、スーパークラスかスーパーインタフェースの 1 つ、または親クラスかインタフェースの 1 つ (検索手順 1 〜 3) を検索します。現在のパッケージのほかの部分やほかのパッケージ (検索手順 4 〜 5) は検索しません。
  • メソッドまたはコンストラクタが、getValue のように括弧を付けずに名前として入力され、かつ同じ名前のフィールドがない場合は、Javadoc は正確にリンクを作成しますが、括弧と引数を追加するように促す警告メッセージを出力します。このメソッドをオーバーロードした場合、Javadoc は、指定されたメソッドではなく、検索で見つかった最初のメソッドにリンクします。
  • 内部クラスは、どの形式の場合でも、単に inner という形ではなく、outer.inner という形で指定しなければなりません。
  • すでに述べたとおり、クラスとメンバを区切るのに、ドット (.) ではなくハッシュ文字 (#) が使われていることに注意してください。ドットは、クラス、内部クラス、パッケージ、およびサブパッケージを区切るのにも使われますが、javadoc では、クラスとメンバを区切るのにハッシュ文字を使うことで、あいまいさを排除しています。ただし、一般に、あいまいにならない限りドットは許容され、適切に構文解析されます。 ただし、その場合でも警告は表示されます。

@see の検索順序 - Javadoc は、ソースファイル (.java)、パッケージファイル (package.html)、または概要ファイル (overview.html) 内で使われる @see タグを処理します。あとの 2 つのファイルでは、@see を使って指定する名前を完全修飾する必要があります。ソースファイルでは、完全修飾名と部分修飾名のどちらを指定することもできます。

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

  1. 現在のクラスまたはインタフェース
  2. 名前を囲むクラスとインタフェース。 もっとも近いものを最初に検索
  3. スーパークラスとスーパーインタフェース。 もっとも近いものを最初に検索
  4. 現在のパッケージ
  5. インポートされるパッケージ、クラス、およびインタフェース。 import 文の順序に従って検索

javadoc は、一致する名前が見つかるまで、各クラスについて手順 1 〜 3 を繰り返して検索を続けます。つまり、現在のクラスとそのクラスを囲むクラス E を検索したあと、E のスーパークラスを検索し、最後に E を囲むクラスを検索します。 手順 4 と 5 では、javadoc は、1 つのパッケージ内でのクラスまたはインタフェースの検索を、なんらかの決まった順序で行うわけではありません。この検索順序はコンパイラに依存します。手順 5 では、javadoc は、java.lang を検索します。 これは、java.lang がすべてのプログラムによって自動的にインポートされるためです。

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

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

参照の型 例 表示
@see タグが同じクラスのメンバを参照する @see String#toLowerCase()
toLowerCase()
(クラス名を省略)
@see タグが別のクラスのメンバを参照する @see Character#toLowerCase(char)
Character.toLowerCase(char)
(クラス名を含む)

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

                                           関連項目:
@see java.lang.String                   //  String                           
@see java.lang.String The String class  //  The String class                 
@see String                             //  String                           
@see String#equals(Object)              //  String.equals(Object)            
@see String#equals                      //  String.equals(java.lang.Object)   
@see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)      
@see Character#MAX_RADIX                //  Character.MAX_RADIX              
@see <a href="spec.html">Java Spec</a>  //  Java Spec            
@see "The Java Programming Language"    //  "The Java Programming Language"
@since  since-text
生成されるドキュメントに、指定された since-text を持つ [導入されたバージョン] 見出しを追加します。このテキストには、特別な内部構造はありません。このタグは、特定の変更または機能が、since-text によって指定されたソフトウェアのリリース以来、継続して存在することを意味します。例を示します。
    @since 1.2

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

任意の field-description は、フィールドの意味を説明し、取り得る値のリストを表示する必要があります。必要な場合には、複数の行にまたがって説明を記述することができます。標準ドックレットでは、この情報を直列化形式ページに追加します。

@since タグは、Serializable クラスの初期バージョン以来追加されている各直列化フィールドに対して追加する必要があります。

これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の 1.6 節「クラスの直列化可能なフィールドおよびデータの文書化」を参照してください。また、直列化の FAQ も参照してください。 「javadoc 標準ドックレットでは、@serial または @serialData タグ、あるいはその両方がないという警告がなぜ頻繁に通知されるのか」および「javadoc を -private スイッチを指定しないで実行した場合に、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 の各メソッドの doc コメントで使用できます。

@throws class-name description
@throws タグと @exception タグは同義です。生成されるドキュメンテーションに、class-name および description テキストを持つ [例外] 小見出しを追加します。class-name は、該当するメソッドによってスローされる可能性のある例外の名前です。このクラスが完全修飾されていない場合、javadoc は検索順序に従ってクラスを探します。

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


タグを使用できる場所

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


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

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

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

概要タグ
@see
{@link}
@since

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

パッケージタグは、パッケージのドキュメンテーションコメント (package.html という名前のソースファイルに存在) で使用できるタグです。

パッケージタグ
@see
{@link}
@since
@deprecated

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

次に示すのは、クラスまたはインタフェースのドキュメンテーションコメントで使用できるタグです。

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

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

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

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

次に示すのは、フィールドのドキュメンテーションコメントで使用できるタグです。

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

次は、フィールドコメントの例です。

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

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

次に示すのは、コンストラクタまたはメソッドのドキュメンテーションコメントで使用できるタグです。

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

次はメソッドの doc コメントの例です。

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

コマンド行引数ファイル

javadoc コマンドを短く簡潔にするために、ファイルの各行に 1 つのソースファイル名またはパッケージ名が記述されたファイルを 1 つまたは複数指定することができます。Javadoc の実行時に、ファイル名をファイルのリストとして指定するには、ファイル名の前に「@」文字を付けて渡します。javadoc は、「@」文字で始まる引数に遭遇すると、そのファイルに記述されたファイル名がコマンド行に書かれていたかのように処理を行います。

たとえば、packages というファイル内に、すべてのパッケージ名を列挙できます。ファイルは、次のようになります。 

     com.mypackage1
     com.mypackage2
     com.mypackage3
次のコマンドを使って、javadoc を実行できます。 
  % javadoc -d apidocs @packages

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

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

-1.1
-author
-bootclasspath
-bottom
-charset
-classpath
-d
-docencoding
-doclet
-docletpath
-doctitle
-encoding
-extdirs
-footer
-group
 -header
-help
-helpfile
-J
-link
-linkoffline
-locale
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-nosince
-notree
-overview
 -package
-private
-protected
-public
-serialwarn
-sourcepath
-splitindex
-stylesheetfile
-title
-use
-verbose
-version
-windowtitle

Javadoc のオプション

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

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

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

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

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

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

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

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

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

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

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

-1.1
Javadoc 1.1 によって生成されるドキュメンテーションの外観および機能を持つドキュメンテーションを生成します。生成されるページの背景は灰色になり、ヘッダにはイメージが使われ、表ではなく丸印を使ったリストが使われます。 また、生成先ディレクトリは平坦な構造になり、継承された API は含まれなくなり、HTML フレームは使われず、内部クラスはサポートされません。また、このオプションでは、索引をアルファベットごとに自動的に分類し、別々のファイルに格納します。このような外観を持つ出力を得たい場合、このオプションを使うと、javadoc 1.1 に存在していたいくつかのバグを回避できる利点があります。

-1.1 オプションとは同時に使用できないオプションがあります。使用可能な他のオプションを見つけるには、次のようにコマンド入力します。 

  % javadoc -1.1 -help
このリスト内の -footer オプションの機能は、このページの別の場所で説明する -bottom オプションと同じです。-title オプションの機能は、-doctitle オプションと同じです。

-sourcepath  sourcepathlist
javadoc コマンドにパッケージ名を渡す際に、ソースファイル (.java) 検索用のパスを指定します。-sourcepath オプションは、javadoc コマンドにパッケージ名を渡すときにだけ使用できます。 javadoc コマンドに渡される .java ファイルは検索しません。.java ファイルを検索するには、そのディレクトリに cd によって移動するか、各ファイルの先頭にパスを追加します (「1 つ以上のクラスのドキュメント化」を参照)。-sourcepath が省略された場合は、javadoc はクラスパスを使ってソースファイルを検索します (-classpath を参照)。したがって、デフォルトの -sourcepath はクラスパスの値です。-classpath を省略してパッケージ名を 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) になることを理解しておくと簡単です。

-classpath  classpathlist
javadoc が参照されるクラス (.class) を検索するパスを指定します。 参照されるクラスとは、ドキュメント化されるクラスとそれらのクラスによって参照される任意のクラスのことです。javadoc は、指定されたパス以下のすべてのサブディレクトリで検索を行います。classpathlist には、パス間をコロンで区切って複数のパスを含めることができます。classpathlist の指定については、クラスパスのドキュメントを参照してください。

-sourcepath を省略した場合は、Javadoc は、クラスファイル (下位互換用) とともに、-classpath を使ってソースファイルを検索します。このため、異なるパス内のソースファイルおよびクラスファイルを検索する場合は、-sourcepath と -classpath の両方を使います。

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

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

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

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

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

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

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

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

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

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

   % javadoc -J-version

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

-d  directory
生成された HTML ファイルを保存するディレクトリを指定します (d は「生成先 (destination)」の意味)。このオプションを省略すると、生成されたファイルは現在のディレクトリに保存されます。値 directory には、絶対ディレクトリまたは現在の作業ディレクトリからの相対ディレクトリを指定できます。たとえば、次の例は、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 の <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.3" com.mypackage

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

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

-link  extdocURL
javadoc により生成された既存の外部参照クラスのドキュメンテーションへのリンクを作成します。引数 extdocURL は、リンクを設定する外部ドキュメントの URL です。絶対 URL または 相対 URL のどちらかを指定できます。 相対 URL は生成先ディレクトリ (-d で指定) の相対位置となります。

言い換えると、このオプションを使うと、コードによって参照されていても、現在の javadoc の実行ではドキュメント化されないクラスにリンクできるようになります。リンクが有効なページに移動するようにするには、それらの HTML ページがどこにあるかを調べ、その場所を extdocURL に指定する必要があります。このオプションを使うと、たとえばサードパーティのドキュメンテーションから http://java.sun.com の java.* ドキュメンテーションにリンクすることができます。また、パッケージのセット間をクロスリンクさせることもできます。さらに、一連のパッケージに対して javadoc を実行したあと、これらのパッケージのサブセットに対してもう一度 javadoc を実行することで、一連のパッケージ全体のリンクを維持することもできます。3 回目の使用は、ドキュメントの更新用の「ハッキング」としての使用です。つまり、パッケージのセット全体に javadoc を実行してから、更新されたファイルをオリジナルのセットに挿入できるように、変更したパッケージの一部のセットだけに javadoc を実行します。この方法は時間を節約するために使われますが、扱いが難しいことがあります。 サブセットに対して API の追加または削除を行なった場合は、索引内のリンクが失われたり、壊れたりします。

-link オプションの使用法は、次のとおりです。

  • 現在実行中の javadoc によって生成されるドキュメンテーション内の API だけを対象にリンクを作成する場合は、-link オプションを省略します。ただし、-link オプションがない場合、javadoc はドキュメントが存在するかどうか、また存在する場所を判別できないため、ドキュメントに外部参照のためのリンクを作成しません。

  • javadoc で、外部参照クラスの、extdocURL にあるドキュメンテーションへのリンクも作成する場合は、-link オプションを指定します。

URL が World Wide Web 上にある場合、javadoc がパッケージリストにアクセスするには、ドキュメンテーションの生成時に Web 接続が可能な状態になっていなければなりません。Web 接続が不可能な場合は、代わりに -linkoffline を使用できます。

パッケージリスト - -link オプションでは、javadoc によって生成された package-list という名前のファイルが、このオプションで指定する URL に存在している必要があります。package-list ファイルは、その場所でドキュメント化されているパッケージの名前のリストを含む単純なテキストファイルです。javadoc がどのようにパッケージリストを使用するかについては、以下で説明します。

たとえば、Java 2 プラットフォーム v1.3 API のパッケージリストは http://java.sun.com/products/jdk/1.3/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 オプションが指定されている場合、javadoc は、指定された extdocURL の package-list ファイルから、該当する名前のパッケージを探します。パッケージ名が見つかった場合は、その URL を名前の前に付けます。

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

javadoc 指定された引数がパッケージではなくソースファイルである場合は、package-list ファイルは作成されますが、ファイルの内容は空になります。

例 - たとえば、次のコマンドにより、Javadoc は、指定された URL で package-list ファイルを検索し、そのファイル内のパッケージ名を読み込んでから、これらの外部パッケージ内の API へのリンクを追加する際に、この指定された URL を使います。 

  % javadoc -link http://java.sun.com/products/jdk/1.3/docs/api com.mypackage
複数のリンク - 複数の -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 番目のドキュメントとその外部リンクを生成します。javadoc は、必要な外部の package-list ファイルが存在しない場合は、警告を表示します。

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

まず、この部分的な新規実行用の実行先ディレクトリを作成し、-link および -d に同じ相対パスを設定します。オリジナルのドキュメントが html という名前のディレクトリにある場合は、次のようになります。 

  % javadoc -d update -link . html com.mypackage
javadoc の実行が終了したら、update 内に生成されたファイルで、html 内の元のファイルを上書きします。

内容説明: 一般に、javadoc を実行すると、シグニチャー、@see タグ、{@link} タグ、要約、階層、概要、および索引など、生成されたページの至る所に名前のリンクが生成される可能性があります。これらのリンクの一部は現在の実行で生成されるページに置かれますが、別のリンクは現在の実行では生成されないページに将来的には置かれています。

-linkoffline  extdocURL  packagelistLoc
このオプションは、-link オプションを変えたものです。どちらも、外部参照クラスのドキュメントへのリンクを作成します。javadoc の実行時に、外部ドキュメントの package-list ファイルが、extdocURL (オフライン) に存在せず、別の packageListLoc (ローカル) に存在する場合、-link の代わりにこのオプションを指定する必要があります。これは、javadoc を実行中のシェルが extdocURL への Web アクセスがない場合に発生することがあります。このため、WWW 上でのみ extdocURL にアクセス可能な場合、-linkoffline を設定することにより、ドキュメンテーションの生成時に Web に接続するという制約がなくなります。例を示します。

javadoc を実行するときに、複数の -linkoffline オプションを指定できます。1.2.2 より前は、複数のオプションを指定することはできませんでした。

引数を次に示します。

  • extdocURL は、javadoc によって生成された、外部ドキュメンテーションのルートの URL です。この場所には、相対 URL または絶対 URL を指定できます。 相対 URL の場合、生成先ディレクトリ (-d で指定) の相対位置で指定します。

  • packagelistLoc は、外部ドキュメンテーションの package-list ファイルを含むディレクトリに対する位置を示します。これは、URL (http: または file:) とファイルパスのどちらでもかまいません。 また、絶対パスと相対パスのどちらでも指定できます。相対パスの場合は、javadoc が実行されるカレントディレクトリの相対パスになります。package-list ファイル名を含めてはなりません。

たとえば、http://java.sun.com/products/jdk/1.3/docs/api にある java.lang パッケージにリンクを設定するが、シェルから Web にアクセスできない場合、http://java.sun.com/products/jdk/1.3/docs/api/package-list の package-list ファイルにアクセスして、ローカルディレクトリに保存し、packagelistLoc でこのローカルコピーをポイントします。

package-list ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合、このファイルを手動で独自に作成し、packagelistLoc でそのパスを指定します。この方法は、パッケージ名はわかっているもののまだ公開されていない、新しい外部ドキュメンテーションにリンクするドキュメンテーションを生成する必要がある場合に便利です。Javadoc 1.0 や 1.1 などの初期バージョンで生成されたドキュメンテーションへのリンクを設定するための package-list ファイルを作成する方法もあります。 これらの初期バージョンでは package-list ファイルは生成されませんでした。

2 つの企業が未公開の package-list ファイルを共有することも可能であるため、クロスリンクが設定されているドキュメンテーションを同時にリリースすることも可能です。

次に示すように、このオプションを使うには、外部参照クラスの javadoc 生成ドキュメンテーションの場所を示す extdocURL1 と、このドキュメンテーションの package-list ファイルの場所を示す packagelistLoc1 を指定します。-linkoffline は、参照先の各生成ドキュメント 1 回ずつインクルードします。 次の例では、わかりやすくするためにオプションごとに行を分けています。

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

たとえば、次のコマンドは、package-list ファイル (2 番目の引数で場所を指定) にあるパッケージのドキュメントを指すリンク (最初の引数で指定) を追加します。 

% javadoc -linkoffline http://java.sun.com/products/jdk/1.3/docs/api /jdk/1.3/docs/api/ ...

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

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

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

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

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

  % javadoc -group "Core Packages" "java.lang*:java.util"
            -group "Extension Packages" "javax.*"
            java.lang java.lang.reflect java.util javax.servlet java.new
この結果、次のようなグループ化が行われます。
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new

-nodeprecated
推奨されない API をドキュメンテーションに生成することを禁止します。これは、-nodeprecatedlist オプションを指定した場合の動作に加えて、ドキュメンテーションのほかの部分を通じて、推奨されない API を生成しないことと同じです。このオプションは、コードを記述していて、推奨されないコードを無視したい場合に便利です。

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

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

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

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

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

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

-helpfile  path/filename
上部と下部のナビゲーションバーの [ヘルプ] リンクのリンク先となる代替ヘルプファイル path/filename のパスを指定します。このオプションが指定されていない場合、javadoc は、javadoc にハードコードされているヘルプファイル help-doc.html を自動的に作成します。このオプションを使えば、デフォルトの設定をオーバーライドできます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 文字セットを指定します。例を示します。 
  % 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 ファイルのエンコーディングを指定します。


簡単な例

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

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

パッケージをドキュメント化するには、そのパッケージのソースファイル (*.java) が、パッケージと同じ名前を持つディレクトリ内に存在していなければなりません。パッケージ名が、(ドットで区切られた) いくつかの識別子から構成されている場合は、各識別子がそれぞれ別のディレクトリを表します。したがって、すべての java.awt クラスは、java/awt/ という名前のディレクトリに存在していなければなりません。javadoc は、次の 2 つのどちらかの方法で実行できます。 1 つは、(cd によって) ディレクトリを変更する方法、もう 1 つは -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 は、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。 
  % 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 を実行するために使う効果的なコマンドです。ここでは、180M バイトのメモリを使用して、Java 2 Platform, Standard Edition, v1.2 に存在する、約 1500 の public および protected クラスのドキュメントを生成します。

この例を 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                                               \  
    @filelist
filelist は、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 オプションによってオーバーライドされます。ディレクトリはコロンで分割します。たとえば、次のとおりです。 
.:/home/classes:/usr/local/java/classes

トラブルシューティング

現在のところ、Javadoc のエラーメッセージに関するドキュメントは存在しません。 トラブルシューティングに関するヒントは、Javadoc FAQ を参照してください。

関連項目

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

JavadocTM は Sun Microsystems, Inc の商標です。(javadoc コマンド自体には商標シンボルは必要ありません。)