javadoc
コマンド行の形式はjavadoc [options] [packagenames] [sourcefiles] [@files]
です。オプションはドックレット・オプションまたは標準ドックレット・オプションです。javadoc
コマンドはプログラムで実行することもできます。
javadoc
ツールおよびそのオプションを使用して、Javaソース・ファイルからAPIドキュメントのHTMLページを生成します。
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
には次のいずれかを指定できます。
--show-module-contents value
モジュール宣言の文書粒度を指定します。指定できる値はapi
またはall
です。
--show-packages value
どのモジュール・パッケージをドキュメント化するかを指定します。指定できる値はexported
またはall
パッケージです。
--show-types value
どの宣言(フィールドやメソッド)をドキュメント化するかを指定し、value
には次のいずれかを指定できます。
-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
オプションは、「コードからは参照されていても、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
です。
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
コマンドは警告を出力します。
java.lang
、java.io
およびその他のJava SEパッケージにリンクするにはlinkoffline
オプションを使用します
外部ドキュメントへの絶対リンク
java.lang
、java.io
、およびその他のJava SEパッケージにリンクする場合について考えます。ただし、シェルからWebにアクセスできないとします。この場合は、次のようにします。
API仕様にあるpackage-list
ファイルをブラウザで開きます。
このファイルをローカル・ディレクトリに保存し、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
コマンドに対する引数(-J
オプションを除く)が入った1つ以上のファイルを指定します。このことを利用すれば、どのオペレーティング・システム上でも、任意の長さのjavadoc
コマンドを作成できます。
javadoc
コマンドを実行するときに、各引数ファイルのパスとファイル名を先頭に@
文字を付けて渡します。javadoc
コマンドは、@
文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。
例
argfile
という名前の引数ファイルにjavadoc
コマンドのすべての引数を格納できます: javadoc @argfile
。
引数ファイルには両方のファイルのコンテンツが格納されます。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 © 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 © 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の-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が絶対か相対か、およびh
ttp:
かf
ile:
かにかかわらず、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
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仕様には含まれません。
synchronized
に依存するのではなく、コメントによる主説明としてドキュメント化する必要があります。たとえば、説明は次のようにできます。 A single enumeration cannot be used by multiple threads concurrently.ドキュメントには、これらのセマンティクスを実現する方法を記述しないでください。たとえば、
Hashtable
オプションはスレッドセーフである必要がありますが、「エクスポートされるすべてのメソッドを同期化してそれを実現する」のように指定する根拠はありません。より高度な並行性のために、内部的に同期化する権限を保有しておくことをお薦めします。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
オプションを使用します。次の例では、両方の方法について説明します。
この例では、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
完全修飾のパッケージ名の親ディレクトリに移ります。
ドキュメント化する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
引数にその名前を追加します。
この場合、現在のディレクトリがどこかは問題ではありません。最上位パッケージの親ディレクトリを-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
各ツリーのルートへのパスをコロンで区切ったリストを-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つ以上のソース・ファイルの名前を指定して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
これは、同じルート内にある複数のサブパッケージの個々のソース・ファイルをドキュメント化する場合に便利です。パッケージのルート・ディレクトリに移り、各ソース・ファイルを、ルートからのパスとともに指定します。
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
この場合、現在のディレクトリがどこかは問題ではありません。ドキュメント化するソース・ファイルへの絶対パス(または、現在のディレクトリからの相対パス)を指定して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
オプションは、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。
注意
-windowtitle
オプションを省略すると、javadoc
コマンドによって、ドキュメント・タイトルがウィンドウ・タイトルにコピーされます。-windowtitle
オプションのテキストは、-doctitle
オプションに似ていますが、HTMLタグは使用しません。HTMLタグは、ウィンドウ・タイトルにそのまま文字で(プレーン・テキストで)表示されてしまいます。
-footer
オプションを省略すると、javadoc
コマンドによって、ヘッダー・テキストがフッターにコピーされます。
前の例では必要ありませんでしたが、-classpath
および-link
も重要なオプションです。
javadoc
コマンドは、有効なクラス名を含んでいるファイルだけを読み取ります。javadoc
コマンドがファイルの内容を正しく読み取っていない場合は、クラス名が有効であることを確認してください。