3 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オプションを使用します。このような状況は、ファイアウォールの内側からファイアウォールの外側にあるドキュメントにリンクしようとする場合に発生します。

クラスの参照方法

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

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

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

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

1. API仕様にあるpackage-listファイルをブラウザで開きます。

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

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

javadoc -linkoffline https://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内の元のファイルにコピーします。

タグの配置

タグの配置位置を制限しない場合は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コマンドは、@文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。

例

単一の引数ファイル

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