Java Platform Standard Edition

Javadocガイド

リリース9

E90923-01(原本部品番号:E75727-02)

2017年9月

このガイドには、Java Development Kit (JDK)とともにインストールされるJavadocツールの使用方法についての情報が掲載されています。

Java Platform, Standard Edition Javadocガイド, リリース9

E90923-01

Copyright © 2014, 2017, Oracle and/or its affiliates.  All rights reserved.

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。適用されるお客様とOracle Corporationとの間の契約に別段の定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。適用されるお客様とOracle Corporationとの間の契約に定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

目次

タイトルおよび著作権情報

はじめに

- 対象読者

- ドキュメントのアクセシビリティについて

- 関連ドキュメント

- 表記規則

1 Javadoc

- Javadocの機能

2 ソース・ファイル

3 Javadocコマンド

- Javadocのドックレット

- Javadocドックレットのオプション

- linkオプションの使用

- linkofflineオプションの使用

- タグ・オプションの使用

- javadocコマンド行引数ファイル

- 標準ドックレット

- Javadoc標準ドックレット

- 生成されるファイル

- javadocコマンドの実行例

はじめに

このガイドには、javadocコマンドやそのオプション、標準ドックレットの使用についての情報が掲載されています。

対象読者

このドキュメントはJavadocツールのユーザーを対象としています。Javadocコンテンツを開発するユーザーは、Javadoc仕様を参照してjavadocコンテンツを作成するのに必要な詳細情報を確認する必要もあります。

ドキュメントのアクセシビリティについて

Oracleのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイト(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc)を参照してください。

Oracle Supportへのアクセス

サポートをご購入のOracleのお客様は、My Oracle Supportにアクセスして電子サポートを受けることができます。詳細情報は(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info) か、聴覚に障害のあるお客様は (http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs)を参照してください。

関連ドキュメント

- 他のJDK 9ガイドについては、Oracle JDK 9のドキュメントを参照してください。

- Javadoc開発者はJavadoc仕様も参照できます。

表記規則

このマニュアルでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するGraphical User Interface要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

イタリック体

イタリックは、ユーザーが特定の値を指定するプレースホルダ変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

1 Javadoc

javadocツールは、ソース・ファイルのコレクションを内部形式へと読み込むプログラムです。

構造は次のとおりです: (source-files)->[javadoc-tool:doclet]->(generated files)

Javadocのドックレットは接続可能なバック・エンドのようなもので、いくつかの目標を念頭に置いてこの内部フォームを分析します。このドックレットに基づいて、HTML、MIFまたはXMLファイルを生成できます。

生成されたファイルのコンテンツはドックレットに固有です。標準ドックレットはHTMLドキュメントを生成しますが、他のドックレットの中にはスペルミスのある単語や構文エラーのレポートを生成できるものもあります。

標準ドックレット以外のドックレットを指定した場合、そのドックレットや生成されたファイル(ある場合)の操作にはこのガイドの説明が当てはまらない可能性があります。

javadocツールを使用するには、次の条件を満たしている必要があります。

- ソース・コードを書く際にドキュメント・コメントを含めます。ドキュメント・コメントはHTML形式でフォーマットされ、javadocツールが組み入れられています。

- javadocツールを実行します。ドキュメント・コメントおよびその他の特別なタグを分析できるように、ドックレットを指定する必要があります。ただし、ドックレットを指定しない場合は、デフォルトで標準ドックレットが含められます。多数のコマンド行オプションを指定しますが、そのうちのあるものはjavadocツールそのものに適用され、あるものは選択されたドックレットに固有です。コマンド行ヘルプにより、現在選択されているドックレットに適用されるツールのオプションを表示および識別できます。標準ドックレットを使用した場合、標準ドックレットによって生成される出力は一連のHTMLページで構成されます。別のドックレットを指定した場合、そのドックレットの操作およびそれにより生成されるファイル(ある場合)は、このガイドで説明されている標準ドックレットと同じ場合もあればそうでない場合もあります。

Javadocの機能

Javadocの機能には、Javadoc検索、HTML5出力の生成のサポート、モジュール・システム内のドキュメント・コメントのサポート、および簡略化されたドックレットAPIが含まれます。

検索

javadocツールは、出力を生成するドックレットを実行します。標準ドックレットでは出力が生成され、その生成されたドキュメントで検索ができます。生成されたAPIには検索ボックスがあり、次のものが提供されています。

- APIで定義されている要素や追加のキー・フレーズを検索できます。

- 結果。まず入力された文字に完全に一致する結果、それに続いて、入力された文字が文字列の任意の場所に含まれる結果が表示されます。複数の結果は検索ボックスの下に単純なスクロール・リストとして表示されます。結果は、分類およびユーザー選択がしやすいように次のように分類されます。

- モジュール

- パッケージ

- タイプ

- メンバー

- 検索タグ

検索語または句が@inheritDocタグを使用して継承されている場合、異なるプログラム要素名がある複数の結果が表示されます。

- ユーザー選択に基づくページ・リダイレクション。

次の項目を検索できます。

- 宣言されているモジュール、パッケージ、タイプおよびメンバーの名前: メソッドはオーバーロード可能であるため、メソッドのパラメータ・タイプの単純名も索引付けされ、検索できます。メソッドのパラメータ名はインデックス化されません。

- 新しいインライン・タグ@indexを使用してインデックス化された検索語または句: @index内で他のインライン・タグをネストすることはできません。宣言のjavadocコメント内の、@indexでマークされた句または検索語のみを検索できます。たとえば、ドメイン固有の語ulpsがjava.lang.Mathクラス全体で使用されているものの、クラスやメソッドの宣言名には出現しないとします。Math APIのユーザーのために、APIデザイナはクラス・レベルのjavadocコメントやメソッド・レベルのjavadocコメントに各種出現するulpsをタグ付けできます。タグ付けは{@index ulps}を使用して行います。語ulpsはjavadocツールを使用してインデックス化されます。

モジュール・システム

javadocツールはモジュール宣言内のドキュメンテーション・コメントをサポートしています。一部のJavadocコマンド行オプションでは、ドキュメント化するモジュールのセットを指定し、ドキュメント化されるモジュールの新しいサマリー・ページを生成できます。ドキュメント化されるモジュールのセットを構成し、ドキュメント化されるモジュールの新しいサマリー・ページを生成できる、新しいコマンド行オプションがあります。javadocドックレットのオプションを参照してください。

HTML 5サポート

HTML5出力を生成できます。HTML5完全準拠の出力を得るためには、ドキュメント・コメント内で提供されるHTMLコンテンツがHTML5準拠となっている必要があります。

簡略化されたドックレットAPI

ドックレットAPIでは、すべての言語機能をよりよく表せるように、強力なAPIを使用します。「標準ドックレットのオプション」を参照してください。

2 ソース・ファイル

javadocツールは、次に示す種類のソース・ファイルから出力結果を生成します。そのファイルは、クラスのJava言語ソース・ファイル(.java)、パッケージ・コメント・ファイル、概要コメント・ファイル、およびその他の処理されないファイルです。

このトピックでは、ソース・ツリーにやはり存在する場合があるものの、ドキュメント化しないようにする必要があるソース・ファイルやテスト・ファイル、テンプレート・ファイルについて説明します。

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

各クラスのソース・ファイルには独自のドキュメント・コメントがある場合があります。

概要コメント・ファイル

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

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

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

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

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

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

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

- <body>タグと</body>タグの間にあるすべての内容を処理のためにコピーします。

- 概要タグがあればすべて処理します。

- 生成した概要ページの最後に、処理したテキストを挿入します。

- 概要ページの先頭に、概要コメントの最初の文をコピーする

処理されないファイル

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

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

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

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

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

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

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

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

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

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

- Oracle Solaris、LinuxおよびmacOS: com/package1/test-files/

- Windows: com\package1\test-files\

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

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

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

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

- 処理できるようにコメントをコピーします。package.htmlの場合、javadocツールは、<body>と</body> HTMLタグの間にある内容をすべてコピーします。<head>セクションを含め、そこに<title>タグやソース・ファイルの著作権記述などの情報を配置することもできますが、生成されたドキュメントにはそれらは一切表示されません。

- パッケージ・タグを処理します。

- 生成したパッケージ・サマリー・ページの最後に、処理したテキストを挿入します。

- パッケージのサマリー・ページの先頭に、パッケージ・コメントの最初の文をコピーする。さらに、javadocツールは、概要ページのパッケージ・リストに、パッケージ名とこの最初の文を追加します。
文の末尾は、クラスやメンバーの主説明の最初の文の末尾に使用されるルールによって判断されます。

3 Javadocコマンド

javadocコマンド行の形式はjavadoc [options] [packagenames] [sourcefiles] [@files]です。オプションはドックレット・オプションまたは標準ドックレット・オプションです。javadocコマンドはプログラムで実行することもできます。

この項の内容は次のとおりです。

- Javadocのドックレット

- 標準ドックレット

- Javadocコマンドの実行例

Javadocのドックレット

javadocツールおよびそのオプションを使用して、Javaソース・ファイルからAPIドキュメントのHTMLページを生成します。

Javadocドックレットのオプション

javadocコマンドにはドックレットのオプションがあります。標準ドックレットには追加のオプションがあります。

javadocコマンドは、-docletオプションでカスタム・ドックレットが指定されている場合以外は、ドックレットを使用してその出力とデフォルトの標準ドックレットを決定します。オプション名は大文字と小文字が区別されませんが、その引数では大文字と小文字が区別されます。

形式

javadoc  [packages|source-files] [options][@files]

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

コマンド行オプションをスペースで区切ったものです。

@files

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

説明

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

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

適合性

標準ドックレットではドキュメンテーション・コメントの内容の適合性が検証されることはなく、ドキュメンテーション・コメントのエラーを修正しようとすることもありません。javadocを実行するユーザーは、整合性のない出力やJavaScriptなどの実行可能コンテンツを含む出力を生成する際に生じる可能性のある問題について認識しておく必要があります。標準ドックレットには、開発者がドキュメンテーション・コメントの一般的な問題を検出するのに役立つdoclint機能がありますが、生成された出力を適切な適合性およびその他のチェック・ツールでチェックすることも推奨します。

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

ソース・ファイルの処理

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

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

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

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

リンクの処理

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

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

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

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

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

- インタフェースのメンバーに対する「定義」リンクと、クラスのメンバーに対する「オーバーライド」リンク

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

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

- 索引

処理詳細

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

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

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

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

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

javadocコマンドは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、javadocコマンドは、すべての参照クラスを検索でき、かつそれがブートストラップ・クラス、拡張機能、ユーザー・クラスのいずれであるか判別できる必要があります。

Javadocのドックレット

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

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

Javadocドックレットのオプション

javadocツールはモジュール宣言内のドキュメンテーション・コメントをサポートしています。これには--module-pathや--upgrade-module-path、--module-source-pathのようなコマンド行オプションがあり、ドキュメント化されるモジュールのセットを構成し、ドキュメント化されるモジュールの新しいサマリー・ページを生成できます。モジュール関連のオプションが、ドキュメントの生成のために用意されています。次のオプションは、基本オプションであり、すべてのドックレットで使用できます。

--add-modules module(,module)*

初期モジュールに加えて解決するルート・モジュール、または<module>がALL-MODULE-PATHの場合はモジュール・パスのすべてのモジュールを指定します。

--add-exports module/package=other-module(,other-module)*

定義モジュールから追加モジュールに、あるいはother-moduleがALL-UNNAMEDの場合はすべての名前のないモジュールにエクスポートされると見なされるパッケージを指定します。

--add-reads module/package=other-module(,other-module)

指定モジュールで必須と見なされるように追加モジュールを指定します。名前のないモジュールを必須とするにはother-moduleをALL-UNNAMEDとします。

-bootclasspath classpathlist

ブート・クラスが存在するパスを指定します。通常、これらはJavaプラットフォーム・クラスです。bootclasspathは、javadocコマンドがソース・ファイルとクラス・ファイルを探すときに使う検索パスの一部です。

classpathlistパラメータ内で複数のディレクトリを区切るには、次のいずれかのデリミタを使用します。

- Oracle Solaris、LinuxおよびmacOS: コロン(:)

- Windows: セミコロン(;)

注意:
-bootclasspathオプションは、-source、-targetまたは--releaseにJDK 6、7または8を使用するなど古いバージョンのJavaプラットフォームに対してドキュメントを生成しようとしている場合にのみ使用可能です。

-breakiterator

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

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

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

- 疑問符で必ず最初の文が終了: 二重引用符が疑問符の後に続く場合、二重引用符も最初の文に含まれますが、その文字で文は終了します。

-classpath pathまたは--class-path pathまたは-cp path

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

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

Oracle Solaris、LinuxおよびmacOS: 複数のパスを区切るには、コロン(:)を使用します。たとえば、.:/home/classes:/usr/local/java/classesです

Windows: 複数のパスを区切るには、セミコロン(;)を使用します。たとえば、.;C:\classes;C:\home\java\classesです

javadocコマンドは、指定されたパス以下のすべてのサブディレクトリを検索します。

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

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

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

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

javadoc -sourcepath \user\lib -classpath \user\src com.mypackage

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

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

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

-doclet class

ドキュメントの生成に使うドックレットを起動するためのクラス・ファイルを指定します。完全修飾名を指定してください。このドックレットにより、出力の内容と形式が定義されます。-docletオプションが使われていない場合、javadocコマンドは、標準ドックレットを使ってデフォルトのHTML形式を生成します。このクラスは、jdk.javadoc.doclet.Docletインタフェースを実装する必要があります。この起動クラスへのパスは、-docletpathオプションによって定義されます。

-docletpath path

-docletオプションで指定されているドックレット開始クラス・ファイル、およびそれが依存するJARファイルへのパスを指定します。開始クラス・ファイルがJARファイル内にある場合、このオプションではそのJARファイルへのパスが指定されます。絶対パスまたは現在のディレクトリからの相対パスを指定できます。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。

-encoding name

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

-exclude pkglist

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

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

Oracle Solaris、LinuxおよびmacOS:

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

Windows:

javadoc -sourcepath \user\src -subpackages java -exclude java.net:java.lang

--expand-requires value

ドキュメント化されるモジュールのセットを拡張するようjavadocコマンドに指示します。デフォルトでは、コマンド行で明示的に指定されたモジュールのみがドキュメント化されます。このオプションでは次の値がサポートされます。

- transitive: これらのモジュールの必要なすべての推移的な依存性を追加で含めます。

- all: すべての依存性を含めます。

-extdirs dirlist

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

-helpまたは--help

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

-J flag

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

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

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

--limit-modules module(,module)*

参照可能なモジュールの数を制限します。

-locale name

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

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

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

--module module(,module)*

指定されたモジュールをドキュメント化します。

--module-path pathまたは-p path

アプリケーション・モジュールの参照先を指定します。

アプリケーション・モジュール・パス(--module-pathまたは短縮版の-mp)には、ライブラリおよびアプリケーション・モジュール(すべてのフェーズ)のコンパイル済定義が含まれます。リンク時に、このパスにJava SEおよびJava Development Kit (JDK)モジュールを含めることもできます。

--module-source-path path

複数のモジュールの入力ソース・ファイルの参照先を指定します。--module-source-pathオプションにはソース・フォームのモジュール定義が含まれます(コンパイル時のみ).

-package

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

--patch-module module=file(file*)

モジュール内の引数を、JARファイルまたはディレクトリ内のクラスおよびリソースでオーバーライドします。

注意:
file(:file)*は、--module-pathや--module-source-pathといった他のオプションのpathと同じです。

-private

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

-protected

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

-public

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

-quiet

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

--release release

指定されたリリースとのソース互換性を持たせます。

--show-members value

どのメンバー(フィールドやメソッド)をドキュメント化するかを指定し、valueには次のいずれかを指定できます。

protected

publicおよびprotected宣言を表示します。これはデフォルトです。

public

public値のみを表示します。

package

public、protectedおよびパッケージ宣言を表示します。

private

すべての宣言を表示します。

--show-module-contents value
モジュール宣言の文書粒度を指定します。指定できる値はapiまたはallです。

--show-packages value
どのモジュール・パッケージをドキュメント化するかを指定します。指定できる値はexportedまたはallパッケージです。

--show-types value
どの宣言(フィールドやメソッド)をドキュメント化するかを指定し、valueには次のいずれかを指定できます。

protected

publicおよびprotected宣言を表示します。これはデフォルトです。

public

public値のみを表示します。

package

public、protectedおよびパッケージ宣言を表示します。

private

すべての宣言を表示します。

-source release
受け付けるソース・コードのリリースを指定します。javacコマンドでコードをコンパイルしたときに使用した値に対応するreleaseの値を使用します。最も古いリリースはJDK 6、最新はJDK 9です。

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

Oracle Solaris、LinuxおよびmacOS: 複数のパスを区切るには、コロン(:)を使用します。

Windows: 複数のパスを区切るには、セミコロン(;)を使用します。

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

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

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

Oracle Solaris、LinuxおよびmacOS:

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

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

- sourcepathの値とパッケージ名を連結して、ドットをスラッシュ(/)に変更すると、次のように、パッケージのフル・パスになります。

/home/user/src/com/mypackage

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

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

Windows:

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

javadoc -sourcepath C:\user\src com.mypackage

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

\user\src\com\mypackage

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

javadoc -sourcepath \user1\src;\user2\src com.mypackage

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

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

Oracle Solaris、LinuxおよびmacOS:

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

Windows:

javadoc -d docs -sourcepath \user\src -subpackages java:javax.swing

--system jdk
モジュラ・リリースで使用されるシステム・モジュールの場所をオーバーライドします。

システム・モジュールとは(コンパイル時およびランタイム)環境に組み込まれているコンパイル済モジュールのことです。カスタム・リンクされたイメージの場合は、ライブラリおよびアプリケーション・モジュールを含めることもできます。コンパイル時に、システム・モジュールはシステム・モジュールのロード元のJDKイメージを指定する-systemオプションを使用してオーバーライドできます。

これらのパスに存在するモジュール定義(たとえば--module-source-path path)では、システム・モジュールと一緒に、参照可能なモジュールの数を定義します。モジュール・パスはシーケンスで、その各要素はモジュール定義またはモジュール定義を含むディレクトリのいずれかです。

--upgrade-module-path path
アップグレード可能オプションの場所をオーバーライドします。--upgrade-module-pathオプションには、(コンパイル時およびランタイム)環境に組み込まれているアップグレード可能モジュールのかわりに使用するための、モジュールのコンパイル済定義が含まれます。

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

—X
非標準オプションの形式を出力して終了します。

-Xmaxerrs number
印刷するエラーの最大数を設定します。

-Xmaxwarns number
印刷する警告の最大数を設定します。

-Xold
旧式のjavadocツールを呼び出します。

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

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

例:

javadoc -javafx MyClass.java -d testdir

linkオプションの使用

-linkオプションは、「コードからは参照されていても、javadocコマンドの今回の実行ではドキュメント化されない」というクラスにリンクするのに使用します。

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

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

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

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

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

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

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

java.lang、java.ioおよびその他のJavaプラットフォーム・パッケージへのリンクを作成するには、次のコマンドを使用します。

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

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

例3-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)を基準にしています。

クラスの参照方法

外部参照クラスのテキスト・ラベルだけではなくリンクを表示するには、特定の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するのみでは十分ではありません。import文または宣言のいずれかで参照する必要があります。

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

- 宣言の場合: void mymethod(File f) {}
参照は、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースの戻り値の型またはパラメータの型に置くか、implements、extends、またはthrows文に置くことができます。

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

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

パッケージ・リスト

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

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

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

複数のリンク

複数の-linkオプションを指定すると、生成された任意の数の外部ドキュメントに対してリンクを設定できます。リンクする外部ドキュメントごとに、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オプションの使用

java.lang、java.ioおよびその他のJava SEパッケージにリンクするにはlinkofflineオプションを使用します

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

java.lang、java.io、およびその他のJava SEパッケージにリンクする場合について考えます。ただし、シェルからWebにアクセスできないとします。この場合は、次のようにします。

1. 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ファイルが存在しないという場合です。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。同様に、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

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

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

タグ・オプションの使用

Xaoptcmf引数を使用して、ソース・コード内のタグを配置できる位置と、Xを使ってこのタグを無効にできるかどうかを特定します。

タグの配置

タグの配置位置を制限しない場合はaを指定します。それ以外の文字の組み合わせも可能です。

- X (タグの無効化)

- a (すべて)

- o (概要)

- p (パッケージ)

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

- c (コンストラクタ)

- m (メソッド)

- f (フィールド)

- s (モジュール)

シングル・タグの例

ソース・コード内の任意の位置で使用できるタグのタグ・オプションの例を示します。-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タグにすべきです。そうでない場合は注釈にすべきです。How to Write Doc Comments for the Javadoc ToolのCustom Tags and Annotationsを参照してください。

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

javadocコマンド行引数ファイル

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

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

例

単一の引数ファイル

argfileという名前の引数ファイルにjavadocコマンドのすべての引数を格納できます: javadoc @argfile。

2つの引数ファイル

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

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

Oracle Solaris、LinuxおよびmacOS:

-d docs-filelist
-use
-splitindex
-windowtitle 'Javadoc'
-doctitle 'Javadoc Guide'
-header '<b>Java™ SE </b>'
-bottom 'Copyright &copy; 1993-2011 Oracle and/or its affiliates. All rights reserved.'
-group "Core Packages" "java.*"
-overview /java/jdk9/docs/api/overview-summary
-sourcepath /java/

Windows:

-d docs-filelist
-use
-splitindex
-windowtitle 'Javadoc'
-doctitle 'Javadoc Guide'
-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\jdk9\docs\api\overview-summary.html
-sourcepath \java\

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

com.mypackage1
com.mypackage2
com.mypackage3

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

javadoc @options @packages

パスを使用した引数ファイル

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

Oracle Solaris、LinuxおよびmacOS:

javadoc @path1/options @path2/packages

Windows:

javadoc @path1\options @path2\packages

オプション引数

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

<font size="-1">
<a href="http://bugreport.java.com/bugreport/">Submit a bug or feature</a> </font>

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

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

標準ドックレット

標準ドックレットは、Oracleが提供するドックレットで、JavadocのデフォルトのHTML形式によるAPI出力を生成します。

この項の内容は次のとおりです。

- Javadoc標準ドックレット

- 生成されるファイル

Javadoc標準ドックレット

Javadocの-docletオプションを使用してコマンド行で他のドックレットが指定されていない場合は、標準ドックレットが使用されます。JDK 9ではドックレットAPIが、最新の新しい言語機能すべてをよりよく表せるように、より新しい強力なAPIを使用するよう更新されました。標準ドックレットは、このドックレットAPIを使用するように更新されています。

標準ドックレットは、Oracleが提供するドックレットで、JavadocのデフォルトのHTML形式によるAPI出力を生成します。このJDKドキュメントに含まれるJavaプラットフォームのAPI仕様は、標準ドックレットの出力例です。

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

-author

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

-bottom text

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

-charset name

このドキュメント用のHTML文字セットを指定します。この名前はIANA Registry, Character Setsで指定されている望ましいMultipurpose Internet Mail Extensions (MIME)名である必要があります。

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

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

このMETAタグについては、HTML standard (4197265 and 4137321), HTML Document Representationを参照してください。

-d directory

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

Oracle Solaris、LinuxおよびOS X: たとえば、次のコマンドでは、com.mypackageパッケージのドキュメントが生成され、その結果が/user/doc/ディレクトリに保存されます。

javadoc -d /user/doc/ com.mypackage

Windows: たとえば、次のコマンドでは、com.mypackageパッケージのドキュメントが生成され、その結果が\user\doc\ディレクトリに保存されます。

javadoc -d \user\doc\ com.mypackage

-docencoding name

生成されるHTMLファイルのエンコーディングを指定します。この名前はIANA Registry, Character Setsで指定されている望ましいMIME名である必要があります。

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

-docfilessubdirs

再帰的にdoc-fileサブディレクトリをコピーします

-doctitle title

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

--excludedocfilessubdir name

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

-footer html-code

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

--frames

生成された出力でのフレームの使用を有効化します(デフォルト)。

-group name p1:p2

指定されたパッケージを概要ページでグループ化します。

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

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

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

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

たとえば、次のjavadocコマンドでは、ドキュメント化される3つのパッケージは、Core、Extension、およびOther Packagesに分けられます。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

-header header

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

-helpfile path\filename

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

Oracle Solaris、LinuxおよびmacOS:

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

Windows:

javadoc -helpfile C:\user\myhelp.html java.awt.

-html4

HTML4.0.1出力を生成します。

-html5

HTML5出力を生成します。HTML5によりWebページのセマンティック度が高まり、利用しやすいWebページの作成が容易になります。

注意:
-html4と-html5のいずれのオプションも、ドキュメント・コメント内のHTMLは同じバージョン(4または5)であると見なします。いずれのオプションも指定しない場合は、デフォルトでHTML4出力が生成されます。標準ドックレットは、ユーザー・ドキュメント・コメント内のHTMLを指定された出力バージョンに変換することはしません。

-keywords

HTMLキーワードの<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()">

-link URL

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が絶対か相対か、およびhttp:かfile:かにかかわらず、URL Memo: Uniform Resource Locatorsで指定されているとおりにセパレータとしてスラッシュを使用します。

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

linkオプションの使用を参照してください。

-linkoffline url1 url2

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

url1またはurl2の値は、リンク先にする、Javadocによって生成された外部ドキュメントを含むディレクトリの絶対URLまたは相対URLです。相対値の場合、-dオプションで指定される生成先ディレクトリを基準にした、リンクされるパッケージのルートの相対パスを指定する必要があります。-linkオプションのurlを参照してください。javadocコマンドの1回の実行で、複数の-linkofflineオプションを指定できます。

linkofflineオプションの使用を参照してください。

-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()

-nocomment

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

-nodeprecated

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

-nodeprecatedlist

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

--no-frames

生成された出力でのフレームの使用を無効化します。

-nohelp

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

-noindex

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

-nonavbar

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

-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オプションを使用したかどうかにかかわらず有効です。

-nosince

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

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

-notree

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

-overview filename

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

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

Oracle Solaris、LinuxおよびmacOS: たとえば、java.langパッケージのソース・ツリーが/src/classes/java/lang/の場合、概要ファイルを/src/classes/overview.htmlに配置できます。

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

javadocコマンドの実行例を参照してください。

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

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

-serialwarn

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

-sourcetab tablength

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

-splitindex

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

-stylesheet filename

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

Oracle Solaris、LinuxおよびmacOS:

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

Windows:

javadoc -stylesheet file C:\user\mystylesheet.css com.mypackage

-tag tagname :Xaoptcmf:"taghead"

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

タグ・オプションの使用を参照してください。

-taglet class

そのタグのドキュメントの生成に使うタグレットを起動するためのクラス・ファイルを指定します。classの値には完全修飾名を使用してください。このタグレットは、カスタム・タグのテキスト引数の数も定義します。タグレットは、これらの引数を受け付け、処理し、出力を生成します。

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

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

-tagオプションのかわりに-tagletオプションを使用することもできますが、読みにくくなる場合があります。

-tagletpath tagletpathlist

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

-top

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

-use

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

-version

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

-windowtitle title

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

-Xdoclint

javadocコメントの問題に関する推奨チェックを有効にします。

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

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

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

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

-Xdoclintオプションは、リクエストされたマークアップに基づいて入力コメントを有効にします。

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

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

-Xdoclint none

-Xdoclintオプションを無効にします。

-Xdoclint group

groupチェックを有効にします。

-Xdoclint all

すべてのグループのチェックを有効にします。

-Xdoclint all, -group

groupチェックを除くすべてのチェックを有効にします。

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

accessibility

アクセシビリティ・チェッカで検出されるような問題をチェックします(たとえば、<table>タグにキャプション属性やサマリー属性が指定されていない場合)。

html

高レベルのHTMLの問題を検出します(ブロック要素がインライン要素の内側にある、終了タグを必要とする要素が閉じていない、など)。このルールは、選択された標準ドックレットHTML出力生成に基づいて、HTML4仕様およびHTML5仕様から導出されます。このタイプのチェックを使用すると、一部のブラウザで意図したとおりに解釈されない可能性があるHTMLの問題をjavadocコマンドで検出できます。

missing

javadocコメントまたはタグの欠落をチェックします(たとえば、コメントやクラスが見つからない、メソッドに@returnタグや類似のタグがない、など)。

reference

javadocタグからJava API要素を参照する場合の問題をチェックします(たとえば、@seeに項目が見つからない、@paramの後の名前が正しくない、など)。

syntax

低レベルの問題をチェックします。たとえば、山カッコ(<と>)やアンパサンド(&)がエスケープされていない、javadocタグが無効である、などです。

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

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

注意:

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

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

--Xdoclint/package:([-])packages
特定のパッケージのチェックを有効または無効にします。packagesはカンマで区切られたパッケージ指定子のリストです。パッケージ指定子は、パッケージの修飾された名前、またはパッケージ名の接頭辞の後に*を指定(指定したパッケージのすべてのサブパッケージに拡張)したものです。パッケージ指定子の前に-を指定すると、指定したパッケージに関するチェックを無効にできます。

-Xdocrootparent url
ドキュメント・コメント内の/..が後に続く@docRootのすべてをurlで置換します。

生成されるファイル

javadocコマンドを、HTML形式のドキュメントを生成する標準ドックレットとして使用します。

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

基本内容ページ

- ドキュメント化するクラスまたはインタフェースごとに1つのクラス・ページまたはインタフェース・ページ(classname.html)。

- ドキュメント化するパッケージごとに1つのパッケージ・ページ(package-summary.html)。javadocコマンドは、ソース・ツリーのpackageディレクトリ内にpackage.htmlまたはpackage-info.javaというファイルがあれば、その中のHTMLテキストをこのページに組み入れます。

- パッケージのセット全体に対して1つの概要ページ(overview-summary.html)。概要ページは、生成ドキュメントの先頭ページになります。javadocコマンドは、-overviewオプションで指定されたファイル内のHTMLテキストをこのページに組み入れます。概要ページが作成されるのは、javadocコマンドに複数のパッケージ名を渡した場合のみです。HTMLフレームおよびJavadocドックレットのオプションを参照してください。

相互参照ページ

- パッケージのセット全体に対して1つのクラス階層ページ(overview-tree.html)。階層ページを表示するには、ナビゲーション・バーの「概要」をクリックしてから、「階層ツリー」をクリックします。

- 各パッケージに対して1つのクラス階層ページ(package-tree.html)。特定のパッケージ、クラス、またはインタフェースのページを表示してから、「階層ツリー」をクリックすると、そのパッケージのクラス階層が表示されます。

- パッケージごとに1つの「使用」ページ(package-use.html)と、クラスおよびインタフェースごとに1つの「使用」ページ(class-use/classname.html)。「使用」ページには、指定されたクラス、インタフェース、またはパッケージの一部を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。たとえば、クラスまたはインタフェースAを例にすると、その使用ページには、Aのサブクラス、Aとして宣言されたフィールド、Aを返すメソッド、A型のパラメータを持つメソッドおよびコンストラクタが組み込まれます。「使用」ページを表示するには、そのパッケージ、クラスまたはインタフェースに移動し、ナビゲーション・バーの「使用」リンクをクリックしてください。

- 非推奨APIページ(deprecated-list.html)。すべての非推奨APIおよびそれに代わる推奨APIが一覧表示されます。非推奨APIは、将来の実装では削除される可能性があるため、使用しないようにしてください。
定数フィールド値ページ(constant-values.html)。staticフィールドの値用です。

- 直列化された形式ページ(serialized-form.html)。直列化および外部化可能なクラスに関する情報を、フィールドとメソッドの説明とともに提供します。このページの情報は、APIを使う開発者ではなく、再実装を行う開発者に必要な情報です。直列化された形式ページへアクセスするには、直列化されたクラスに移動して、そのクラス・コメントにある「関連項目」セクションで「直列化された形式」をクリックします。標準ドックレットは直列化された形式ページを生成します。このページには、Serializableを実装するすべてのクラス(publicまたは非public)が、そのreadObjectやwriteObjectメソッド、直列化されたフィールド、および@serial、@serialField、@serialDataタグからのドキュメンテーション・コメントとともにリストされます。publicのSerializableクラスを除外するには、そのクラスまたはそのクラスが属するパッケージを@serial excludeタグで指定します。package-privateのSerializableクラスを含めるには、そのクラスまたはそのクラスが属するパッケージを@serial includeタグで指定します。-privateオプションの指定なしでjavadocコマンドを実行することにより、publicクラスおよびprivateクラスの完全に直列化された形式を生成できます。Javadocドックレットのオプションを参照してください。

- 索引ページ(index-*.html)。すべてのクラス名、インタフェース名、コンストラクタ名、フィールド名、およびメソッド名が、アルファベット順に並んでいます。索引ページは、Unicodeを扱えるように国際化されています。1つのファイルとして生成することも、先頭文字(英語の場合A–Z)ごとに別々のファイルとして生成することもできます。

サポート・ページ

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

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

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

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

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

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

Javadocドックレットのオプションを参照してください。

HTMLフレーム

javadocコマンドは、コマンドに渡された値に応じて、最低限必要な数(2つまたは3つ)のフレームを作成します。単一のパッケージ名、または単一のパッケージに属するソース・ファイルを引数としてjavadocコマンドに渡した場合、パッケージの一覧は省略されます。かわりに、javadocコマンドは、左側の列にクラスの一覧を表示するフレームを1つ作成します。javadocコマンドに複数のパッケージ名を渡した場合は、概要ページ(overview-summary.html)に加えて、すべてのパッケージを一覧表示する第3のフレームが作成されます。HTMLフレームはデフォルトで有効にされていますが、--no-framesオプションにより無効にできます。フレームを省略するには、「フレームなし」リンクをクリックするか、overview-summary.htmlページからページ・セットを表示します。Javadocの検索機能により、画面スペースのナビゲートと保存がしやすくなります。

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

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

Oracle Solaris、LinuxおよびmacOS: たとえば、java.math.BigDecimalクラスに対して生成されたドキュメントはjava/math/BigDecimal.htmlに格納されます。

Windows: たとえば、java.math.BigDecimalクラスに対して生成されたドキュメントはjava\math\BigDecimal.htmlに格納されます。

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

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

生成される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に依存するのではなく、コメントによる主説明としてドキュメント化する必要があります。たとえば、説明は次のようにできます。

A single enumeration cannot be used by multiple threads concurrently.
ドキュメントには、これらのセマンティクスを実現する方法を記述しないでください。たとえば、Hashtableオプションはスレッドセーフである必要がありますが、「エクスポートされるすべてのメソッドを同期化してそれを実現する」のように指定する根拠はありません。より高度な並行性のために、内部的に同期化する権限を保有しておくことをお薦めします。

javadocコマンドの実行例

javadocコマンドは、パッケージ全体に対して実行することも、個々のソース・ファイルに対して実行することもできます。Java言語で記述されたプログラムからjavadocコマンドを呼び出すには、公開プログラム・インタフェースを使用します。

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

Java言語で記述されたプログラムからjavadocコマンドを呼び出すには、com.sun.tools.javadoc.Mainの公開プログラム・インタフェースを使用します(javadocコマンドはリエントラントです)。

次の手順では、標準HTMLドックレットを呼び出します。カスタム・ドックレットを呼び出すには、-docletおよび-docletpathオプションを使用します。

簡単な例

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

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

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

1つまたは複数のパッケージのドキュメント化: パッケージをドキュメント化するには、そのパッケージのソース・ファイルを、そのパッケージと同じ名前のディレクトリ内に格納する必要があります。

Oracle Solaris、LinuxおよびmacOS:

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

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

Windows:

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

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

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

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

この例では、javadocコマンドを再帰的処理のために任意のディレクトリから実行できるように-sourcepathを使用します。これは、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. 完全修飾のパッケージ名の親ディレクトリに移ります。

2. ドキュメント化する1つ以上のパッケージの名前を指定してjavadocコマンドを実行します。
Oracle Solaris、LinuxおよびmacOS:

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

Windows:

cd C:\home\src\
javadoc -d C:\home\html java.awt java.awt.event

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

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

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

Oracle Solaris、LinuxおよびmacOS:

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

Windows:

javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event

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

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

Oracle Solaris、LinuxおよびmacOS:

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

Windows:

javadoc -d C:\home\html -sourcepath C:\home\src1;C:\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つのフレームを持つことになります。

Oracle Solaris、LinuxおよびmacOS:

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

Windows:

cd C:\home\src\java\awt
javadoc -d C:\home\html Button.java Canvas.java Graphics*.java

例2   パッケージのルート・ディレクトリに移る

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

Oracle Solaris、LinuxおよびmacOS:

cd /home/src/
javadoc -d /home/html java/awt/Button.java java/math/BigDecimal.java

Windows:

cd C:\home\src
javadoc -d \home\html java\awt\Button.java java\math\BigDecimal.java

例3   任意のディレクトリからファイルをドキュメント化する

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

Oracle Solaris、LinuxおよびmacOS:

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

Windows:

javadoc -d C:\home\html C:\home\src\java\awt\Button.java ^
C:\home\src\java\awt\Graphics*.java

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

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

例 1

Oracle Solaris、LinuxおよびmacOS:

avadoc -d /home/html -sourcepath /home/src java.awt \
/home/src/java/math/BigDecimal.java

例 2

Windows:

javadoc -d C:\home\html -sourcepath C:\home\src java.awt ^
C:\home\src\java\math\BigDecimal.java

注意

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

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

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

- javadocコマンドは、有効なクラス名を含んでいるファイルだけを読み取ります。javadocコマンドがファイルの内容を正しく読み取っていない場合は、クラス名が有効であることを確認してください。

Oracleの法律上の注意点

コピーライト

Copyright © 1994-2017, Oracle and/or its affiliates. All rights reserved.

ライセンス制約の保証と結果的に生じる損害の免責

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

保証免責

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクルまでご連絡ください。

制限付権利について

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

危険な用途への使用について

このソフトウェアまたはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアまたはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアまたはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアまたはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、Oracle Corporationおよびその関連会社は一切の責任を負いかねます。

商標と登録商標について

OracleおよびJavaはオラクルおよびその関連会社の登録商標です。その他の社名、商品名等は各社の商標または登録商標である場合があります。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

第三者のコンテンツ、製品、サービスに対する免責事項

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。適用されるお客様とOracle Corporationとの間の契約に別段の定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。適用されるお客様とOracle Corporationとの間の契約に定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

Pre-General Availability (一般提供前)版のドキュメントについて

このドキュメントがPre-General Availability (一般提供前)版の場合:

このドキュメントはPre-General Availability (一般提供前)版であり、デモおよび暫定使用のみを目的としたものです。このソフトウェアを使用するハードウェアに限定するものではありません。Oracle Corporationおよびその関連会社は、このドキュメントに関して一切の責任を負わず、いかなる保証もいたしません。また、このドキュメントを使用したことによって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。

非公開のPre-General Availability (一般提供前)版のドキュメントについて

このドキュメントが非公開のPre-General Availability (一般提供前)版の場合:

このドキュメントに含まれる情報は、情報の共有のみを目的としたものであって、顧客諮問委員会(Customer Advisory Board)のメンバーとしてのお客様の立場でのみ、またはお客様のPre-General Availability Trial Agreement (Pre-GAトライアル契約)のみに従って検討されるべきものとします。マテリアル、コード、または機能の提供をお約束するものではなく、購入決定を行う際の判断材料とすべきではありません。このドキュメントに記載されている特徴または機能の開発、リリースおよび時期については、オラクルの裁量により決定されます。

このドキュメントには、ソフトウェアまたは印刷物などの形式を問わず、オラクルが独占的な権利を有する財産的情報が含まれています。この機密資料へのアクセスと使用は、お客様とオラクルとの間で締結され、お客様が遵守に同意した、Oracle Master Agreement、Oracle License and Oracle Services Agreement (オラクル・ライセンスおよびサービスに関する契約書)、Oracle Partner Network Agreement、Oracle Distribution Agreementまたはその他のライセンス契約の条件に従うものとします。このドキュメントとその内容の開示、コピー、複製および配布には、オラクルによる事前の承諾を必要とします。このドキュメントはライセンス契約の一部となるものではなく、オラクルおよびその子会社や関連会社との契約を構成するものではありません。

ドキュメントのアクセシビリティ

オラクルのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイト(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc)を参照してください。

Oracle Supportへのアクセス

サポートをご契約のお客様には、My Oracle Supportを通して電子支援サービスを提供しています。詳細情報は(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info)か、聴覚に障害のあるお客様は(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs)を参照してください。