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

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

目次

形式

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

解説

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

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

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

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

コンパイラに依存することによって、HTML 出力が、実際の実装に正確に対応することが保証されます。実際の実装は、明示的でなく暗黙的にソースコードに依存している場合があります。たとえば、Javadoc は、.class ファイル内には存在するが、ソースコード内には存在しないデフォルトコンストラクタ (「Java Language Specification」の項 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 は、Java 言語ソースファイル (.java)、パッケージコメントファイル、概要コメントファイル、およびその他の処理されないファイルの 4 種類の「ソース」ファイルを基にして、出力を生成します。これから、Java 言語ソースファイルを除く 3 種類のソースファイルについて説明します。

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

各パッケージは、独自のドキュメンテーションコメントを持つことができ、「ソース」ファイルに保持します。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 つ持つことができます。たとえば、ボタンの画像 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 から表示するようにすると、フレームを省略できます。

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 インタフェースを使用するページ

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

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

ソースコードの任意のエンティティ (クラス、インタフェース、メソッド、コンストラクタ、またはフィールド) の宣言の前には、ドキュメンテーションコメントを入れることができます。このコメントは、Javadoc コメントとも呼ばれ、テキストは 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
 */

doc コメントは、コメントの始まりを示す文字列 /** とコメントの終わりを示す文字列 */ との間にある文字で構成されます。doc コメントのテキストは、1 つ以上の行に分かれます。javadoc は、doc コメントを解析するときに、各行の先頭にある文字アスタリスク (*) をすべて破棄します。また、最初のアスタリスク (*) より前の空白とタブも破棄します。また、最初のアスタリスク (*) より前の空白とタブも破棄します。コメントには、HTML タグを含めることができます。行頭のアスタリスクを省略した場合は、行頭のすべての空白が削除されます。行頭のアスタリスクはある程度まで省略できます。行頭のアスタリスクを省略することで問題が発生する例として、サンプルコードなどで <pre> タグを使って複数の行に渡るインデントを設定する場合が挙げられます。行頭のアスタリスクがないと、行頭の空白が削除されるため、生成されるドキュメント内でインデントが失われます。

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

ドキュメンテーションコメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置かれているときにだけ認識されます。1 つの宣言につき 1 つのドキュメンテーションコメントだけが Javadoc ツールによって認識されます。

doc コメント内に HTML タグを埋め込む場合は、<H1>、<H2> などの HTML 見出しタグを使わないでください。javadoc では、構造化されたドキュメント全体が javadoc によって作成されるため、構造化タグがあると、生成されるドキュメントのフォーマットが乱れます。

@ 文字で始まるドキュメンテーションコメントの最初の行は、説明が終了し、タグ付き段落セクションが開始することを表します。上の例のタグ @see は、このようなタグ付き段落です。

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


javadoc のタグ

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

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

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

タグ 導入された JDK のバージョン
@author 1.0
@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 行に複数の名前を指定します。

@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  name  label}
指定された名前を指すインラインリンクを挿入します。このタグの name と 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 を指すリンクまたはテキストエントリを持つ [関連項目] 見出しを追加します。doc コメントには任意の数の @see タグを含めることができ、これらのタグはすべて同じ見出しの下にまとめられます。@see タグには次の 3 つの形式があります。3 番目がもっとも一般的な形式です。

@see "string"     注 - この形式は JDK1.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 を省略した場合は、該当する名前が <code> HTML タグで囲まれて、表示テキストとして代わりに表示されます。ラベルは、表示テキストを短縮する場合や、該当する名前と異なる表示テキストを指定する場合に使います。

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

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

  • 空白文字は package.class#member と label の間の区切り文字です。括弧内の空白文字は、ラベルの開始を意味しないため、メソッドのパラメータ間のデリミタとして使うことができます。

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

 /**
  * @see String#equals(Object) equals
  */
標準ドックレットは、次のような HTML を生成します。 
<dl>
<dt><b>関連項目:</b>
<dd><a href="../../java/lang/String#equals(java.lang.Object)">equals</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 Language Specification」の第 6 章「Names」で正式に定義され、内部クラス仕様で修正されています。具体的には、検索は次の順序で行われます。

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

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

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

名前の表示方法 - label が省略された場合は、package.class.member が表示されます。通常、package.class.member は、現在のクラスおよびパッケージに応じて適切に短くされます。「短くされる」とは、Javadoc が必要最小限の名前を表示するということです。たとえば、次のようになります。

@see タグを含むメソッド @see タグ 表示
String.toUpperCase() @see String#toLowerCase()
(同じクラスのメンバを参照) 		toLowerCase()
(クラス名を省略)
String.toUpperCase() @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(Objetc)              //  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 JDK1.1

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

省略可能な field-description は、フィールドの doc コメントを拡張します。この説明では、フィールドの意味および取り得る値のリストを指定しなければなりません。必要な場合には、複数の行にまたがって説明を記述することができます。

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

private クラスの直列化された形式を取得するには、-private オプションを使います。したがって、public および private クラスの両方の直列化された形式を生成するには、javadoc でこの -private オプションを使います。

これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の 1.6 節 「クラスの直列化可能なフィールドおよびデータの文書化」を参照してください。

@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 つ以下です。通常、バージョンは、該当するクラスまたはメンバを含むソフトウェア (JDK など) のバージョンを指します。


タグを使用できる場所

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


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

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

注 - JDK 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%, %G%
 * @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 は、@ 文字で始まる引数に遭遇すると、そのファイルに記述されたファイル名がコマンド行に書かれていたかのように処理を行います。

たとえば、packages というファイル内に、次のようにすべてのソースファイル名のリストを記述できます。 

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

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

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

-1.1
-author
-bootclasspath
-bottom
-classpath
-d
-docencoding
-doclet
-docletpath
-doctitle
-encoding
-extdirs
-footer
-group
 -header
-help
-helpfile
-J
-link
-linkoffline
-locale
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-notree
-overview
 -package
-private
-protected
-public
-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 で指定するファイルについては、「概要コメントファイル」を参照してください。

特定の状況下では、概要ページが生成されません。詳細は、「HTML フレーム」を参照してください。

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

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

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

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

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

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

-docletpath  classpathlist
-doclet オプションで指定されているドックレットクラスファイルへのパスを指定します。目的のドックレットが検索パス内にある場合は、このオプションは不要です。

-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 ファイルは検索できないことに注意してください。-sourcepath が省略された場合は、javadoc はクラスパスを使ってソースファイルを検索します (-classpath を参照)。

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 が参照されるクラスの検索を行うパスを指定します。参照されるクラスとは、ドキュメント化されるクラスとそれらのクラスによって参照される任意のクラスのことです。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
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 バイトを確保する必要がある場合は、次のようにします。

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

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

-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 テキストを含めます。このテキストは、デフォルトでは省略されます。

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

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

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

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

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

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

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

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

-link  docURL
javadoc により生成された既存の外部参照クラスのドキュメンテーションへのリンクを作成します。引数 docURL は、リンクを設定する、javadoc で生成した外部ドキュメントの URL です。この場所は、相対 URL または絶対 URL で指定できます。

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

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

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

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

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

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

たとえば、Java プラットフォーム 1.2 API のパッケージリストは http://java.sun.com/products/jdk/1.2/docs/api/package-list にあり、次のようになっています。 

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

-link オプションを指定せずに javadoc を実行した場合、ドキュメンテーションの生成時に外部参照クラスに属する名前を見つけると、javadoc はその名前をリンクを持たない形で出力します。一方、-link オプションが指定されている場合、javadoc は、指定された docURL の場所にある package-list ファイルから、該当する名前のパッケージを探します。パッケージ名が見つかった場合は、その URL を名前の前に付けます。指定された URL が相対 URL で、-d オプションの生成先ディレクトリが相対パスである場合、javadoc は URL に生成先ディレクトリの相対パスを付加し、生成先ディレクトリを起点としてリンクが動作するようにします。

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

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

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

  % javadoc -link http://java.sun.com/products/jdk/1.2/docs/api com.mypackage
複数のリンク - 複数の -link オプションを提供して、外部で生成されたドキュメントに任意数のリンクを設定できます。既知のバグ - Javadoc 1.2 には、複数の -link コマンドを提供できないというバグがあります。このバグは、将来のリリースでは修正される予定です。

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

   % javadoc -link docURL1 -link docURL2 ... -link docURLn com.mypackage

docURL1、docURL2、... docURLn は、それぞれ外部ドキュメントのルートを指し、各ルートには、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 -linkoffline . html com.mypackage
javadoc の実行が終了したら、update 内に生成されたファイルで、html 内の元のファイルを上書きします。

内容説明: 一般に、javadoc を実行すると、シグニチャー、@see タグ、{@link} タグ、要約、階層、概要、およびインデックスなど、生成されるページ全体を通じて表示される名前のリンクが潜在的には生成されています。これらのリンクの一部は現在の実行で生成されるページに置かれますが、別のリンクは現在の実行では生成されないページに潜在的には置かれています。

-linkoffline  docURL  packagelistURL
このオプションは、外部参照クラスの名前を対象として、ドキュメンテーションへのリンクを作成します。

  • docURL は、javadoc によって生成された、リンク先の外部ドキュメンテーションのルートの場所の URL です。この場所には、相対 URL または絶対 URL を指定できます。

  • packagelistURL は、リンク先の外部ドキュメンテーションの package-list ファイルを含むディレクトリの URL です。このファイルは、必要に応じて手動で作成することもできます。

このオプションは、-link オプションの変種です。-linkoffline オプションは、javadoc の実行時に、docURL で指定された場所に packages-list ファイルが存在しない場合に使用できます。生成されるドキュメントのリンク先のパッケージ名と、該当するドキュメントが存在する場所がわかっている場合は、このオプションを使うと、該当する場所に package-list ファイルがまだ実際には存在していなくても、外部リンクを持つドキュメンテーションを生成できます。このオプションを使えば、package-list のコピーを独自に用意することで、適切なリンクを持ったドキュメンテーションを生成できます。

この方法は、パッケージ名はわかっているもののまだ公開されていない、新しい外部ドキュメンテーションをリンク先に持つドキュメンテーションを生成する必要がある場合に便利です。この方法を使えば、2 つの企業がそれぞれのドキュメンテーションを同時にリリースできます。また、package-list が存在しない外部ドキュメンテーション (javadoc 1.0、1.1、および 1.2 Beta3 までで作成されたドキュメンテーションなど) にリンクしたドキュメンテーションを生成することもできます。

このオプションを指定する場合は、javadoc を実行する時点で、ドキュメンテーションの URL にアクセスできるようになっている必要はありません。したがって、URL が World Wide Web 上にある場合は、Web 接続を行わなくてもドキュメンテーションを生成できます。

次に示すように、このオプションを使うには、javadoc によって生成された、外部参照クラスのドキュメンテーションの場所を示す docURL1 と、このドキュメンテーションの package-list ファイルの場所を示す packagelistURL1 を指定します。両者が同じ場所にある場合は、-linkoffline ではなく、-link を使用できます。-linkoffline は、参照先の生成されたドキュメントごとに指定します。

% javadoc -linkoffline docURL1 packagelistURL1 -linkoffline docURL2 packagelistURL2

たとえば、次のコマンドは、第 1 引数として渡された URL を使ってリンクを追加し、第 2 引数で渡された package-list ファイルを検索します。 

% javadoc -linkoffline http://java.sun.com/products/jdk/1.2/docs/api /usr/web/work/products/jdk/1.2/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 がソースコードに含まれておらず、ナビゲーションバーをすっきりと見せたい場合に便利です。

-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
-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 は、次の 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 には、多くの便利なオプションがあり、その中のいくつかは、ほかのオプションよりもよく使われます。以下は、makefile 変数を使って Java プラットフォーム API 上で javadoc を実行するために使う効果的なコマンドです。ただし、ドキュメント化されるパッケージのすべてがリストされているわけではありません。 
javadoc -sourcepath /jdk/src/share/classes ¥   /* Path for source files          */
        -d /jdk/build/api                  ¥   /* 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)                ¥   /* Core heading for overview page */
        -group $(GROUPEXT)                 ¥   /* Ext heading for overview page  */
        -overview overview-core.html       ¥   /* For overview text              */
        -J-Xmx180m                         ¥   /* For 180MB memory               */
        java.lang java.lang.reflect        ¥   /* Packages to document           */
        java.util java.io java.net         ¥
        java.applet
        
WINDOWTITLE = 'Java Platform 1.2 Final API Specification'
DOCTITLE = 'Java<sup><font size="-2">TM</font></sup> Platform 1.2 Final API Specification'
HEADER = '<b>Java Platform 1.2</b><br><font size="-1">Final</font>'
BOTTOM = '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit
    a bug or feature</a><br><br>Java is a trademark or registered trademark 
    of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-1998    
    Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.  
    All Rights Reserved.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"
GROUPEXT  = '"Extension Packages" "javax.*"'

-windowtitle オプションを省略した場合は、javadoc は、ウィンドウタイトルにドキュメントタイトルをコピーします。ドキュメントタイトルに HTML タグが含まれていない場合は、-windowtitle オプションは必要ありません。

この例のように -footer オプションを省略した場合は、javadoc は、ヘッダテキストをフッタにコピーします。

このほかに重要なものは、-classpath オプションと -link オプションです。


環境

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

関連項目

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