Java Platform, Standard Editionツール・リファレンス
目次    前    次

javadoc

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

形式

javadoc {packages|source-files} [options] [@argfiles]

packages

ドキュメント化するパッケージの名前をスペースで区切ったものです。たとえば、java.lang java.lang.reflect java.awtのように指定します。サブパッケージもドキュメント化するには、-subpackagesオプションを使用してパッケージを指定します。

デフォルトでは、javadocは指定されたパッケージを現在のディレクトリおよびそのサブディレクトリで検索します。パッケージを検索するディレクトリのリストを指定するには、-sourcepathオプションを使用します。

source-files

ドキュメント化するJavaソース・ファイルの名前をスペースで区切ったものです。たとえば、Class.java Object.java Button.javaのように指定します。デフォルトでは、javadocは指定されたクラスを現在のディレクトリで検索します。ただし、クラス・ファイルのフル・パスを指定し、ワイルドカード文字を使用することができます。たとえば、/home/src/java/awt/Graphics*.javaのように指定します。現在のディレクトリからの相対パスを指定することもできます。

options

コマンド行オプションをスペースで区切ったものです。「オプション」を参照してください。

@argfiles

javadocコマンド・オプション、パッケージ名、およびソース・ファイル名を任意の順序で並べたリストが含まれているファイルの名前です。

説明

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

javadocコマンドは、パッケージ全体、個々のソース・ファイル、またはその両方に対して実行できます。パッケージ全体をドキュメント化する場合は、ディレクトリとそのサブディレクトリを再帰的にたどるために-subpackagesを使用するか、パッケージ名の明示的なリストを渡します。個々のソース・ファイルをドキュメント化する場合は、Javaソース・ファイル名のリストを渡します。「簡単な例」を参照してください。

適合性

標準ドックレットではドキュメンテーション・コメントの内容の適合性が検証されることはなく、ドキュメンテーション・コメントのエラーを修正しようとすることもありません。javadocコマンドを実行するときは、整合性のない出力やJavaScriptなどの実行可能コンテンツを含む出力を生成する際に生じる可能性のある問題について注意してください。標準ドックレットには、ドキュメンテーション・コメントの一般的な問題を検出するのに役立つ-Xdoclintオプションがありますが、生成された出力を適切な適合性およびチェック・ツールでチェックすることもお薦めします。

HTML5ドキュメントの適合性要件の詳細は、HTML5仕様のConformance requirementsを参照してください。Webページに関連したセキュリティ問題の詳細は、Open Web Application Security Project (OWASP)を参照してください。

ソース・ファイルの処理

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

  • ファイル名の接頭辞(.javaを取り除いたもの)が、有効なクラス名になっている。

  • ソース・ツリーのルートからの相対的なパス名が、区切り文字をドットに変換すると、有効なパッケージ名になっている。

  • パッケージ文には有効なパッケージ名が含まれている。

リンクの処理

javadocコマンドは、処理の実行中に、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、相互参照リンクを追加します。このようなリンクは、次の場所に追加されます。@タグについては、「Javadocタグ」を参照してください。

  • 宣言(戻り値の型、引数の型、およびフィールドの型)。

  • @seeタグから生成された関連項目セクション。

  • {@link}タグから生成されたインライン・テキスト。

  • @throwsタグから生成された例外の名前。

  • インタフェースのメンバーに対する定義リンクと、クラスのメンバーに対するオーバーライド・リンク「メソッド・コメントの継承」を参照してください。

  • パッケージ、クラス、およびメンバーを列挙しているサマリー表。

  • パッケージおよびクラスの継承ツリー。

  • 索引

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

処理詳細

javadocコマンドは、実行するたびに1つの完全なドキュメントを作成します。以前の実行結果を変更したり直接組み入れたりする追加生成は行いません。ただし、javadocコマンドでは、以前の実行結果に対してリンクを追加することはできます。

javadocコマンドの実装は、Javaコンパイラを必要とし、Javaコンパイラに依存しています。javadocコマンドは、javacコマンドの一部を呼び出すことによって宣言をコンパイルし、メンバーの実装は無視します。javadocコマンドは、クラス階層を含むクラスの豊富な内部表現とクラスの使用関係を構築して、HTMLを生成します。さらに、javadocコマンドは、ソース・コードのドキュメンテーション・コメントから、ユーザーの提供したドキュメントも取得します。「ドキュメンテーション・コメント」を参照してください。

javadocコマンドは、メソッド本体のない純粋なスタブ・ファイルであるソース・ファイル上で実行されます。したがって、APIの実装を記述する前の設計の早い段階で、ドキュメンテーション・コメントを記述してjavadocコマンドを実行できます。

コンパイラに依存することによって、HTML出力は、実際の実装に正確に対応します。実際の実装は、明示的なソース・コードにではなく、暗黙のソース・コードに依存する場合があります。たとえば、javadocコマンドは、コンパイル済みクラス・ファイル内に存在するが、ソース・コード内には存在しないデフォルト・コンストラクタをドキュメント化します。

通常、javadocコマンドでは、ソース・ファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。デバッグやトラブルシューティングを完了する前にドキュメントを生成できます。javadocコマンドはドキュメンテーション・コメントの基本的なチェックを行います。

javadocコマンドは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、javadocコマンドは、ブートストラップ・クラス、拡張機能、またはユーザー・クラスにかかわらず、すべての参照クラスを検索できなければなりません。次の場所にある「クラスの検索方法」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/tools/findingclasses.html

通常、作成するクラスは、拡張機能としてロードするか、javadocコマンドのクラス・パス内に置く必要があります。

Javadocのドックレット

javadocコマンドの出力の内容と形式は、ドックレットを使ってカスタマイズできます。javadocコマンドには、標準ドックレットと呼ばれるデフォルトの組込みドックレットがあります。標準ドックレットは、HTML形式のAPIドキュメントを生成します。標準ドックレットを修正またはそのサブクラスを作成することや、HTML、XML、MIF、RTFなどの好みの出力形式を生成する独自のドックレットを記述することも可能です。

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

ソース・ファイル

javadocコマンドは、次に示す種類のソース・ファイルから出力結果を生成します。そのファイルは、クラスのJava言語ソース・ファイル(.java)、パッケージ・コメント・ファイル、概要コメント・ファイル、およびその他の処理されないファイルです。このセクションでは、ドキュメント化したくないがソース・ツリーに存在する場合があるテスト・ファイルやテンプレート・ファイルについても説明します。

クラス・ソース・ファイル

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

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

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

パッケージ・コメント・ファイルを作成する場合、次のファイルのいずれかにコメントを格納できます。

  • package-info.javaファイルには、パッケージ宣言、パッケージ注釈、パッケージ・コメント、およびJavadocタグを格納できます。このファイルをお薦めします。

  • package.htmlファイルに格納できるのはパッケージ・コメントとJavadocタグだけです。パッケージ注釈は格納できません。

各パッケージは、単一のpackage.htmlファイル、単一のpackage-info.javaファイルのいずれかを持つことができますが、両方を持つことはできません。このどちらかのファイルをソース・ファイルとともに、ソース・ツリー内のそのパッケージのディレクトリ内に配置してください。

package-info.javaファイル

package-info.javaファイルには、次の構造のパッケージ・コメントを格納できます。コメントはパッケージ宣言の前に配置します。

注: コメント区切り文字の/**と*/は記述する必要がありますが、中間行の行の先頭のアスタリスクは省略してもかまいません。

/**
 * Provides the classes necessary to create an  
 * applet and the classes an applet uses 
 * to communicate with its applet context.
 * <p>
 * The applet framework involves two entities:
 * the applet and the applet context.
 * An applet is an embeddable window (see the
 * {@link java.awt.Panel} class) with a few extra
 * methods that the applet context can use to 
 * initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

package.htmlファイル

package.htmlファイルには、次の構造のパッケージ・コメントを格納できます。コメントは<body>要素内に配置します。

File: java/applet/package.html

<HTML>
<BODY>
Provides the classes necessary to create an applet and the 
classes an applet uses to communicate with its applet context.
<p>
The applet framework involves two entities: the applet
and the applet context. An applet is an embeddable
window (see the {@link java.awt.Panel} class) with a
few extra methods that the applet context can use to
initialize, start, and stop the applet. 

@since 1.0 
@see java.awt
</BODY>
</HTML>

package.htmlファイルは通常のHTMLファイルであり、パッケージ宣言を含んでいません。パッケージ・コメント・ファイルの内容はHTMLで記述されていますが、例外が1つあります。それは、このドキュメンテーション・コメントには、コメント区切り文字である/**と*/、および行の先頭のアスタリスクを含めてはならない、ということです。コメントを書く場合は、最初の文をパッケージのサマリーとし、<body>タグと最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージ・タグを含めることはできます。すべてのブロック・タグは、主説明の後に置く必要があります。パッケージ・コメント・ファイルに@seeタグを追加する場合は、完全修飾名を使用する必要があります。

コメント・ファイルの処理

javadocコマンドは、実行時にパッケージ・コメント・ファイルを検索します。パッケージ・コメント・ファイルが見つかった場合、javadocコマンドは次の処理を行います。

概要コメント・ファイル

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

このファイルにoverview.htmlなどの任意の名前を付け、任意の場所に置くことができます。通常はソース・ツリーの最上位に置きます。

たとえば、java.appletパッケージのソース・ファイルが/home/user/src/java/appletディレクトリに含まれている場合は、/home/user/src/overview.htmlに概要コメント・ファイルを作成できます。

異なるパッケージのセットに対してjavadocコマンドを複数回実行する場合は、同じ1つのソース・ファイルのセットに対して複数の概要コメント・ファイルを作成できます。たとえば、内部ドキュメンテーション用に-privateを指定してjavadocコマンドを1回実行した後、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメント・ファイルの1文目で、そのドキュメンテーションを公開用または内部用として記述できます。

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

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

処理されないファイル

ソース・ファイルには、javadocコマンドによって生成先のディレクトリにコピーする任意のファイルを含めることができます。一般に、このようなファイルには、グラフィック・ファイル、サンプルのJavaソース・ファイルおよびクラス・ファイル、通常のJavaソース・ファイルのドキュメンテーション・コメントを凌駕する圧倒的な量の内容を持つHTMLファイルなどがあります。

処理されないファイルを含めるには、それらをdoc-filesというディレクトリに置きます。doc-filesディレクトリは、ソース・ファイルがある任意のパッケージ・ディレクトリの下に作成できます。doc-filesサブディレクトリは、パッケージごとに1つ用意できます。

たとえば、ボタンのイメージをjava.awt.Buttonクラスのドキュメントに含める場合は、そのイメージ・ファイルを/home/user/src/java/awt/doc-files/ディレクトリに置きます。doc-filesディレクトリを/home/user/src/java/doc-filesに置くことはできません。これは、javaはパッケージではないからです。そこにソース・ファイルは入っていません。

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

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

テスト・ファイルおよびテンプレート・ファイル

ソース・ツリー内で、ソース・ファイルが置かれているディレクトリと同じディレクトリまたはそのサブディレクトリに、テスト・ファイルとテンプレート・ファイルを格納できます。テスト・ファイルとテンプレート・ファイルが処理されないようにするには、個々のソース・ファイル名を明示的に渡してjavadocコマンドを実行します。

テスト・ファイルは、有効でコンパイル可能なソース・ファイルです。テンプレート・ファイルは、有効でコンパイル可能なソース・ファイルではありませんが、多くの場合.java接尾辞を持っています。

テスト・ファイル

名前のないパッケージまたはソース・ファイルが入っているパッケージとは別のパッケージにテスト・ファイルを所属させるには、ソース・ファイルの下のサブディレクトリに無効な名前を付け、そこにテスト・ファイルを置きます。ソースと同じディレクトリにテスト・ファイルを置き、コマンド行引数でそのパッケージ名を指定してjavadocコマンドを呼び出すと、テスト・ファイルによって警告またはエラーが発生します。無効な名前のサブディレクトリにテスト・ファイルを置いた場合、そのテスト・ファイル・ディレクトリはスキップされ、エラーや警告は発生しません。たとえば、com.package1のソース・ファイルのテスト・ファイルを追加する場合は、無効なパッケージ名を持つサブディレクトリに置きます。次のディレクトリ名はハイフンを含んでいるため無効です。

com/package1/test-files/

テスト・ファイルにドキュメンテーション・コメントが含まれている場合は、com/package1/test-files/*.javaのようにワイルドカードでテスト・ソース・ファイル名を渡してjavadocコマンドを別個に実行すると、テスト・ファイルのドキュメントを生成できます。

テンプレート・ファイル

ソース・ディレクトリにテンプレート・ファイルを置く場合、javadocコマンドの実行時にエラーが発生しないようにするには、このファイルに無効なファイル名(Buffer-Template.javaなど)を付けます。こうすることで、処理されないようになります。javadocコマンドは、.java接尾辞を除いた名前が有効なクラス名であるソース・ファイルだけを処理します。

生成されるファイル

デフォルトでは、javadocコマンドは、HTML形式のドキュメントを生成する標準ドックレットを使います。標準ドックレットは、基本内容、相互参照、およびサポートのページを生成します。これらはここで説明されています。各HTMLページは個別のファイルに相当します。javadocコマンドは2種類のファイルを生成します。最初の種類には、クラスやインタフェースにちなんだ名前が付けられます。2番目の種類には、最初の種類のファイルと競合しないように、ハイフンが含まれています(package-summary.htmlなど)。

基本内容ページ

相互参照ページ

サポート・ページ

  • ヘルプ・ページ(help-doc.html)。ナビゲーション・バーや前述の各ページに関する説明が記載されています。-helpfileを使うと、デフォルトのヘルプ・ファイルを独自のカスタム・ヘルプ・ファイルでオーバーライドできます。

  • 表示用のHTMLフレームを作成する1つのindex.htmlファイル。このファイルは、フレーム付きの先頭ページを表示する場合にロードします。index.htmlファイルには、テキスト内容は含まれていません。

  • いくつかのフレーム・ファイル(*-frame.html)。パッケージ、クラス、およびインタフェースのリストが含まれています。フレーム・ファイルはHTMLフレームを表示します。

  • パッケージ・リスト・ファイル(package-list)。-linkオプションおよび-linkofflineオプションで使用されます。パッケージ・リスト・ファイルはテキスト・ファイルであり、リンクからはアクセスできません。

  • スタイル・シート・ファイル(stylesheet.css)。生成されるページ上のいくつかの要素について、色、フォント・ファミリ、フォント・サイズ、フォント・スタイル、および配置の情報を制御します。

  • doc-filesディレクトリ。生成先ディレクトリにコピーするイメージ、サンプル、ソース・コードなどのファイルがすべて格納されます。これらのファイルは、javadocコマンドによって処理されません。このディレクトリは、ソース・ツリーの中にある場合にのみ処理されます。

「オプション」を参照してください。

HTMLフレーム

javadocコマンドは、コマンドに渡された値に応じて、最低限必要な数(2つまたは3つ)のフレームを作成します。単一のパッケージ名、または単一のパッケージに属するソース・ファイルを引数としてjavadocコマンドに渡した場合、パッケージの一覧は省略されます。かわりに、javadocコマンドは、左側の列にクラスの一覧を表示するフレームを1つ作成します。javadocコマンドに複数のパッケージ名を渡した場合は、概要ページ(overview-summary.html)に加えて、すべてのパッケージを一覧表示する第3のフレームが作成されます。フレームを省略するには、「フレームなし」リンクをクリックするか、overview-summary.htmlページからページ・セットに入ります。

生成されるファイルの構造

生成されるクラス・ファイルおよびインタフェース・ファイルは、Javaソース・ファイルおよびクラス・ファイルと同じディレクトリ階層に編成されます。1つのサブパッケージにつき1つのディレクトリ、という構造になります。

たとえば、java.applet.Appletクラスに対して生成されるドキュメントは、java/applet/Applet.htmlに格納されます。

生成先のディレクトリの名前がapidocsだとすると、java.appletパッケージのファイル構造は下記のようになります。前述のように、frameという語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外のHTMLファイルは、すべて右側のフレームに表示されます。

ディレクトリは太字で示してあります。アスタリスク(*)は、javadocコマンドへの引数がパッケージ名ではなくソース・ファイル名である場合に省略されるファイルおよびディレクトリを示しています。引数がソース・ファイル名の場合は、空のパッケージ・リストが作成されます。doc-filesディレクトリは、ソース・ツリー内に存在する場合にのみ、生成先に作成されます。「生成されるファイル」を参照してください。

  • apidocs: 最上位ディレクトリ

    • index.html: HTMLフレームを設定する最初のページ

    • *overview-summary.html: パッケージ・リストとサマリー

    • overview-tree.html: 全パッケージのクラス階層

    • deprecated-list.html: 全パッケージの非推奨API

    • constant-values.html: 全パッケージのstaticフィールドの値

    • serialized-form.html: 全パッケージの直列化された形式

    • *overview-frame.html: 左上のフレームに表示される全パッケージ

    • allclasses-frame.html: 左下のフレームに表示される全クラス

    • help-doc.html: Javadocのページ構成に関するヘルプ

    • index-all.html: -splitindexオプションなしで作成されるデフォルトの索引

    • index-files: -splitindexオプションによって作成されるディレクトリ

      • index-<number>.html: -splitindexオプションによって作成される索引ファイル

    • package-list: 外部参照を解決するためのパッケージ名

    • stylesheet.css: フォント、色、配置などを定義します

  • 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.html: このパッケージが使用されている場所

      • doc-files: イメージおよびサンプル・ファイルのディレクトリ

      • class-use: イメージおよびサンプル・ファイルの場所

        - Applet.html: Appletクラスの使用

        - AppletContext.html: AppletContextインタフェースの使用

        - AppletStub.html: AppletStubインタフェースの使用

        - AudioClip.html: AudioClipインタフェースの使用

  • src-html: ソース・コード・ディレクトリ

    • java: パッケージ・ディレクトリ

      • applet: サブパッケージ・ディレクトリ

        - Applet.html: Appletのソース・コード

        - AppletContext.html: AppletContextのソース・コード

        - AppletStub.html: AppletStubのソース・コード

        - AudioClip.html: AudioClipのソース・コード

生成されるAPI宣言

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

public final class Boolean
extends Object
implements Serializable

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

public static Boolean valueOf(String s)

javadocコマンドは、修飾子public、protected、private、abstract、final、static、transient、およびvolatileを組み込むことができますが、synchronizedとnativeを組み込むことができません。synchronizedおよびnative修飾子は、実装の詳細と見なされているため、API仕様には含まれません。

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

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

このセクションでは、ソース・コードのコメントとコメント継承について説明します。

ソース・コードのコメント

ソース・コードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーション・コメントを記述できます。また、各パッケージにドキュメンテーション・コメントを作成できます。構文は若干異なりますが、概要にもドキュメンテーション・コメントを作成できます。ドキュメンテーション・コメントは、文字列/**と、コメントの終わりを示す文字列*/の間にある文字で構成されます。行の先頭のアスタリスクは、各行に記述できます。詳細は、次のセクションで説明します。コメントのテキストは、複数行にわたって記述できます。

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

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

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

コメントの配置

ドキュメンテーション・コメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置かれているときにだけ認識されます。メソッドの本体に置かれているドキュメンテーション・コメントは無視されます。javadocコマンドでは、1つの宣言文につき1つのドキュメンテーション・コメントだけが認識されます。「タグを使用できる場所」を参照してください。

よくある間違いは、クラスのコメントとクラスの宣言の間にimport文を置いてしまうことです。javadocコマンドでクラス・コメントが無視されることになるため、import文をこの場所に置かないでください。

/**
 * This is the class comment for the class Whatever.
 */
 
import com.example;   // MISTAKE - Important not to put import statement here
 
public class Whatever{ }

コメントの部分

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

/**
 * This sentence holds the main description for this documentation comment.
 * @see java.lang.Object
 */

ブロック・タグとインライン・タグ

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

/**
 * @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>を使っています。

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

行の先頭のアスタリスク

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

最初の文

各ドキュメンテーション・コメントの最初の文は、宣言されているエンティティに関する簡潔かつ完全なサマリー文である必要があります。この文は、直後にスペース、タブ、または改行が続く最初のピリオド、または最初のブロック・タグがある位置で終わります。最初の文は、javadocコマンドによってHTMLページの最初にあるメンバーのサマリーの部分にコピーされます。

複数フィールドの宣言

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

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

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

public int x

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

public int y

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

見出しタグの使用

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

メソッド・コメントの継承

javadocコマンドでは、クラスとインタフェースのメソッド・コメントの継承により、見つからないテキストを挿入することができます。あるいは、メソッド・コメントを明示的に継承することもできます。コンストラクタ、フィールド、およびネストされたクラスは、ドキュメンテーション・コメントを継承しません。

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

見つからないテキストの挿入

主説明または@return、@param、@throwsタグがメソッド・コメントで見つからない場合、javadocコマンドは、このメソッドがオーバーライドまたは実装しているメソッドがあればそこから、対応する主説明またはタグ・コメントをコピーします。「メソッド・コメントの継承」を参照してください。

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

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

「Javadocタグ」および「オプション」を参照してください。

明示的な継承

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

クラスとインタフェースの継承

クラスおよびインタフェースからの継承が行われる可能性のあるすべての場合に、コメントの継承が行われます。

  • クラスのメソッドがスーパー・クラスのメソッドをオーバーライドしている

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

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

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

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

メソッド・コメントのアルゴリズム

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

  1. 直接に実装されている(または、拡張されている)インタフェースを、メソッドの宣言でimplements (またはextends)キーワードの後に出現する順序で、1つずつ調べます。このメソッドについて最初に見つかったドキュメンテーション・コメントを採用します。

  2. ステップ1でドキュメンテーション・コメントが見つからなかった場合は、直接実装されている(または、拡張されている)インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用します(その際の順序は、ステップ1でインタフェースを調べたときの順序と同じ)。

  3. ステップ2でドキュメンテーション・コメントが見つからなかった場合で、このクラスがObject以外のクラスである(ただし、インタフェースではない)場合は、次のように処理します。

    1. スーパー・クラスにこのメソッドについてのドキュメンテーション・コメントが記述されていれば、そのコメントを採用します。

    2. ステップ3aでドキュメンテーション・コメントが見つからなかった場合は、スーパー・クラスに対して、このアルゴリズム全体を再帰的に適用します。

Javadocタグ

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

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

カスタム・タグについては、-tag tagname:Xaoptcmf:"taghead"を参照してください。「タグを使用できる場所」も参照してください。

タグの説明

@author name-text

JDK 1.0で導入

-authorオプションが使われている場合、生成ドキュメントに「作成者」の項目を追加し、指定されたname-textを書き込みます。1つのドキュメンテーション・コメントに複数の@authorタグを含めることができます。1つの@authorタグに1つの名前を指定することも、1つのタグに複数の名前を指定することもできます。前者の場合は、javadocコマンドによって、名前の間にカンマ(,)とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにコピーされます。したがって、カンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1つのタグに複数の名前を指定してください。Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、@authorのセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@author

{@code text}

JDK 1.5で導入

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

テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、テキストをコード・フォントで表示します。これにより、ドキュメンテーション・コメントで、HTMLエンティティ(&lt;および&gt;)のかわりに、パラメータ型(<Object>)、不等号(3 < 4)、または矢印(<-)のように通常の山カッコ(<および>)を使用できます。たとえば、ドキュメンテーション・コメントのテキスト{@code A<B>C}は、生成されたHTMLページでそのままA<B>Cと表示されます。つまり、<B>は太字であると解釈されず、コード・フォントになります。コード・フォントなしで同じ機能を実現するには、{@literal}を使用します。

@deprecated deprecated-text

JDK 1.0で導入

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

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

プログラムの要素を非推奨にするには、@deprecated注釈を使用します。次の場所にある「いつ、どのようにAPIを非推奨とするか」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/guides/javadoc/deprecation/deprecation.html

Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、@deprecatedのセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@deprecated

{@docRoot}

JDK 1.3で導入

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

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

  • コマンド行では、ヘッダー、フッター、またはボトムを定義する場合、次のようにします。javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'

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

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

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

    このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。<a href="{@docRoot}/copyright.html">という表現は、java/lang/Object.javaの場合は<a href="../../copyright.html">に解決され、java/lang/ref/Reference.javaの場合は<a href="../../../copyright.html">に解決されます。

@exception class-name description

JDK 1.0で導入

@throwsタグと同じです。@throws class-name descriptionを参照してください。

{@inheritDoc}

JDK 1.4で導入

もっとも近い継承可能なクラスまたは実装可能なインタフェースから、このタグの現在のドキュメンテーション・コメントに、ドキュメントを継承(コピー)します。この機能により、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使って記述することができます。

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

  • メソッドの主説明ブロック内。この場合、主説明は、上位階層のクラスまたはインタフェースからコピーされる

  • メソッドの@return、@param、@throwsタグのテキスト引数内。この場合、タグ・テキストは、上位階層の対応するタグからコピーされる

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

{@link package.class#member label}

JDK 1.2で導入

表示テキストlabelを持つインライン・リンクを挿入します。このリンクは、参照クラスの指定されたパッケージ、クラス、またはメンバー名のドキュメンテーションを指し示します。このタグは、すべてのドキュメンテーション・コメント(概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールド)で有効です。また、@return、@param、@deprecatedタグなどの任意のタグのテキスト部分でも有効です。Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、@linkのセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#{@link

このタグは@seeタグに似ています。どちらのタグも、参照を必要とし、package.class#memberおよびlabelの構文を受け入れます。大きな違いは、{@link}タグは、リンクを「関連項目」セクションに置くのではなく、インライン・リンクを生成するということです。インライン・テキストの他の部分と区別するために、{@link}タグの最初と最後に中カッコを記述します。ラベルの中で右中カッコ(})を使う必要がある場合は、HTMLエンティティ表記「&#125;」を使います。

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

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

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

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

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

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

Use the getComponentAt method.
{@linkplain package.class#member label}

JDK 1.4で導入

リンクのラベルがコード・フォントではなくプレーン・テキストで表示される点以外は{@link}と同じ動作になります。ラベルがプレーン・テキストで記述されていると便利です。たとえば、Refer to {@linkplain add() the overridden method}は、Refer to the overridden methodと表示されます。

{@literal text}

JDK 1.5で導入

テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、textを表示します。これにより、ドキュメンテーション・コメントで、HTMLエンティティ(&lt;および&gt;)のかわりに、パラメータ型(<Object>)、不等号(3 < 4)、または矢印(<-)のように山カッコ(<および>)を使用できます。たとえば、ドキュメンテーション・コメントのテキスト{@literal A<B>C}は、生成されたHTMLページでそのままA<B>Cとブラウザに表示されます。<B>は太字であると解釈されません(コード・フォントにならない)。コード・フォントで同じ機能を実現するには、{@code}タグを使用します。

@param parameter-name description

JDK 1.0で導入

指定したparameter-nameと指定したdescriptionを使用してパラメータを「パラメータ」セクションに追加します。ドキュメンテーション・コメントを記述するときは、descriptionを複数行に続けることができます。このタグは、メソッド、コンストラクタ、またはクラスのドキュメンテーション・コメント内でのみ有効です。Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、@paramのセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@param

parameter-nameは、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタの型パラメータの名前になります。山カッコでパラメータ名を囲むと、型パラメータを使用することを指定します。

クラスの型パラメータの例:

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

メソッドの型パラメータの例:

/**
 * @param string  the string to be converted
 * @param type    the type to convert the string to
 * @param <T>     the type of the element
 * @param <V>     the value of the element
 */
<T, V extends T> V convert(String string, Class<T> type) {
}
@return description

JDK 1.0で導入

descriptionテキスト付きで「戻り値」セクションを追加します。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーション・コメントでのみ有効です。Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、@returnのセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return

@see reference

JDK 1.0で導入

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

形式1。@see stringというタグ形式は、stringのテキスト・エントリを追加します。リンクは生成されません。stringは、書籍またはURLではアクセスできない情報の参照先です。javadocコマンドは、最初の文字が二重引用符(")かどうかを調べて、この形式を前述の形式と区別します。たとえば、@see "The Java Programming Language"からは次のテキストが生成されます。

関連項目:

The Java Programming Language

形式2。@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

形式3。@see package.class#member labelという形式は、表示テキストlabelを持つリンクを挿入します。このリンクは、指定された名前を持つ、参照されているJava言語のメンバーのドキュメントを指します。labelはオプションです。labelを省略すると、表示テキストのかわりに、名前が適切に短縮されて表示されます。-noqualifierオプションを使用すると、表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストを指定する場合に使います。「名前が表示される方法」を参照してください。

Java SE 1.2だけは、ラベルではなく名前が、<code> HTMLタグ内に自動的に表示されます。Java SE 1.2.2からは、ラベルを使用するかどうかにかかわらず、表示テキストを囲む<code>タグが常に追加されます。

  • package.class#memberには、参照されている任意の有効なプログラム要素の名前を指定します。つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。ただし、メンバー名の前のドットは、シャープ記号(#)で置き換えます。classは、トップレベルまたはネストされた、任意のクラスまたはインタフェースを表します。memberは、任意のコンストラクタ、メソッドまたはフィールド(ネストされたクラスまたはインタフェースではない)を表します。指定した名前が、ドキュメント化されているクラスに含まれている場合、javadocコマンドは、その名前へのリンクを作成します。外部参照クラスへのリンクを作成するには、-linkオプションを使います。参照クラスに属していない名前のドキュメントを参照するには、他の2つの@seeタグ形式を使います。「名前の指定」を参照してください。

    注: 外部参照クラスは、コマンド行でjavadocコマンドに渡されないクラスのことです。生成ドキュメント内で外部参照クラスにリンクしている箇所は、外部参照または外部リンクと呼ばれます。たとえば、java.awtパッケージに対してだけjavadocコマンドを実行した場合、Objectなどのjava.lang内のすべてのクラスが外部参照クラスになります。外部参照クラスにリンクするには、-linkおよび-linkofflineオプションを使用します。外部参照クラスのソース・コメントは、javadocコマンドの実行で利用できません。

  • 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にはメソッドまたはコンストラクタを指定できます。

Typical forms for @see package.class#member 
Referencing a member of the current class
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...) 

Referencing another class in the current or imported packages
@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
@see Class#constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class 

Referencing an element in another package (fully qualified)
@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
@see package.Class#constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package

上記のリストに関する注意:

  • 最初の種類の形式(パッケージとクラスを省略)の場合、javadocコマンドは、現在のクラスの階層だけを検索します。つまり、現在のクラスかインタフェース、そのスーパー・クラスかスーパー・インタフェース、または現在のクラスかインタフェースを囲んでいるクラスかインタフェースからメンバーを検索します(項目13を検索)。現在のパッケージの他の部分や、他のパッケージは検索しません(項目45を検索)。「@seeタグの検索順序」を参照してください。

  • メソッドまたはコンストラクタを指定するときにカッコを付けずに名前だけ(getValueなど)を使用した場合、同じ名前のフィールドが存在しなければ、javadocコマンドはそのメソッドに対してリンクを作成します。このメソッドがオーバーロードされている場合、javadocコマンドは、検索で最初に見つかったメソッドにリンクします。結果は前もって特定できません。

  • ネストされたクラスは、上記のどの形式の場合も、単にinnerではなく、outer.innerとして指定しなければなりません。

  • すでに述べたとおり、クラスとメンバーを区切るために、ドット(.)ではなくシャープ記号(#)を使用することに注意してください。このように指定すると、javadocコマンドは、あいまいさを解決できます。ドットは、クラス、ネストされたクラス、パッケージ、およびサブパッケージを区切るためにも使用されます。ただし、javadocコマンドでは、あいまいさがなければ、ドットでも正しく解析されます。その場合でも警告は表示されます。

@seeタグの検索順序

javadocコマンドは、ソース・ファイル、パッケージ・ファイル、または概要ファイルの中に出現する@seeタグを処理します。後者の2つのファイルでは、完全修飾名を@seeタグに指定しなければなりません。ソース・ファイルでは、完全修飾または部分修飾の名前を指定できます。

@seeタグの検索順序は次のとおりです。

  1. 現在のクラスまたはインタフェース。

  2. 外側を囲んでいるクラスとインタフェース(もっとも近いものから検索)。

  3. スーパー・クラスとスーパー・インタフェース(もっとも近いものから検索)。

  4. 現在のパッケージ。

  5. インポートされているパッケージ、クラス、およびインタフェース(import文の順序に従って検索)。

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

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

  1. 現在のクラスまたはインタフェース。

  2. 外側を囲んでいるクラスとインタフェース(もっとも近いものから検索)。

  3. スーパー・クラスとスーパー・インタフェース(もっとも近いものから検索)。

  4. 現在のパッケージ。

  5. インポートされているパッケージ、クラス、およびインタフェース(import文の順序に従って検索)。

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

名前が表示される方法

labelを省略すると、package.class.memberが表示されます。一般に、現在のクラスおよびパッケージに応じて適切に短縮されます。「短縮される」とは、必要最小限の名前だけがjavadocコマンドで表示されるということです。たとえば、String.toUpperCase()メソッドに、同じクラスのメンバーへの参照と他のクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースだけです(次のリストを参照)。パッケージ名を全体的に削除するには、-noqualifierオプションを使用します。


参照の種類: @seeタグが同じクラス、同じパッケージのメンバーを参照している
例: @see String#toLowerCase()
表示: toLowerCase() - パッケージ名とクラス名は省略されます

参照の種類: @seeタグが異なるクラス、同じパッケージのメンバーを参照している
例: @see Character#toLowerCase(char)
表示: Character.toLowerCase(char) - パッケージ名は省略され、クラス名は含まれます

参照の種類: @seeタグが異なるクラス、異なるパッケージのメンバーを参照している
例: @see java.io.File#exists()
表示: java.io.File.exists() - パッケージ名とクラス名が含まれます

@seeタグの例

右側のコメントは、@seeタグが別のパッケージのクラス(java.applet.Appletなど)内にある場合に、名前がどのように表示されるかを示しています。Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、@seeのセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@see

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

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

@serial field-description | include | exclude

JDK 1.2で導入

デフォルトの直列化可能フィールドのドキュメンテーション・コメントで使用します。次の場所にある「クラスの直列化可能なフィールドおよびデータの文書化」を参照してください。
http://docs.oracle.com/javase/jp/8/platform/serialization/spec/serial-arch.html#5251

また、直列化形式仕様にクラスを含めるためのOracleの条件も参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/serialized-criteria-137781.html

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

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

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

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

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

たとえば、javax.swingパッケージは、package.htmlまたはpackage-info.java内で、@serial excludeタグで指定されています。publicクラスjava.security.BasicPermissionは、@serial excludeタグで指定されています。package-privateクラスjava.util.PropertyPermissionCollectionは、@serial includeタグで指定されています。

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

@serialData data-description

JDK 1.2で導入

data-descriptionの値を使用して、直列化された形式でのデータの型と順序をドキュメント化します。このデータには、writeObjectメソッドによって書き込まれるオプションのデータ、およびExternalizable.writeExternalメソッドによって書き込まれるすべてのデータ(基底クラスを含む)が含まれます。

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

@serialField field-name field-type field-description

JDK 1.2で導入

SerializableクラスのserialPersistentFieldsメンバーのObjectStreamFieldコンポーネントをドキュメント化します。各ObjectStreamFieldコンポーネントに対して@serialFieldタグを1つ使用してください。

@since since-text

JDK 1.1で導入

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

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

@throws class-name description

JDK 1.2で導入

@exceptionタグと同じ動作になります。Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、@throwsのセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@exception

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

すべてのチェック例外がドキュメント化されるようにするために、throws節内の例外に@throwsタグが存在しない場合は、@throwsタグでドキュメント化されたかのように、javadocコマンドによって例外がHTML出力に説明なしで追加されます。

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

{@value package.class#field}

JDK 1.4で導入

定数の値を表示します。{@value}タグが静的フィールドのドキュメンテーション・コメントで引数なしで使用されている場合、その定数の値が表示されます。

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

{@value}タグが任意のドキュメンテーション・コメント内で引数package.class#fieldありで使用されている場合は、指定した定数の値が表示されます。

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

引数package.class#fieldは、@seeタグの引数と似た形式になります。ただし、メンバーが静的フィールドでなければならない点が異なります。

これらの定数の値は、次の場所にある「定数フィールド値」にも表示されます。
http://docs.oracle.com/javase/jp/8/api/constant-values.html

@version version-text

JDK 1.0で導入

-versionオプションが使われている場合、生成ドキュメントに「バージョン」小見出しを追加して、指定されたversion-textの値を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のリリース番号を保持するように意図されています。これに対し、@sinceは、このコードが導入されたリリース番号を保持します。version-textの値には、特別な内部構造はありません。Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、@versionのセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@version

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

タグを使用できる場所

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

概要タグ

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

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

概要タグは次のとおりです。

@see reference || @since since-text || @serialField field-name field-type field-description || @author name-text || @version version-text || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||

パッケージ・タグ

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

パッケージ・タグは次のとおりです。

@see reference || @since since-text || @serial field-description | include | exclude || @author name-text || @version version-text || {@linkplain package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||

クラスおよびインタフェース・タグ

次に、クラスまたはインタフェースのドキュメンテーション・コメントで使用できるタグを示します。@serialタグは、クラスまたはインタフェースのドキュメンテーション・コメント内でのみ使用でき、includeまたはexclude引数を取ります。

@see reference || @since since-text || @deprecated deprecated-text || @serial field-description | include | exclude || @author name-text || @version version-text || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||

クラス・コメントの例:

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

フィールド・タグ

フィールドで使用できるタグは次のとおりです。

@see reference || @since since-text || @deprecated deprecated-text || @serial field-description | include | exclude || @serialField field-name field-type field-description || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} || {@value package.class#field}

フィールド・コメントの例:

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

コンストラクタおよびメソッド・タグ

次に、コンストラクタまたはメソッドのドキュメンテーション・コメント内で使用できるタグを示します。ただし、@returnタグはコンストラクタでは使用できず、{@inheritDoc}タグには制限があります。

@see reference || @since since-text || @deprecated deprecated-text || @param parameter-name description || @return description || @throws class-name description || @exception class-name description || @serialData data-description || {@link package.class#member label} || {@linkplain package.class#member label} || {@inheritDoc} || {@docRoot}

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

メソッド・コメントの例:

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

オプション

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

オプションは次のとおりです。

次のオプションは、Javadocの基本オプションであり、すべてのドックレットで使用できます。標準ドックレットはその他のドックレットを提供します。-bootclasspath、-breakiterator、-classpath、-doclet、-docletpath、-encoding、-exclude、-extdirs、-help、-locale、-overview、-package、-private、-protected、-public、-quiet、-source、-sourcepath、-subpackages、および-verbose。

Javadocオプション

-overview path/filename

javadocコマンドに対して、path/filenameで指定されたソース・ファイルから概要ドキュメント用のテキストを取得し、そのテキストを概要ページ(overview-summary.html)に配置するように指定します。path/filenameは、現在のディレクトリからの相対パスです。

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

たとえば、java.langパッケージのソース・ツリーが/src/classes/java/lang/の場合、概要ファイルは/src/classes/overview.htmlに配置できます

「実際の例」を参照してください。

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

概要ページが作成されるのは、javadocコマンドに複数のパッケージ名を渡した場合だけです。詳細は、「HTMLフレーム」を参照してください。概要ページのタイトルは、-doctitleによって設定されます。

-Xdoclint:(all|none|[-]<group>)

不正な参照、アクセシビリティの欠如、およびJavadocコメントの欠落について警告を報告し、無効なJavadoc構文およびHTMLタグの欠落についてエラーを報告します。

javadocコマンドでこのオプションを使用すると、生成された出力に含まれているすべてのドキュメンテーション・コメントをチェックできます。生成される出力に含める項目は、通常どおり標準オプション-public、-protected、-package、および-privateを使用して選択できます。

-Xdoclintを有効にすると、javacコマンドに似たメッセージによって問題が報告されます。javadocコマンドは、メッセージ、ソース行のコピー、およびエラーが検出された正確な位置を指すキャレットを出力します。メッセージは警告またはエラーです。どちらになるかは、その重要度、および生成されたドキュメントに対してバリデータを実行した場合にエラーを招く可能性によって決まります。たとえば、不正な参照やJavadocコメントの欠落は、javadocコマンドが無効なHTMLを生成する原因にはならないため、このような問題は警告として報告されます。構文エラーやHTML終了タグの欠落は、javadocコマンドが無効な出力を生成する原因になるため、このような問題はエラーとして報告されます。

デフォルトでは、-Xdoclintオプションは有効になっています。無効にするには、-Xdoclint:noneオプションを使用します。

-Xdoclintオプションで報告する項目を変更するには、次のオプションを使用します。

  • -Xdoclint
    none     : -Xdoclintオプションを無効にします

  • -Xdoclint
    group : groupのチェックを有効にします

  • -Xdoclint
    all     : すべてのグループのチェックを有効にします

  • -Xdoclint
    all,    -group : groupのチェックを除くすべてのチェックを有効にします

変数groupは、次のいずれかの値を取ります。

-Xdoclintオプションは複数回指定できるため、複数のカテゴリのエラーと警告をチェックできます。または、前述のオプションを使用して、エラーと警告のカテゴリを複数指定することもできます。たとえば、ファイルfilenameのHTML、構文、およびアクセシビリティの問題をチェックするには、次のコマンドのどちらかを使用します。

javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility filename
javadoc -Xdoclint:html,syntax,accessibility filename

注: javadocコマンドでは、これらのチェックの完全性は保証されません。具体的に言うと、これは完全なHTMLコンプライアンス・チェッカではありません。-Xdoclintオプションの目的は、一般的なエラーの大部分をjavadocコマンドで報告できるようにすることです。

javadocコマンドは、無効な入力を修正しようとはせず、報告するだけです。

-public

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

-protected

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

-package

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

-private

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

-help

オンライン・ヘルプを表示します。javadocおよびdocletのコマンド行オプションが一覧表示されます。

-doclet class

ドキュメントの生成に使うドックレットを起動するためのクラス・ファイルを指定します。完全修飾名を使用してください。このドックレットにより、出力の内容と形式が定義されます。-docletオプションが使われていない場合、javadocコマンドは、標準ドックレットを使ってデフォルトのHTML形式を生成します。このクラスには、start(Root)メソッドが含まれていなければなりません。この起動クラスへのパスは、-docletpathオプションによって定義されます。次の場所にある「ドックレットの概要」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/guides/javadoc/doclet/overview.html

-docletpath classpathlist

-docletオプションで指定されているドックレット開始クラス・ファイル、およびそれが依存するJARファイルへのパスを指定します。開始クラス・ファイルがJARファイル内にある場合、このオプションではそのJARファイルへのパスが指定されます。絶対パスまたは現在のディレクトリからの相対パスを指定できます。classpathlistに複数のパスまたはJARファイルを含める場合、Oracle Solarisではコロン(:)、Windowsではセミコロン(;)を使用して区切ります。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。次の場所にある「ドックレットの概要」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/guides/javadoc/doclet/overview.html

-1.1

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

-source release

受け付けるソース・コードのリリースを指定します。releaseパラメータには値1.3、1.4、1.5、6、7または8を指定できます。javacコマンドでコードをコンパイルしたときに使用した値に対応する値を使用します。

-sourcepath sourcepathlist

javadocコマンドにパッケージ名または-subpackagesオプションを渡すときに、ソース・ファイルを検索するためのパスを指定します。

複数のパスはコロン(:)で区切ります。

javadocコマンドは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使って、ドキュメント化されるソース・ファイルの位置だけでなく、それ自体はドキュメント化されないがドキュメント化されるソース・ファイルに継承されるコメントを持つソース・ファイルの位置も確認できます。

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

sourcepathlistには、ドキュメント化するパッケージ名のソース・ツリーのルート・ディレクトリを設定します。

たとえば、com.mypackageという名前のパッケージをドキュメント化する場合に、そのソース・ファイルが/home/user/src/com/mypackage/*.javaにあるとします。次のように、sourcepathを/home/user/src (com\mypackageを含むディレクトリ)に指定し、パッケージ名を指定します。

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

ソース・パスの値とパッケージ名を連結して、ドットをスラッシュ(/)に変えると、パッケージのフル・パスになることに注目してください。

/home/user/src/com/mypackage

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

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

javadocコマンドが参照クラスを検索するパスを指定します。参照クラスとは、ドキュメント化されるクラスとそれらのクラスによって参照されるすべてのクラスのことです。

複数のパスはコロン(:)で区切ります。

javadocコマンドは、指定されたパス以下のすべてのサブディレクトリを検索します。classpathlistの値を指定するときは、クラス・パスのドキュメントにある指示に従ってください。

-sourcepathが省略されている場合、javadocコマンドは、-classpathを使って、ソース・ファイルとクラス・ファイルを検索します(下位互換性のため)。ソース・ファイルとクラス・ファイルを別々のパスから検索する必要がある場合は、-sourcepathと-classpathの両方を使います。

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

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

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

javadocコマンドは拡張機能クラスおよびブートストラップ・クラスに関連しているため、javadocコマンドが-classpathを使用してユーザー・クラスを検索する方法についての詳細は、次の場所にある「クラスの検索方法」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/tools/findingclasses.html

*というベース名を含むクラス・パス要素は、ディレクトリ内の拡張子.jarまたは.JARを持つすべてのファイルのリストを指定するのと同じとみなされます。

たとえば、ディレクトリmydirにa.jarとb.JARが含まれている場合、クラス・パス要素foo/*はA.jar:b.JARに展開されます(JARファイルの順番は不確定)。このリストには、隠しファイルも含め、指定されたディレクトリ内のすべてのJARファイルが含まれます。*からなるクラスパス・エントリは、カレント・ディレクトリ内のすべてのJARファイルのリストに展開されます。CLASSPATH環境変数も同様に展開されます。クラス・パスのワイルドカード展開は、Java仮想マシン(JVM)の起動前に実行されます。System.getenv("CLASSPATH")の呼出しなどによって環境を照会しないかぎり、Javaプログラムが展開されていないワイルドカードを認識することはありません。

-subpackages package1:package2:...

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

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

javadoc -d docs -sourcepath /home/user/src  -subpackages java:javax.swing
-exclude packagename1:packagename2:...

指定されたパッケージとそのサブパッケージを-subpackagesによって作成されたリストから無条件に除外します。過去の-subpackagesオプションの指定によって組み込まれたパッケージ、または将来組み込まれるパッケージも除外の対象となります。

次の例では、java.io、java.util、java.mathなどは組み込まれますが、java.netとjava.lang以下のパッケージは除外されます。この例では、java.langのサブパッケージであるjava.lang.refは除外されます。

javadoc -sourcepath /home/user/src -subpackages java -exclude 
    java.net:java.lang
-bootclasspath classpathlist

ブート・クラスが存在するパスを指定します。通常、これらはJavaプラットフォーム・クラスです。bootclasspathは、javadocコマンドがソース・ファイルとクラス・ファイルを探すときに使う検索パスの一部です。詳細は、次の場所にある「クラスの検索方法」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/tools/findingclasses.html

classpathlistパラメータ内で複数のディレクトリを区切るには、Windowsではセミコロン(;)、Oracle Solarisではコロン(:)を使用します。

-extdirs dirist

拡張機能クラスが存在するディレクトリを指定します。拡張機能クラスとは、Java拡張機能メカニズムを使うすべてのクラスです。extdirsオプションは、javadocコマンドがソース・ファイルとクラス・ファイルを探すときに使う検索パスの一部です。詳細は、-classpathオプションを参照してください。dirlist内で複数のディレクトリを区切るには、Windowsではセミコロン(;)、Oracle Solarisではコロン(:)を使用します。

-verbose

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

-quiet

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

-breakiterator

java.text.BreakIteratorの国際化された文境界を使用して、パッケージ、クラス、またはメンバーの英文の主説明における最初の文の終わりを判断します。他のすべてのロケールはすでに、英語言語というロケール固有のアルゴリズムではなくBreakIteratorクラスを使用しています。最初の文は、パッケージ、クラス、またはメンバーのサマリーにコピーされ、アルファベット順のインデックスにコピーされます。JDK 1.2以降、BreakIteratorクラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、1.2以降では、-breakiteratorオプションは英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。

  • 英文のデフォルトの文区切りアルゴリズム。空白またはHTMLブロック・タグ(<P>など)が続くピリオドで停止します。

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

Java SE 1.5では、-breakiteratorオプションの警告メッセージが削除されました。デフォルトの文区切りアルゴリズムは変更されていません。Java SE 1.4.xで-breakiteratorオプションの警告をなくすためのソース・コード変更を行っていない場合は、何も処置を取る必要がありません。Java SE 1.5.0以降、この警告は表示されなくなります。

-locale language_country_variant

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

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

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

-encoding

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

-Jflag

javadocコマンドを実行するJava Runtime Environment (JRE)に、flagを直接渡します。たとえば、生成ドキュメントを処理するためにシステムで32Mバイトのメモリーを確保しておく必要がある場合は、-Xmxオプションをjavadoc -J-Xmx32m -J-Xms32m com.mypackageのように呼び出します。ただし、-Xmsは初期メモリーのサイズを設定するだけなので、オプションです。これは、必要なメモリーの最小サイズがわかっている場合に便利です。

Jとflagの間には空白を入れません。

使用しているjavadocコマンドのバージョンを確認するには、-versionオプションを使用します。出力ストリームには標準ドックレットのバージョン番号が含まれます。「Javadocコマンドの実行」を参照してください。

javadoc -J-version
java version "1.7.0_09"
Java(TM) SE Runtime Environment (build 1.7.0_09-b05)
Java HotSpot(TM) 64-Bit Server VM (build 23.5-b02, mixed mode)
-javafx

標準ドックレットに対してJavaFX拡張機能を使用して、HTMLドキュメントを生成します。生成されたドキュメントには、標準Javaドックレットで生成された他のサマリー・セクションに加えて「プロパティのサマリー」セクションが含まれています。リストされたプロパティは、各プロパティのgetterおよびsetterメソッドのセクションにリンクされます。

getterおよびsetterメソッドに対して明示的に記載されているドキュメント・コメントがない場合、プロパティ・メソッドのドキュメント・コメントがこれらのメソッドに対して生成されたドキュメントに自動的にコピーされます。このオプションは、プロパティのデフォルト値を記述できる新しい@defaultValueタグも追加します。

例:

javadoc -javafx MyClass.java -d testdir

標準ドックレットのオプション

-d directory

javadocコマンドで生成されたHTMLファイルを保存する生成先ディレクトリを指定します。-dオプションを省略すると、ファイルは現在のディレクトリに保存されます。directoryの値には、絶対ディレクトリ、または現在の作業ディレクトリからの相対ディレクトリを指定できます。Java SE 1.4では、javadocコマンドを実行すると生成先ディレクトリが自動的に作成されます。

たとえば、次のコマンドは、com.mypackageパッケージのドキュメントを生成し、結果を/user/doc/ directoryディレクトリに保存します。javadoc -d /user/doc/ com.mypackage

-use

ドキュメント化されるクラスおよびパッケージごとに1つの「使用」ページを組み込みます。このページには、その特定のクラスまたはパッケージのAPIを使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドが記述されます。たとえば、クラスCを例にとると、クラスCを使っているものとしては、Cのサブクラス、Cとして宣言されているフィールド、Cを返すメソッド、および、型Cのパラメータを持つメソッドとコンストラクタがあります。たとえば、String型の「使用」ページを見てみましょう。java.awt.FontクラスのgetNameメソッドは、String型を返します。したがって、getNameメソッドはStringを使っているので、Stringの「使用」ページにはgetNameメソッドがあります。ドキュメント化されるのはAPIの使用だけであって、実装はドキュメント化されません。あるメソッドが、その実装の中でStringを使っていても、引数として文字列を取ったり、文字列を返したりしない場合は、Stringの「使用」とは見なされません。生成された「使用」ページにアクセスするには、目的のクラスまたはパッケージに移動し、ナビゲーション・バーの「使用」リンクをクリックします。

-version

生成ドキュメントに、@versionのテキストを組み込みます。このテキストは、デフォルトでは省略されます。使用しているjavadocコマンドのバージョンを確認するには、-J-versionオプションを使用します。

-author

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

-splitindex

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

-windowtitle title

HTMLの<title>タグに配置するタイトルを指定します。titleタグに指定されたテキストは、ウィンドウのタイトルや、このページに対して作成されたブラウザのブックマーク(お気に入り)に表示されます。このタイトルにはHTMLタグを含めないでください。タイトルにHTMLタグが含まれていると、ブラウザがタグを正しく解釈できません。titleタグ内の内部引用符には、エスケープ文字を使用してください。-windowtitleオプションが省略されている場合、javadocコマンドは、-windowtitleオプションのかわりに-doctitleオプションの値を使います。例: javadoc -windowtitle "Java SE Platform" com.mypackage

-doctitle title

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

-title title

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

-header header

各出力ファイルの上端に配置するヘッダー・テキストを指定します。ヘッダーは、上部ナビゲーション・バーの右側に配置されます。headerには、HTMLタグと空白を含めることができますが、これらを含める場合は、headerを引用符で囲まなければなりません。ヘッダー内の内部引用符には、エスケープ文字を使用してください。例: javadoc -header "<b>Java Platform </b><br>v1.4" com.mypackage

-footer footer

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

-top

各出力ファイルの最上部に配置するテキストを指定します。

-bottom text

各出力ファイルの最下部に配置するテキストを指定します。このテキストは、下部ナビゲーション・バーより下の、ページの最下部に配置されます。テキストには、HTMLタグと空白を含めることができますが、これらを含める場合は、テキストを引用符で囲まなければなりません。テキスト内の内部引用符には、エスケープ文字を使用してください。

-link extdocURL

Javadocにより生成された既存の外部参照クラスのドキュメンテーションへのリンクを作成します。extdocURL引数は、リンク先にする、Javadocによって生成された外部ドキュメントを含むディレクトリの絶対URLまたは相対URLです。javadocコマンドの実行時に複数の-linkオプションを指定して、複数のドキュメントへのリンクを作成することもできます。

このディレクトリ内にpackage-listファイルが存在していなければなりません。そうでない場合は、-linkofflineオプションを使用します。javadocコマンドはpackage-listファイルからパッケージ名を読み取り、これらのパッケージをそのURLにリンクします。javadocコマンドを実行すると、作成される<A HREF>リンク内にextdocURLの値がコピーされます。したがって、extdocURLはファイルへのURLではなくディレクトリへのURLでなければなりません。extdocURLへの絶対リンクを使用すると、ユーザーのドキュメントを任意のWebサイト上のドキュメントにリンクできます。相対位置へリンクするだけでよい場合は相対リンクを使用できます。相対リンクを使用する場合、-dオプションで指定される生成先ディレクトリを基準にした、リンクされるパッケージのあるディレクトリの相対パスを指定する必要があります。通常、絶対リンクを指定する場合は、HTTPリンクを使用します。Webサーバーを持たないファイル・システムにリンクする場合は、ファイル・リンクを使用できます。ファイル・リンクを使用するのは、生成されたドキュメントにアクセスするすべてのユーザーが同じファイル・システムを共有している場合だけにしてください。いかなる場合にも、いかなるオペレーティング・システムでも、絶対URLか相対URLか、http:ベースかfile:ベースかにかかわらず、スラッシュを区切り文字として使用します。次の場所にあるURL (Uniform Resource Locator)に関するメモを参照してください。
http://www.ietf.org/rfc/rfc1738.txt

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

-linkofflineオプションと-linkオプションの相違点

-linkオプションは次の場合に使用します。

  • 外部APIドキュメントへの相対パスを使用する場合。

  • 外部APIドキュメントへの絶対URLを使用する場合で、そのURLに対して読取り用の接続を開くことがシェルによって許可されているとき。

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

例1 - 外部ドキュメントへの絶対リンク

次の場所に示されているjava.lang、java.io、およびその他のJavaプラットフォーム・パッケージにリンクする場合は、次のコマンドを使用します。
http://docs.oracle.com/javase/jp/8/api/index.html

javadoc -link http://docs.oracle.com/javase/8/docs/api/ com.mypackage

このコマンドは、Java SEパッケージへのリンクを含む、com.mypackageパッケージのドキュメントを生成します。生成されたドキュメントには、たとえばクラス・ツリー内のObjectクラスへのリンクが含まれています。-sourcepathや-dなどの他のオプションは表示されません。

例2 - 外部ドキュメントへの相対リンク

この例では、2つのパッケージがあり、そのドキュメントがjavadocコマンドを複数回実行して生成されているとします。さらに、これらのドキュメントが相対パスで分割されているとします。パッケージは、API であるcom.apipackageと、SPI(サービス・プロバイダ・インタフェース)であるcom.spipackageです。ドキュメントの格納先はdocs/api/com/apipackageとdocs/spi/com/spipackageです。APIパッケージのドキュメントがすでに生成されていて、現在のディレクトリがdocsである場合、このAPIドキュメントへのリンクを持つSPIパッケージをドキュメント化するには、javadoc -d ./spi -link ../api com.spipackageを実行します。

-linkオプションは生成先ディレクトリ(docs/spi)を基準にしていることに注意してください。

注

-linkオプションを使うと、「コードからは参照されていても、javadocコマンドの今回の実行ではドキュメント化されない」というクラスにリンクできるようになります。このようなリンクから有効なページに移動できるようにするには、それらのHTMLページがある場所を調べ、その場所をextdocURLに指定する必要があります。これにより、サード・パーティのドキュメントから、
http://docs.oracle.comにあるjava.*のドキュメントにリンクできるようになります。javadocコマンドの今回の実行で生成されるドキュメント内のAPIだけを対象にリンクを作成する場合は、-linkオプションを省略します。-linkオプションが指定されていない場合、javadocコマンドは、外部参照されたドキュメントへのリンクを作成しません。これは、そのドキュメントが存在するかどうか、および存在する場合はその場所を判別できないからです。-linkオプションでは、生成ドキュメント内の複数の場所にリンクを作成できます。「ソース・ファイルの処理」を参照してください。また、このオプションを使うと、複数のパッケージ群の間にクロスリンクを作成することもできます。つまり、ある一式のパッケージに対してjavadocコマンドを実行した後、別の一式のパッケージに対してjavadocコマンドを実行し、これら2つのパッケージ群の間に双方向のリンクを作成できます。

クラスの参照方法

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

すべての種類のインポート文の場合。ワイルドカードによるインポート、名前による明示的なインポート、またはjava.lang.*に対する自動的なインポート。

Java SE 1.3.nおよび1.2.nでは、名前による明示的なインポートのみ機能します。ワイルドカードによるimport文は機能せず、自動的なimport java.lang.*も機能しません。

宣言の場合: void mymethod(File f) {}

参照は、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースの戻り値の型またはパラメータの型に置くか、implements、extends、またはthrows文に置くことができます。

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

パッケージ・リスト

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

たとえば、Java SE APIのパッケージ・リストは次の場所にあります。
http://docs.oracle.com/javase/jp/8/api/package-list

パッケージ・リストは次のような内容で始まっています。

java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
and so on ....

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

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

複数のリンク

複数の-linkオプションを指定すると、生成された任意の数の外部ドキュメントに対してリンクを設定できます。Javadoc 1.2には、複数の-linkオプションを指定できないというバグがあります。これはJavadoc 1.2.2で修正されました。リンクする外部ドキュメントごとに、javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn com.mypackageのように別々のリンク・オプションを指定します。extdocURL1、extdocURL2、... extdocURLnは、それぞれ外部ドキュメントのルートを指し、各ルートにはpackage-listという名前のファイルが入っています。

クロスリンク

以前に生成された複数のドキュメントをクロスリンクする場合は、ブートストラップが必要になります。どのドキュメントについてもpackage-listが存在していない場合は、最初のドキュメントに対してjavadocコマンドを実行する時点で、2番目のドキュメントのpackage-listがまだ存在していません。したがって、外部リンクを作成するには、2番目のドキュメントを生成した後で、最初のドキュメントを生成し直す必要があります。

この場合、最初のドキュメント生成の目的は、そのドキュメントのpackage-listを作成することです。パッケージ名をすべて把握している場合は、package-listを手動で作成することもできます。次に、2番目のドキュメントとその外部リンクを生成します。必要な外部のpackage-listファイルが存在しない場合、javadocコマンドは警告を出力します。

-linkoffline extdocURL packagelistLoc

このオプションは、-linkオプションのバリエーションです。どちらも、Javadocによって生成された外部参照クラスのドキュメントへのリンクを作成します。javadocコマンドがWeb接続を使ってドキュメントにアクセスできないとき、Web上のドキュメントにリンクするには、-linkofflineオプションを使用します。外部ドキュメントのpackage-listファイルにアクセスできないとき、またはこのファイルがextdocURLで指定された場所とは異なる場所(通常、packageListLocで指定可能なローカルな場所)に存在するとき、-linkofflineオプションを使用します。extdocURLにWorld Wide Web上でしかアクセスできない場合は、-linkofflineオプションを指定することにより、ドキュメントの生成時にjavadocコマンドがWebに接続できなければならないという制約がなくなります。さらに、ドキュメントを更新するためのワークアラウンドとしての使用も可能です。パッケージのセット全体に対してjavadocコマンドを実行したあと、変更した一部のパッケージに対して再度javadocコマンドを実行できます。こうして、更新されたファイルを、オリジナルのファイル・セットに挿入できるようにします。次に例を示します。-linkofflineオプションは引数を2つ取ります。最初の引数は<a href>リンクに組み込まれる文字列を指定する引数、2番目の引数は-linkofflineオプションに対してpackage-listの検索場所を指定する引数です。

  • extdocURLの値は、リンク先にする、Javadocによって生成された外部ドキュメントを含むディレクトリの絶対URLまたは相対URLです。相対値の場合、-dオプションで指定される生成先ディレクトリを基準にした、リンクされるパッケージのルートの相対パスを指定する必要があります。詳細は、-linkオプションのextdocURLを参照してください。

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

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

外部ドキュメントへの絶対リンク

次の場所に示されているjava.lang、java.io、およびその他のJava SEパッケージにリンクする場合について考えます。
http://docs.oracle.com/javase/jp/8/api/index.html

ただし、シェルからWebにアクセスできないとします。この場合は、次のようにします。

  1. 次の場所にあるpackage-listファイルをブラウザで開きます。http://docs.oracle.com/javase/jp/8/api/package-list

  2. このファイルをローカル・ディレクトリに保存し、2番目の引数packagelistLocにこのローカル・コピーの場所を指定します。この例では、パッケージ・リスト・ファイルはカレントディレクト(.)に保存されています。

次のコマンドは、Java SEパッケージへのリンクを含む、com.mypackageパッケージのドキュメントを生成します。生成されたドキュメントには、たとえばクラス・ツリー内のObjectクラスへのリンクが含まれています。-sourcepathなどの他の必要なオプションは表示されません。

javadoc -linkoffline http://docs.oracle.com/javase/8/docs/api/ .  com.mypackage

外部ドキュメントへの相対リンク

-linkofflineに相対パスを使用することは一般的ではありません。通常は-linkオプションで十分だからです。-linkofflineオプションを使用する場合、package-listファイルは通常はローカル・ファイルです。また、相対リンクを使用する場合、リンク先のファイルもローカル・ファイルです。したがって、通常は、-linkofflineオプションの2つの引数に別々のパスを指定する必要はありません。2つの引数が同一である場合は、-linkオプションを使用できます。

package-listファイルの手動作成

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

複数のドキュメントへのリンク

-linkofflineオプションは、参照先の生成ドキュメントごとに1つずつ指定できます。

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

ドキュメントの更新

-linkofflineオプションは、プロジェクトに大量のパッケージが含まれている場合にも使用できます。すでにツリー全体に対してjavadocコマンドの実行が完了している場合に、ドキュメンテーション・コメントに少量の変更を手早く加えた後、ソース・ツリーの一部に対してだけjavadocコマンドを再実行することができます。ただし、2回目の実行が正しく機能するのは、ドキュメンテーション・コメントに対して変更を加え、宣言は変更していない場合だけです。ソース・コードの宣言を追加、削除、または変更した場合は、索引、パッケージ・ツリー、継承されるメンバーのリスト、「使用」ページなどの場所で、リンクが壊れることがあります。

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

javadoc -d update -linkoffline . html com.mypackage

javadocコマンドの実行が完了したら、update/com/package内に生成されたクラス・ページをコピーし(概要、索引ではない)、html/com/package内の元のファイルを上書きします。

-linksource

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

このオプションは、-public、-package、-protected、-privateの各オプションとは関係なく、privateクラス、privateフィールド、privateメソッドの本体を始めとする組み込まれたソース・ファイル内のすべての非公開実装の詳細を公開します。-privateオプションを指定しないかぎり、privateクラスやprivateインタフェースの一部には、リンクを介してアクセスできないことがあります。

各リンクは、その宣言内の識別子名の上に作成されます。たとえば、Buttonクラスのソース・コードへのリンクは、「Button」という語の上に作成されます。

public class Button extends Component implements Accessible

ButtonクラスのgetLabelメソッドのソース・コードへのリンクは、「getLabel」という語の上に作成されます。

public String getLabel()
-group groupheading packagepattern:packagepattern

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

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

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

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

たとえば、次のjavadocコマンドでは、ドキュメント化される3つのパッケージは、コア・パッケージ、拡張機能パッケージ、およびその他のパッケージに分けられます。java.lang*には末尾のドット(.)がありません。java.lang.*のようにドットを入れると、java.langパッケージは除外されることになります。

javadoc -group "Core Packages" "java.lang*:java.util"
        -group "Extension Packages" "javax.*"
        java.lang java.lang.reflect java.util javax.servlet java.new

コア・パッケージ

java.lang

java.lang.reflect

java.util

拡張機能パッケージ

javax.servlet

その他のパッケージ

java.new

-nodeprecated

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

-nodeprecatedlist

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

-nosince

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

-notree

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

-noindex

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

-nohelp

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

-nonavbar

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

-helpfile path\filename

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

javadoc -helpfile /home/user/myhelp.html java.awt.
-stylesheet path/filename

代替HTMLスタイルシート・ファイルのパスを指定します。このオプションが指定されていない場合、javadocコマンドは、javadocコマンド内にハードコードされているスタイルシート・ファイルstylesheet.cssを自動的に作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。ファイル名には任意の名前を指定でき、stylesheet.cssには限定されません。次に例を示します。

javadoc -stylesheet file /home/user/mystylesheet.css com.mypackage
-serialwarn

@serialタグがない場合は、コンパイル時に警告を生成します。デフォルトでは、Javadoc 1.2.2以降のバージョンでは、直列化の警告は生成されません。これより前のリリースとは逆になっています。このオプションを使用すると、直列化の警告が表示されるので、デフォルトの直列化可能フィールドとwriteExternalメソッドを適切にドキュメント化するのに役立ちます。

-charset name

このドキュメント用のHTML文字セットを指定します。この名前は推奨されるMIME名であるべきです。推奨されるMIME名は、次の場所にあるIANAレジストリの文字セットに関するガイドで指定されています。
http://www.iana.org/assignments/character-sets

たとえば、javadoc -charset "iso-8859-1" mypackageを実行すると、生成されるすべてのページの先頭に次の行が挿入されます。

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

このMETAタグについては、HTML標準(4197265および4137321)のHTMLドキュメントの表現に関するセクションを参照してください。
http://www.w3.org/TR/REC-html40/charset.html#h-5.2.2

-encodingおよび-docencoding nameオプションも参照してください。

-docencoding name

生成されるHTMLファイルのエンコーディングを指定します。この名前は推奨されるMIME名であるべきです。推奨されるMIME名は、次の場所にあるIANAレジストリの文字セットに関するガイドで指定されています。
http://www.iana.org/assignments/character-sets

-docencodingオプションを省略しながら-encodingオプションを使用した場合、生成されるHTMLファイルのエンコーディングは、-encodingオプションによって決まります。たとえば、javadoc -docencoding "iso-8859-1" mypackageのように使用します。-encodingおよび-docencoding nameオプションも参照してください。

-keywords

HTMLキーワードの<META>タグを、クラスごとに生成されるファイルに追加します。これらのタグは、<META>タグを検索するサーチ・エンジンがページを見つける場合に役立ちます。インターネット全体を検索する多くのサーチ・エンジンは、ページが<META>タグを誤用している場合があるため、<META>タグを調べません。検索を自身のWebサイトに限定している企業では、サーチ・エンジンが<META>タグを調べることによってメリットを得られます。<META>タグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同じであるため含まれません。たとえば、クラスStringは次のキーワードで開始します。

<META NAME="keywords" CONTENT="java.lang.String class">
<META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
<META NAME="keywords" CONTENT="length()">
<META NAME="keywords" CONTENT="charAt()">
-tag tagname:Xaoptcmf:"taghead"

javadocコマンドがドキュメンテーション・コメント内の引数を1つ取る単純なカスタム・ブロック・タグ@tagnameを解釈できるようにします。javadocコマンドでタグ名のスペル・チェックを行うには、ソース・コード内のすべてのカスタム・タグに-tagオプションを組み込むことが重要です。今回の実行で出力されないタグは、Xを付けて無効にします。コロン(:)は常に区切り文字になります。-tagオプションは、タグの見出しtagheadを太字で出力します。その次の行には、このオプションの引数で指定したテキストが続きます。ブロック・タグと同様、この引数のテキストにはインライン・タグを含めることができます。このインライン・タグも解釈されます。出力は、引数を1つ取る標準のタグ(@return、@authorなど)の出力とよく似ています。tagheadを省略すると、tagnameが見出しになります。

タグの配置: Xaoptcmf引数は、ソース・コード内のタグを配置できる位置と、Xを使ってこのタグを無効にできるかどうかを特定します。タグの配置位置を制限しない場合はaを指定します。それ以外の文字の組み合わせも可能です。

X (タグの無効化)

a (すべて)

o (概要)

p (パッケージ)

t (型すなわちクラスおよびインタフェース)

c (コンストラクタ)

m (メソッド)

f (フィールド)

シングル・タグの例: ソース・コード内の任意の位置で使用できるタグのタグ・オプションの例を示します。-tag todo:a:"To Do:"

@todoタグをコンストラクタ、メソッド、フィールドのみで使用する場合は、以下のオプションを使用します。-tag todo:cmf:"To Do:"

最後のコロン(:)は、パラメータ区切り子ではなく、見出しテキストの一部であることに注意してください。次の例のように、@todoタグを含むソース・コードでは、いずれかのタグ・オプションを使用します。@todo The documentation for this method needs work

タグ名に含まれるコロン: タグ名に使用するコロンはバックスラッシュでエスケープします。次のドキュメンテーション・コメントには、-tag ejb\\:bean:a:"EJB Bean:"オプションを使用します。

/**
 * @ejb:bean
 */

タグ名のスペル・チェック: ソース・コード内に配置した一部のカスタム・タグの出力を抑制したい場合があります。このような場合、ソース・コード内のすべてのタグを一覧表示し、出力したいタグを有効にし、出力したくないタグを無効にします。Xを指定するとそのタグは無効になり、指定しないとそのタグは有効になります。これにより、javadocコマンドは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。未知のタグを検出した場合、javadocコマンドは警告を出力します。すでに配置されている値にXを追加できます。こうしておけば、Xを削除するだけでタグを有効にすることができます。たとえば、@todoタグの出力を抑制したい場合、次のように指定します。-tag todo:Xcmf:"To Do:"さらに単純にするには、次のように指定します。-tag todo:X構文-tag todo:Xは、@todoタグがタグレットで定義されている場合も有効です。

タグの順序: -tagおよび-tagletオプションの順序によって、タグの出力順序が決定します。カスタム・タグと標準タグを組み合わせて使用することもできます。標準タグのタグ・オプションは、順序を決定するためだけのプレースホルダーです。これらは標準タグ名のみを使用します。標準タグの小見出しは変更できません。これについては、次の例で説明します。-tagオプションがない場合、-tagletオプションの位置によってその順序が決定します。タグが両方とも存在する場合、コマンド行の最後にあるほうがその順序を決定します。これは、タグやタグレットがコマンド行に指定された順番に処理されるためです。たとえば、-tagletオプションと-tagオプションの両方がtodoという名前を持っている場合、コマンド行の最後にある方が順序を決定します。

タグの完全セットの例: この例では、出力の「Parameters」と「Throws」の間に「To Do」を挿入します。また、Xを使用して、@exampleタグがソース・コード内で検出されても今回の実行では出力されないタグであることを指定します。@argfileタグを使用する場合は、次のように、引数ファイル内の別々の行にタグを配置できます。行の継続を示す文字は不要です。

-tag param
-tag return
-tag todo:a:"To Do:"
-tag throws
-tag see
-tag example:X

javadocコマンドがドキュメンテーション・コメントを解析する際に検出されたタグのうち、標準タグでも-tagや-tagletオプションで渡されるタグでもないものは、未知のタグと見なされます。この場合、警告がスローされます。

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

競合の回避: 独自の名前空間を作成するには、com.mycompany.todoのように、パッケージに使用されている命名規則に似たドット区切りの命名規則を使用します。Oracleは、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Oracleが提供する同じ名前のタグの動作をオーバーライドします。ユーザーが@todoという名前のタグまたはタグレットを作成している場合、Oracleが後から同じ名前の標準タグを作成しても、そのタグまたはタグレットはユーザーが定義した元の動作を保持します。

注釈とJavadocタグの比較: 通常、追加しようとしているマークアップの目的がドキュメントの変更または生成である場合は、Javadocタグにすべきです。そうでない場合は注釈にすべきです。Javadocツールのドキュメンテーション・コメントの記述方法に関するガイドで、カスタム・タグと注釈に関するセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#annotations

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

-taglet class

そのタグのドキュメントの生成に使うタグレットを起動するためのクラス・ファイルを指定します。classの値には完全修飾名を使用してください。このタグレットは、カスタム・タグのテキスト引数の数も定義します。タグレットは、これらの引数を受け付け、処理し、出力を生成します。詳細なドキュメントとサンプル・タグレットについては、次の「タグレットの概要」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/guides/javadoc/taglet/overview.html

タグレットは、ブロック・タグまたはインライン・タグで便利です。タグレットは任意の数の引数をとることができます。また、テキストを太字にする、箇条書きを作成する、テキストをファイルに書き出す、その他のプロセスを開始するなどのカスタム動作を実装できます。タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガーするなどの副作用は得られます。タグレットのパスを指定するには、-tagletpathオプションを使用します。以下は、生成されるページの「Parameter」と「Throws」の間に「To Do」タグレットを挿入する例です。-tagオプションのかわりに-tagletオプションを使用することもできますが、読みにくくなる場合があります。

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

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

-docfilesubdirs

doc-filesディレクトリの深いコピーを有効にします。コピー先には、サブディレクトリとすべての内容が再帰的にコピーされます。たとえば、doc-files/example/imagesディレクトリとその内容がすべてコピーされます。サブディレクトリを除外するオプションもあります。

-excludedocfilessubdir name1:name2

指定された名前のdoc-filesサブディレクトリを除外します。これにより、SCCSとその他のソース・コード制御サブディレクトリのコピーを防ぎます。

-noqualifier all | packagename1:packagename2...

出力されるクラス名から修飾パッケージ名を省略します。-noqualifierオプションの引数としてallを指定した場合、すべてのパッケージ修飾子が省略されます。削除するパッケージ修飾子をコロン区切りリストやワイルドカードで指定することもできます。クラスまたはインタフェースの名前が表示される場所からパッケージ名が削除されます。「ソース・ファイルの処理」を参照してください。

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

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

次の例では、javaで始まるパッケージ修飾子とcom.sunのサブパッケージを省略しますが、javaxは省略しません。-noqualifier java.*:com.sun.*

パッケージ修飾子が上記の動作に従って表示される場合、名前は適切に短縮されます。「名前が表示される方法」を参照してください。この規則は、-noqualifierオプションを使用したかどうかにかかわらず有効です。

-notimestamp

タイムスタンプが抑制されます。各ページ先頭近くにある、生成されたHTML内のHTMLコメントにタイムスタンプが隠されます。javadocコマンドを2つのソース・ベースで実行し、それらに対してdiffを実行する場合、-notimestampオプションを使用すると、タイムスタンプによってdiffが発生しなくなるので便利です(このオプションを使用しないと、各ページでdiffになります)。タイムスタンプにはjavadocコマンドのリリース番号が含まれており、現在は次のようになります。<!-- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 -->

-nocomment

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

-sourcetab tablength

ソース内の各タブが使用する空白文字の数を指定します。

コマンド行引数ファイル

javadocコマンドを短くしたり簡潔にしたりするために、javadocコマンドに対する引数(-Jオプションを除く)が入った1つ以上のファイルを指定できます。このことを利用すれば、どのオペレーティング・システム上でも、任意の長さのjavadocコマンドを作成できます。

引数ファイルには、javacのオプションとソース・ファイル名を自由に組み合わせて記述できます。ファイル内の各引数は、スペースまたは改行で区切ります。ファイル名に空白が含まれている場合は、そのファイル名全体を二重引用符で囲みます。

引数ファイル内のファイル名は、現在のディレクトリから相対的で、引数ファイルの位置からではありません。これらのリストでは、ワイルドカード(*)(*.javaと指定するなど)は使用できません。ファイルを再帰的に解釈するための単価記号(@)の使用はサポートされていません。-Jオプションはサポートされていません(それらはランチャに渡され、それが引数ファイルをサポートしていないため)。

javadocコマンドを実行するときに、各引数ファイルのパスとファイル名の先頭に@文字を付けて渡します。javadocコマンドは、単価記号(@)で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。

例1 - 単一の引数ファイル

argfileという名前の引数ファイルにjavadocコマンドのすべての引数を格納できます: javadoc @argfile。引数ファイルには、次の例で示されている2つのファイルの内容を両方とも入れることができます。

例2 - 2つの引数ファイル

javadocコマンドのオプション用に1つ、パッケージ名またはソース・ファイル名用に1つというように、2つの引数ファイルを作成することができます。なお、この後のリストでは、行の継続文字を使用していません。

次を含むoptionsという名前のファイルを作成します。

-d docs-filelist 
-use 
-splitindex
-windowtitle 'Java SE 7 API Specification'
-doctitle 'Java SE 7 API Specification'
-header '<b>Java SE 7</b>'
-bottom 'Copyright &copy; 1993-2011 Oracle and/or its affiliates. All rights reserved.'
-group "Core Packages" "java.*"
-overview /java/pubs/ws/1.7.0/src/share/classes/overview-core.html
-sourcepath /java/pubs/ws/1.7.0/src/share/classes

次を含むpackagesという名前のファイルを作成します。

com.mypackage1
com.mypackage2
com.mypackage3

javadocコマンドを次のように実行します。

javadoc @options @packages
例3 - パス付きの引数ファイル

引数ファイルにはパスを指定できますが、ファイル内のすべてのファイル名は、現在の作業ディレクトリに相対的になります(path1やpath2でなく)。

javadoc @path1/options @path2/packages
例4 - オプションの引数

次に、javadocコマンド・オプションの引数を引数ファイルに保存する例を示します。ここでは、-bottomを例に取り上げます。そのオプションには、かなり長い引数を指定することがあるからです。次のようなテキスト引数を含む、bottomという名前のファイルを作成します。

<font size="-1">
    <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
    Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved. <br/>
    Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
    Other names may be trademarks of their respective owners.</font>

javadocコマンドを次のように実行します。javadoc -bottom @bottom @packages

また、引数ファイルの先頭に-bottomオプションを組み込んでおき、javadocコマンドを次のように実行することもできます。javadoc @bottom @packages

Javadocコマンドの実行

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

Java言語で記述されたプログラムからjavadocコマンドを呼び出すには、公開プログラム・インタフェースを使用します。このインタフェースはcom.sun.tools.javadoc.Mainにあります(javadocコマンドは再入可能)。詳細は、次の「標準ドックレット」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/guides/javadoc/standard-doclet.html#runningprogrammatically

下記の説明は、標準HTMLドックレットを呼び出すためのものです。カスタム・ドックレットを呼び出すには、-docletおよび-docletpathオプションを使用します。次の場所にある「ドックレットの概要」を参照してください。
http://docs.oracle.com/javase/jp/8/technotes/guides/javadoc/doclet/overview.html

簡単な例

javadocコマンドは、パッケージ全体に対して実行することも、個々のソース・ファイルに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。

次の例では、ソース・ファイルは/home/src/java/awt/*.javaにあります。生成先ディレクトリは/home/htmlです。

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

パッケージをドキュメント化するには、そのパッケージのソース・ファイルが、パッケージと同じ名前を持つディレクトリ内に存在していなければなりません。

パッケージ名が複数の識別子で構成されている(java.awt.colorのように、各識別子はドットで区切られている)場合は、後続の各識別子が下位のサブディレクトリに対応していなければなりません(java/awt/colorなど)。

1つのパッケージのための複数のソース・ファイルを、異なる場所にある2つのディレクトリ・ツリーに分けて格納することも可能です。ただし、その場合は、-sourcepathによって、その両方の場所を指定しなければなりません。たとえば、src1/java/awt/colorとsrc2/java/awt/colorです。

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

例1 - 1つ以上のパッケージから再帰的に実行

この例では、javadocコマンドを任意のディレクトリから実行できるように-sourcepathを使用し、再帰的処理のために-subpackages (1.4の新オプション)を使用します。これは、javaディレクトリのサブパッケージ(java.netおよびjava.langをルートとするパッケージを除く)を処理します。java.langのサブパッケージであるjava.lang.refは除外されることに注意してください。その他のパッケージ・ツリーを巡回するには、java:javax:org.xml.saxのように、-subpackages引数にその名前を追加します。

javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude
例2 - ルートに移ってから明示的なパッケージに対して実行

完全修飾のパッケージ名の親ディレクトリに移ります。次に、ドキュメント化する1つ以上のパッケージの名前を指定してjavadocコマンドを実行します。

cd /home/src/
javadoc -d /home/html java.awt java.awt.event

その他のパッケージ・ツリーを巡回するには、java:javax:org.xml.saxのように、-subpackages引数にその名前を追加します。

例3 - 1つのツリーにある明示的なパッケージに対して任意のディレクトリから実行

このケースでは、現在のディレクトリがどこであってもかまいません。最上位パッケージの親ディレクトリを-sourcepathオプションに指定して、javadocコマンドを実行します。ドキュメント化する1つ以上のパッケージの名前を指定します。

javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
例4 - 複数のツリーにある明示的なパッケージに対して任意のディレクトリから実行

各ツリーのルートへのパスをコロンで区切ったリストを-sourcepathオプションに指定して、javadocコマンドを実行します。ドキュメント化する1つ以上のパッケージの名前を指定します。1つのパッケージのすべてのソース・ファイルが、1つのルート・ディレクトリの下に存在しなければならない、ということはありません。ただし、ソース・パスとして指定された場所のどこかで見つかる必要があります。

javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event

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

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

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

例1 - ソース・ディレクトリに移る

ソース・ファイルのあるディレクトリに移ります。次に、ドキュメント化する1つ以上のソース・ファイルの名前を指定してjavadocコマンドを実行します。

この例では、クラスButtonとCanvas、および名前がGraphicsで始まるクラスについて、HTML形式のドキュメントが生成されます。パッケージ名ではなくソース・ファイルがjavadocコマンドに引数として渡されているので、ドキュメントは、クラスのリストとメイン・ページという2つのフレームを持つことになります。

cd /home/src/java/awt
javadoc -d /home/html Button.java Canvas.java Graphics*.java
例2 - パッケージのルート・ディレクトリに移る

これは、同じルート内にある複数のサブパッケージの個々のソース・ファイルをドキュメント化する場合に便利です。パッケージのルート・ディレクトリに移り、各ソース・ファイルを、ルートからのパスとともに指定します。

cd /home/src/
javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
例3 - 任意のディレクトリからファイルをドキュメント化する

このケースでは、現在のディレクトリがどこであってもかまいません。ドキュメント化するソース・ファイルへの絶対パス(または、現在のディレクトリからの相対パス)を指定してjavadocコマンドを実行します。

javadoc -d /home/html /home/src/java/awt/Button.java
/home/src/java/awt/Graphics*.java

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

パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に前述の2つの例を組み合わせた例を示します。-sourcepathオプションは、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。

javadoc -d /home/html -sourcepath /home/src java.awt
/home/src/java/applet/Applet.java

実際の例

次に示すjavadocコマンドのコマンド行バージョンとmakefileバージョンは、JavaプラットフォームAPI上で実行されます。Java SE 1.2に存在する、約1500個のpublicおよびprotectedクラスについてドキュメントを生成するために、180Mバイトのメモリーを使用します。どちらの例も、オプションの引数に絶対パスを使用しているため、任意のディレクトリからこのjavadocコマンドを実行できます。

コマンド行の例

次のコマンドは、一部のシェルでは長過ぎて入力できません。この制限を回避するには、コマンド行引数ファイルを使用します。または、シェル・スクリプトを記述します。

この例で、packagesは、処理対象のパッケージ名(java.applet java.langなど)が入っているファイルの名前です。各オプションの、単一引用符で囲まれた引数の内側には、改行文字を挿入できません。たとえば、この例をコピー&ペーストする場合は、-bottomオプションから改行文字を削除してください。

javadoc -sourcepath /java/jdk/src/share/classes \
-overview /java/jdk/src/share/classes/overview.html \
-d /java/jdk/build/api \
-use \
-splitIndex \
-windowtitle 'Java Platform, Standard Edition 7 API Specification' \
-doctitle 'Java Platform, Standard Edition 7 API Specification' \
-header '<b>Java SE 7</b>' \
-bottom '<font size="-1">
<a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.</font>' \
-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \
-group "Extension Packages" "javax.*" \
-J-Xmx180m \  
@packages

プログラマティック・インタフェース

JavadocアクセスAPIを使用すると、新しいプロセスを実行することなく、JavaアプリケーションからJavadocツールを直接呼び出すことができます。

たとえば、次の文はコマンドjavadoc -d /home/html -sourcepath /home/src -subpackages java -exclude java.net:java.lang com.exampleと同等です。

import javax.tools.DocumentationTool;
import javax.tools.ToolProvider;

public class JavaAccessSample{
    public static void main(String[] args){
        DocumentationTool javadoc = ToolProvider.getSystemDocumentationTool();
        int rc = javadoc.run( null, null, null,
                 "-d", "/home/html",
                 "-sourcepath", "home/src",
                 "-subpackages", "java",
                 "-exclude", "java.net:java.lang",
                 "com.example");
     }
 }

このrunメソッドで、最初の3つの引数は入力、標準出力、および標準エラーのストリームを指定しています。Nullは、それぞれSystem.in、System.out、およびSystem.errを表すデフォルト値です。

makefileの例

ここでは、GNU makefileの例を示します。makefileの引数は、単一引用符で囲みます。Windowsのmakefileの例については、Javadoc FAQのmakefileに関するセクションを参照してください。
http://www.oracle.com/technetwork/java/javase/documentation/index-137483.html#makefiles

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 SE 7 API Specification'
DOCTITLE = 'Java Platform Standard Edition 7 API Specification'
HEADER = '<b>Java SE 7</font>'
BOTTOM = '<font size="-1">
      <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
      Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
      Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
      Other names may be trademarks of their respective owners.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
GROUPEXT  = '"Extension Packages" "javax.*"'
SRCDIR = '/java/jdk/1.7.0/src/share/classes'

注

  • -windowtitleオプションを省略すると、javadocコマンドによって、ドキュメント・タイトルがウィンドウ・タイトルにコピーされます。-windowtitleオプションのテキストは、-doctitleオプションに似ていますが、HTMLタグは使用しません。HTMLタグは、ウィンドウ・タイトルに生のテキストとして表示されてしまいます。

  • -footerオプションを省略すると、javadocコマンドによって、ヘッダー・テキストがフッターにコピーされます。

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

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

エラーと警告

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

たとえば、「error: cannot read: Class1.java」というメッセージは、javadocコマンドが現在のディレクトリのClass1.javaをロードしようとしていることを示します。クラス名は絶対パスまたは相対パスとともに表示されます。

環境

CLASSPATH

CLASSPATHは、javadocコマンドがユーザー・クラスのファイルを探すときに使うパスを指定する環境変数です。この環境変数は、-classpathオプションによってオーバーライドされます。複数のディレクトリを区切るには、Windowsではセミコロン、Oracle Solarisではコロンを使用します。

Windowsの例: .;C:\classes;C:\home\java\classes

Oracle Solarisの例: .:/home/classes:/usr/local/java/classes

関連項目

関連ドキュメント
目次   前   次
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved.