." Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
."
." This code is free software; you can redistribute it and/or modify it
." under the terms of the GNU General Public License version 2 only, as
." published by the Free Software Foundation.
."
." This code is distributed in the hope that it will be useful, but WITHOUT
." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
." FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
." version 2 for more details (a copy is included in the LICENSE file that
." accompanied this code).
."
." You should have received a copy of the GNU General Public License version
." 2 along with this work; if not, write to the Free Software Foundation,
." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
."
." Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
." or visit www.oracle.com if you need additional information or have any
." questions.
."
.TH javadoc 1 "14 Apr 2011"
.SH "名前"
javadoc \- Java API ドキュメントジェネレータ
.LP
Java ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている Javadoc の例は、 Solaris を使用した場合のものです。
.SH "形式"
.LP
\f4javadoc\fP\f2\ [\ \fP\f2options\fP\f2\ ]\ [\ packagenames\ ]\ [\ sourcefilenames\ ]\ [\ \-subpackages\fP\ \f2pkg1:pkg2:...\fP\f2\ ]\ [\ \fP\f2@argfiles\fP\f2\ ]\fP
.LP
引数を指定する順序は任意です。Javadoc ツールでの、処理対象の .java ファイルを決定する方法の詳細については、「ソースファイルの処理」\f2を参照\fPしてください。
.RS 3
.TP 3
options
このドキュメントで説明されているコマンド行オプションです。Javadoc オプションの標準的な使用法については、「使用例」を参照してください。
.TP 3
packagenames
スペースで区切られた一連のパッケージ名です。たとえば、 \f2java.lang\ java.lang.reflect\ java.awt のように指定します\fP。ドキュメント化するパッケージを個別に指定する必要があります。ワイルドカードは使用不可です。再帰的処理のためには、\-subpackages を使用します。Javadoc ツールは、\f2\-sourcepath\fP を使用してこれらのパッケージ名を検索します。「1 つ以上のパッケージのドキュメント化」の例を参照してください。
.TP 3
sourcefilenames
スペースで区切られた一連のソースファイル名です。 各ファイルは、パスで始まります。アスタリスク (*) などのワイルドカードを含めることができます。Javadoc ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、その拡張子を除いた名前が実際に有効なクラス名であるすべてのファイルです (
.na
\f2「Identifiers」\fP @
.fi
http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625を参照)。したがって、ハイフンを含む名前 ( \f2X\-Buffer\fP など) や、その他の無効な文字を含む名前を付けることによって、それらのファイルをドキュメント化の対象から除外できます。これは、テスト用のファイルや、テンプレートから生成されたファイルの場合に便利です。ソースファイル名の前に指定したパスによって、javadoc がそのファイルを検索する場所が決まります。Javadoc ツールは、これらのソースファイル名を検索するときには \f2\-sourcepath\fP を使用しません。相対パスは現在のディレクトリを起点とするため、 \f2Button.java\fP を渡すことは、 \f2./Button.java\fP を渡すことと同じです。ソースファイル名をフルパスで指定すると、 \f2/home/src/java/awt/Graphics*.java のようになります\fP。 「1 つ以上のクラスのドキュメント化」の例を参照してください。また、「パッケージとクラスのドキュメント化」の例のように、パッケージ名とソースファイル名を混在させることもできます。
.TP 3
\-subpackages pkg1:pkg2:...
ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。パッケージ名またはソースファイル名を指定する必要はありません。
.TP 3
@argfiles
Javadoc オプション、パッケージ名、およびソースファイル名を任意の順序で並べたリストが含まれる 1 つ以上のファイルです。ワイルドカード (*) や \f2\-J\fP オプションは、このファイルの中では指定できません。
.RE
.SH " 説明"
.LP
\f3Javadoc\fP ツールは、一連の Java ソースファイルにある宣言およびドキュメンテーションコメントを解析し、デフォルトでは public クラス、protected クラス、入れ子にされたクラス (匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連の HTML ページを生成します。また、API (アプリケーションプログラミングインタフェース) ドキュメントの生成や、一連のソースファイルの実装ドキュメントの生成に使用できます。
.LP
Javadoc ツールは、パッケージ全体、個々のソースファイル、またはその両方に対して実行できます。パッケージ全体のドキュメント化を行うには、\f2\-subpackages\fP を使用して最上位ディレクトリから下方に再帰的にたどるか、パッケージ名の明示的なリストを渡します。個々ソースファイルに対して javadoc を実行する場合は、一連のソース (.\f2.java\fP) ファイル名を渡します。具体的な例は、このドキュメントの最後に紹介します。次に、Javadoc によるソースファイルの処理について説明します。
.SS
ソースファイルの処理
.LP
Javadoc ツールは、末尾が「\f2.java\fP」のファイルを処理するだけでなく、「ソースファイル」で説明するその他のファイルも処理します。個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、どの \f2.java\fP ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソースファイル名を明示的に指定しなくても、Javadoc ツールは 3 つの方法で実行できます。その方法とは、(1) パッケージ名を渡す、(2) \f2\-subpackages\fP を使用する、(3) ソースファイル名でワイルドカードを使用する (\f2*.java\fP)、の 3 つです。これらの場合、Javadoc ツールが「\f2.java\fP」ファイルの処理を行うのは、そのファイルが次のすべての要件を満たす場合だけです。
.RS 3
.TP 2
o
名前から接尾辞「\f2.java\fP」を取り除くと実際に有効なクラス名になっている (有効な文字については
.na
\f2「Identifiers」\fP @
.fi
http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625を参照)
.TP 2
o
ソースツリーのルートから相対的なディレクトリパスが、区切り文字をドットに変換すると、実際に有効なパッケージ名になっている
.TP 2
o
パッケージ文には有効なパッケージ名が含まれる (前項目で指定)
.RE
.LP
\f3リンクの処理\fP \- Javadoc ツールは、処理の実行中に、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、自動的に相互参照リンクを追加します。このようなリンクは、次のような場所に追加されます。
.RS 3
.TP 2
o
宣言 (戻り値の型、引数の型、フィールドの型)
.TP 2
o
\f2@see\fP タグから生成された [関連項目] セクション
.TP 2
o
\f2{@link}\fP タグから生成されたインラインテキスト
.TP 2
o
\f2@throws\fP タグから生成された例外の名前
.TP 2
o
インタフェースのメンバーに対する「定義」リンクと、クラスのメンバーに対する「オーバーライド」リンク
.TP 2
o
パッケージ、クラス、およびメンバーを列挙している概要テーブル
.TP 2
o
パッケージおよびクラスの継承ツリー
.TP 2
o
索引
.RE
.LP
コマンド行で指定しなかったクラスについての既存のテキスト (別に生成したテキスト) に対してハイパーリンクを追加するには、\f2\-link\fP および \f2\-linkoffline\fP オプションを利用できます。
.LP
\f3その他の処理についての詳細\fP \- Javadoc ツールは、実行するたびに 1 つの完全なドキュメントを作成します。ドキュメントを追加生成することはできません。つまり、Javadoc ツールの以前の実行結果を修正したり、その内容を直接組み入れたりすることはできません。ただし、前述のように、以前の実行結果に対してリンクを追加することはできます。
.LP
実装上の理由から、Javadoc ツールは、処理を実行するために java コンパイラを必要とし、java コンパイラに依存しています。Javadoc ツールは、 \f2javac\fP の一部を呼び出して宣言をコンパイルしますが、メンバーの実装は無視します。Javadoc ツールは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、その情報から HTML を生成します。さらに、Javadoc ツールは、ソースコードのドキュメンテーションコメントから、ユーザーの提供したドキュメントも取得します。
.LP
実際には、Javadoc ツールは、メソッド本体を持たない純粋なスタブファイルであるような \f2.java\fP ソースファイルでも動作します。したがって、API の作成時には、実装を記述する前の設計の早い段階で、ドキュメンテーションコメントを記述して javadoc ツールを実行できます。
.LP
コンパイラに依存することによって、HTML 出力は、実際の実装に正確に対応します。実際の実装は、明示的なソースコードにではなく、暗黙のソースコードに依存する場合があります。たとえば、Javadoc ツールは、.class ファイルには存在するがソースコードには存在しない
.na
\f2デフォルトコンストラクタ\fP @
.fi
http://java.sun.com/docs/books/jls/second_edition/html/names.doc.html#36154 (Java 言語仕様のセクション 8.6.7) \f2をドキュメント化\fP します。
.LP
通常、Javadoc ツールでは、ソースファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。このため、デバッグやトラブルシューティングを完了する前にドキュメントを生成できます。たとえば、Java 言語仕様によると、抽象メソッドを含むクラスは、それ自体抽象として宣言されなければなりません。このエラーを検出すると、javac コンパイラは停止しますが、Javadoc ツールは警告を出さずに処理を続行します。Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。
.LP
Javadoc ツールは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、Javadoc ツールは、ブートストラップクラス、拡張機能、またはユーザークラスにかかわらず、すべての参照クラスを検索できなければなりません。詳細は、
.na
\f2「クラスの検索方法」\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.htmlを参照してください。通常、作成するクラスは、拡張機能としてロードするか、Javadoc ツールのクラスパス内に置く必要があります。
.SS
Javadoc のドックレット
.LP
Javadoc ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。Javadoc ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み」ドックレットがあります。標準ドックレットは、HTML 形式の API ドキュメントを生成します。標準ドックレットを修正またはサブクラス化することや、HTML、XML、MIF、RTF などの好みの出力形式を生成する独自のドックレットを記述することも可能です。ドックレットとその使用法については、次の項目を参照してください。
.RS 3
.TP 2
o
.na
\f2Javadoc のドックレット\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html
.TP 2
o
\f2\-doclet\fP コマンド行オプション
.RE
.LP
\f2\-doclet\fP コマンド行オプションでカスタムドックレットが指定されていない場合、Javadoc ツールは、デフォルトの標準ドックレットを使用します。javadoc ツールには、使用されているドックレットに関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらのほかに、いくつかのコマンド行オプションが追加されます。どちらのオプションについても、このあとの「オプション」で説明します。
.SS
関連ドキュメントおよびドックレット
.RS 3
.TP 2
o
.na
\f2Javadoc に施された拡張機能\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html \- Javadoc 1.4 で追加された改良点の詳細
.TP 2
o
.na
\f2Javadoc FAQ\fP @
.fi
http://java.sun.com/j2se/javadoc/faq/index.html \- 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法
.TP 2
o
.na
\f2How to Write Doc Comments for Javadoc\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html \- ドキュメンテーションコメントの記述方法に関する Sun の規約
.TP 2
o
.na
\f2Requirements for Writing API Specifications\fP @
.fi
http://java.sun.com/j2se/javadoc/writingapispecs/index.html \- Java SE プラットフォーム仕様を記述する際に使用された標準要件この情報は、ソースファイルのドキュメンテーションコメント形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも役立ちます。検証可能なアサーションを満たすパッケージ、クラス、インタフェース、フィールド、およびメソッドについての要件を定めています。
.TP 2
o
.na
\f2ドキュメンテーションコメントの仕様\fP @
.fi
http://java.sun.com/docs/books/jls/first_edition/html/18.doc.html \- ドキュメンテーションコメントのオリジナル仕様については、『Java Language Specification』 (James Gosling、Bill Joy、Guy Steele 共著) の初版の第 18 章「Documentation Comments」を参照してください。この章は、第 2 版では削除されました。
.TP 2
o
.na
\f2DocCheck ドックレット\fP @
.fi
http://java.sun.com/javadoc/doccheck \- ソースファイル内のドキュメンテーションコメントをチェックし、検出されたエラーや不正のレポートを生成します。Doc Check ユーティリティーの一部です。
.TP 2
o
.na
\f2MIF ドックレット\fP @
.fi
http://java.sun.com/javadoc/mifdoclet \- MIF、FrameMaker、PDF の書式で API ドキュメントを自動生成します。MIF は Adobe FrameMaker の交換書式です。
.RE
.SS
用語
.LP
\f2「ドキュメンテーションコメント」\fP、\f2「doc コメント」\fP、\f2「主説明」\fP、\f2「タグ」\fP、\f2「ブロックタグ」\fP、および\f2「インラインタグ」\fPの用語については、「ドキュメンテーションコメント」で説明します以下のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。
.RS 3
.TP 3
生成ドキュメント (generated document)
javadoc ツールが Java ソースコード内のドキュメンテーションコメントから生成したドキュメントのことです。デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。
.LP
.TP 3
名前 (name)
Java 言語で書かれたプログラム要素の名前、つまりパッケージ、クラス、インタフェース、フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、 \f2java.lang.String.equals(java.lang.Object)\fP のような完全修飾名にすることも、 \f2equals(Object)\fP のような部分修飾名にすることもできます。
.LP
.TP 3
ドキュメント化されるクラス (documented classes)
javadoc ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。ドキュメント化するには、ソースファイルが使用可能でなければならず、ソースファイル名またはパッケージ名を javadoc コマンドに渡され、アクセス修飾子 (public、protected、package\-private または private) によってフィルタ処理されないようにしなければなりません。ドキュメント化されるクラスは、javadoc ツールの出力に組み込まれるクラス、つまり「包含クラス」とも呼ばれます。
.LP
.TP 3
包含クラス (included classes)
ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。「ドキュメント化されるクラス」と同じ。
.LP
.TP 3
除外クラス (excluded classes)
ツールの実行によって詳細なドキュメントが生成されないクラスおよびインタフェースのことです。
.LP
.TP 3
参照クラス (referenced classes)
ドキュメント化されるクラスおよびインタフェースの定義 (実装) またはドキュメンテーションコメントの中で明示的に参照されているクラスおよびインタフェースのことです。参照の例としては、戻り値の型、パラメータの型、キャストの型、拡張されたクラス、実装されたインタフェース、インポートされたクラス、メソッド本体で使用されるクラス、@see、{@link}、{@linkplain}、{@inheritDoc} タグなどがあります。この定義は
.na
\f21.3\fP @
.fi
http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses から変更されています。javadoc ツールを実行するときは、Javadoc のブートクラスパスおよびクラスパス内にあるすべての参照クラスをメモリーにロードする必要があります。参照クラスが見つからない場合は、「クラスが見つかりません」という警告が表示されます。Javadoc ツールは、クラスの存在とそのメンバーの完全指定の名前を判別するのに必要なすべての情報を、.class ファイルから引き出すことができます。
.LP
.TP 3
外部参照クラス (external referenced classes)
参照クラスのうち、javadoc ツールの実行中にドキュメントが生成されないクラスのことです。つまり、これらのクラスは、コマンド行で Javadoc ツールに渡されていません。生成ドキュメント内でこれらのクラスにリンクしている箇所は、「外部参照」または「外部リンク」と呼ばれます。たとえば、Javadoc ツールの実行対象が \f2java.awt\fP パッケージのみである場合、 \f2java.lang\fP 内のすべてのクラス ( \f2Object\fPなど) が外部参照クラスになります。外部参照クラスにリンクするには、 \f2\-link\fP および \f2\-linkoffline\fP オプションを使用します。外部参照クラスには、通常そのソースコメントを javadoc ツールの実行で利用できないという重要な特徴があります。この場合、それらのコメントを継承することはできません。
.RE
.SH "ソースファイル"
.LP
Javadoc ツールは 4 種類の異なる「ソース」ファイルから出力を生成します。その 4 種類とは、クラスの Java 言語ソースファイル (\f2.java\fP)、パッケージコメントファイル、概要コメントファイル、およびその他の処理されないファイルです。また、ドキュメント化しないがソースツリーに存在する場合があるテストファイルやテンプレートファイルについても説明します。
.SS
クラスソースコードファイル
.LP
それぞれのクラスまたはインタフェース、およびそのメンバーは、独自のドキュメンテーションコメントを持つことができ、それを \f2.java\fP ファイル内に保持します。ドキュメンテーションコメントの詳細は、「ドキュメンテーションコメント」を参照してください。
.SS
パッケージコメントファイル
.LP
それぞれのパッケージは、独自のドキュメンテーションコメントを持つことができ、それを専用の「ソース」ファイルに保持します。その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、そのパッケージ全体に当てはまるドキュメントを記述します。
.LP
パッケージコメントファイルを作成する場合、コメントの格納先として、次の 2 つのファイルのいずれかを選択できます。
.RS 3
.TP 2
o
\f2package\-info.java\fP \- パッケージ宣言、パッケージ注釈、パッケージコメント、および Javadoc タグを格納できます。このファイルは一般に、package.html よりも推奨されます。
.TP 2
o
\f2package.html\fP \- 格納できるのはパッケージコメントと Javadoc タグだけです。パッケージ注釈は格納できません。
.RE
.LP
各パッケージでは、単一の \f2package.html\fP ファイル、単一の \f2package\-info.java\fP ファイルのいずれかを選択できますが、その両方を選択することはできません。このどちらかのファイルを \f2.java\fP ファイルとともに、ソースツリー内のそのパッケージのディレクトリ内に配置してください。
.LP
\f4package\-info.java\fP \- このファイルには、次の構造のパッケージコメントを格納できます。 コメントはパッケージ宣言の前に配置します。
.LP
File: \f2java/applet/package\-info.java\fP
.nf
\f3
.fl
/**
.fl
* Provides the classes necessary to create an
.fl
* applet and the classes an applet uses
.fl
* to communicate with its applet context.
.fl
*
.fl
* The applet framework involves two entities:
.fl
* the applet and the applet context.
.fl
* An applet is an embeddable window (see the
.fl
* {@link java.awt.Panel} class) with a few extra
.fl
* methods that the applet context can use to
.fl
* initialize, start, and stop the applet.
.fl
*
.fl
* @since 1.0
.fl
* @see java.awt
.fl
*/
.fl
package java.lang.applet;
.fl
\fP
.fi
.LP
コメント区切り文字の \f2/**\fP と \f2/*\fP は存在している必要がありますが、中間行の行頭のアスタリスクは省略してもかまいません。
.LP
\f4package.html\fP \- このファイルには、次の構造のパッケージコメントを格納できます。コメントは \f2
\fP 要素内に配置します。
.LP
File: \f2java/applet/package.html\fP
.nf
\f3
.fl
Provides the classes necessary to create an applet and the classes an applet uses to communicate with its applet context.
.fl
The applet framework involves two entities: the applet
.fl
and the applet context. An applet is an embeddable window (see the {@link java.awt.Panel} class) with a few extra methods that the applet context can use to initialize, start, and stop the applet.@since 1.0 @see java.awt
.fl
\fP
.fi
.LP
これは単なる通常の HTML ファイルであり、パッケージ宣言を含んでいない点に注意してください。パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に HTML で記述しますが、1 つだけ例外があります。それは、このドキュメンテーションコメントには、コメント区切り文字 である \f2/**\fP と \f2*/\fP 、および行頭のアスタリスクを含めてはならない、という点です。コメントを書く場合は、最初の文をパッケージの概要とし、 \f2
\fP と最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージタグを含めることはできますが、ほかのドキュメンテーションコメントと同様、すべてのブロックタグは、主説明のあとに置かなければなりません。 \f2@see\fP タグをパッケージコメントファイルに追加する場合には、完全修飾名を使用する必要があります。詳細は、
.na
\f2package.html\fPの例 @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#packagecommentsを参照してください。
.LP
\f3パッケージコメントファイルの処理\fP \- Javadoc ツールは、実行時にパッケージコメントファイルを自動的に検索し、このファイルを見つけると次の処理を行います。
.RS 3
.TP 2
o
処理できるようにコメントをコピーする( \f2package.html\fP の場合であれば、 \f2\fP と \f2\fP HTML タグの間にある内容をすべてコピーする。 \f2\fP セクションを含め、そこに \f2\fP やソースファイルの著作権記述などの情報を配置することもできるが、生成後のドキュメンテーションにはそれらは一切表示されない)
.TP 2
o
パッケージタグがあれば、すべて処理する
.TP 2
o
生成したパッケージの概要ページの最後に、処理したテキストを挿入する (例:
.na
\f2パッケージの概要\fP @
.fi
http://java.sun.com/javase/6/docs/api/java/applet/package\-summary.html)
.TP 2
o
パッケージの概要ページの先頭に、パッケージコメントの最初の文をコピーする。さらに、概要ページのパッケージリストに、パッケージ名とパッケージコメントの最初の文を追加する (例:
.na
\f2概要の要約\fP @
.fi
http://java.sun.com/javase/6/docs/api/overview\-summary.html)。文の末尾は、クラスやメンバーの主説明の最初の文の末尾と同じ規則によって判断される
.RE
.SS
概要コメントファイル
.LP
ドキュメント化する各アプリケーションまたはパッケージセットは、独自の概要ドキュメンテーションコメントを持つことができ、それは専用の「ソース」ファイルに保持されます。その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージセット全体に当てはまるドキュメントを記述します。
.LP
概要コメントファイルを作成するには、ファイルに任意の名前 (通常は \f4overview.html\fP) を付け、それを任意の場所 (通常はソースツリーの最上位) に配置できます。たとえば、 \f2java.applet\fP パッケージのソースファイルが \f2/home/user/src/java/applet\fP ディレクトリに格納されていれば、概要コメントファイルは \f2/home/user/src/overview.html に作成できます\fP。
.LP
異なるパッケージのセットに対して javadoc を複数回実行する場合は、同じ 1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。たとえば、内部ドキュメンテーション用に \-private を指定して javadoc を 1 回実行したあと、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメントファイルの 1 文目で、そのドキュメンテーションを公開用または内部用として記述できます。
.LP
概要コメントファイルの内容は、前述のパッケージコメントファイルと同様、HTML で記述された 1 つの大きなドキュメンテーションコメントです。詳細は、前述の説明を参照してください。要点を繰り返すと、このコメントを記述する場合は、最初の文をアプリケーションまたはパッケージセットの要約とし、 \f2<body>\fP と最初の文の間にタイトルその他のテキストを含めないようにします。概要タグを含めることができます。ほかのドキュメンテーションコメントと同じく、 \f2{@link}\fP などのインラインタグを除くすべてのタグは、主説明のあとに配置する必要があります。 \f2@see\fP タグを追加する場合には、完全修飾名を使用する必要があります。
.LP
Javadoc ツールの実行時に、\-overview オプションを使って概要コメントファイル名を指定します。このファイルは、パッケージコメントファイルと同じように処理されます。
.RS 3
.TP 2
o
\f2<body>\fP タグと \f2</body>\fP タグの間にあるすべての内容を処理対象としてコピーする
.TP 2
o
概要タグがあれば、すべて処理する
.TP 2
o
生成した概要ページの最後に、処理したテキストを挿入する (例:
.na
\f2概要の要約\fP @
.fi
http://java.sun.com/javase/6/docs/api/overview\-summary.html)
.TP 2
o
概要ページの先頭に、概要コメントの最初の文をコピーする
.RE
.SS
その他の未処理のファイル
.LP
ソースには、Javadoc ツールによって生成先のディレクトリにコピーされる、その他の任意のファイルを含めることができます。一般に、このようなファイルには、グラフィックファイル、サンプルの Java ソース (.java) およびクラス (.class) ファイル、内容が通常の Java ソースファイルのドキュメンテーションコメントの影響を受けない独立した HTML ファイルなどがあります。
.LP
処理されないファイルを含めるには、\f4doc\-files\fP という名前のディレクトリ内にそれらのファイルを配置します。このディレクトリは、ソースファイルが格納された任意のパッケージディレクトリのサブディレクトリにします。このようなサブディレクトリは、パッケージごとに 1 つ用意できます。イメージ、サンプルコード、ソースファイル、.class ファイル、アプレット、および HTML ファイルをこのディレクトリに格納できます。たとえば、ボタンの画像 \f2button.gif\fP を \f2java.awt.Button\fP クラスのドキュメンテーションに含める場合には、そのファイルを \f2/home/user/src/java/awt/doc\-files/\fP ディレクトリ内に配置します。なお、 \f2doc\-files\fP ディレクトリを \f2/home/user/src/java/doc\-files\fP に配置することはできません。なぜなら、 \f2java\fP はパッケージではないからです。つまり、java に直接含まれているソースファイルは 1 つも存在していません。
.LP
これらの未処理のファイルへのリンクは、すべて明示的に記述する必要があります。これは、Javadoc ツールがそれらのファイルを見ずに、単にディレクトリとその内容を生成先にコピーするだけだからです。たとえば、 \f2Button.java\fP のドキュメンテーションコメント内のリンクは、次のようになります。
.nf
\f3
.fl
/**
.fl
* This button looks like this:
.fl
* <img src="doc\-files/Button.gif">
.fl
*/
.fl
\fP
.fi
.SS
テストファイルおよびテンプレートファイル
.LP
一部の開発者から、テストファイルおよびテンプレートファイルを対応するソースファイルの近くのソースツリーに保存したいという要望がありました。つまり、これらのソースファイルと同じディレクトリまたはサブディレクトリに保存したいということです。
.LP
個別のソースファイル名で明示的に渡して Javadoc ツールを実行する場合は、テストファイルおよびテンプレートファイルを意図的に除外して、処理されないようにすることができます。ただし、パッケージ名またはワイルドカードで渡す場合は、以下のルールに従って、これらのテストファイルおよびテンプレートファイルが処理されないようにする必要があります。
.LP
テストファイルとテンプレートファイルの違いは、テストファイルは、正当でコンパイル可能なソースファイルであるのに対して、テンプレートファイルは、そうではないという点です。ただし、テンプレートファイルも「.java」で終わることができます。
.LP
\f3テストファイル\fP \- 開発者の多くは、あるパッケージのコンパイル可能で実行可能なテストファイルをそのパッケージのソースファイルと同じディレクトリに配置したいと考えています。しかしテストファイルは、名前なしパッケージなど、ソースファイルパッケージとは別のパッケージに属させたいとも考えています (そのため、テストファイルには package ステートメントがないか、またはソースとは別の package ステートメントがある)。このような状況では、コマンド行で指定されているソースのパッケージ名を指定してそのソースがドキュメント化されているときに、テストファイルは警告またはエラーを引き起こします。そのようなテストファイルはサブディレクトリに配置する必要があります。たとえば、 \f2com.package1\fP 内のソースファイルに対するテストファイルを追加する場合は次のように、ハイフンを含んでいるためにパッケージ名としては無効であるようなサブディレクトリ内に、それらのファイルを配置します。
.nf
\f3
.fl
com/package1/test\-files/
.fl
\fP
.fi
.LP
こうすると、Javadoc ツールでは警告なしで test ディレクトリをスキップします。
.LP
テストファイルに doc コメントが含まれる場合、次のようにワイルドカードを含んだテストソースファイル名で渡してテストファイルのドキュメントを生成するように、Javadoc ツールを別個に実行できるように設定できます。たとえば、 \f2com/package1/test\-files/*.java などです\fP。
.LP
\f3ソースファイルのテンプレート\fP \- テンプレートファイルの名前は「.java」で終わることもありますが、テンプレートファイルはコンパイルできません。ソースディレクトリ内に保持したいソースファイルのテンプレートがある場合は、 \f2Buffer\-Template.java\fP のようにハイフンやその他の無効な Java 文字を名前に含めることで、テンプレートが処理されないようにします。これは、Javadoc ツールが処理するのは、「.java」接尾辞を除いた名前が 正規のクラス名であるソースファイルだけであるためです (
.na
\f2「Identifiers」\fP @
.fi
http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625参照)。
.SH "生成されるファイル"
.LP
デフォルトでは、javadoc ツールは、HTML 形式のドキュメントを生成する標準ドックレットを使います。このドックレットは、以下の種類のファイルを生成します。それぞれの HTML ページは、個々のファイルに相当します。javadoc が生成するファイルの名前には、クラスやインタフェースの名前にちなんだものと、そうでないもの ( \f2package\-summary.html など\fP) の 2 種類があります。後者のグループのファイル名には、前者のグループとファイル名が競合しないように、ハイフンが含まれています。
.LP
\f3基本内容ページ\fP
.RS 3
.TP 2
o
ドキュメント化するクラスまたはインタフェースごとに 1 つの\f3クラスページまたはインタフェースページ\fP (\f2クラス名\fP\f2.html\fP)
.TP 2
o
ドキュメント化するパッケージごとに 1 つの\f3パッケージページ\fP (\f2package\-summary.html\fP)。Javadoc ツールは、 \f2package.html\fP または \f2package\-info.java\fP という名前のファイル内の HTML テキストをすべて組み入れます。
.TP 2
o
パッケージのセット全体に対して 1 つの\f3概要ページ\fP (\f2overview\-summary.html\fP)。これは、生成ドキュメントの先頭ページになります。Javadoc ツールは、\f2\-overview\fP オプションで指定されたファイル内の HTML テキストをすべて組み入れます。このページのファイルは、javadoc に複数のパッケージ名を渡した場合にだけ作成されます。詳細は、「HTML フレーム」を参照してください。
.RE
.LP
\f3相互参照ページ\fP
.RS 3
.TP 2
o
\f3パッケージのセット全体に対して 1 つのクラス階層ページ\fP (\f2overview\-tree.html\fP)。このページを表示するには、ナビゲーションバーの [概要] をクリックしてから、[階層ツリー] をクリックします。
.TP 2
o
\f3パッケージごとに 1 つのクラス階層ページ\fP (\f2package\-tree.html\fP)。これを表示するには、特定のパッケージ、クラス、またはインタフェースのページに移動し、[階層ツリー] をクリックしてそのパッケージの階層を表示させます。
.TP 2
o
\f3パッケージごとに 1 つの [使用] ページ\fP (\f2package\-use.html\fP) と、クラスおよびインタフェースごとに 1 つずつの [使用] ページ (\f2class\-use/\fP\f2クラス名\fP\f2.html\fP)。このページには、特定のクラス、インタフェース、またはパッケージの一部を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。クラスまたはインタフェース A を例にして考えると、その [使用] ページには、A のサブクラス、A として宣言されたフィールド、A を返すメソッド、A 型のパラメータを持つメソッドおよびコンストラクタが表示されます。 このページを表示するには、まず、パッケージ、クラス、またはインタフェースのページに移動してから、ナビゲーションバーの [使用] リンクをクリックします。
.TP 2
o
\f3非推奨 API ページ\fP (\f2deprecated\-list.html\fP)。推奨されない名前がすべて一覧表示されます。非推奨名は、一般に改良された API が存在するために使用が推奨されていない API の名前であり、通常、それに置き換わる名前が提示されています。非推奨 API は、将来の実装では削除される可能性があります。
.TP 2
o
\f3定数フィールド値ページ\fP (\f2constant\-values.html\fP)。static フィールドの値用です。
.TP 2
o
\f3直列化された形式ページ\fP (\f2serialized\-form.html\fP)。直列化可能かつ外部化可能なクラスに関する情報用です。これらの各クラスには、直列化フィールドおよびメソッドに関する説明があります。これらの情報は、API を使う開発者ではなく、再実装を行う開発者に必要な情報です。ナビゲーションバーにこのページへのリンクはありませんが、直列化されたクラスに移動して、そのクラスの説明にある「関連項目」セクションで「直列化された形式」をクリックすると、この情報を取得できます。標準ドックレットは直列化された形式ページを自動生成します。Serializable を実装するすべてのクラス (public または 非 public) が含まれるほか、 \f2readObject\fP メソッドや \f2writeObject\fP メソッド、直列化されるフィールド、および \f2@serial\fP、\f2@serialField\fP、\f2@serialData\fP タグからのドキュメンテーションコメントも含まれます。public 直列化可能クラスを除外するには、そのクラス (またはそのパッケージ) を \f2@serial exclude\fP でマークします。package\-private 直列化可能クラスを含めるには、そのクラス (またはそのパッケージ) を \f2@serial include\fP でマークします。バージョン 1.4 では \f2\-private\fP オプションの指定なしで javadoc ツールを実行することにより、public クラスおよび private クラスの完全に直列化されたクラスを生成できます。
.TP 2
o
\f3索引\fP (\f2index\-*.html\fP)。すべてのクラス、インタフェース、コンストラクタ、フィールド、およびメソッドの名前がアルファベット順に並んでいます。索引は、Unicode を扱えるように国際化されています。1 つのファイルとして生成することも、先頭文字 (英語の場合 A ~ Z) ごとに別々のファイルとして生成することもできます。
.RE
.LP
\f3サポートファイル\fP
.RS 3
.TP 2
o
\f3ヘルプページ\fP (\f2help\-doc.html\fP)。ナビゲーションバーや前述の各ページに関する説明が記載されています。デフォルトのヘルプファイルに代わる独自のカスタムヘルプファイルを提供するには、\f2\-helpfile\fP を使用します。
.TP 2
o
表示用の HTML フレームを作成する 1 つの \f3index.html ファイル\fP。このファイルは、フレーム付きの先頭ページを表示する場合にロードします。このファイル自体には、テキスト内容は含まれていません。
.TP 2
o
複数の\f3フレームファイル\fP (\f2*\-frame.html\fP)。パッケージ、クラス、およびインタフェースのリストが含まれています。HTML フレームを表示するときに使用されます。
.TP 2
o
\f3パッケージリスト\fPファイル (\f2package\-list\fP)。 \f2\-link\fP および \f2\-linkoffline\fP オプションで使用されます。これは、HTML ファイルではなくテキストファイルであり、どのリンクからもアクセスできません。
.TP 2
o
\f3スタイルシート\fPファイル (\f2stylesheet.css\fP)。生成されるページ上のいくつかの要素について、色、フォントファミリ、フォントサイズ、フォントのスタイル、および配置を制御します。
.TP 2
o
\f3doc\-files\fP ディレクトリ。生成先ディレクトリにコピーするイメージ、サンプルコード、ソースコードなどのファイルがすべて格納されます。これらのファイルは、Javadoc ツールによって処理されないため、ファイル内に ｊavadoc タグがあっても無視されます。このディレクトリは、ソースツリーの中にある場合にのみ生成されます。
.RE
.LP
\f3HTML フレーム\fP
.LP
Javadoc ツールは、下の図に示すように、2 ~ 3 つの HTML フレームを生成します。1 つのパッケージしかない場合 (またはパッケージがない場合) は、パッケージの一覧を省略することによって最低限必要な数のフレームを作成します。単一のパッケージに属するソースファイル (*.java) または単一のパッケージ名を引数として javadoc コマンドに渡す場合は、左側の列にクラスの一覧を表示するフレーム (C) 1 つだけが作成されます。Javadoc に複数のパッケージ名を渡した場合は、概要ページ (Detail) に加えて、すべてのパッケージを一覧表示する第 3 のフレーム (P) が作成されます。この概要ページのファイル名は、 \f2overview\-summary.html です\fP。したがって、このファイルは、2 つ以上のパッケージ名を渡した場合にだけ作成されます。「フレームなし」リンクをクリックするか、overview\-summary.html を最初に表示すると、フレームを省略できます。
.LP
HTML フレームに慣れていない場合は、特定のフレームを印刷およびスクロールするには、そのフレームに「フォーカス」がなければならないことに注意してください。フレームにフォーカスを与えるには、そのフレームをクリックします。このようにすると、多くのブラウザでは、矢印キーやページキーを使ってそのフレームをスクロールしたり、「印刷」メニューコマンドを使ってそのフレームを印刷したりできます。
.LP
HTML フレームが必要かどうかによって、次のどちらかのファイルを開始ページとしてロードします。
.RS 3
.TP 2
o
\f2index.html\fP (フレームあり)
.TP 2
o
\f2overview\-summary.html\fP (フレームなし)
.RE
.LP
\f3生成されるファイルの構造\fP
.LP
生成されるクラスファイルおよびインタフェースファイルは、Java ソースファイルおよびクラスファイルと同じディレクトリ階層に編成されます。1 つのサブパッケージにつき 1 つのディレクトリ、という構造になります。
.LP
たとえば、 \f2java.applet.Applet\fP クラス用に生成されたドキュメントは、 \f2java/applet/Applet.html\fP に格納されます。生成先のディレクトリの名前が \f2apidocs\fP だとすると、java.applet パッケージのファイル構造は、その下に構築されます。前述のように、「frame」という語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外の HTML ファイルは、すべて右側のフレームに表示されます。
.LP
注 \- 下の階層図で、ディレクトリは\f3太字\fP (bold) で示してあります。アスタリスク (\f2*\fP) は、javadoc への引数がパッケージ名ではなくソースファイル名 (*.java) である場合に省略されるファイルおよびディレクトリを示しています。また、引数がソースファイル名の場合、 \f2package\-list\fP は作成されますが、その中身は空です。doc\-files ディレクトリは、ソースツリー内に存在する場合にのみ、生成先に作成されます。
.nf
\f3
.fl
.fl
\fP\f3apidocs\fP 最上位ディレクトリ
.fl
index.html HTML フレームを設定する初期ページ
.fl
* overview\-summary.html 全パッケージのリスト。先頭文による要約付き
.fl
overview\-tree.html 全パッケージのクラス階層のリスト
.fl
deprecated\-list.html 全パッケージの非推奨 API のリスト
.fl
constant\-values.html 全パッケージの static フィールドの値のリスト
.fl
serialized\-form.html 全パッケージの直列化された形式のリスト
.fl
* overview\-frame.html 全パッケージのリスト。左上のフレームで使用される
.fl
allclasses\-frame.html 全パッケージの全クラスのリスト。左下のフレームで使用される
.fl
help\-doc.html これらのページの構成を示すユーザーヘルプのリスト
.fl
index\-all.html \-splitindex オプションを指定しなかった場合に作成されるデフォルトの索引
.fl
\f3index\-files\fP \-splitindex オプションを指定した場合に作成されるディレクトリ
.fl
index\-<number>.html \-splitindex オプションを指定した場合に作成される索引ファイル
.fl
package\-list パッケージ名のリスト。外部参照を解決するためだけに使用される
.fl
stylesheet.css フォント、色、配置を定義する HTML スタイルシート
.fl
\f3java\fP パッケージディレクトリ
.fl
\f3applet\fP サブパッケージディレクトリ
.fl
Applet.html Applet クラスのページ
.fl
AppletContext.html AppletContext インタフェースのページ
.fl
AppletStub.html AppletStub インタフェースのページ
.fl
AudioClip.html AudioClip インタフェースのページ
.fl
* package\-summary.html このパッケージのクラスのリスト。先頭文による要約付き
.fl
* package\-frame.html このパッケージのクラスのリスト。左下のフレームで使用される
.fl
* package\-tree.html このパッケージのクラス階層のリスト
.fl
package\-use このパッケージが使用されている場所のリスト
.fl
\f3doc\-files\fP 画像やサンプルファイルを保持するディレクトリ
.fl
\f3class\-use\fP API が使用されている場所のページを保持するディレクトリ
.fl
Applet.html Applet クラスの使用に関するページ
.fl
AppletContext.html AppletContext インタフェースの使用に関するページ
.fl
AppletStub.html AppletStub インタフェースの使用に関するページ
.fl
AudioClip.html AudioClip インタフェースの使用に関するページ
.fl
\f3src\-html\fP ソースコードディレクトリ
.fl
\f3java\fP パッケージディレクトリ
.fl
\f3applet\fP サブパッケージディレクトリ
.fl
Applet.html Applet ソースコードのページ
.fl
AppletContext.html AppletContext ソースコードのページ
.fl
AppletStub.html AppletStub ソースコードのページ
.fl
AudioClip.html AudioClip ソースコードのページ
.fl
.fi
.SS
生成される API 宣言
.LP
Javadoc ツールは、それぞれのクラス、インタフェース、フィールド、コンストラクタ、およびメソッドの説明の最初に、その API 用の宣言を生成します。たとえば、 \f2Boolean\fP クラスの宣言は、次のようになります。
.LP
\f2public final class Boolean\fP
.br
\f2extends Object\fP
.br
\f2implements Serializable\fP
.LP
また、 \f2Boolean.valueOf\fP メソッドの宣言は、次のようになります。
.LP
\f2public static Boolean valueOf(String s)\fP
.LP
Javadoc ツールでは、修飾子 \f2public\fP、 \f2protected\fP、 \f2private\fP、 \f2abstract\fP、 \f2final\fP、 \f2static\fP、 \f2transient\fP、および \f2volatile\fP は組み込めますが、 \f2synchronized\fP と \f2native\fP は組み込めません。これら後者の 2 つの修飾子は、実装の詳細と見なされているため、API 仕様には含まれません。
.LP
API では、並行性セマンティクスについて、キーワード \f2synchronized\fP に依存するのではなく、コメントの主説明としてドキュメント化すべきです。 \f2たとえば、「1 つの Enumeration を\fP 複数のスレッドから並行して使用することはできない」などと記述します。ドキュメントには、これらのセマンティクスを実現する方法を記述するべきではありません。たとえば、 \f2Hashtable\fP はスレッドに対して安全である必要がありますが、「エクスポートされるすべてのメソッドを同期化すればそれを実現できる」のようには指定する根拠はありません。バケットレベルで内部的に同期化する権利を残しておく必要があります。そうすれば、より高度な並行性が提供されます。
.SH "ドキュメンテーションコメント"
.LP
オリジナルの「ドキュメンテーションコメントの仕様」は、「関連項目」を参照してください。
.SS
ソースコードへのコメントの挿入
.LP
ソースコードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーションコメント ("doc comments") を記述することができます。各パッケージにドキュメンテーションコメントを作成できます。構文は若干異なりますが、概要にもドキュメンテーションコメントを作成できます。ドキュメンテーションコメントは、非公式に「Javadoc コメント」と呼ばれています (この用語は商標関連の使用法に違反)。ドキュメンテーションコメントは、コメントを始まりを示す文字列 \f2/**\fP と、コメントを終わりを示す文字列 \f2*/\fP の間にある文字から構成されます。行の先頭のアスタリスクは、各行に記述できます。詳細は、以下で説明します。コメントのテキストは、複数行にわたって記述できます。
.nf
\f3
.fl
/**
.fl
* This is the typical format of a simple documentation comment
.fl
* that spans two lines.
.fl
*/
.fl
\fP
.fi
.LP
次のようにして 1 行に記述すると、スペースを節約できます。
.nf
\f3
.fl
/** This comment takes up only one line.*/
.fl
\fP
.fi
.LP
\f3コメントの配置\fP \- ドキュメンテーションコメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置かれているときにだけ認識されます。クラスの例、メソッドの例、およびフィールドの例を参照してください。メソッドの本体に置かれているドキュメンテーションコメントは無視されます。javadoc ツールでは、1 つの宣言文につき 1 つのドキュメンテーションコメントだけが認識されます。
.LP
よくある間違いは、クラスコメントとクラス宣言の間に \f2import\fP 文を置いてしまうことです。このような記述はしないでください。このようなクラスコメントは無視されます。
.nf
\f3
.fl
/**
.fl
* This is the class comment for the class Whatever.
.fl
*/
.fl
.fl
import com.sun; // MISTAKE \- Important not to put import statement here
.fl
.fl
public class Whatever {
.fl
}
.fl
\fP
.fi
.LP
\f3ドキュメンテーションコメントは主説明のあとにタグセクションが続く \- コメントの開始区切り文字である\fP \f2/**\fP のあとからタグセクションまでが主説明になります。タグセクションは、行の先頭にある最初の \f2@\fP で定義される最初のブロックタグから始まります (先頭のアスタリスク、空白、先頭の区切り文字 \f2/**\fP は除く)。主説明を記述せず、タグセクションだけのコメントを記述することもできます。主説明は、タグセクション以降に続けることはできません。タグの引数は、複数行にわたって記述できます。タグの数に制限はありません。何回も記述できるタグと、1 回しか記述できないタグがあります。たとえば、次の \f2@see\fP は、タグセクションを開始しています。
.nf
\f3
.fl
/**
.fl
* This sentence would hold the main description for this doc comment.
.fl
* @see java.lang.Object
.fl
*/
.fl
\fP
.fi
.LP
\f3ブロックタグとインラインタグ\fP \- \f2「タグ」\fPは、Javadoc が処理できる、ドキュメンテーションコメント内の特別なキーワードです。タグには 2 種類あります。1 つは @tag のように表記されるブロックタグ \f2(「標準タグ」とも呼ばれる)、\fP もう 1 つは {@tag} のように中括弧で囲まれるインラインタグ \f2です\fP。ブロックタグが正しく解釈されるためには、行の先頭のアスタリスク、空白、区切り文字 (\f2/**\fP) を除いて、行の先頭に置かなければなりません。これは、 \f2@\fP 文字をテキスト内の別の場所で使用した場合にはタグの開始として解釈されないことを意味しています。行の先頭で \f2@\fP 文字を使用してもそれが解釈されないようにするには、HTML エンティティー \f2@\fP を使用します。それぞれのブロックタグには、対応付けられたテキストがあります。このテキストは、タグのあとから、次のタグの前、またはドキュメンテーションコメントの最後までの間に記述されたテキスト (タグやコメント区切り文字を除く) です。この関連テキストは複数行にわたって記述できます。インラインタグは、テキストを記述できる場所であればどこにでも置くことができ、正しく解釈されます。次の例にはブロックタグ \f2@deprecated\fP とインラインタグ \f2{@link}\fP が含まれています。
.nf
\f3
.fl
/**
.fl
* @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
.fl
*/
.fl
\fP
.fi
.LP
\f3コメントは HTML で記述する\fP \- テキストは HTML 形式で記述しなければなりません。これは、HTML のエンティティーを使う必要があること、および HTML タグを使用できることを意味します。記述する HTML のバージョンとしては、使用するブラウザがサポートする任意のバージョンを使用できます。標準ドックレットは、カスケーディングスタイルシート (CSS) とフレームを含め、すべての部分 (ドキュメンテーションコメント以外の部分) で HTML 3.2 に準拠したコードを生成するように作成されています。ただし、フレームセット対応のため、生成される各ファイルには「HTML 4.0」と記述されます。
.LP
たとえば、より小さい (\f2<\fP) 記号およびより大きい (\f2>\fP) 記号のエンティティーは、 \f2<\fP および \f2>\fP と記述すべきです。同様に、アンパサンド (\f2&\fP) は \f2&\fP と記述すべきです。次の例ではボールドの HTML タグ \f2<b>\fP が示されています。
.LP
次に、ドキュメンテーションコメントを示します。
.nf
\f3
.fl
/**
.fl
* This is a <b>doc</b> comment.
.fl
* @see java.lang.Object
.fl
*/
.fl
\fP
.fi
.LP
\f3行頭のアスタリスク\fP \- javadoc によるドキュメンテーションコメントの解析時に、各行の先頭にあるアスタリスク (\f2*\fP) 文字は破棄されます。最初のアスタリスク (\f2*\fP) 文字より前にある空白やタブも破棄されます。バージョン 1.4 からは、行の先頭のアスタリスクを省略しても、先頭の空白文字は削除されなくなりました。このため、コード例を直接ドキュメンテーションコメントの \f2<PRE>\fP タグ内にペーストしても、インデントが保持されます。通常、ブラウザは、空白文字をタブよりも一律に解釈します。インデントの起点は左マージンになります (区切り文字 \f2/**\fP または \f2<PRE>\fP タグではなく)。
.LP
\f3最初の文\fP \- 各ドキュメンテーションコメントの最初の文は、宣言されているエンティティーに関する簡潔かつ完全な要約文である必要があります。この「最初の文」は、直後にスペース、タブ、または改行が続く最初のピリオド (ロケールが英語に設定されている場合)、または最初のタグがある位置で終わります。最初の文は、Javadoc ツールによって HTML ページの最初にあるメンバーの概要の部分にコピーされます。
.LP
\f3複数フィールドの宣言\fP \- Java では、1 つの文で複数のフィールドを宣言できます。ただし、この文には、1 つのドキュメンテーションコメントしか記述できません。そのコメントが、すべてのフィールドに対してコピーされます。したがって、フィールドごとにドキュメンテーションコメントを記述する必要がある場合は、各フィールドを別々の文で宣言しなければなりません。たとえば、次のドキュメンテーションコメントは、1 つの宣言として記述すると不適切です。この場合は、宣言を 2 つに分けることをお勧めします。
.nf
\f3
.fl
/**
.fl
* The horizontal and vertical distances of point (x,y)
.fl
*/
.fl
public int x, y; // Avoid this
.fl
\fP
.fi
.LP
上記のコードからは、次のようなドキュメントが生成されます。
.nf
\f3
.fl
public int \fP\f3x\fP
.fl
.fi
.RS 3
The horizontal and vertical distances of point (x,y)
.RE
.nf
\f3
.fl
public int \fP\f3y\fP
.fl
.fi
.RS 3
The horizontal and vertical distances of point (x,y)
.RE
.LP
\f3見出しタグはなるべく使用しない\fP \- メンバーに対してドキュメンテーションコメントを記述するときには、<H1> や <H2> などの HTML 見出しタグは、なるべく使わないでください。 Javadoc ツールは、完全に構造化されたドキュメントを作成するので、このような構造化タグが使われていると、生成ドキュメントの形式が悪影響を受けることがあります。ただし、クラスやパッケージのコメントでは、これらの見出しタグを使って独自の構造を組み立ててかまいません。
.SS
メソッドコメントの自動コピー
.LP
Javadoc ツールには、次の 2 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラスは、ドキュメンテーションコメントを継承しません。
.RS 3
.TP 2
o
\f3自動的にコメントを継承して見つからないテキストを埋める\fP \- 主説明、 \f2@return\fP タグ、 \f2@param\fP タグ、または \f2@throws\fP タグがメソッドコメントに見つからない場合、Javadoc ツールは、オーバーライドまたは実装している場合はその対象となるメソッドから、対応する主説明またはタグコメントを、次のアルゴリズムに従ってコピーします。
.LP
厳密には、特定のパラメータの \f2@param\fP タグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。特定の例外の \f2@throws\fP タグが見つからない場合、その例外が宣言されている場合にかぎり、 \f2@throws\fP タグがコピーされます。
.LP
この動作はバージョン 1.3 以前の動作とは対照的です。これまでのバージョンでは、主説明またはタグが存在すれば、コメントは一切継承されませんでした。
.TP 2
o
\f3{@inheritDoc} タグを含むコメントを明示的に継承する\fP \- インラインタグ \f2{@inheritDoc}\fP を、メソッドの主説明内または \f2@return\fP、 \f2@param\fP 、 \f2@throws\fP のいずれかのタグコメント内に挿入します。対応する継承された主説明またはタグコメントがその位置にコピーされます。
.RE
.LP
ドキュメンテーションコメントを実際にコピーに利用するには、継承したメソッドのソースファイルが \-sourcepath で指定したパスだけに置かれていることが必要になります。コマンド行で、クラスもパッケージも渡す必要はありません。この点は、クラスがドキュメント化されるクラスでなければならなかった 1.3.x 以前のリリースと異なります。
.LP
\f3クラスおよびインタフェースからの継承\fP \- クラスおよびインタフェースから継承する次の 3 つの場合に、コメントの継承が行われます。
.RS 3
.TP 2
o
クラスのメソッドがスーパークラスのメソッドをオーバーライドしている
.TP 2
o
インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドしている
.TP 2
o
クラスのメソッドがインタフェースのメソッドを実装している
.RE
.LP
最初の 2 つのケース (メソッドがオーバーライドしている場合) では、Javadoc ツールは、そのコメントが継承されているかどうかにかかわらず、オーバーライドしているメソッドのドキュメント内に「オーバーライド」という小見出しを生成し、オーバーライドされているメソッドへのリンクを書き込みます。
.LP
3 つ目のケース (特定のクラスのメソッドがインタフェースのメソッドを実装している場合) では、javadoc ツールは、オーバーライドしているメソッドのドキュメント内に「定義」という小見出しを生成し、実装されているメソッドへのリンクを書き込みます。これは、コメントが継承されているかどうかにかかわりません。
.LP
\f3メソッドの説明が継承されるアルゴリズム\fP \- あるメソッドにドキュメンテーションコメントが記述されていない場合、または {@inheritDoc} タグがある場合、Javadoc ツールは、次のようなアルゴリズムを使用して適切なコメントを検索します。 このアルゴリズムは、もっとも適切なドキュメンテーションコメントを検索できるように設計されており、スーパークラスよりもインタフェースが優先されるようになっています。
.RS 3
.TP 3
1.
直接に実装されている (または、拡張されている) インタフェースを、メソッドの宣言で implements (または extends) キーワードのあとに登場する順序で、1 つずつ調べる。このメソッドについて最初に見つかったドキュメンテーションコメントを採用する
.TP 3
2.
手順 1 でドキュメンテーションコメントが見つからなかった場合は、直接実装されている (または、拡張されている) インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用する (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ)
.TP 3
3.
手順 2 でドキュメンテーションコメントが見つからなかった場合で、このクラスが Object 以外のクラスである (インタフェースではない) 場合は、次のように処理する
.RS 3
.TP 3
a.
スーパークラスにこのメソッドについてのドキュメンテーションコメントが記述されていれば、そのコメントを採用する
.TP 3
b.
手順 3a でドキュメンテーションコメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を適用する
.RE
.RE
.SH "javadoc タグ"
.LP
Javadoc ツールは、Java のドキュメンテーションコメント内に埋め込まれた特別なタグを解析します。これらのドキュメンテーションタグを使うと、書式の整った完全な API ドキュメントをソースコードから自動的に生成できます。タグは「アットマーク」記号 (\f2@\fP) で始まり、大文字と小文字の区別があります。タグは、大文字と小文字を使用して、表示されているとおりに入力する必要があります。タグは、行の先頭 (先行する空白と省略可能なアスタリスクは除く) に置かなければなりません。慣例として、同じ名前のタグは 1 か所にまとめて記述するようにします。たとえば、 \f2@see\fP タグはすべて同じ場所に配置します。
.LP
タグには 2 つのタイプがあります。
.RS 3
.TP 2
o
\f3ブロックタグ\fP \- 主説明に続くタグセクション内にのみ記述可能。ブロックタグは、 \f2@tag\fP の形式をとります。
.TP 2
o
\f3インラインタグ\fP \- 主説明内、またはブロックタグのコメント内に記述可能。インラインタグは、 \f2{@tag}\fP.のように中括弧で囲みます。
.RE
.LP
今後のリリースで導入されるタグについては、
.na
\f2「Proposed Javadoc Tags」\fP @
.fi
http://java.sun.com/j2se/javadoc/proposed\-tags.htmlを参照してください。
.LP
現時点で有効なタグは、次のとおりです。
.LP
.TS
.if \n+(b.=1 .nr d. \n(.c-\n(c.-1
.de 35
.ps \n(.s
.vs \n(.vu
.in \n(.iu
.if \n(.u .fi
.if \n(.j .ad
.if \n(.j=0 .na
..
.nf
.nr #~ 0
.if n .nr #~ 0.6n
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.fc
.nr 33 \n(.s
.rm 80 81
.nr 34 \n(.lu
.eo
.am 81
.br
.di a+
.35
.ft \n(.f
.ll \n(34u*1u/3u
.if \n(.l<\n(81 .ll \n(81u
.in 0
\f3導入された JDK/SDK のバージョン\fP
.br
.di
.nr a| \n(dn
.nr a- \n(dl
..
.ec \
.35
.nf
.ll \n(34u
.nr 80 0
.nr 38 \w\f3タグ\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@author\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2{@code}\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2{@docRoot}\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@deprecated\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@exception\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2{@inheritDoc}\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2{@link}\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2{@linkplain}\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2{@literal}\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@param\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@return\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@see\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@serial\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@serialData\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@serialField\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@since\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@throws\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2{@value}\fP
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \w\f2@version\fP
.if \n(80<\n(38 .nr 80 \n(38
.80
.rm 80
.nr 81 0
.nr 38 \w1.0
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.5
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.3
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.0
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.0
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.4
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.2
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.4
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.5
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.0
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.0
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.0
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.2
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.2
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.2
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.1
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.2
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.4
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \w1.0
.if \n(81<\n(38 .nr 81 \n(38
.81
.rm 81
.nr 38 \n(a-
.if \n(81<\n(38 .nr 81 \n(38
.35
.nf
.ll \n(34u
.nr 38 1n
.nr 79 0
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr 41 \n(80+(3*\n(38)
.nr 81 +\n(41
.nr TW \n(81
.if t .if \n(TW>\n(.li .tm Table at line 867 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
.eo
.de T#
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.mk ##
.nr ## -1v
.ls 1
.ls
..
.ec
.ne \n(a|u+\n(.Vu
.if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v)
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f3タグ\fP\h'|\n(41u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 (\n(41u+\n(81u-\n(a-u)/2u
.in +\n(37u
.a+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@author\fP\h'|\n(41u'1.0
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2{@code}\fP\h'|\n(41u'1.5
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2{@docRoot}\fP\h'|\n(41u'1.3
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@deprecated\fP\h'|\n(41u'1.0
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@exception\fP\h'|\n(41u'1.0
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2{@inheritDoc}\fP\h'|\n(41u'1.4
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2{@link}\fP\h'|\n(41u'1.2
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2{@linkplain}\fP\h'|\n(41u'1.4
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2{@literal}\fP\h'|\n(41u'1.5
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@param\fP\h'|\n(41u'1.0
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@return\fP\h'|\n(41u'1.0
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@see\fP\h'|\n(41u'1.0
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@serial\fP\h'|\n(41u'1.2
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@serialData\fP\h'|\n(41u'1.2
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@serialField\fP\h'|\n(41u'1.2
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@since\fP\h'|\n(41u'1.1
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@throws\fP\h'|\n(41u'1.2
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2{@value}\fP\h'|\n(41u'1.4
.ta \n(80u \n(81u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f2@version\fP\h'|\n(41u'1.0
.fc
.nr T. 1
.T# 1
.35
.rm a+
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-44
.LP
カスタムタグについては、\-tag オプションを参照してください。
.RS 3
.TP 3
@author\ name\-text
\-author オプションが使用されている場合、指定された \f2name\-text\fP を含む [作成者] エントリを生成ドキュメントに追加します。1 つのドキュメンテーションコメントに複数の \f2@author\fP タグを含めることができます。1 つの \f2@author\fP タグに 1 つの名前を指定することも、複数の名前を指定することもできます。前者の場合は、Javadoc ツールによって名前と名前の間にコンマ (\f2,\fP) と空白が挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。
.RE
.LP
詳細については、「タグを使用できる場所」および
.na
\f2@author タグのドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@authorを参照してください。
.LP
.RS 3
.TP 3
@deprecated\ deprecated\-text 注: @Deprecated 注釈を使って特定のプログラム要素を非推奨にできます。
.RE
.LP
この API は動作し続けますが、この API を使用するべきではないことを示すコメントを追加します。Javadoc ツールは、 \f2deprecated\-text\fP を主説明の前に移動してイタリックにし、その前にボールドの警告「推奨されません。」を追加します。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
.LP
\f2deprecated\-text\fP の最初の文では、少なくとも、その API が推奨されなくなった時期と、代替使用するべき API を読者に提示する必要があります。Javadoc ツールは、この最初の文だけを、概要セクションと索引にコピーします。そのあとの文では、その API が推奨されない理由を説明することもできます。代わりのAPI を指し示す \f2{@link}\fP タグ ( Javadoc 1.2 以降の場合) を含めるべきです。
.LP
詳細については、
.na
\f2@deprecated タグのドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@deprecatedを参照してください。
.RS 3
.TP 2
o
Javadoc 1.2 以降では \f2{@link}\fP タグを使用します。これにより、必要な場所にインラインでリンクを作成できます。たとえば、
.nf
\f3
.fl
/**
.fl
* @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
.fl
*/
.fl
.fl
\fP
.fi
.TP 2
o
Javadoc 1.1 の場合の標準形式は、 \f2@see\fP タグ (インラインは不可) を \f2@deprecated\fP タグごとに作成することです。
.RE
.LP
推奨されないタグについての詳細は、
.na
\f2@deprecated タグ\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/guides/javadoc/deprecation/index.htmlのドキュメントを参照してください。
.LP
.RS 3
.TP 3
{@code\ text}
\f2<code>{@literal}</code>\fP と同等です。
.LP
テキストを \f2HTML マークアップ\fP または \f2入れ子になった javadoc タグ\fP として解釈せずに、text をコードフォントで表示します。このため、ドキュメンテーションコメント内で通常の山括弧 (\f2<\fP および \f2>\fP) を HTML エンティティー (\f2<\fP および \f2>\fP) の代わりに使用できます。たとえば、パラメータの型 (\f2<Object>\fP)、不等号 (\f23 < 4\fP)、矢印 (\f2<\-\fP) などです。たとえば、次のドキュメンテーションコメント
.nf
\f3
.fl
\fP\f4{@code A<B>C}\fP\f3
.fl
.fl
\fP
.fi
.LP
は、生成された HTML ページで、次のようにそのまま表示されます。
.nf
\f3
.fl
\fP\f4A<B>C\fP\f3
.fl
.fl
\fP
.fi
.LP
ここで注目すべき点は、 \f2<B>\fP が太字として解釈されず、そのフォントはコードフォントになる、という点です。
.LP
コードフォントなしで同じ機能を実現するには、\f2{@literal}\fP を使用します。
.LP
.TP 3
{@docRoot}
生成されるページから見た、生成ドキュメントの (生成先の) ルートディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。通常は、各ページの下部から著作権のページにリンクします。
.LP
この \f2{@docRoot}\fP タグは、コマンド行でもドキュメンテーションコメント内でも使用できます。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
.RS 3
.TP 3
1.
コマンド行では、ヘッダー、フッター、またはボトムノートは次のように定義します。
.nf
\f3
.fl
javadoc \-bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
.fl
.fl
\fP
.fi
.LP
注 \- \f2{@docRoot}\fP を Makefile 内でこのように利用する場合、一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする必要があります。たとえば、Inprise MAKE バージョン 5.2 を Windows 上で実行する場合は、 \f2{{@docRoot}} のように、中括弧を二重にする必要があります\fP。さらに、 \f2\-bottom\fP などのオプションに対する引数を、単一引用符ではなく二重引用符で囲む必要もあります ( \f2href\fP の引数を囲む引用符は省略)。
.TP 3
2.
ドキュメンテーションコメントの中では、次のように使用します。
.nf
\f3
.fl
/**
.fl
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
.fl
*/
.fl
.fl
\fP
.fi
.RE
.LP
このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。次に例を示します。
.nf
\f3
.fl
<a href="{@docRoot}/copyright.html">
.fl
.fl
\fP
.fi
.LP
次のように解決されます。
.nf
\f3
.fl
<a href="../../copyright.html"> java/lang/Object.java の場合
.fl
.fl
\fP
.fi
.LP
かつ
.nf
\f3
.fl
<a href="../../../copyright.html"> java/lang/ref/Reference.java の場合
.fl
.fl
\fP
.fi
.LP
.TP 3
@exception\ class\-name\ description
\f2@exception\fP タグは \f2@throws\fP と同義です。
.LP
.TP 3
{@inheritDoc}\
もっとも近い継承可能なクラスまたは実装可能なインタフェースから、このタグの現在のドキュメンテーションコメントに、ドキュメントを継承 (コピー) します。この機能により、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使って記述することができます。
.LP
このタグは、ドキュメンテーションコメントの次の位置でのみ有効です。
.RS 3
.TP 2
o
メソッドの主説明ブロック内。この場合、主説明は、上位階層のクラスまたはインタフェースからコピーされる
.TP 2
o
メソッドの @return、@param、@throws タグのテキスト引数内。この場合、タグテキストは、上位階層の対応するタグからコピーされる
.RE
.LP
継承階層でコメントを見つける方法に関する正確な説明について、「メソッドコメントの自動コピー」を参照してください。このタグが見つからない場合、コメントは、この節で説明するルールに応じて、自動的に継承されるかどうかが決まります。
.LP
.TP 3
{@link\ package.class#member\ label}
表示テキスト \f2label\fP とのインラインリンクを挿入します。label は、参照クラスの指定されたパッケージ、クラス、またはメンバーの名前のドキュメンテーションを指し示します。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
.LP
このタグは \f2@see\fP と非常によく似ています。どちらも、\f2package.class\fP\f2#\fP\f2member\fP と \f2label\fP の参照の仕方が同じで、有効な構文もまったく同じです。大きな違いは、 \f2{@link}\fP では、[関連項目] セクションにリンクが配置される代わりに、インラインのリンクが生成されるという点です。また、インラインテキストのほかの部分と区別するために、 \f2{@link}\fP タグの最初と最後に中括弧を記述します。ラベルの中で「}」を使う必要がある場合は、HTML エンティティーの「}」を使います。
.LP
1 文内で使用可能な \f2{@link}\fP タグの数に制限はありません。このタグは、ドキュメンテーションコメントの主説明部分、または @deprecated、@return、@param などの任意のタグのテキスト部分で使うことができます。
.LP
たとえば、次のコメントでは \f2getComponentAt(int, int)\fP メソッドを参照しています。
.nf
\f3
.fl
{@link #getComponentAt(int, int) getComponentAt} メソッドを使用します。
.fl
.fl
\fP
.fi
.LP
標準ドックレットでは、上記のコメントから次の HTML が生成されます (このコメントが同じパッケージの別のクラスを参照している場合)。
.nf
\f3
.fl
<a href="Component.html#getComponentAt(int, int)">getComponentAt</a> メソッドを使用します。
.fl
.fl
\fP
.fi
.LP
この HTML は、Web ページ上では次のように表示されます。
.nf
\f3
.fl
getComponentAt メソッドを使用します。
.fl
.fl
\fP
.fi
.LP
\f2{@link}\fP を拡張してドキュメント化されないクラスへのリンクも可能にするには、\f2\-link\fP オプションを使用します。
.LP
詳細については、
.na
\f2{@link} タグのドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#{@link}を参照してください。
.LP
.TP 3
{@linkplain\ package.class#member\ label}
リンクのラベルがコードフォントではなくプレーンテキストで表示される点以外は \f2{@link}\fP と同じです。ラベルがプレーンテキストで記述されていると便利です。次の例を参照してください。例:
.nf
\f3
.fl
{@linkplain add() the overridden method} を参照してください。
.fl
.fl
\fP
.fi
.LP
これは以下のように表示されます。
.LP
the overridden method を参照してください。
.LP
.TP 3
{@literal\ text}
テキストを HTML マークアップまたは入れ子になった javadoc タグとして解釈せずに、 \f2text\fP を表示します。このため、ドキュメンテーションコメント内で通常の山括弧 (\f2<\fP および \f2>\fP) を HTML エンティティー (\f2<\fP および \f2>\fP) の代わりに使用できます。たとえば、パラメータの型 (\f2<Object>\fP)、不等号 (\f23 < 4\fP)、矢印 (\f2<\-\fP) などです。たとえば、次のドキュメンテーションコメント
.nf
\f3
.fl
\fP\f4{@literal A<B>C}\fP\f3
.fl
.fl
\fP
.fi
.LP
は、生成された HTML ページはブラウザで次のようにそのまま表示されます。
.LP
\f2\ \ \ \ \ \fPA<B>C
.LP
ここで注目すべき点は、 \f2<B>\fP が太字として解釈されず、そのフォントはコードフォントになる、という点です。
.LP
コードフォントで同じ機能を実現するには、\f2{@code}\fP を使用します。
.LP
.TP 3
@param\ parameter\-name description
指定された \f2parameter\-name\fP のあとに指定された \f2description\fP が続くパラメータを、[パラメータ] セクションに追加します。ドキュメンテーションコメントを記述するときには、 \f2description\fP を複数行にわたって記述することもできます。このタグは、メソッド、コンストラクタ、またはクラスの doc コメント内でのみ有効です。
.LP
\f2parameter\-name\fP は、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタのタイプパラメータの名前になります。山括弧でパラメータ名を囲むと、型パラメータを使用することを 指定します。
.LP
クラスの型パラメータの例:
.nf
\f3
.fl
/**
.fl
* @param <E> Type of element stored in a list
.fl
*/
.fl
public interface List<E> extends Collection<E> {
.fl
}
.fl
.fl
\fP
.fi
.LP
メソッドの型パラメータの例:
.nf
\f3
.fl
/**
.fl
* @param string the string to be converted
.fl
* @param type the type to convert the string to
.fl
* @param <T> the type of the element
.fl
* @param <V> the value of the element
.fl
*/
.fl
<T, V extends T> V convert(String string, Class<T> type) {
.fl
}
.fl
.fl
\fP
.fi
.LP
詳細については、
.na
\f2@param タグのドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@paramを参照してください。
.LP
.TP 3
@return\ description
[戻り値] セクションを追加して、 \f2description\fP のテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーションコメントでのみ有効です。
.LP
詳細については、
.na
\f2@return タグのドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@returnを参照してください。
.LP
.TP 3
@see\ reference
「関連項目」見出しを追加し、 \f2reference を指すリンクか、またはテキストエントリを書き込みます\fP。ドキュメンテーションコメントには任意の数の \f2@see\fP タグを含めることができますが、それらはすべて同じ見出しの下にグループ化されます。 \f2@see\fP タグには、次の 3 種類の形式があります。もっともよく使われるのは、3 番目の形式です。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。パッケージ、クラス、またはメンバーに対するインラインリンクを文中に挿入する方法は、\f2{@link}\fP を参照してください。
.RS 3
.TP 3
@see "string"
\f2string のテキストエントリを追加します\fP。リンクは生成されません。 \f2string\fP は、書籍または URL ではアクセスできない情報の参照先です。Javadoc ツールは、最初の文字が二重引用符 (\f2"\fP) かどうかを調べて、この形式をほかの 2 つの形式と区別します。たとえば、
.nf
\f3
.fl
@see "The Java Programming Language"
.fl
.fl
\fP
.fi
.LP
これは次のようなテキストを生成します。
.RE
.RE
.RS 3
.RS 3
.RS 3
.RS 3
.TP 3
関連項目:
The Java Programming Language
.RE
.RE
.TP 3
@see <a href="URL#value">label</a>
\f2URL\fP#\f2value\fP で定義されたとおりにリンクを追加します。 \f2URL\fP#\f2value\fP は相対 URL または絶対 URL です。Javadoc ツールは、最初の文字が「より小さい」記号 (\f2<\fP) かどうかを調べて、この形式をほかの 2 つの形式と区別します。たとえば、
.nf
\f3
.fl
@see <a href="spec.html#section">Java Spec</a>
.fl
\fP
.fi
これは次のようなリンクを生成します。
.RS 3
.TP 3
関連項目:
Java Spec
.RE
.TP 3
@see\ package.class#member\ label
可視のテキスト \f2label\fP を持つリンクを追加します。このリンクは、参照先となる、指定された Java 言語の名前のドキュメンテーションを指します。 \f2label\fP は省略可能です。label を省略すると、リンク先のメンバーの名前が適切に短縮されて表示されます。 「名前が表示される方法」を参照してください。\-noqualifier を使用すると、表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストを指定する場合に使います。
.LP
バージョン 1.2 だけは、ラベルではなく、名前が <code> HTML タグ内に自動的に表示されます。 1.2.2 からは、ラベルを使用するか、しないかにかかわらず、<code> は常に表示テキストを囲むかたちで、含まれます。
.LP
.RS 3
.TP 2
o
\f4package.class\fP\f4#\fP\f4member\fP には、参照されている任意の有効なプログラム要素の名前を指定します。つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。ただし、メンバー名ーの前のドットは、シャープ記号 (\f2#\fP) で置き換えます。 \f2class\fP は、任意のトップレベルまたは入れ子にされたクラスまたはインタフェースを表します。 \f2member\fP は、任意のコンストラクタ、メソッドまたはフィールド (入れ子にされたクラスまたはインタフェースではない) を表します。指定した名前が、ドキュメント化されているクラスに含まれている場合、Javadoc ツールは、その名前へのリンクを自動的に作成します。外部参照クラスへのリンクを作成するには、\f2\-link\fP オプションを使います。参照先のクラスに属していない名前のドキュメンテーションを参照するには、残り 2 つの \f2@see\fP 形式のうちのどちらかを使用します。この引数については、このあとの「名前の指定」で詳しく説明します。
.TP 2
o
\f4label\fP は、省略可能なテキストで、リンクのラベルとして表示されます。 \f2label\fP には空白を含めることができます。 \f2label\fP を省略すると、\f2package.class.member\fP が、現在のクラスおよびパッケージに応じて適切に短縮されて表示されます。「名前が表示される方法」を参照してください。
.TP 2
o
空白が、 \f2package.class\fP\f2#\fP\f2member\fP と \f2label\fP の間の区切り文字になります。括弧の内側の空白文字はラベルの先頭とは解釈されないため、メソッドのパラメータ間に空白文字を入れてもかまいません。
.RE
.LP
\f3例\fP \- この例では、 \f2@see\fP タグ ( \f2Character\fP クラス内) が String クラスの \f2equals\fP メソッド \f2を参照\fP しています。このタグには名前「\f2String#equals(Object)\fP」とラベル「\f2equals\fP」の両方の引数が含まれています。
.nf
\f3
.fl
/**
.fl
* @see String#equals(Object) equals
.fl
*/
.fl
\fP
.fi
標準ドックレットは、次のような HTML を生成します。
.nf
\f3
.fl
<dl>
.fl
<dt><b>See Also:</b>
.fl
<dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
.fl
</dl>
.fl
\fP
.fi
これは、ブラウザでは次のように表示され、ラベルがリンクテキストになります。
.RS 3
.TP 3
関連項目:
equals
.RE
.LP
\f3名前の指定\fP \- この \f2package.class\fP\f2#\fP\f2member\fP という名前は、 \f2java.lang.String#toUpperCase()\fP のような完全修飾名にすることも、 \f2String#toUpperCase()\fP や \f2#toUpperCase()\fP のような非完全修飾名にすることもできます。名前が完全指定されていない場合、Javadoc ツールは、Java コンパイラの通常の検索順序でその名前を検索します。詳細は、このあとの「@see の検索順序」を参照してください。名前には、メソッドの複数の引数の間など、括弧の内側であれば空白を含めることができます。
.LP
「部分的に指定」した短い名前を指定することの利点は、入力する文字数が減ることや、ソースコードが読みやすくなることです。次の表に、さまざまな形式の名前を示します。ここで、 \f2Class\fP にはクラスまたはインタフェースを、 \f2Type\fP にはクラス、インタフェース、配列、または基本データ型を、 \f2method\fP にはメソッドまたはコンストラクタを、それぞれ指定できます。
.LP
.LP
.TS
.if \n+(b.=1 .nr d. \n(.c-\n(c.-1
.de 35
.ps \n(.s
.vs \n(.vu
.in \n(.iu
.if \n(.u .fi
.if \n(.j .ad
.if \n(.j=0 .na
..
.nf
.nr #~ 0
.if n .nr #~ 0.6n
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.fc
.nr 33 \n(.s
.rm 80
.nr 34 \n(.lu
.eo
.am 80
.br
.di a+
.35
.ft \n(.f
.ll \n(34u*1u/2u
.if \n(.l<\n(80 .ll \n(80u
.in 0
\f4@see\fP\f3\ \fP\f4package.class#member\fP\f3 の一般的な形式\fP
.br
.di
.nr a| \n(dn
.nr a- \n(dl
..
.ec \
.eo
.am 80
.br
.di b+
.35
.ft \n(.f
.ll \n(34u*1u/2u
.if \n(.l<\n(80 .ll \n(80u
.in 0
\f3現在のクラスのメンバーを参照する\fP
.br
\f2@see\fP\ \f2#\fP\f2フィールド\fP
.br
\f2@see\fP\ \f2#\fP\f2method(Type,\ Type,...)\fP
.br
\f2@see\fP\ \f2#\fP\f2method(Type\ argname,\ Type\ argname,...)\fP
.br
\f2@see\fP\ \f2#\fP\f2constructor(Type,\ Type,...)\fP
.br
\f2@see\fP\ \f2#\fP\f2constructor(Type\ argname,\ Type\ argname,...)\fP
.br
.di
.nr b| \n(dn
.nr b- \n(dl
..
.ec \
.eo
.am 80
.br
.di c+
.35
.ft \n(.f
.ll \n(34u*1u/2u
.if \n(.l<\n(80 .ll \n(80u
.in 0
\f3現在の、またはインポートされたパッケージの別のクラスを参照する\fP
.br
\f2@see\fP\ \f2クラス\fP\f2#\fP\f2フィールド\fP
.br
\f2@see\fP\ \f2クラス\fP\f2#\fP\f2method(Type,\ Type,...)\fP
.br
\f2@see\fP\ \f2クラス\fP\f2#\fP\f2method(Type\ argname,\ Type\ argname,...)\fP
.br
\f2@see\fP\ \f2クラス\fP\f2#\fP\f2constructor(Type,\ Type,...)\fP
.br
\f2@see\fP\ \f2クラス\fP\f2#\fP\f2constructor(Type\ argname,\ Type\ argname,...)\fP
.br
\f2@see\fP\ \f2Class.NestedClass\fP
.br
\f2@see\fP\ \f2クラス\fP
.br
.di
.nr c| \n(dn
.nr c- \n(dl
..
.ec \
.eo
.am 80
.br
.di d+
.35
.ft \n(.f
.ll \n(34u*1u/2u
.if \n(.l<\n(80 .ll \n(80u
.in 0
\f3別のパッケージの要素を参照する\fP\ (完全修飾)
.br
\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2フィールド\fP
.br
\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2method(Type,\ Type,...)\fP
.br
\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2method(Type\ argname,\ Type\ argname,...)\fP
.br
\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2constructor(Type,\ Type,...)\fP
.br
\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2constructor(Type\ argname,\ Type\ argname,...)\fP
.br
\f2@see\fP\ \f2package.Class.NestedClass\fP
.br
\f2@see\fP\ \f2package.Class\fP
.br
\f2@see\fP\ \f2パッケージ\fP
.br
.di
.nr d| \n(dn
.nr d- \n(dl
..
.ec \
.35
.nf
.ll \n(34u
.nr 80 0
.80
.rm 80
.nr 38 \n(a-
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \n(b-
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \n(c-
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \n(d-
.if \n(80<\n(38 .nr 80 \n(38
.35
.nf
.ll \n(34u
.nr 38 1n
.nr 79 0
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
.if t .if \n(TW>\n(.li .tm Table at line 1358 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
.eo
.de T#
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.mk ##
.nr ## -1v
.ls 1
.ls
..
.ec
.ne \n(a|u+\n(.Vu
.if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v)
.ta \n(80u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(40u
.in +\n(37u
.a+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.ne \n(b|u+\n(.Vu
.if (\n(b|+\n(#^-1v)>\n(#- .nr #- +(\n(b|+\n(#^-\n(#--1v)
.ta \n(80u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(40u
.in +\n(37u
.b+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.ne \n(c|u+\n(.Vu
.if (\n(c|+\n(#^-1v)>\n(#- .nr #- +(\n(c|+\n(#^-\n(#--1v)
.ta \n(80u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(40u
.in +\n(37u
.c+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.ne \n(d|u+\n(.Vu
.if (\n(d|+\n(#^-1v)>\n(#- .nr #- +(\n(d|+\n(#^-\n(#--1v)
.ta \n(80u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(40u
.in +\n(37u
.d+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.fc
.nr T. 1
.T# 1
.35
.rm a+
.rm b+
.rm c+
.rm d+
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-58
.LP
上の表に対する補足事項を次に示します。
.RS 3
.TP 2
o
最初の種類の形式 (パッケージとクラスを省略) の場合、Javadoc ツールは、現在のクラスの階層だけを検索します。つまり、現在のクラスかインタフェース、そのスーパークラスかスーパーインタフェース、または現在のクラスかインタフェースを囲んでいるクラスかインタフェースからメンバーを検索します (このあとの検索手順 1 ~ 3)。現在のパッケージのほかの部分や、ほかのパッケージは検索しません (検索手順 4 ~ 5)。
.TP 2
o
メソッドまたはコンストラクタの指定時に、 \f2getValue\fP のように括弧なしの名前を使用した場合、同じ名前のフィールドが存在していなければ、Javadoc ツールによってその名前へのリンクが正しく作成されますが、括弧や引数の追加をユーザーに促すための警告メッセージが表示されます。このメソッドがオーバーロードされている場合、Javadoc ツールは、検索で最初に見つかったメソッドにリンクします。結果は前もって特定できません。
.TP 2
o
入れ子になったクラスは、すべての形式について、 \f2outer\fP\f2.\fP\f2inner\fP として指定する必要があります。単純に \f2inner\fP とはしないでください。
.TP 2
o
すでに述べたように、\f2クラスとメンバーとの間の区切り文字としては、\fPドット (\f2.\fP) ではなくシャープ文字 (#) を使用します。このように指定すると、Javadoc ツールは、あいまいさを解決できます。ドットは、クラス、入れ子にされたクラス、パッケージ、およびサブパッケージを区切るためにも使用されます。ただし、Javadoc ツールでは一般に許容範囲が広く、あいまいさがなければ、ドットでも正しく解析されます。その場合でも警告は表示されます。
.RE
.LP
\f3@see の検索順序\fP \- Javadoc ツールは、ソースファイル (.java)、パッケージファイル (package.html または package\-info.java) または概要ファイル (overview.html) に含まれる \f2@see\fP タグを処理します。後者の 2 つのファイルでは、完全指定の名前を \f2@see\fP タグに指定しなければなりません。ソースファイルでは、完全指定の名前、または部分指定の名前を指定できます。
.LP
Javadoc ツールは、完全指定でない名前が記述された \f2@see\fP タグを \f2.java ファイル内で見つけると、\fP Java コンパイラと同じ順序で指定された名前を検索します。 ただし、Javadoc ツールは、特定の名前空間のあいまいさを検出しません。 これは、ソースコードにこれらのエラーが存在していないことを前提としているためです。この検索順序は、Java 言語仕様第 2 版の第 6 章「Names」で正式に定義されています。Javadoc ツールは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてから名前を検索します。具体的には、次の順序で検索します。
.RS 3
.TP 3
1.
現在のクラスまたはインタフェース
.TP 3
2.
外側を囲んでいるクラスとインタフェース (もっとも近いものから検索)
.TP 3
3.
スーパークラスとスーパーインタフェース (もっとも近いものから検索)
.TP 3
4.
現在のパッケージ
.TP 3
5.
インポートされているパッケージ、クラス、およびインタフェース (import 文の順序に従って検索)
.RE
.LP
Javadoc ツールは、各クラスについて手順 1 ~ 3 を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にそのクラスを囲んでいるクラス E を検索し、その次に E のスーパークラスを検索し、さらにその次に E を囲んでいるクラスを検索します。 手順 4 と 5 では、1 つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません。その順序は、個々のコンパイラによって異なります。手順 5 では、Javadoc ツールは、java.lang を検索します。このパッケージは、すべてのプログラムに自動的にインポートされるからです。
.LP
Javadoc ツールは、必ずしもサブクラスを検索するとは限りません。また、javadoc の実行中にほかのパッケージのドキュメントが生成される場合でも、ほかのパッケージを検索しません。たとえば、 \f2@see\fP タグが \f2java.awt.event.KeyEvent\fP クラス内に含まれていて、 \f2java.awt\fP パッケージ内のある名前を参照していても、そのクラス内でそのパッケージがインポートされないかぎり、javadoc はそのパッケージ内での検索を行いません。
.LP
\f3名前が表示される方法\fP \- \f2label\fP を省略した場合は、\f2package.class.member\fP が表示されます。一般に、package.class.member は、現在のクラスおよびパッケージに応じて適切に短縮されます。「短縮される」とは、必要最小限の名前だけが表示されるということです。たとえば、 \f2String.toUpperCase()\fP メソッドに、同じクラスのメンバーへの参照とほかのクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースだけです (次の表を参照)。
.LP
パッケージ名を広域的に削除するには、\-noqualifier を使用します。
.br
.LP
.TS
.if \n+(b.=1 .nr d. \n(.c-\n(c.-1
.de 35
.ps \n(.s
.vs \n(.vu
.in \n(.iu
.if \n(.u .fi
.if \n(.j .ad
.if \n(.j=0 .na
..
.nf
.nr #~ 0
.if n .nr #~ 0.6n
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.fc
.nr 33 \n(.s
.rm 80 81 82
.nr 34 \n(.lu
.eo
.am 81
.br
.di a+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(81 .ll \n(81u
.in 0
\f4String.toUpperCase() での例\fP
.br
.di
.nr a| \n(dn
.nr a- \n(dl
..
.ec \
.eo
.am 80
.br
.di b+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(80 .ll \n(80u
.in 0
\f2@see\fP タグが同じクラス、同じパッケージのメンバーを参照している
.br
.di
.nr b| \n(dn
.nr b- \n(dl
..
.ec \
.eo
.am 82
.br
.di c+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(82 .ll \n(82u
.in 0
\f2toLowerCase()\fP (クラス名は省略)
.br
.di
.nr c| \n(dn
.nr c- \n(dl
..
.ec \
.eo
.am 80
.br
.di d+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(80 .ll \n(80u
.in 0
\f2@see\fP タグが異なるクラス、同じパッケージのメンバーを参照している
.br
.di
.nr d| \n(dn
.nr d- \n(dl
..
.ec \
.eo
.am 81
.br
.di e+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(81 .ll \n(81u
.in 0
\f2@see Character#toLowerCase(char)\fP
.br
.di
.nr e| \n(dn
.nr e- \n(dl
..
.ec \
.eo
.am 82
.br
.di f+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(82 .ll \n(82u
.in 0
\f2Character.toLowerCase(char)\fP (パッケージ名は省略し、クラス名を含む)
.br
.di
.nr f| \n(dn
.nr f- \n(dl
..
.ec \
.eo
.am 80
.br
.di g+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(80 .ll \n(80u
.in 0
\f2@see\fP タグが異なるクラス、異なるパッケージのメンバーを参照している
.br
.di
.nr g| \n(dn
.nr g- \n(dl
..
.ec \
.eo
.am 81
.br
.di h+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(81 .ll \n(81u
.in 0
\f2@see java.io.File#exists()\fP
.br
.di
.nr h| \n(dn
.nr h- \n(dl
..
.ec \
.eo
.am 82
.br
.di i+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(82 .ll \n(82u
.in 0
\f2java.io.File.exists()\fP (パッケージ名とクラス名を含む)
.br
.di
.nr i| \n(dn
.nr i- \n(dl
..
.ec \
.35
.nf
.ll \n(34u
.nr 80 0
.nr 38 \w\f3参照の種類\fP
.if \n(80<\n(38 .nr 80 \n(38
.80
.rm 80
.nr 38 \n(b-
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \n(d-
.if \n(80<\n(38 .nr 80 \n(38
.nr 38 \n(g-
.if \n(80<\n(38 .nr 80 \n(38
.nr 81 0
.nr 38 \w\f2@see String#toLowerCase()\fP
.if \n(81<\n(38 .nr 81 \n(38
.81
.rm 81
.nr 38 \n(a-
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \n(e-
.if \n(81<\n(38 .nr 81 \n(38
.nr 38 \n(h-
.if \n(81<\n(38 .nr 81 \n(38
.nr 82 0
.nr 38 \w\f3表示される名前\fP
.if \n(82<\n(38 .nr 82 \n(38
.82
.rm 82
.nr 38 \n(c-
.if \n(82<\n(38 .nr 82 \n(38
.nr 38 \n(f-
.if \n(82<\n(38 .nr 82 \n(38
.nr 38 \n(i-
.if \n(82<\n(38 .nr 82 \n(38
.35
.nf
.ll \n(34u
.nr 38 1n
.nr 79 0
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr 41 \n(80+(3*\n(38)
.nr 81 +\n(41
.nr 42 \n(81+(3*\n(38)
.nr 82 +\n(42
.nr TW \n(82
.if t .if \n(TW>\n(.li .tm Table at line 1434 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
.eo
.de T#
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.mk ##
.nr ## -1v
.ls 1
.ls
..
.ec
.ne \n(a|u+\n(.Vu
.if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v)
.ta \n(80u \n(81u \n(82u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\f3参照の種類\fP\h'|\n(41u'\h'|\n(42u'\f3表示される名前\fP
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(41u
.in +\n(37u
.a+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.ne \n(b|u+\n(.Vu
.ne \n(c|u+\n(.Vu
.if (\n(b|+\n(#^-1v)>\n(#- .nr #- +(\n(b|+\n(#^-\n(#--1v)
.if (\n(c|+\n(#^-1v)>\n(#- .nr #- +(\n(c|+\n(#^-\n(#--1v)
.ta \n(80u \n(81u \n(82u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\h'|\n(41u'\f2@see String#toLowerCase()\fP\h'|\n(42u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(40u
.in +\n(37u
.b+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(##u-1v
.nr 37 \n(42u
.in +\n(37u
.c+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.ne \n(d|u+\n(.Vu
.ne \n(e|u+\n(.Vu
.ne \n(f|u+\n(.Vu
.if (\n(d|+\n(#^-1v)>\n(#- .nr #- +(\n(d|+\n(#^-\n(#--1v)
.if (\n(e|+\n(#^-1v)>\n(#- .nr #- +(\n(e|+\n(#^-\n(#--1v)
.if (\n(f|+\n(#^-1v)>\n(#- .nr #- +(\n(f|+\n(#^-\n(#--1v)
.ta \n(80u \n(81u \n(82u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\h'|\n(41u'\h'|\n(42u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(40u
.in +\n(37u
.d+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(##u-1v
.nr 37 \n(41u
.in +\n(37u
.e+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(##u-1v
.nr 37 \n(42u
.in +\n(37u
.f+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.ne \n(g|u+\n(.Vu
.ne \n(h|u+\n(.Vu
.ne \n(i|u+\n(.Vu
.if (\n(g|+\n(#^-1v)>\n(#- .nr #- +(\n(g|+\n(#^-\n(#--1v)
.if (\n(h|+\n(#^-1v)>\n(#- .nr #- +(\n(h|+\n(#^-\n(#--1v)
.if (\n(i|+\n(#^-1v)>\n(#- .nr #- +(\n(i|+\n(#^-\n(#--1v)
.ta \n(80u \n(81u \n(82u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\h'|\n(41u'\h'|\n(42u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(40u
.in +\n(37u
.g+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(##u-1v
.nr 37 \n(41u
.in +\n(37u
.h+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(##u-1v
.nr 37 \n(42u
.in +\n(37u
.i+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.fc
.nr T. 1
.T# 1
.35
.rm a+
.rm b+
.rm c+
.rm d+
.rm e+
.rm f+
.rm g+
.rm h+
.rm i+
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-28
.LP
\f3@see の例\fP
.br
右側のコメントは、 \f2@see\fP タグが \f2java.applet.Applet\fP のような別のパッケージのクラス内にある場合に、名前がどのように表示されるかを示しています。
.nf
\f3
.fl
関連項目:
.fl
@see java.lang.String // String \fP\f3
.fl
@see java.lang.String The String class // The String class \fP\f3
.fl
@see String // String \fP\f3
.fl
@see String#equals(Object) // String.equals(Object) \fP\f3
.fl
@see String#equals // String.equals(java.lang.Object) \fP\f3
.fl
@see java.lang.Object#wait(long) // java.lang.Object.wait(long) \fP\f3
.fl
@see Character#MAX_RADIX // Character.MAX_RADIX \fP\f3
.fl
@see <a href="spec.html">Java Spec</a> // Java Spec \fP\f3
.fl
@see "The Java Programming Language" // "The Java Programming Language" \fP\f3
.fl
\fP
.fi
\f2@see\fP を拡張してドキュメント化されないクラスへのリンクも可能にするには、\f2\-link\fP オプションを使用します。
.LP
詳細については、
.na
\f2@see タグのドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@seeを参照してください。
.RE
.RE
.LP
.RS 3
.TP 3
@serial\ field\-description | include | exclude
デフォルトの直列化可能フィールドのドキュメンテーションコメントで使用します。
.LP
\f2field\-description\fP (省略可能) では、フィールドの意味を説明し、取り得る値のリストを示す必要があります。必要に応じて、複数の行に渡って説明を記述できます。標準ドックレットは、この情報を、直列化された形式のページに追加します。
.LP
クラスを直列化したあとしばらくしてから直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。
.LP
\f2include\fP および \f2exclude\fP 引数は、直列化された形式のページにクラスまたはパッケージを含めるか除外するかを示します。これらの引数には、次のような効果があります。
.RS 3
.TP 2
o
\f2Serializable\fP を実装している public または protected クラスは、そのクラス (またはそのパッケージ) が \f2@serial exclude\fP としてマークされていないかぎり、含められます。
.TP 2
o
\f2Serializable\fP を実装している private または package\-private クラスは、そのクラス (またはそのパッケージ) が \f2@serial include\fP として マークされていないかぎり、除外されます。
.RE
.LP
例: \f2javax.swing\fP パッケージは \f2@serial exclude\fP ( \f2package.html\fP または \f2package\-info.java\fP内) としてマークされています。public クラス \f2java.security.BasicPermission\fP は \f2@serial exclude\fP としてマークされています。package\-private クラス \f2java.util.PropertyPermissionCollection\fP は \f2@serial include\fP としてマークされています。
.LP
クラスレベルで指定された @serial タグは、パッケージレベルで指定された @serial タグをオーバーライドします。
.LP
これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の第 1.6 節
.na
\f2「クラスの直列化可能なフィールドおよびデータの文書化」\fP @
.fi
http://java.sun.com/javase/6/docs/platform/serialization/spec/serial\-arch.htmlを参照してください。また、
.na
\f2「直列化の FAQ」\fP @
.fi
http://java.sun.com/products/jdk/serialization/faq/#javadoc_warn_missingも参照してください。この FAQ には、「\-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。直列化形式仕様にクラスを含める場合には、
.na
\f2「Sun の仕様」\fP @
.fi
http://java.sun.com/j2se/javadoc/writingapispecs/serialized\-criteria.htmlも参照してください。
.LP
.TP 3
@serialField\ field\-name\ field\-type\ field\-description
Serializable \f2クラスの\fP serialPersistentFields \f2メンバーの\fP ObjectStreamField コンポーネント \f2をドキュメント化\fP します。1 つの \f2@serialField\fP タグを各 \f2ObjectStreamField\fP コンポーネントで使用すべきです。
.LP
.TP 3
@serialData\ data\-description
\f2data\-description\fP は、直列化された形式でのデータの型と順序を説明するテキストです。具体的に言うと、このデータには、 \f2writeObject\fP メソッドによって書き込まれる省略可能なデータ、および \f2Externalizable.writeExternal\fP メソッドによって書き込まれるすべてのデータ (基底クラスも含む) が含まれます。
.LP
\f2@serialData\fP タグは、 \f2writeObject\fP、 \f2readObject\fP、 \f2writeExternal\fP、 \f2readExternal\fP、 \f2writeReplace\fP、および \f2readResolve\fP メソッドのドキュメンテーションコメント内で使用できます。
.LP
.TP 3
@since\ since\-text
生成ドキュメントに [導入されたバージョン] 見出しを追加し、指定された \f2since\-text\fP を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、 \f2since\-text に示されたソフトウェアリリース以降、存在していることを意味します\fP。たとえば、
.nf
\f3
.fl
@since 1.5
.fl
.fl
\fP
.fi
.LP
Java プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。
.LP
.TP 3
@throws\ class\-name\ description
\f2@throws\fP タグと \f2@exception\fP タグは同義です。生成ドキュメントに「例外」小見出しを追加して、 \f2class\-name\fP および \f2description\fP のテキストを書き込みます。 \f2class\-name\fP は、そのメソッドからスローされる可能性のある例外の名前です。このタグは、メソッド、コンストラクタの doc コメント内でのみ有効です。このクラスが完全指定の名前で記述されていない場合、Javadoc ツールは、検索順序に従ってクラスを探します。同じまたは異なる例外の doc コメントで、複数の \f2@throws\fP タグを使用できます。
.LP
すべてのチェック済み例外がドキュメント化されるようにするために、 \f2@throws\fP タグが throws 節内の例外用に存在しない場合は、@throws タグのあるドキュメントであるかのように、Javadoc ツールによって例外が HTML 出力に説明なしで自動的に追加されます。
.LP
オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、 \f2@throws\fP ドキュメンテーションがそのメソッドからサブクラスにコピーされます。インタフェースメソッドから実装メソッドにコピーされる場合も同様です。@throws にドキュメンテーションを継承させるには、{@inheritDoc} を使用できます。
.LP
詳細については、
.na
\f2@throws タグのドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@exceptionを参照してください。
.LP
.TP 3
{@value\ package.class#field}
\f2{@value}\fP が静的フィールドの doc コメントで 引数なしで使用されている場合、その定数の値が表示されます。
.nf
\f3
.fl
/**
.fl
* The value of this constant is {@value}.
.fl
*/
.fl
public static final String SCRIPT_START = "<script>"
.fl
.fl
\fP
.fi
.LP
任意のドキュメンテーションコメント内で引数 \f2package.class#field\fP ありで使用された場合は、その指定された定数の値が表示されます。
.nf
\f3
.fl
/**
.fl
* Evaluates the script starting with {@value #SCRIPT_START}.
.fl
*/
.fl
public String evalScript(String script) {
.fl
}
.fl
.fl
\fP
.fi
.LP
引数 \f2package.class#field\fP は、@see 引数と同一の形式になります。ただし、メンバーが静的フィールドになければならない点が異なります。
.LP
これらの定数での値は、
.na
\f2定数フィールド値\fP @
.fi
http://java.sun.com/javase/6/docs/api/constant\-values.htmlページにも表示されます。
.LP
.TP 3
@version\ version\-text
\-version オプションが使用されると、生成ドキュメントに [バージョン] 小見出しを追加し、指定された \f2version\-text\fP を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のバージョン番号を保持するように意図されています。これに対し、@since は、このコードが導入されたバージョン番号を保持します。 \f2version\-text\fP には、特別な内部構造はありません。バージョンタグを使用できる場所を調べるには、「タグを使用できる場所」を参照してください。
.LP
1 つのドキュメンテーションコメントに複数の \f2@version\fP タグを含めることができます。意味が失われない範囲内で、1 つの \f2@version\fP タグに 1 つのバージョン番号を指定することも、複数のバージョン番号を指定することもできます。前者の場合は、Javadoc ツールによって名前と名前の間にコンマ (\f2,\fP) と空白が名前の間に挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。
.LP
詳細については、
.na
\f2@version タグのドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@versionを参照してください。
.RE
.SS
タグを使用できる場所
.LP
ここでは、タグを使用できる場所について説明します。すべてのドキュメンテーションコメントで使用可能なタグは次のとおりです。 \f2@see\fP、 \f2@since\fP、 \f2@deprecated\fP、 \f2{@link}\fP、 \f2{@linkplain}\fP、および \f2{@docroot}\fP。
.SS
概要のドキュメンテーションタグ
.LP
概要タグは、概要ページのドキュメンテーションコメントで使用できるタグです。このドキュメンテーションコメントは、通常 \f2overview.html\fP という名前のソースファイル内にあります。 ほかのドキュメンテーションコメントの場合と同様に、これらのタグは、主説明のあとで使う必要があります。
.LP
\f3注\fP \- バージョン 1.2 では、概要ドキュメント内の \f2{@link}\fP タグにバグがあります。テキストは正しく表示されますが、リンクが設定されません。現在のところ、 \f2{@docRoot}\fP タグは、概要ドキュメント内では動作しません。
.LP
\f3概要タグ\fP
.RS 3
.TP 2
o
\f2@see\fP
.TP 2
o
\f2@since\fP
.TP 2
o
\f2@author\fP
.TP 2
o
\f2@version\fP
.TP 2
o
\f2{@link}\fP
.TP 2
o
\f2{@linkplain}\fP
.TP 2
o
\f2{@docRoot}\fP
.RE
.SS
パッケージドキュメンテーションタグ
.LP
パッケージタグは、パッケージのドキュメンテーションコメントで使用できるタグです。このドキュメンテーションコメントは \f2package.html\fP または \f2package\-info.java\fP という名前のソースファイル内にあります。ここで使用できる \f2@serial\fP タグは、 \f2include\fP または \f2exclude\fP 引数が指定されたものだけです。
.LP
\f3パッケージタグ\fP
.RS 3
.TP 2
o
\f2@see\fP
.TP 2
o
\f2@since\fP
.TP 2
o
\f2@serial\fP
.TP 2
o
\f2@author\fP
.TP 2
o
\f2@version\fP
.TP 2
o
\f2{@link}\fP
.TP 2
o
\f2{@linkplain}\fP
.TP 2
o
\f2{@docRoot}\fP
.RE
.SS
クラスおよびインタフェースドキュメンテーションタグ
.LP
次に、クラスまたはインタフェースのドキュメンテーションコメントで使用できるタグを示します。ここで使用できる \f2@serial\fP タグは、 \f2include\fP または \f2exclude\fP 引数が指定されたものだけです。
.LP
\f3クラスおよびインタフェースタグ\fP
.RS 3
.TP 2
o
\f2@see\fP
.TP 2
o
\f2@since\fP
.TP 2
o
\f2@deprecated\fP
.TP 2
o
\f2@serial\fP
.TP 2
o
\f2@author\fP
.TP 2
o
\f2@version\fP
.TP 2
o
\f2{@link}\fP
.TP 2
o
\f2{@linkplain}\fP
.TP 2
o
\f2{@docRoot}\fP
.RE
\f3次にクラスコメントの例を示します。\fP
.nf
\f3
.fl
/**
.fl
* A class representing a window on the screen.
.fl
* For example:
.fl
* <pre>
.fl
* Window win = new Window(parent);
.fl
* win.show();
.fl
* </pre>
.fl
*
.fl
* @author Sami Shaio
.fl
* @version 1.13, 06/08/06
.fl
* @see java.awt.BaseWindow
.fl
* @see java.awt.Button
.fl
*/
.fl
class Window extends BaseWindow {
.fl
...
.fl
}
.fl
\fP
.fi
.SS
フィールドドキュメンテーションタグ
.LP
次に、フィールドのドキュメンテーションコメントで使用できるタグを示します。
.LP
\f3フィールドタグ\fP
.RS 3
.TP 2
o
\f2@see\fP
.TP 2
o
\f2@since\fP
.TP 2
o
\f2@deprecated\fP
.TP 2
o
\f2@serial\fP
.TP 2
o
\f2@serialField\fP
.TP 2
o
\f2{@link}\fP
.TP 2
o
\f2{@linkplain}\fP
.TP 2
o
\f2{@docRoot}\fP
.TP 2
o
\f2{@value}\fP
.RE
\f3次にフィールドコメントの例を示します。\fP
.nf
\f3
.fl
/**
.fl
* The X\-coordinate of the component.
.fl
*
.fl
* @see #getLocation()
.fl
*/
.fl
int x = 1263732;
.fl
\fP
.fi
.SS
コンストラクタおよびメソッドドキュメンテーションタグ
.LP
次に、コンストラクタまたはメソッドのドキュメンテーションコメントで使用できるタグを示します。ただし、 \f2@return\fP はコンストラクタでは使用できず、 \f2{@inheritDoc}\fP には特定の制限があります。 \f2@serialData\fP タグは特定の直列化メソッドの doc コメントでのみ使用できます。
.LP
\f3メソッドおよびコンストラクタタグ\fP
.RS 3
.TP 2
o
\f2@see\fP
.TP 2
o
\f2@since\fP
.TP 2
o
\f2@deprecated\fP
.TP 2
o
\f2@param\fP
.TP 2
o
\f2@return\fP
.TP 2
o
\f2@throws\fP と \f2@exception\fP
.TP 2
o
\f2@serialData\fP
.TP 2
o
\f2{@link}\fP
.TP 2
o
\f2{@linkplain}\fP
.TP 2
o
\f2{@inheritDoc}\fP
.TP 2
o
\f2{@docRoot}\fP
.RE
\f3次にメソッドのドキュメンテーションコメントの例を示します。\fP
.nf
\f3
.fl
/**
.fl
* Returns the character at the specified index. An index
.fl
* ranges from <code>0</code> to <code>length() \- 1</code>.
.fl
*
.fl
* @param index the index of the desired character.
.fl
* @return the desired character.
.fl
* @exception StringIndexOutOfRangeException
.fl
* if the index is not in the range <code>0</code>
.fl
* to <code>length()\-1</code>.
.fl
* @see java.lang.Character#charValue()
.fl
*/
.fl
public char charAt(int index) {
.fl
...
.fl
}
.fl
\fP
.fi
.SH "オプション"
.LP
javadoc ツールは、ドックレットを使って出力を決定します。Javadoc ツールは、\-doclet オプションでカスタムドックレットが指定されている場合以外は、デフォルトの標準ドックレットを使います。Javadoc ツールには、任意のドックレットとともに使用できるコマンド行オプションがあります。これらのオプションについては、このあとの「Javadoc オプション」で説明します。標準ドックレットでは、このほかに、いくつかの追加のコマンド行オプションが提供されます。これらのオプションについては、そのあとの「標準ドックレットが提供するオプション」で説明します。どのオプション名も、大文字と小文字が区別されません。ただし、オプションの引数では、大文字と小文字が区別されます。
.LP
オプションは次のとおりです。
.LP
.TS
.if \n+(b.=1 .nr d. \n(.c-\n(c.-1
.de 35
.ps \n(.s
.vs \n(.vu
.in \n(.iu
.if \n(.u .fi
.if \n(.j .ad
.if \n(.j=0 .na
..
.nf
.nr #~ 0
.if n .nr #~ 0.6n
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.fc
.nr 33 \n(.s
.rm 80 81 82
.nr 34 \n(.lu
.eo
.am 80
.br
.di a+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(80 .ll \n(80u
.in 0
\-\f21.1\fP
.br
\-author
.br
\-\f2bootclasspath\fP
.br
\-bottom
.br
\-\f2breakiterator\fP
.br
\-charset
.br
\-\f2classpath\fP
.br
\-d
.br
\-docencoding
.br
\-docfilessubdirs
.br
\-\f2doclet\fP
.br
\-\f2docletpath\fP
.br
\-doctitle
.br
\-\f2encoding\fP
.br
\-\f2exclude\fP
.br
\-excludedocfilessubdir
.br
\-\f2extdirs\fP
.br
\-footer
.br
\-group
.br
.br
.di
.nr a| \n(dn
.nr a- \n(dl
..
.ec \
.eo
.am 81
.br
.di b+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(81 .ll \n(81u
.in 0
\-header
.br
\-\f2help\fP
.br
\-helpfile
.br
\-\f2J\fP
.br
\-keywords
.br
\-link
.br
\-linkoffline
.br
\-linksource
.br
\-\f2locale\fP
.br
\-nocomment
.br
\-nodeprecated
.br
\-nodeprecatedlist
.br
\-nohelp
.br
\-noindex
.br
\-nonavbar
.br
\-noqualifier
.br
\-nosince
.br
\-notimestamp
.br
\-notree
.br
\-\f2overview\fP
.br
\-\f2package\fP
.br
.br
.di
.nr b| \n(dn
.nr b- \n(dl
..
.ec \
.eo
.am 82
.br
.di c+
.35
.ft \n(.f
.ll \n(34u*1u/4u
.if \n(.l<\n(82 .ll \n(82u
.in 0
\-\f2private\fP
.br
\-\f2protected\fP
.br
\-\f2public\fP
.br
\-\f2quiet\fP
.br
\-serialwarn
.br
\-\f2source\fP
.br
\-\f2sourcepath\fP
.br
\-sourcetab
.br
\-splitindex
.br
\-stylesheetfile
.br
\-\f2subpackages\fP
.br
\-tag
.br
\-taglet
.br
\-tagletpath
.br
\-top
.br
\-title
.br
\-use
.br
\-\f2verbose\fP
.br
\-version
.br
\-windowtitle
.br
.br
.di
.nr c| \n(dn
.nr c- \n(dl
..
.ec \
.35
.nf
.ll \n(34u
.nr 80 0
.80
.rm 80
.nr 38 \n(a-
.if \n(80<\n(38 .nr 80 \n(38
.nr 81 0
.81
.rm 81
.nr 38 \n(b-
.if \n(81<\n(38 .nr 81 \n(38
.nr 82 0
.82
.rm 82
.nr 38 \n(c-
.if \n(82<\n(38 .nr 82 \n(38
.35
.nf
.ll \n(34u
.nr 38 1n
.nr 79 0
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr 41 \n(80+(3*\n(38)
.nr 81 +\n(41
.nr 42 \n(81+(3*\n(38)
.nr 82 +\n(42
.nr TW \n(82
.if t .if \n(TW>\n(.li .tm Table at line 2009 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
.eo
.de T#
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.mk ##
.nr ## -1v
.ls 1
.ls
..
.ec
.ne \n(a|u+\n(.Vu
.ne \n(b|u+\n(.Vu
.ne \n(c|u+\n(.Vu
.if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v)
.if (\n(b|+\n(#^-1v)>\n(#- .nr #- +(\n(b|+\n(#^-\n(#--1v)
.if (\n(c|+\n(#^-1v)>\n(#- .nr #- +(\n(c|+\n(#^-\n(#--1v)
.ta \n(80u \n(81u \n(82u
.nr 31 \n(.f
.nr 35 1m
\&\h'|\n(40u'\h'|\n(41u'\h'|\n(42u'
.mk ##
.nr 31 \n(##
.sp |\n(##u-1v
.nr 37 \n(40u
.in +\n(37u
.a+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(##u-1v
.nr 37 \n(41u
.in +\n(37u
.b+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(##u-1v
.nr 37 \n(42u
.in +\n(37u
.c+
.in -\n(37u
.mk 32
.if \n(32>\n(31 .nr 31 \n(32
.sp |\n(31u
.fc
.nr T. 1
.T# 1
.35
.rm a+
.rm b+
.rm c+
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-127
.LP
\f2イタリック\fP で示されたオプションは、Javadoc の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、イタリックでないオプションを提供します。
.SS
Javadoc オプション
.RS 3
.TP 3
\-overview \ path/filename
Javadoc に対して、\f2path/filename\fP で指定された「ソース」ファイルから概要ドキュメント用のテキストを取得し、そのテキストを概要ページ (\f2overview\-summary.html\fP) に配置するように指定します。 \f2path/filename\fP は、カレントディレクトリからの相対パスです。
.LP
\f2filename\fPで任意の名前を使用し、\f2path\fP で任意の配置先を選択することも可能ですが、通常は \f2overview.html\fP という名前を付け、ソースツリー内の最上位パッケージディレクトリを含むディレクトリ内に配置します。この場所に配置すると、パッケージをドキュメント化するときに \f2path\fP を指定する必要がなくなります。なぜなら、 \f2\-sourcepath\fP によってこのファイルが指し示されるからです。たとえば、 \f2java.lang\fP パッケージのソースツリーが \f2/src/classes/java/lang/\fP の場合、概要ファイルを \f2/src/classes/overview.html\fP に配置できます。「使用例」を参照してください。
.LP
\f2path/filename\fP で指定するファイルについては、「概要コメントファイル」を参照してください。
.LP
概要ページが作成されるのは、Javadoc に複数のパッケージ名を渡した場合だけです。詳細は、「HTML フレーム」を参照してください。
.LP
概要ページのタイトルは、\f2\-doctitle\fP によって設定されます。
.LP
.TP 3
\-public
public クラスおよびメンバーだけを表示します。
.LP
.TP 3
\-protected
protected および public のクラスとメンバーだけを表示します。これがデフォルトです。
.LP
.TP 3
\-package
package、protected、および public のクラスとメンバーだけを表示します。
.LP
.TP 3
\-private
すべてのクラスとメンバーを表示します。
.LP
.TP 3
\-help
オンラインヘルプを表示します。Javadoc とドックレットのコマンド行オプションが一覧表示されます。
.LP
.TP 3
\-doclet\ class
ドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。完全指定の名前を指定してください。このドックレットにより、出力の内容と形式が定義されます。\f4\-doclet\fP オプションが使われていない場合、Javadoc は、標準ドックレットを使ってデフォルトの HTML 形式を生成します。このクラスには \f2start(Root)\fP が含まれている必要があります。この起動クラスへのパスは \f2\-docletpath\fP オプションによって定義されます。
.LP
たとえば、MIF ドックレットを呼び出すには、次のように指定します。
.nf
\f3
.fl
\-doclet com.sun.tools.doclets.mif.MIFDoclet
.fl
\fP
.fi
.LP
特定のドックレットを実行した完全な例については、
.na
\f2MIF Doclet のドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.htmlを参照してください。
.LP
.TP 3
\-docletpath\ classpathlist
\f2\-doclet\fP オプションで指定されたドックレット開始クラスファイル、 およびそのクラスが依存するすべての JAR ファイルへのパスを指定します。開始クラスファイルが jar ファイル内にある場合、以下の例のように jar ファイルのパスが指定されます。絶対パスまたは現在のディレクトリからの相対パスを指定できます。 \f2classpathlist\fP には、複数のパスまたは JAR ファイルを含めることができます。 その場合、各パスまたは JAR ファイルを、Solaris の場合にはコロン (:)、Windows の場合にはセミコロン (;) で区切ります。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。
.LP
jar ファイルへのパスの例には、ドックレット開始クラスファイルが含まれています。jar ファイル名が含まれている点に注目してください。
.nf
\f3
.fl
\-docletpath /home/user/mifdoclet/lib/mifdoclet.jar
.fl
\fP
.fi
ドックレット開始クラスファイルのパスの例。クラスファイル名が省略されている点に注目してください。
.nf
\f3
.fl
\-docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/
.fl
\fP
.fi
特定のドックレットを実行した完全な例については、
.na
\f2MIF Doclet のドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.htmlを参照してください。
.LP
.TP 3
\-1.1
\f2この機能は Javadoc 1.4 から削除されました。代替機能はありません。このオプションは、Javadoc 1.1 によって生成されるのと同じ外見と機能を持つドキュメントを作成するためのものでした。入れ子のクラスはサポートされていません。このオプションが必要な場合は、Javadoc 1.2 または 1.3 を使用してください。\fP
.LP
.TP 3
\-source release
受け付けるソースコードのバージョンを指定します。\f2release\fP には次の値を指定できます。
.RS 3
.TP 2
o
\f31.5\fP \- javadoc は、JDK 1.5 で導入された総称などの言語機能を含むコードを受け付けます。\f3\-source\fP フラグが使用されなかった場合のコンパイラのデフォルト動作は、1.5 のものになります。
.TP 2
o
\f31.4\fP Javadoc は、JDK 1.4 で導入された、アサーションを含むコードを受け付けます。
.TP 2
o
\f31.3\fP Javadoc は、JDK 1.3 以降に導入されたアサーション、総称、または他の言語機能をサポートしません。
.RE
.LP
javac でコードをコンパイルするときに使用した値に対応する \f2release\fP の値を使用します。
.LP
.TP 3
\-sourcepath\ sourcepathlist
パッケージ名または \-subpackages を javadoc コマンドに渡すときは、ソースファイル (.\f2.java\fP) を見つけるための \f2検索パス\fP を指定 \f2します\fP 。\f2sourcepathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使って、ドキュメント化されるソースファイルの位置だけでなく、それ自体はドキュメント化されないがドキュメント化されるソースファイルから継承されたコメントを持つソースファイルの位置も確認できます。
.LP
\f2\-sourcepath\fP オプションを使用できるのは、javadoc コマンドにパッケージ名を渡す場合だけです。このパスからは、javadoc コマンドに渡された \f2.java\fP ファイルは \f2検索\fP されません。 \f2.java\fP ファイルを検索するには、そのファイルのあるディレクトリに cd によって移動するか、または各ファイルの先頭にパスを含めます (「1 つ以上のクラスのドキュメント化」を参照)。 \f2\-sourcepath\fP が省略された場合、Javadoc は、クラスパスを使ってソースファイルを検索します (\-classpath を参照)。したがって、デフォルトの \-sourcepath は、クラスパスの値です。\-classpath も省略してパッケージ名を Javadoc に渡すと、Javadoc は現在のディレクトリおよびそのサブディレクトリからソースファイルを検索します。
.LP
\f2sourcepathlist\fP には、ドキュメント化するパッケージ名のソースツリーのルートディレクトリを設定します。たとえば、 \f2com.mypackage\fP という名前のパッケージをドキュメント化する場合に、そのソースファイルが次の場所にあるとします。
.nf
\f3
.fl
/home/user/src/com/mypackage/*.java
.fl
\fP
.fi
このとき次のように、 \f2sourcepath\fP を、com/mypackage を含むディレクトリである \f2/home/user/src\fP に指定したあと、 パッケージ名 \f2com.mypackage\fP を指定します。
.nf
\f3
.fl
% \fP\f3javadoc \-sourcepath /home/user/src/ com.mypackage\fP
.fl
.fi
この方法は、ソースパスの値とパッケージ名を連結して、ドットを (円記号) 「\\」に変えると、パッケージのフルパス \f2/home/user/src/com/mypackage になることを理解すると簡単です\fP。
.LP
2 つのソースパスを設定するには、次のようにします。
.nf
\f3
.fl
% \fP\f3javadoc \-sourcepath /home/user1/src:/home/user2/src com.mypackage\fP
.fl
.fi
.LP
.TP 3
\-classpath\ classpathlist
javadoc が参照クラス (\f2.class\fP ファイル) の検索を行うときに使用するパスを指定します。参照クラスとは、ドキュメント化されるクラスと、それらのクラスから参照されるすべてのクラスを指します。\f2classpathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。 Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。classpathlist を指定するときは、
.na
\f2クラスパス\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/tools/index.html#generalのドキュメントにある指示 \f2に従ってください\fP。
.LP
\f2\-sourcepath\fP が省略されると、Javadoc ツールはクラスファイルを検索するときだけでなく、ソースファイルを検索するときにも \f2\-classpath\fP を使用します (下位互換性のため)。したがって、ソースファイルとクラスファイルを別々のパスから検索する必要がある場合は、 \f2\-sourcepath\fP と \f2\-classpath の両方を使います\fP.。
.LP
たとえば、 \f2com.mypackage\fP をドキュメント化する場合に、そのソースファイルがディレクトリ \f2/home/user/src/com/mypackage\fP 内に格納されており、このパッケージが \f2/home/user/lib\fP 内のライブラリに依存しているとします。このとき次のように指定します。
.nf
\f3
.fl
% \fP\f3javadoc \-classpath /home/user/lib \-sourcepath /home/user/src com.mypackage\fP
.fl
.fi
\f2\-classpath\fP が指定されなかった場合、Javadoc ツールはほかのツールと同じく、CLASSPATH 環境変数が設定されていればその値を使用します。どちらも設定されていない場合、Javadoc ツールは現在のディレクトリからクラスを検索します。
.LP
Javadoc ツールが \f2\-classpath\fP を使用してユーザークラスを検索する方法について、拡張クラスやブートストラップクラスと関連付けて説明している情報を入手するには、
.na
\f2「クラスの検索方法」\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.htmlを参照してください。
.LP
便宜上、 \f2*\fP のベース名を含むクラスパス要素は、 \f2.jar\fP または \f2.JAR\fP を拡張子に持つディレクトリ内のすべてのファイルのリストを指定するのと同等とみなされます (java プログラムはこの 2 つの呼び出しを区別できない)。
.br
.br
たとえば、ディレクトリ \f2foo\fP に \f2a.jar\fP と \f2b.JAR\fP が含まれている場合、クラスパス要素 \f2foo/*\fP は \f2A.jar:b.JAR\fP に展開されます。ただし、JAR ファイルの順番は未指定となります。このリストには、隠しファイルも含め、指定されたディレクトリ内のすべての JAR ファイルが含まれます。* だけから成る \f2クラスパスエントリは、\fP カレントディレクトリ内のすべての JAR ファイルのリストに展開されます。 \f2CLASSPATH\fP 環境変数も、定義時には同様に展開されます。クラスパスのワイルドカード展開は必ず、Java 仮想マシンの起動前に実行されます。したがって、\f2System.getenv("CLASSPATH")\fP 呼び出しのように環境に問い合わせを行わない限り、Java プログラムが展開されていないワイルドカードを認識することはありません。
.LP
.TP 3
\-subpackages\ \ package1:package2:...
ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソースコードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。各 \f2package\fP 引数は、任意の最上位サブパッケージ ( \f2java\fP など) または完全修飾パッケージ ( \f2javax.swing\fP など) になります。ソースファイルを含める必要はありません。引数は、コロンで区切られます (すべてのオペレーティングシステム)。ワイルドカードは不要です (使用不可)。パッケージの検索場所を指定するには、\f2\-sourcepath\fP を使用します。このオプションは、「ソースファイルの処理」で説明したとおり、ソースツリーにあるがパッケージには属していないソースファイルを処理しないので役立ちます。
.LP
たとえば、
.nf
\f3
.fl
% \fP\f3javadoc \-d docs \-sourcepath /home/user/src \-subpackages java:javax.swing\fP
.fl
.fi
このコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。
.LP
\f2\-subpackages\fP と \f2\-exclude\fP を組み合わせて使用すると、特定のパッケージを除外できます。
.LP
.TP 3
\-exclude\ \ packagename1:packagename2:...
指定されたパッケージとそのサブパッケージを \f2\-subpackages\fP によって作成されたリストから無条件に除外します。 過去の \f2\-subpackages\fP オプションの指定によって組み込まれたパッケージ、または将来組み込まれるパッケージも除外の対象となります。 次に例を示します。
.nf
\f3
.fl
% \fP\f3javadoc \-sourcepath /home/user/src \-subpackages java \-exclude java.net:java.lang\fP
.fl
.fi
この場合、 \f2java.io\fP、 \f2java.util\fP、 \f2java.math\fP などが含められ、 \f2java.net\fP と \f2java.lang\fP をルートに持つパッケージが除外されます。この場合、 \f2java.lang\fP のサブパッケージである \f2java.lang.ref\fP も除外される点に注意してください。
.LP
.TP 3
\-bootclasspath\ classpathlist
ブートクラスが存在するパスを指定します。ブートクラスとは、通常、Java プラットフォームのコアクラスのことです。ブートクラスパスは、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、
.na
\f2「クラスの検索方法」\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html#srcfilesを参照してください。コロン (:) を、 \f2classpathlist\fP 内のディレクトリ間の区切り文字として使用します。
.LP
.TP 3
\-extdirs\ dirlist
拡張機能クラスが存在するディレクトリを指定します。拡張機能クラスとは、Java 拡張機能機構を使うすべてのクラスです。extdirs は、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、前述の \f2\-classpath\fP を参照してください。コロン (:) を、 \f2dirlist\fP 内のディレクトリ間の区切り文字として使用します。
.LP
.TP 3
\-verbose
javadoc の実行中に詳細なメッセージを表示します。verbose オプションを指定しないと、ソースファイルのロード時、ドキュメントの生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時にメッセージが表示されます。verbose オプションを指定すると、各 Java ソースファイルの解析に要した時間 (ミリ秒単位) など、追加のメッセージが表示されます。
.LP
.TP 3
\-quiet
エラーメッセージまたは警告メッセージ以外のメッセージを抑制し、警告とエラーだけが表示されるようにして、これらを特定しやすくします。バージョン文字列も抑制します。
.LP
.TP 3
\-breakiterator\
英語の最初の文の末尾を決定する際に、英語用のロケール固有のアルゴリズムではなく、
.na
\f2java.text.BreakIterator\fP @
.fi
http://java.sun.com/javase/6/docs/api/java/text/BreakIterator.html の国際化された文境界を使用します (ほかのすべてのロケールではすでに \f2BreakIterator\fP が使用されている)。\f2「最初の文」\fPとは、パッケージ、クラス、またはメンバーの主説明での最初の文のことです。この文は、パッケージ、クラス、またはメンバーの要約にコピーされ、アルファベット順のインデックスにコピーされます。
.LP
JDK 1.2 以降、BreakIterator クラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、 \f2\-breakiterator\fP オプションは、1.2 以降では英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。
.RS 3
.TP 2
o
英文のデフォルトの文区切りアルゴリズム \- 空白または HTML ブロックタグ ( \f2<P>\fP など) が続くピリオドで停止する
.TP 2
o
breakiterator 文区切りアルゴリズム \- 一般に、次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止する。このアルゴリズムでは「The serial no. is valid」など、ほとんどの省略表記が処理されますが、「Mr. Smith」などは処理されません。HTML タグや、数字または記号で始まる文では停止しない。HTML タグに埋め込まれている場合でも、「../filename」の最後のピリオドで停止する
.RE
.LP
注: 1.5.0 からは、1.4.x に設けられていた breakiterator 警告メッセージを削除し、デフォルトの文区切りアルゴリズムを変更していません。つまり、\\\-breakiterator オプションは、1.5.0 ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャーリリース」(1.5.0) でデフォルトを変更するという、以前の目的とは逆になっています。つまり、ソースコードを変更せず、1.4.x での breakiterator 警告を除去していない場合でも、1.5.0 からは何もする必要がなく、警告は消滅しています。この逆戻りの理由は、breakiterator をデフォルトにするメリットよりも、デフォルトにするために必要となる、互換性のないソースの変更の方が負担が大きかったためです。この件で皆様に余分の手間をおかけし、混乱を招いたことをお詫びいたします。
.TP 3
\-locale\ language_country_variant
.LP
\f3重要\fP \- \f2\-locale\fP オプションは、\f2標準ドックレットが提供するすべてのオプション\fP、またはその他の任意のドックレットの提供するすべてのオプションより前 (左側) に指定する必要があります。そうしないと、ナビゲーションバーが英語で表示されます。このコマンド行オプションだけは、指定する順序に依存します。
.LP
Javadoc がドキュメントを生成するときに使うロケールを指定します。この引数は次のような、java.util.Locale のドキュメンテーションで説明されているロケールの名前です。 \f2en_US\fP (英語、米国) または \f2en_US_WIN\fP (Windows で使用される英語)。
.LP
ロケールを指定すると、指定したロケールのリソースファイルが Javadoc によって選択されて、メッセージ (ナビゲーションバー、リストと表の見出し、ヘルプファイルの目次、stylesheet.css のコメントなどの文字列) のために使われます。また、アルファベット順にソートされるリストのソート順、および最初の文の末尾を判別するための文の区切り文字も、指定したロケールによって決まります。ただし、このオプションは、ドキュメント化されるクラスのソースファイル内で指定されているドキュメンテーションコメントのテキストのロケールを決定するものではありません。
.LP
.TP 3
\-encoding\ name
ソースファイルのエンコーディングの名前 ( \f2EUCJIS/SJIS\fP など) を指定します。 このオプションが指定されていない場合は、プラットフォームのデフォルトコンバータが使われます。
.LP
\-docencoding および \-charset も参照してください。
.LP
.TP 3
\-Jflag
javadoc を実行する実行時システム java に、\f2flag\fP を直接渡します。 \f2J\fP と \f2flag\fP の間に空白を入れないように注意してください。たとえば、生成ドキュメントの処理用として32M バイトのメモリーをシステムで確保しておく必要がある場合には、java の \f2\-Xmx\fP オプションを次のように呼び出します。\f2\-Xms\fP は省略可能です。これは、メモリーの初期サイズを設定するだけのオプションで、メモリーの最低必要量がわかっている場合に便利です。
.nf
\f3
.fl
% \fP\f3javadoc \-J\-Xmx32m \-J\-Xms32m\fP \f3com.mypackage\fP
.fl
.fi
使用している javadoc のバージョンを確認するには、次のように Java の\f2「\-version」\fPオプションを呼び出します。
.nf
\f3
.fl
% \fP\f3javadoc \-J\-version\fP
.fl
java version "1.2"
.fl
Classic VM (build JDK\-1.2\-V, green threads, sunwjit)
.fl
.fi
出力ストリームには標準ドックレットのバージョン番号が含まれます。
.RE
.SS
標準ドックレットが提供するオプション
.RS 3
.TP 3
\-d\ directory
生成された HTML ファイルを保存する生成先ディレクトリを指定します(「d」は「生成先 (destination)」の意味)。このオプションを省略すると、生成されたファイルは現在のディレクトリに保存されます。値 \f2directory\fP には、絶対ディレクトリ、または現在の作業ディレクトリからの相対ディレクトリを指定できます。バージョン 1.4 では、javadoc を実行すると生成先ディレクトリが自動的に作成されます。
.LP
たとえば次の場合、パッケージ \f2com.mypackage\fP のドキュメントが生成され、その結果が \f2/home/user/doc/\fP ディレクトリに保存されます。
.nf
\f3
.fl
% \fP\f3javadoc \-d /home/user/doc com.mypackage\fP
.fl
.fi
.LP
.TP 3
\-use
ドキュメント化されるクラスおよびパッケージごとに 1 つの「使用」ページを組み込みます。このページには、その特定のクラスまたはパッケージの API を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドが記述されます。たとえば、クラス C を例にとると、クラス C を使っているものとしては、C のサブクラス、C として宣言されているフィールド、C を返すメソッド、および、型 C のパラメータを持つメソッドとコンストラクタがあります。
.LP
たとえば、String の [使用] ページに何が表示されるかを見てみましょう。java.awt.Font クラスの \f2getName()\fP メソッドは、 \f2String\fP 型の値を \f2返します\fP。したがって、 \f2getName()\fP は \f2String\fP を使用しているので、String の [使用] ページに \f2このメソッドが表示されます\fP。
.LP
ただし、ドキュメント化されるのは API の使用だけであって、実装はドキュメント化されません。あるメソッドが、その実装の中で \f2String\fP を使っていても、引数として文字列をとったり、文字列を返したりしない場合は、 \f2String\fP の「使用」とはみなされません。
.LP
生成された [使用] ページにアクセスするには、目的のクラスまたはパッケージに移動し、ナビゲーションバーの [使用] リンクをクリックします。
.TP 3
\-version
生成ドキュメントに、@version のテキストを組み込みます。このテキストは、デフォルトでは省略されます。使用している Javadoc ツールのバージョンを確認するには \f2\-J\-version\fP オプションを使用します。
.LP
.TP 3
\-author
生成ドキュメントに、@author のテキストを組み込みます。
.LP
.TP 3
\-splitindex
索引ファイルをアルファベットごとに複数のファイルに分割し、文字ごとに 1 つのファイルと、アルファベット以外の文字で始まる索引エントリ用に 1 つのファイルを作成します。
.LP
.TP 3
\-windowtitle\ title
HTML の <title> タグに配置するタイトルを指定します。指定したタイトルは、ウィンドウのタイトルや、このページに対して作成されたブラウザのブックマーク (お気に入り) に表示されます。このタイトルには HTML タグを含めないでください。タイトルに HTML タグが含まれていると、ブラウザがタグを正しく解釈できません。\f2title\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。\-windowtitle が省略されている場合、Javadoc ツールは、このオプションの代わりに \-doctitle の値を使います。
.nf
\f3
.fl
% \fP\f3javadoc \-windowtitle "Java SE Platform" com.mypackage\fP
.fl
.fi
.TP 3
\-doctitle\ title
概要ファイルの最上部の近くに配置するタイトルを指定します。タイトルは中央揃えになり、レベル 1 の見出しとして、上部ナビゲーションバーのすぐ下に置かれます。\f2title\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2title\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。
.nf
\f3
.fl
% \fP\f3javadoc \-doctitle "Java(TM)" com.mypackage\fP
.fl
.fi
.TP 3
\-title\ title
\f3このオプションはもう存在していません。\fPこのオプションは Javadoc 1.2 のベータ版にしか存在していませんでした。このオプションの名前は \f2\-doctitle\fP に変更されました。名前を変更した理由は、このオプションが、ウィンドウのタイトルではなくドキュメントのタイトルを定義することを明確にするためです。
.LP
.TP 3
\-header\ header
各出力ファイルの上端に配置するヘッダーテキストを指定します。ヘッダーは、上部ナビゲーションバーの右側に配置されます。\f2header\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2header\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。
.nf
\f3
.fl
% \fP\f3javadoc \-header "<b>Java 2 Platform </b><br>v1.4" com.mypackage\fP
.fl
.fi
.LP
.TP 3
\-footer\ footer
各出力ファイルの下端に配置するフッターテキストを指定します。フッターは、下部ナビゲーションバーの右側に配置されます。\f2footer\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2footer\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。
.LP
.TP 3
\-top
各出力ファイルの上端に配置するテキストを指定します。
.LP
.TP 3
\-bottom\ text
各出力ファイルの最下部に配置するテキストを指定します。このテキストは、下部ナビゲーションバーより下の、ページの最下部に配置されます。 \f2text\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。引用符を \f2text\fP 内で使用する場合、引用符をエスケープしなければならない可能性があります。
.LP
.TP 3
\-link\ extdocURL
javadoc により生成された既存の外部参照クラスのドキュメンテーションへのリンクを作成します。引数を 1 つとります。
.LP
.RS 3
.TP 2
o
\f4extdocURL\fP は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。あとで例を示します。このディレクトリ内にパッケージリストファイルが存在していなければなりません。 存在しない場合は、\f2\-linkoffline\fP を使用します。Javadoc ツールは、 \f2package\-list\fP ファイルからパッケージ名を読み取ったあと、その URL でそれらのパッケージにリンクします。Javadoc ツールの実行時に、\f2extdocURL\fP の値がそのまま、作成された \f2<A HREF>\fP リンク内にコピーされます。したがって、\f2extdocURL\fP はファイルへの URL ではなく「ディレクトリへの URL」でなければなりません。
.LP
\f2extdocURL\fP への絶対リンクを使用すると、ユーザーのドキュメントを任意の Web サイト上のドキュメントにリンクできます。相対位置へリンクするだけでよい場合は相対リンクを使用できます。相対リンクの場合、ユーザーが渡す値は、( \f2\-d\fP で指定された) 生成先ディレクトリから、リンク先となるパッケージを含むディレクトリへの相対パスにすべきです。
.LP
通常、絶対リンクを指定する場合は、 \f2http:\fP リンクを使用します。Web サーバーを持たないファイルシステムにリンクする場合は、 \f2file: リンクを使用できます。\fP ただし、この方法は、すべてのユーザーが生成された同じファイルシステムを共有するドキュメントにアクセスする必要がある場合以外は使用しないでください。
.LP
すべての場合、すべてのオペレーティングシステムで、絶対 URL と相対 URL、「http:」ベースと「file:」ベースにかかわらず、スラッシュを区切り文字として使用します (
.na
\f2URL Memo\fP @
.fi
http://www.ietf.org/rfc/rfc1738.txt で指定)。
.RS 3
.TP 3
http: ベースの絶対リンク:
\f2\-link http://<host>/<directory>/<directory>/.../<name>\fP
.TP 3
file: ベースの絶対リンク:
\f2\-link file://<host>/<directory>/<directory>/.../<name>\fP
.TP 3
相対リンク:
\f2\-link <directory>/<directory>/.../<name>\fP
.RE
.RE
.LP
javadoc の 1 回の実行で複数の \f2\-link\fP オプションを指定すれば、複数のドキュメントへのリンクを作成できます。 \f3\-linkoffline または \-link の選択\fP
.br
\f2\-link\fPを使用する場合:
.RS 3
.TP 2
o
外部 API ドキュメントへの相対パスを使用する場合
.TP 2
o
外部 API ドキュメントへの絶対 URL を使用する場合 (プログラムがその URL に接続し、読み取りを行うことがシェルによって許可されている場合)
.RE
\f2\-linkoffline\fP を使用する場合:
.RS 3
.TP 2
o
外部 API ドキュメントへの絶対 URL を使用する場合 (プログラムがその URL に接続し、読み取りを行うことがシェルによって許可されていない場合)このような状況は、リンク先のドキュメントがファイアウォールの向こう側にある場合に発生します。
.RE
.LP
\f3外部ドキュメントへの絶対リンクの使用例\fP \- \f2java.lang\fP、 \f2java.io\fP 、その他の Java プラットフォームパッケージ (
.na
\f2http://java.sun.com/javase/6/docs/api/\fP @
.fi
http://java.sun.com/javase/6/docs/api 内) にリンクする場合を考えます。次のコマンドは、Java SE プラットフォームパッケージへのリンクを含んだ、パッケージ \f2com.mypackage\fP のドキュメントを生成します。生成されたドキュメントには、たとえばクラスツリー内の \f2Object\fP クラスへのリンクが含まれています。なお、 \f2\-sourcepath\fP や \f2\-d\fP など、その他のオプションは示していません。
.nf
\f3
.fl
% \fP\f3javadoc \-link http://java.sun.com/javase/6/docs/api com.mypackage\fP
.fl
.fi
\f3外部ドキュメントへの相対リンクの使用例\fP \- 2 つのパッケージがあり、そのドキュメントが Javadoc ツールを複数回実行した結果生成されたものであるとします。さらに、これらのドキュメントが相対パスで分割されているとします。この例の場合、パッケージは、API である \f2com.apipackage\fP と、SPI (サービスプロバイダインタフェース) である \f2com.spipackage\fP です。ドキュメントの格納先は、 \f2docs/api/com/apipackage\fP と \f2docs/spi/com/spipackage\fP です。API パッケージのドキュメントはすでに生成済みで、 \f2docs\fP がカレントディレクトリになっていると仮定すると、API ドキュメントへのリンクを含む SPI パッケージをドキュメント化するには、次のコマンドを実行します。
.nf
\f3
.fl
% \fP\f3javadoc \-d ./spi \-link ../api com.spipackage\fP
.fl
.fi
.LP
\f2\-link\fP の引数は、生成先ディレクトリ (\f2docs/spi\fP) からの相対パスです。
.LP
\f3詳細\fP \- \f2\-link\fP オプションを使うと、「コードからは参照されていても、Javadoc の今回の実行ではドキュメント化されない」というクラスにリンクできるようになります。リンクから有効なページに移動できるようにするには、それらの HTML ページがある場所を調べ、その場所を \f2extdocURL\fP に指定する必要があります。これにより、たとえば、サードパーティーのドキュメントから \f2http://java.sun.com 上の java.*\fP のドキュメントへのリンクが \f2可能となります\fP。
.LP
今回の実行で Javadoc によって生成されるドキュメント内の API だけを対象に \f2リンクを作成する場合は、\fP \-link オプションを省略します。 \f2\-link\fP オプションが指定されていない場合、Javadoc ツールは、外部参照されたドキュメントへのリンクを作成しません。これは、そのドキュメントが存在するかどうか、および存在する場合はその場所を判別できないからです。
.LP
このオプションでは、生成ドキュメント内の複数の場所にリンクを作成できます。
.LP
もう 1 つの用途は、パッケージセット間でのクロスリンクです。一方のパッケージセットに対して javadoc を実行したあと、他方のパッケージセットに対して javadoc を再度実行することにより、両セット間で双方向のリンクを作成できます。
.LP
\f3クラスの参照方法\fP \- 外部参照クラスへのリンクを、テキストラベルだけではなく実際に表示するには、次の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するだけでは十分ではありません。それらのクラスは、 \f2import\fP 文、宣言のいずれの場所で参照されている必要があります。Here are examples of how the class \f2java.io.File\fP can be referenced:
.RS 3
.TP 2
o
すべての種類の \f2import\fP 文の場合: ワイルドカードによるインポート、名前による明示的なインポート、または \f2java.lang.* に対する自動的なインポート\fP。たとえば、次のようにすれば十分です。
.br
\f2import java.io.*;\fP
.br
1.3.x および 1.2.x では、名前による明示的なインポートだけです。ワイルドカードによるインポート文も、 \f2java.lang.* の自動インポートも使用できません\fP。
.TP 2
o
宣言の場合:
.br
\f2void foo(File f) {}\fP
.br
この参照を使用し、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースの戻り値の型またはパラメータの型に置くか、 \f2implements\fP、 \f2extends\fP 、または \f2throws\fP 文に置きます。
.RE
.LP
重要な結果として、 \f2\-link\fP オプションの使用時に、この制限のために誤って表示されないリンクが多数発生する可能性があります。テキストはハイパーテキストリンクが付けられずに表示されます。これらのリンクが表示する警告から、このリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するためのもっとも安全な方法は上で説明したとおり、当該のクラスをインポートすることです。
.LP
\f3パッケージリスト\fP \- \f2\-link\fP オプションが正しく機能するには、Javadoc ツールによって生成される \f2package\-list\fP という名前のファイルが、ユーザーが \f2\-link\fP に指定した URL に存在している必要があります。 \f2package\-list\fP ファイルは、その場所にあるドキュメント化されたパッケージの名前のリストが入った単純なテキストファイルです。前の例では、Javadoc ツールは、指定された URL で \f2package\-list\fP という名前のファイルを検索し、パッケージ名を読み込んだあと、その URL にあるそれらのパッケージへのリンクを作成しました。
.LP
たとえば、Java SE 6 API のパッケージリストは
.na
\f2http://java.sun.com/javase/6/docs/api/package\-list\fP @
.fi
http://java.sun.com/javase/6/docs/api/package\-list にあり、次のような内容で始まっています。
.nf
\f3
.fl
java.applet
.fl
java.awt
.fl
java.awt.color
.fl
java.awt.datatransfer
.fl
java.awt.dnd
.fl
java.awt.event
.fl
java.awt.font
.fl
その他
.fl
\fP
.fi
.LP
\f2\-link\fP オプションを指定せずに javadoc を実行した場合、外部参照クラスに属する名前を見つけると、javadoc はその名前をリンクを持たない形で出力します。一方、 \f2\-link\fP オプションが指定された場合、Javadoc ツールは、 \f2指定された\fP \f2extdocURL\fP の場所にある package\-list ファイル内で、そのパッケージ名を検索します。パッケージ名が見つかると、\f2extdocURL\fP が名前の前に付加されます。
.LP
すべてのリンクが正しく機能するためには、外部参照のすべてのドキュメントが、指定した URL に存在していなければなりません。Javadoc ツールは、指定された package\-list が存在するかどうかを調べるだけで、指定された URL に目的のページが存在するかどうかはチェックしません。
.LP
\f3複数のリンク\fP \- 複数の \f2\-link\fP オプションを指定すると、任意の数の外部生成ドキュメントへのリンクを作成できます。Javadoc 1.2 には、複数の \f2\-link\fP コマンドを指定できないというバグがあります。これは 1.2.2 で修正されました。
.LP
リンクする外部ドキュメントごとに、次のように別々のリンクオプションを指定します。
.LP
\ \ \f2% \fP\f4javadoc \-link\fP \f2extdocURL1\fP \f4\-link\fP \f2extdocURL2\fP \f2... \fP\f4\-link\fP \f2extdocURLn\fP \f4com.mypackage\fP
.LP
\f2extdocURL1\fP、\f2extdocURL2\fP、... \f2extdocURLn\fP は、それぞれ外部ドキュメントのルートを指し、各ルートには、 \f2package\-list\fP という名前のファイルが入っています。
.LP
\f3クロスリンク\fP \- まだ生成されていない 2 つ以上のドキュメントをクロスリンクする場合は、「ブートストラップ」が必要になります。つまり、どのドキュメントについても \f2package\-list\fP が存在していない場合は、最初のドキュメントに対して Javadoc ツールを実行する時点で、2 番目のドキュメントの \f2package\-list\fP はまだ存在していません。したがって、外部リンクを作成するには、2 番目のドキュメントを生成したあとで、最初のドキュメントを生成し直す必要があります。
.LP
この場合、最初のドキュメント生成の目的は、 \f2package\-list\fP を作成することです。パッケージ名をすべて把握している場合は、package\-list を手動で作成してもかまいません。次に、2 番目のドキュメントとその外部リンクを生成します。必要な外部の \f2package\-list\fP ファイルが存在しない場合は、Javadoc ツールから警告が出力されます。
.LP
.TP 3
\-linkoffline\ extdocURL\ packagelistLoc
このオプションは \f2\-link\fP のバリエーションの 1 つです。どちらも、外部参照クラスの javadoc 生成ドキュメントへのリンクを作成します。Javadoc \f2ツール自体が\fP オフラインになっているとき (Web 接続を使ってドキュメントにアクセスできないとき)、Web 上のドキュメントにリンクするには、\-linkoffline オプションを使用します。
.LP
厳密には、 \f2外部\fP ドキュメントの \f2package\-list\fP ファイルにアクセスできないとき、またはこのファイルが \f2extdocURL\fP で指定された場所とは異なる場所 (通常、\f2packageListLoc\fP で指定可能なローカルな場所) に存在するとき、\-linkoffline を使用します。したがって、WWW 経由でしか \f2extdocURL\fP にアクセスできない場合、 \f2\-linkoffline\fP を指定することにより、ドキュメントの生成時に Javadoc ツールが Web に接続できなければならないという制約がなくなります。
.LP
さらに、ドキュメントを更新するための「ハッキング」としての使用も可能です。パッケージのセット全体に対して javadoc を実行したあと、変更した一部のパッケージだけに対して javadoc を実行します。こうして、更新されたファイルを、オリジナルのファイルセットに挿入できるようにします。例をあとで示します。
.LP
\f2\-linkoffline\fP オプションは引数を 2 つ取ります。1 つは、 \f2<a href>\fP リンクに組み込まれる文字列を表す引数、もう 1 つは \f2package\-list\fP の検索場所を示す引数です。
.RS 3
.TP 2
o
\f4extdocURL\fP は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。相対リンクの場合、その値は、( \f2\-d\fP で指定された) 生成先ディレクトリからリンク先パッケージのルートへの相対パスにすべきです。詳細は、\-link オプションの \f2extdocURL\fP \f2を参照\fP してください。
.TP 2
o
\f4packagelistLoc\fP は、外部ドキュメントの \f2package\-list\fP ファイルを含むディレクトリへのパスまたは URL です。これは、URL (http: または file:) でもファイルパスでもかまいませんし、絶対パスでも相対パスでもかまいません。相対パスの場合は、javadoc が実行されるカレントディレクトリからの相対パスとして指定します。ファイル名 \f2package\-list\fP は含めないでください。
.RE
.LP
1 回の javadoc 実行で複数の \f2\-linkoffline\fP オプションを指定できます。1.2.2 より前は、複数のオプションを指定することはできませんでした。
.LP
\f3外部ドキュメントへの絶対リンクの使用例\fP \- http://java.sun.com/javase/6/docs/api 内の \f2java.lang\fP、 \f2java.io\fP 、およびその他の Java SE プラットフォームパッケージ \f2にリンクしたくても\fP Web にアクセスできない場合を考えます。ブラウザで \f2、\fP
.na
\f2http://java.sun.com/javase/6/docs/api/package\-list\fP @
.fi
http://java.sun.com/javase/6/docs/api/package\-list にある package\-list ファイルを開き、それをローカルディレクトリに保存し、第 2 引数 \f2packagelistLoc\fP でこのローカルコピーへのパスを指定します。この例では、パッケージリストファイルはカレントディレクトリ "\f2.\fP" に保存されています。次のコマンドは、Java SE プラットフォームパッケージへのリンクを含んだ、パッケージ \f2com.mypackage\fP のドキュメントを生成します。生成されたドキュメントには、たとえばクラスツリー内の \f2Object\fP クラスへのリンクが含まれています。なお、 \f2\-sourcepath\fP など、その他の必要オプションは示されていません。
.nf
\f3
.fl
% \fP\f3javadoc \-linkoffline http://java.sun.com/javase/6/docs/api . com.mypackage\fP
.fl
.fi
.LP
\f3外部ドキュメントへの相対リンクの使用例\fP \- \f2\-linkoffline\fP で相対パスを使用することは、あまりありません。理由は単純で、通常は \f2\-link\fP で十分だからです。 \f2\-linkoffline\fP を使用する際、 \f2package\-list\fP には通常ローカルのファイルを指定します。 相対リンクを使用する際も、リンク先のファイルには通常ローカルのファイルを指定します。したがって、 \f2\-linkoffline の 2 つの引数に別々のパスを指定する必要はありません\fP。2 つの引数が同一である場合は、 \f2\-link\fP を使用できます。 \f2\-link\fP の相対リンクの例を参照してください。
.LP
\f4package\-list\fP\f3 ファイルを手動で作成\fP \- \f2package\-list\fP ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルを自分で作成し、packagelistLoc \f2でそのパスを指定することができます。\fPcom.apipackage が最初に生成される時点で \f2com.spipackage\fP のパッケージリストが存在していなかったという、 \f2前出のケースが\fP 一例として挙げられます。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。また、Javadoc 1.0 または 1.1 で生成されたパッケージの \f2package\-list\fP ファイルを作成する必要がある場合にも、この方法が使えます。これらのバージョンでは、 \f2package\-list\fP ファイルは生成されていませんでした。同様に、2 つの企業が未公開の \f2package\-list\fP ファイルを共有すれば、クロスリンクを含むドキュメントを同時にリリースすることも可能となります。
.LP
\f3複数のドキュメントへのリンク\fP \- 参照先となる生成ドキュメントごとに \f2\-linkoffline\fP を 1 回ずつ含めることができます。わかりやすくするために、オプションごとに改行して示しています。
.LP
\f2% \fP\f4javadoc \-linkoffline\fP \f2extdocURL1\fP \f2packagelistLoc1\fP \f2\\\fP
.br
\f2\ \ \ \ \ \ \ \ \ \ \fP\f4\-linkoffline\fP \f2extdocURL2\fP \f2packagelistLoc2\fP \f2\\\fP
.br
\f2\ \ \ \ \ \ \ \ \ \ ...\fP
.LP
\f3ドキュメントの更新\fP \- 前述の \f2\-linkoffline\fP オプションのもうひとつの用途は、プロジェクトに大量のパッケージが含まれていて、すでにツリー全体に対して javadoc の実行が完了している場合に、次の実行では、少量の変更を手早く加えたあと、ソースツリーのごく一部に対してだけ javadoc を再実行する場合に便利です。これは、ドキュメンテーションコメントに対してだけ変更を加え、宣言は変更しない場合にのみ正しく処理されるので、ハッキングのようなものです。ソースコードの宣言を追加、削除、または変更した場合は、索引、パッケージツリー、継承されるメンバーのリスト、「使用」ページなどの場所で、リンクが壊れることがあります。
.LP
まず、この新しい小さな実行用として、新しい生成先ディレクトリ ( \f2update\fP と命名) を作成します。元の生成先ディレクトリの名前が \f2html\fP だったとします。もっとも単純な例では、 \f2html ディレクトリの親ディレクトリに移動 (cd) します\fP。 \f2\-linkoffline\fP の第 1 引数をカレントディレクトリ「.」に設定し、第 2 引数を、package\-list が含まれている \f2html\fP への相対パスに設定し、 \f2更新するパッケージのパッケージ名のみを\fP渡します。
.nf
\f3
.fl
% \fP\f3javadoc \-d update \-linkoffline . html com.mypackage\fP
.fl
.fi
Javadoc ツリーの終了後、 \f2update/com/package\fP 内の生成されたクラスのページをコピーし (概要や索引は除く)、 \f2html/com/package 内の元のファイルに上書きします\fP。
.LP
.TP 3
\-linksource\
各ソースファイル (行番号付き) の HTML バージョンを作成し、標準 HTML ドキュメントからソースファイルへのリンクを追加します。リンクは、ソースファイル内に宣言されているクラス、インタフェース、コンストラクタ、メソッド、フィールドに対して作成されます。デフォルトコンストラクタ、生成されたクラスに対しては作成されません。
.LP
\f3このオプションは、\fP\f4\-public\fP\f3、 \fP\f4\-package\fP\f3、 \fP\f4\-protected\fP\f3 、 \fP\f4\-private\fP\f3 の各オプションとは関係なく、非公開のクラス、フィールド、非公開のメソッドの本体をはじめとする組み込まれたソースファイル内のすべての非公開実装の詳細を公開します。\fP\f2\-private\fP オプションも併せて指定しないかぎり、非公開のすべてのクラスやインタフェースにリンク経由でアクセスできるとはかぎりません。
.LP
各リンクは、その宣言内の識別子名の上に作成されます。たとえば、 \f2Button\fP クラスのソースコードへのリンクは、「Button」という語の上に作成されます。
.nf
\f3
.fl
public class Button
.fl
extends Component
.fl
implements Accessible
.fl
\fP
.fi
また、Button クラスの \f2getLabel()\fP メソッドのソースコードへのリンクは、「getLabel」という語の上に作成されます。
.nf
\f3
.fl
public String getLabel()
.fl
\fP
.fi
.LP
.TP 3
\-group\ groupheading\ packagepattern:packagepattern:...
概要ページの複数のパッケージを、指定したグループに分けて、グループごとに表を作成します。各グループは、それぞれ別の \f2\-group\fP オプションで指定します。これらのグループは、コマンド行で指定した順序でページに表示されます。各グループ内では、パッケージがアルファベット順に並べられます。ある特定の \f2\-group\fP オプションでは、 \f2packagepattern\fP 式のリストに一致するパッケージが、 \f2groupheading\fP という見出しの表に表示されます。
.RS 3
.TP 2
o
\f4groupheading\fP には、任意のテキストを指定でき、空白を含めることができます。指定したテキストは、グループの表見出しになります。
.TP 2
o
\f4packagepattern\fP には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (\f2*\fP) を指定できます。 アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。ワイルドカードとして指定できるのは、アスタリスクだけです。1 つのグループには、コロン (\f2:\fP) で区切って複数のパターンを含めることができます。
.RE
.LP
\f3注: パターンやパターンリスト内でアスタリスクを使う場合は、 \fP\f4"java.lang*:java.util" のように、パターンリストを引用符で囲む必要があります。\fP
.LP
ユーザーが \f2\-group\fP オプションを 1 つも指定しなかった場合、「パッケージ」という見出しの 1 つのグループ内に、すべてのパッケージが配置されます。ドキュメント化されるパッケージの中に、指定したグループのどのグループにも入らないパッケージがある場合、このようなパッケージは「その他のパッケージ」という見出しを持つ独立したグループに入れられます。
.LP
たとえば、次のようにオプションを指定すると、ドキュメント化される 5 つのパッケージは、コアパッケージ、拡張機能パッケージ、およびその他のパッケージに分けられます。「java.lang*」では、最後のドットを指定していないことに注目してください。「java.lang.*」のようにドットを入れると、java.lang パッケージは除外されることになります。
.nf
\f3
.fl
% \fP\f3javadoc \-group "Core Packages" "java.lang*:java.util"
.fl
\-group "Extension Packages" "javax.*"
.fl
java.lang java.lang.reflect java.util javax.servlet java.new\fP
.fl
.fi
この結果、次のようなグループ化が行われます。
.RS 3
.TP 3
コアパッケージ
\f2java.lang\fP
\f2java.lang.reflect\fP
\f2java.util\fP
.TP 3
拡張機能パッケージ
\f2javax.servlet\fP
.TP 3
その他のパッケージ
\f2java.new\fP
.RE
.LP
.TP 3
\-nodeprecated
推奨されない API をドキュメントに生成しないようにします。このオプションを指定すると、\-nodeprecatedlist オプションを指定した場合と同じ効果があることに加えて、ドキュメントのほかの部分全体でも、推奨されない API が生成されません。このオプションは、コードを記述しているとき、推奨されないコードによって気を散らされたくない場合に便利です。
.LP
.TP 3
\-nodeprecatedlist
推奨されない API のリストを含むファイル (deprecated\-list.html)、およびナビゲーションバーのそのページへのリンクが生成されないようにします。ただし、ドキュメントのほかの部分では、推奨されない API が生成されます。このオプションは、推奨されない API がソースコードに含まれておらず、ナビゲーションバーをすっきりと見せたい場合に便利です。
.LP
.TP 3
\-nosince
生成ドキュメントから、@since タグに対応する「導入されたバージョン」 セクションを省略します。
.LP
.TP 3
\-notree
生成されるドキュメントからクラスおよびインタフェースの階層ページを省略します。これらのページには、ナビゲーションバーの「ツリー」ボタンからアクセスできます。デフォルトでは、階層が生成されます。
.LP
.TP 3
\-noindex
生成ドキュメントから、索引を省略します。デフォルトでは、索引が生成されます。
.LP
.TP 3
\-nohelp
出力の各ページの最上部と最下部にあるナビゲーションバーから「ヘルプ」リンクを省略します。
.LP
.TP 3
\-nonavbar
生成されるページの最上部と最下部に表示されるナビゲーションバー、ヘッダー、およびフッターを生成しないようにします。このオプションは、bottom オプションには影響を与えません。 \f2\-nonavbar\fP オプションは、印刷するためだけにファイルを PostScript または PDF に変換する場合など、内容だけが重要で、ナビゲーションの必要がない場合に便利です。
.LP
.TP 3
\-helpfile\ path/filename
上部と下部のナビゲーションバーの「ヘルプ」リンクのリンク先となる代替ヘルプファイル \f2path/filename\fP のパスを指定します。このオプションが指定されないと、Javadoc ツールは、ツール内でハードコードされているヘルプファイル \f2help\-doc.html\fP を自動作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。\f2filename\fP にはどんなファイル名でも指定でき、 \f2help\-doc.html には限定されません。\fP Javadoc ツールは、ナビゲーションバー内のリンクを必要に応じて調整します。次に例を示します。
.nf
\f3
.fl
% \fP\f3javadoc \-helpfile /home/user/myhelp.html java.awt\fP
.fl
.fi
.TP 3
\-stylesheetfile\ path/filename
代替 HTML スタイルシートファイルのパスを指定します。このオプションが指定されないと、Javadoc ツールは、ツール内でハードコードされているスタイルシートファイル \f2stylesheet.css\fP を自動作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。\f2filename\fP にはどんなファイル名でも指定でき、 \f2stylesheet.css には限定されません\fP。たとえば、
.nf
\f3
.fl
% \fP\f3javadoc \-stylesheetfile /home/user/mystylesheet.css com.mypackage\fP
.fl
.fi
.TP 3
\-serialwarn
@serial タグがない場合は、コンパイル時に警告を生成します。デフォルトでは、Javadoc 1.2.2 以降のバージョンでは、直列化の警告は生成されません1.2.2 より前の初期バージョンでは、警告が生成されます。このオプションを使用すると、直列化の警告が表示されるので、デフォルトの直列化可能フィールドと \f2writeExternal\fP メソッドを適切にドキュメント化するのに役立ちます。
.LP
.TP 3
\-charset\ name
このドキュメント用の HTML 文字セットを指定します。この名前は、
.na
\f2IANA Registry\fP @
.fi
http://www.iana.org/assignments/character\-sets で与えられた、推奨される MIME 名でなければなりません。たとえば、
.nf
\f3
.fl
% \fP\f3javadoc \-charset "iso\-8859\-1" mypackage\fP
.fl
.fi
生成されるすべてのページの先頭に、次の行が挿入されます。
.nf
\f3
.fl
<META http\-equiv="Content\-Type" content="text/html; charset=ISO\-8859\-1">
.fl
\fP
.fi
この META タグについては、
.na
\f2HTML の標準\fP @
.fi
http://www.w3.org/TR/REC\-html40/charset.html#h\-5.2.2 (4197265 および 4137321) を参照してください。
.LP
\-encoding および \-docencoding も参照してください。
.LP
.TP 3
\-docencoding\ name
生成される HTML ファイルのエンコーディングを指定します。この名前は、
.na
\f2IANA Registry\fP @
.fi
http://www.iana.org/assignments/character\-sets で与えられた、推奨される MIME 名でなければなりません。このオプションを省略しながら \-encoding を使用した場合、生成される HTML ファイルのエンコードは、\-encoding によって決められます。例:
.nf
\f3
.fl
% \fP\f3javadoc \-docencoding "ISO\-8859\-1" mypackage\fP
.fl
.fi
\-encoding および \-charset も参照してください。
.LP
.TP 3
\-keywords
HTML メタキーワードタグを、クラスごとに生成されるファイルに追加します。これらのタグは、メタタグを検索するサーチエンジンがページを見つける場合に役立ちます。インターネット全体を検索する多くのサーチエンジンは、ページがメタタグを誤用しているため、メタタグを調べません。一方、検索を自身の Web サイトに限定している企業では、サーチエンジンがメタタグを調べることによってメリットを得られます。
.LP
メタタグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同じであるため含まれません。たとえば、クラス String は次のキーワードで開始します。
.nf
\f3
.fl
<META NAME="keywords" CONTENT="java.lang.String class">
.fl
<META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
.fl
<META NAME="keywords" CONTENT="length()">
.fl
<META NAME="keywords" CONTENT="charAt()">
.fl
\fP
.fi
.LP
.TP 3
\-tag\ \ tagname:Xaoptcmf:"taghead"
Javadoc ツールがドキュメンテーションコメント内の引数を 1 つ取る単純なカスタムブロックタグ \f2@\fP\f2tagname\fP を解釈できるようにします。Javadoc ツールはタグ名の「スペルチェック」を行うことができるので、ソースコード内に存在するすべてのカスタムタグについて、 \f2\-tag\fP オプションを含めることが重要です。今回の実行では出力されないタグは、X を付けて無効 \f2にします\fP。
.LP
コロン (\f4:\fP) が常に区切り文字になります。tagname \f2でコロンを使用する方法については、\fP 「タグ名でのコロンの使用」を参照してください。
.LP
\f2\-tag\fP オプションは、タグの見出し「taghead」を太字で出力します。 その次の行には、このオプションの引数で指定したテキストが続きます。 以下の例を参照してください。ブロックタグと同様、この引数のテキストにはインラインタグを含めることができます。このインラインタグも解釈されます。出力は、引数を 1 つ取る標準のタグ ( \f2@return\fP や \f2@author\fP など) の出力とよく似ています。\f2taghead\fP を省略すると、\f2tagname\fP が見出しとして表示されます。
.LP
\f3タグの配置\fP \- 引数の \f4Xaoptcmf\fP 部分は、ソースコード内のタグを配置できる位置と、 を使ってこのタグを無効にできるかどうかを特定します。 \f2X\fP). タグの配置位置を制限しない場合は \f4a\fP を指定します。それ以外の文字の組み合わせも可能です。 \f4X\fP (タグの無効化)
.br
\f4a\fP (すべて)
.br
\f4o\fP (概要)
.br
\f4p\fP (パッケージ)
.br
\f4t\fP (型、つまりクラスとインタフェース)
.br
\f4c\fP (コンストラクタ)
.br
\f4m\fP (メソッド)
.br
\f4f\fP (フィールド)
.LP
\f3シングルタグの例\fP \- ソースコード内の任意の位置で使用できるタグのタグオプションの例を示します。
.nf
\f3
.fl
\-tag todo:a:"To Do:"
.fl
\fP
.fi
@todo をコンストラクタ、メソッド、フィールドのみで使用する場合は、以下のオプションを使用します。
.nf
\f3
.fl
\-tag todo:cmf:"To Do:"
.fl
\fP
.fi
上の例の最後のコロン (\f2:\fP) は、パラメータ区切り子ですが、見出しテキストの一部になっています (以下の例を参照)。次の例のように、 \f2@todo\fP タグを含むソースコードでは、いずれかのタグオプションを使用します。
.nf
\f3
.fl
@todo The documentation for this method needs work.
.fl
\fP
.fi
\f3タグ名にコロンを使用する\fP \- コロン (:) をバックスラッシュでエスケープすると、コロンをタグ名に使用することができます。このドキュメンテーションコメントの中では、次のように使用します。
.nf
\f3
.fl
/**
.fl
* @ejb:bean
.fl
*/
.fl
\fP
.fi
でこのタグオプションを使用すると、
.nf
\f3
.fl
\-tag ejb\\\\:bean:a:"EJB Bean:"
.fl
\fP
.fi
\f3タグ名のスペルチェック (タグの無効化)\fP \- ソースコード内に配置した一部のカスタムタグの出力を抑制したい場合があります。この場合も、ソースコード内にすべてのタグを配置し、出力を抑制しないタグを有効にし、出力を抑制するタグを無効にします。 \f2X\fP が存在する場合はタグが無効になり、存在しない場合はタグが有効になります。これにより、Javadoc ツールは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。未知のタグを検出した場合、Javadoc ツールは警告を出力します。
.LP
すでに配置されている値に \f2X\fP を追加できます。こうしておけば、 \f2X を削除するだけでタグを有効にすることができます\fP。たとえば、@todo タグの出力を抑制したい場合、次のように指定します。
.nf
\f3
.fl
\-tag todo:Xcmf:"To Do:"
.fl
\fP
.fi
さらに単純な指定方法もあります。
.nf
\f3
.fl
\-tag todo:X
.fl
\fP
.fi
.LP
構文 \f2\-tag todo:X\fP は、 \f2@todo\fP がタグレットで定義されていても有効です。
.LP
\f3タグの順序\fP \- \f2\-tag\fP (および \f2\-taglet\fP) オプションの順序によって、タグの出力順が決まります。カスタムタグと標準タグを組み合わせて使用することもできます。標準タグのタグオプションは、順序を決定するためだけのプレースホルダです。これらは標準タグ名のみを使用します。(標準タグの小見出しは変更できません。)これについては、以下の例で説明します。
.LP
\f2\-tag\fP が存在しない場合は、 \f2\-taglet\fP の位置によってその順序が決まります。タグが両方とも存在する場合、コマンド行の最後にあるほうがその順序を決定します。これは、タグやタグレットがコマンド行に指定された順番に処理されるためです。たとえば、 \f2\-taglet\fP と \f2\-tag\fP の両方が todo という名前を持っている場合、コマンド行の最後にあるほうが順序を決定します。
.LP
\f3タグの完全セットの例\fP \- この例では、出力の「Parameters」と「Throws」の間に「To Do」を挿入します。X を使用して、@example が、ソースコード内の今回の実行では出力されないタグであることを指定します。@argfile を使用する場合は、次のように、引数ファイル内の別々の行にタグを配置できます。行の継続を示す文字は不要です。
.nf
\f3
.fl
\-tag param
.fl
\-tag return
.fl
\-tag todo:a:"To Do:"
.fl
\-tag throws
.fl
\-tag see
.fl
\-tag example:X
.fl
\fP
.fi
.LP
javadoc がドキュメンテーションコメントを解析する際に検索されたタグのうち、標準タグでも、 \f2\-tag\fP や \f2\-taglet\fP で渡されたタグでもないものはすべて未知のタグとみなされ、警告がスローされます。
.LP
標準タグは、最初、デフォルトの順序でリスト内に内部的に格納されます。 \f2\-tag\fP オプションを使用すると、このリストに追加されるタグ、すなわち標準タグの位置がデフォルトの位置から移動します。つまり、標準タグに \f2\-tag\fP オプションを付けなければ、これらはデフォルトの位置に配置されたままになります。
.LP
\f3競合の回避\fP \- 固有の名前空間を細かく分けるには、パッケージに使用されている \f2com.mycompany.todo という名前のように、ドット (.) を区切り記号とする名前を使います\fP。Oracle は、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Oracle が提供する同じ名前のタグの動作をオーバーライドします。つまり、 \f2@todo\fP という名前のタグまたはタグレットをユーザーが作成した場合、Oracle がその後同じ名前の標準タグを作成したとしても、その動作は常にユーザーが定義した動作と同じになります。
.LP
\f3注釈 vs. Javadoc タグ\fP \- 一般に、追加する必要のあるマークアップが、ドキュメンテーションに影響を与えたりドキュメンテーションを生成したりするためのものである場合、そのマークアップは javadoc タグにすべきです。それ以外の場合は注釈にすべきです。
.na
\f2「Comparing Annotations and Javadoc Tags」\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#annotationsを参照してください。
.LP
\-taglet オプションを使用して、より複雑なブロックタグやカスタムインラインタグを 作成することができます。
.LP
.TP 3
\-taglet\ \ class
そのタグのドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。クラスの完全指定名を指定してください。このタグレットは、カスタムタグのテキスト引数の数も定義します。タグレットは、これらの引数を受け付け、処理し、出力を生成します。外部ドキュメントとサンプルタグレットについては、以下を参照してください。
.RS 3
.TP 2
o
.na
\f2「タグレットの概要」\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/guides/javadoc/taglet/overview.html
.RE
.LP
タグレットは、ブロックタグまたはインラインタグで便利です。タグレットは任意の数の引数をとることができます。また、テキストを太字にする、箇条書きを作成する、テキストをファイルに書き出す、その他のプロセスを開始するなどのカスタム動作を実装できます。
.LP
タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガーするなどの副作用は得られます。
.LP
タグレットのパスを指定するには、\f2\-tagletpath\fP オプションを使用します。以下は、生成されるページの「Parameter」と「Throws」の間に「To Do」タグレットを挿入する例です。
.nf
\f3
.fl
\-taglet com.sun.tools.doclets.ToDoTaglet
.fl
\-tagletpath /home/taglets
.fl
\-tag return
.fl
\-tag param
.fl
\-tag todo
.fl
\-tag throws
.fl
\-tag see
.fl
\fP
.fi
.LP
また、 \f2\-taglet\fP オプションを \f2\-tag\fP オプションの代わりに使用することもできますが、そうすると可読性が低下する可能性があります。
.LP
.TP 3
\-tagletpath\ \ tagletpathlist
taglet クラスファイル (.class) の検索パスを指定します。\f2tagletpathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。
.LP
.TP 3
\-docfilessubdirs\
「\f2doc\-files\fP」ディレクトリの深いコピーを有効にします。つまり、コピー先には、サブディレクトリとすべてのコンテンツがコピーされます。たとえば、ディレクトリ \f2doc\-files/example/images\fP とそのすべての内容がコピーされます。ここでも、サブディレクトリを除外する指定が可能です。
.LP
.TP 3
\-excludedocfilessubdir\ \ name1:name2...
「\f2doc\-files\fP」の、指定された名前のサブディレクトリをすべて除外します。これにより、SCCS とその他のソースコード制御サブディレクトリのコピーを防ぎます。
.LP
.TP 3
\-noqualifier\ \ all\ | \ packagename1:packagename2:...
出力されるクラス名の先頭のパッケージ名 (パッケージ修飾子) を省略します。 \f2\-noqualifier\fP の引数は、「\f2all\fP」(すべてのパッケージ修飾子が省略される)、修飾子として削除すべきパッケージのコロン区切りリスト (ワイルドカードも可)、のいずれかとなります。クラスまたはインタフェース名が表示される位置からパッケージ名が削除されます。
.LP
次の例では、すべてのパッケージ修飾子を省略します。
.nf
\f3
.fl
\-noqualifier all
.fl
\fP
.fi
次の例では、パッケージ修飾子 java.lang および java.io を省略します。
.nf
\f3
.fl
\-noqualifier java.lang:java.io
.fl
\fP
.fi
次の例では、java で始まるパッケージ修飾子と com.sun というサブパッケージ (javax ではない) を省略します。
.nf
\f3
.fl
\-noqualifier java.*:com.sun.*
.fl
\fP
.fi
パッケージ修飾子が上記の動作に従って表示される場合、名前は適切に短くされます。詳細は「名前の表示方法」を参照してください。この規則は、 \f2\-noqualifier\fP を使用するかどうかにかかわらず有効です。
.LP
.TP 3
\-notimestamp\
タイムスタンプが抑制されます。各ページ先頭近くにある、生成された HTML 内の HTML コメントでタイムスタンプが隠されます。Javadoc を 2 つのソースベースで実行し、それらに対して diff を実行するときにこのオプションを使用すると、タイムスタンプによって diff が発生しなくなるので便利です (このオプションを使用しないと、各ページで diff になります)。タイムスタンプには Javadoc のバージョン番号が含まれており、次のようになります。
.nf
\f3
.fl
<!\-\- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 \-\->
.fl
\fP
.fi
.LP
.TP 3
\-nocomment\
主説明およびすべてのタグを含むコメント本文全体を抑制し、宣言だけを生成します。このオプションにより、元は異なる目的のためだったソースファイルを再利用し、新しいプロジェクトの早い段階でスケルトン HTML ドキュメントを作成できるようになりました。
.LP
.TP 3
\-sourcetab tabLength
ソース内で各タブが獲得する空白の数を指定します。
.RE
.SH "コマンド行引数ファイル"
.LP
javadoc のコマンド行を短くしたり簡潔にしたりするために、 \f2javadoc\fP コマンドに対する引数 ( \f2\-J\fP オプションを除く) が入った 1 つ以上のファイルを指定することができます。このことを利用すれば、どのオペレーティングシステム上でも、任意の長さの javadoc コマンドを作成できます。
.LP
引数ファイルには、javac のオプションとソースファイル名を自由に組み合わせて記述できます。ファイル内の各引数は、スペースまたは改行で区切ります。ファイル名に空白が含まれている場合は、そのファイル名全体を二重引用符で囲みます。
.LP
引数ファイル内のファイル名は、現在のディレクトリから見た相対パスになります。引数ファイルの位置から見た相対パスではありません。引数ファイル内のファイル名リストでは、ワイルドカード (*) は使用できません。たとえば、 \f2*.java\fP とは指定できません。引数ファイル内の引数で \f2@\fP 文字を使用して、複数のファイルを再帰的に解釈することはサポートされていません。また、 \f2\-J\fP オプションもサポートされていません。 このオプションは起動ツールに渡されますが、起動ツールでは引数ファイルをサポートしていないからです。
.LP
javadoc を実行するときに、各引数ファイルのパスとファイル名の先頭に \f2@\fP 文字を付けて渡します。javadoc は、\f2@\fP 文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。
.SS
引数ファイルを 1 つ指定する例
.LP
次のように、「\f2argfile\fP」という名前の単一の引数ファイル内に、Javadoc のすべての引数を格納します。
.nf
\f3
.fl
% \fP\f3javadoc @argfile\fP
.fl
.fi
.LP
この引数ファイルには、次の例で示されている 2 つのファイルの内容を両方とも入れることができます。
.SS
引数ファイルを 2 つ指定する例
.LP
2 つの引数ファイルを作成できます。1 つは Javadoc オプション用、もう 1 つはパッケージ名またはソースファイル名用です。なお、次のリストでは行継続文字を使用していません。
.LP
次の内容を含む、「\f2options\fP」という名前のファイルを作成します。
.nf
\f3
.fl
\-d docs\-filelist
.fl
\-use
.fl
\-splitindex
.fl
\-windowtitle 'Java SE 7 API Specification'
.fl
\-doctitle 'Java SE 7 API Specification'
.fl
\-header '<b>Java(TM) SE 7</b>'
.fl
\-bottom 'Copyright © 1993\-2011 Oracle and/or its affiliates. All rights reserved.'
.fl
\-group "Core Packages" "java.*"
.fl
\-overview /java/pubs/ws/1.7.0/src/share/classes/overview\-core.html
.fl
\-sourcepath /java/pubs/ws/1.7.0/src/share/classes
.fl
\fP
.fi
.LP
次の内容を含む、「\f2packages\fP」という名前のファイルを作成します。
.nf
\f3
.fl
com.mypackage1
.fl
com.mypackage2
.fl
com.mypackage3
.fl
\fP
.fi
.LP
そのあと、次のコマンドを使用して javadoc を実行します。
.nf
\f3
.fl
% \fP\f3javadoc @options @packages\fP
.fl
.fi
.SS
パス付きの引数ファイルの例
.LP
引数ファイルには、パスを指定できます。ただし、そのファイル内に指定されたファイル名は、現在の作業ディレクトリから見た相対パスになります。つまり、下の例の場合は、 \f2path1\fP や \f2path2\fP から見た相対パスではありません。
.nf
\f3
.fl
% \fP\f3javadoc @path1/options @path2/packages\fP
.fl
.fi
.SS
オプションの引数の例
.LP
次に、Javadoc オプションに対する引数だけを引数ファイルに格納する例を示します。ここでは \f2\-bottom\fP オプションを使用します。というのも、引数が長くなる可能性があるからです。次のようなテキスト引数を含む、「\f2bottom\fP」という名前のファイルを作成できます。
.nf
\f3
.fl
<font size="\-1">
.fl
<a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit a bug or feature</a><br/>
.fl
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
.fl
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
.fl
Other names may be trademarks of their respective owners.</font>
.fl
\fP
.fi
.LP
そのあと、次のようにして Javadoc ツールを実行します。
.nf
\f3
.fl
% \fP\f3javadoc \-bottom @bottom @packages\fP
.fl
.fi
.LP
あるいは、引数ファイルの先頭に \f2\-bottom\fP オプションも組み込んだあと、次のように実行してもかまいません。
.nf
\f3
.fl
% \fP\f3javadoc @bottom @packages\fP
.fl
.fi
.SH "名前"
実行
.SH "Javadoc の実行"
.LP
\f3バージョン番号\fP \- javadoc のバージョン番号を判別するには、\f3javadoc \-J\-version\fP を使用します。出力ストリームには標準ドックレットのバージョン番号が含まれます。その出力を無効にするには、 \f2\-quiet\fP を使用します。
.LP
\f3公開プログラムインタフェース\fP \- Java 言語で記述されたプログラムから Javadoc ツールを起動するとき使用します。このインタフェースは \f2com.sun.tools.javadoc.Main にあります\fP (javadoc は再入可能)。詳細は、
.na
\f2「標準ドックレット」\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/guides/javadoc/standard\-doclet.html#runningprogrammaticallyを参照してください。
.LP
\f3ドックレットの実行\fP \- 下記の説明は、標準 HTML ドックレットを呼び出すためのものです。カスタムドックレットを呼び出すには、\-doclet および \-docletpath オプションを使用します。特定のドックレットを実行した完全な例については、
.na
\f2MIF Doclet のドキュメント\fP @
.fi
http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.htmlを参照してください。
.SH "簡単な例"
.LP
javadoc は、パッケージ全体に対して実行することも、個々のソースファイルに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。次の例では、ソースファイルは \f2/home/src/java/awt/*.java にあります\fP。生成先ディレクトリは \f2/home/html です\fP。
.SS
1 つ以上のパッケージのドキュメント化
.LP
あるパッケージをドキュメント化するには、そのパッケージのソースファイル (\f2*.java\fP) を、そのパッケージと同じ名前のディレクトリ内に格納する必要があります。パッケージ名が ( \f2java.awt.color\fP のようにドットで区切られた) いくつかの識別子から構成されている場合、右側の識別子に進むたびに、その識別子がより深いサブディレクトリに対応している必要があります ( \f2java/awt/color\fP など)。 単一パッケージのソースファイルを 2 グループに分け、異なる場所にあるそのような 2 つのディレクトリツリー内にそれぞれ格納してもかまいません。ただし、その両方のディレクトリへのパスを、 \f2\-sourcepath\fP に設定する必要があります。例: \f2src1/java/awt/color\fP および \f2src2/java/awt/color\fP。
.LP
javadoc を実行するには、 \f2cd\fP を使用してディレクトリを変更するか、 \f2\-sourcepath\fP オプションを使用します。以下の例では、両方の方法について説明します。
.RS 3
.TP 2
o
\f3ケース 1 \- 1 つ以上のパッケージからの起動を再帰的に実行\fP \- この例では javadoc が任意のディレクトリから実行できるように、\-sourcepath を使用し、再帰的処理のために \-subpackages (1.4 の新オプション) を使用します。これは、 \f2java\fP ディレクトリのサブパッケージをたどりますが、その際に、 \f2java.net\fP と \f2java.lang\fP をルートに持つパッケージは除外されます。このとき、 \f2java.lang のサブパッケージ\fPである java.lang.ref も \f2除外されます\fP。
.nf
\f3
.fl
% \fP\f3javadoc \fP\f3\-d\fP\f3 /home/html \fP\f3\-sourcepath\fP\f3 /home/src \fP\f3\-subpackages\fP\f3 java \fP\f3\-exclude\fP\f3 java.net:java.lang\fP
.fl
.fi
.LP
ほかのパッケージツリーも下方にたどるには、 \f2java:javax:org.xml.sax のように、\fP それらのパッケージの名前を \-subpackages \f2の引数の末尾に追加します\fP。
.TP 2
o
\f3ケース 2 \- ルートソースディレクトリに移ってから明示的なパッケージに対して実行\fP \- 完全指定のパッケージ名の親ディレクトリに移ります。次に、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。
.nf
\f3
.fl
% \fP\f3cd /home/src/\fP
.fl
% \f3javadoc \-d /home/html java.awt java.awt.event\fP
.fl
.fi
.TP 2
o
\f3ケース 3 \- 任意のディレクトリから実行。ソースファイルは 1 つのディレクトリツリー内にある\fP \- このケースでは、現在のディレクトリがどこであってもかまいません。最上位パッケージの親ディレクトリを \f2\-sourcepath\fP に指定し、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。
.nf
\f3
.fl
% \fP\f3javadoc \-d /home/html \-sourcepath /home/src java.awt java.awt.event\fP
.fl
.fi
.TP 2
o
\f3ケース 4 \- 任意のディレクトリから実行。ソースファイルは複数のディレクトリツリー内にある\fP \- これはケース 3 と似ていますが、パッケージが複数のディレクトリツリーに存在します。それぞれのツリーのルートへのパスを \f2\-sourcepath\fP に指定し (コロンで区切る)、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。1 つのパッケージのすべてのソースファイルが、1 つのルートディレクトリの下に存在しなければならない、ということはありません。ソースパスとして指定された場所のどこかで見つかれば十分です。
.nf
\f3
.fl
% \fP\f3javadoc \-d /home/html \-sourcepath /home/src1:/home/src2 java.awt java.awt.event\fP
.fl
.fi
.RE
.LP
結果: すべてのケースでパッケージ \f2java.awt\fP および \f2java.awt.event\fP 内の public および protected クラスとインタフェースについて、HTML 形式のドキュメントが生成され、指定された生成先ディレクトリ (\f2/home/html\fP) に HTML ファイルが保存されます。2 つ以上のパッケージが生成されているので、ドキュメントは、パッケージのリスト、クラスのリスト、およびメインのクラスページという 3 つのフレームを持つことになります。
.SS
1 つ以上のクラスのドキュメント化
.LP
また、1 つ以上のソースファイル (\f2.java\fP) を渡して、Javadoc ツールを実行することもできます。javadoc は、次の 2 つの方法のいずれかで実行できます。1 つは \f2cd\fP を使用してディレクトリを変更する方法、もう 1 つは \f2.java\fP ファイルへのパスを完全に指定する方法です。相対パスは、現在のディレクトリを起点とします。ソースファイル名を渡すときは、 \f2\-sourcepath\fP オプションは無視されます。アスタリスク (*) のようなコマンド行ワイルドカードを使用すると、クラスのグループを指定できます。
.RS 3
.TP 2
o
\f3ケース 1 \- ソースディレクトリに移る\fP \- \f2.java\fP ファイルのあるディレクトリに移ります。次に、ドキュメント化する 1 つ以上のソースファイルの名前を指定して javadoc を実行します。
.nf
\f3
.fl
% \fP\f3cd /home/src/java/awt\fP
.fl
% \f3javadoc \-d /home/html Button.java Canvas.java Graphics*.java\fP
.fl
.fi
この例では、クラス \f2Button\fP と \f2Canvas\fP 、および名前が \f2Graphics で始まるクラスについて、HTML 形式のドキュメントが生成されます\fP。パッケージ名ではなくソースファイルが javadoc に引数として渡されているので、ドキュメントは、クラスのリストとメインページという 2 つのフレームを持つことになります。
.TP 2
o
\f3ケース 2 \- パッケージのルートディレクトリに移る\fP \- これは、同じルート内にある複数のサブパッケージの個々のソースファイルをドキュメント化する場合に便利です。パッケージのルートディレクトリに移り、各ソースファイルを、ルートからのパスとともに指定します。
.nf
\f3
.fl
% \fP\f3cd /home/src/\fP
.fl
% \f3javadoc \-d /home/html java/awt/Button.java java/applet/Applet.java\fP
.fl
.fi
この例では、クラス \f2Button\fP および \f2Applet について、HTML 形式のドキュメントが生成されます\fP。
.TP 2
o
\f3ケース 3 \- 任意のディレクトリから\fP \- このケースでは、現在のディレクトリがどこであってもかまいません。ドキュメント化する .java ファイルへの絶対パス (またはカレントディレクトリからの相対パス) を指定して \f2javadoc\fP を実行します。
.nf
\f3
.fl
% \fP\f3javadoc \-d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java\fP
.fl
.fi
この例では、クラス \f2Button\fP と、名前が \f2Graphics で始まるクラスについて、HTML 形式のドキュメントが生成されます\fP。
.RE
.SS
パッケージとクラスのドキュメント化
.LP
パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に前述の 2 つの例を組み合わせた例を示します。 \f2\-sourcepath\fP は、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。
.nf
\f3
.fl
% \fP\f3javadoc \-d /home/html \-sourcepath /home/src java.awt /home/src/java/applet/Applet.java\fP
.fl
.fi
.LP
この例では、パッケージ \f2java.awt\fP とクラス \f2Applet について、HTML 形式のドキュメントが生成されます\fP。Javadoc ツールは、 \f2Applet.java ソースファイル内にパッケージ宣言があれば、\fP その宣言に基づいて \f2Applet のパッケージ名を\fP 判定します。
.SH "使用例"
.LP
Javadoc ツールには多くの便利なオプションがあり、その中にはほかのオプションよりも頻繁に使われるものがあります。ここで紹介するのは、Java プラットフォーム API に対して Javadoc ツールを実行するときに使用する実際のコマンドです。ここでは、Java SE Platform, Standard Edition, v1.2 の (約) 1500 個の public および protected クラスのドキュメントを生成するために、180M バイトのメモリーを使用します。
.LP
同じ例を 2 回掲載します。最初の例はコマンド行から実行するもので、2 番目の例は Makefile から実行するものです。オプションの引数で絶対パスが使用されているため、同じ \f2javadoc\fP コマンドをどのディレクトリからでも実行できます。
.SS
コマンド行の例
.LP
次の例は、DOS などの一部のシェルでは長すぎる可能性があります。この制限を回避するには、コマンド行引数ファイルを使用します。または、シェルスクリプトを記述します。
.nf
\f3
.fl
% javadoc \-sourcepath /java/jdk/src/share/classes \\
.fl
\-overview /java/jdk/src/share/classes/overview.html \\
.fl
\-d /java/jdk/build/api \\
.fl
\-use \\
.fl
\-splitIndex \\
.fl
\-windowtitle 'Java Platform, Standard Edition 7 API Specification' \\
.fl
\-doctitle 'Java Platform, Standard Edition 7 API Specification' \\
.fl
\-header '<b>Java(TM) SE 7</b>' \\
.fl
\-bottom '<font size="\-1">
.fl
<a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit a bug or feature</a><br/>
.fl
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
.fl
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
.fl
Other names may be trademarks of their respective owners.</font>' \\
.fl
\-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \\
.fl
\-group "Extension Packages" "javax.*" \\
.fl
\-J\-Xmx180m \\
.fl
@packages
.fl
\fP
.fi
.LP
上記のコマンドで、 \f2packages\fP は、処理対象のパッケージ名 ( \f2java.applet java.lang\fP など) が入っているファイルの名前です。各オプションの、単一引用符で囲まれた引数の内側には、改行文字を挿入できません。たとえば、この例をコピー＆ペーストする場合は、 \f2\-bottom\fP オプションから改行文字を削除してください。さらに、このあとの「注」も参照してください。
.SS
Makefile の例
.LP
ここでは、GNU Makefile の例を示します。Windows の Makefile の例については、
.na
\f2Windows の Makefile の作成方法\fP @
.fi
http://java.sun.com/j2se/javadoc/faq/index.html#makefilesを参照してください。
.nf
\f3
.fl
javadoc \-\fP\f3sourcepath\fP\f3 $(SRCDIR) \\ /* Sets path for source files */
.fl
\-\fP\f3overview\fP\f3 $(SRCDIR)/overview.html \\ /* Sets file for overview text */
.fl
\-\fP\f3d\fP\f3 /java/jdk/build/api \\ /* Sets destination directory */
.fl
\-\fP\f3use\fP\f3 \\ /* Adds "Use" files */
.fl
\-\fP\f3splitIndex\fP\f3 \\ /* Splits index A\-Z */
.fl
\-\fP\f3windowtitle\fP\f3 $(WINDOWTITLE) \\ /* Adds a window title */
.fl
\-\fP\f3doctitle\fP\f3 $(DOCTITLE) \\ /* Adds a doc title */
.fl
\-\fP\f3header\fP\f3 $(HEADER) \\ /* Adds running header text */
.fl
\-\fP\f3bottom\fP\f3 $(BOTTOM) \\ /* Adds text at bottom */
.fl
\-\fP\f3group\fP\f3 $(GROUPCORE) \\ /* 1st subhead on overview page */
.fl
\-\fP\f3group\fP\f3 $(GROUPEXT) \\ /* 2nd subhead on overview page */
.fl
\-\fP\f3J\fP\f3\-Xmx180m \\ /* Sets memory to 180MB */
.fl
java.lang java.lang.reflect \\ /* Sets packages to document */
.fl
java.util java.io java.net \\
.fl
java.applet
.fl
.fl
WINDOWTITLE = 'Java(TM) SE 7 API Specification'
.fl
DOCTITLE = 'Java(TM) Platform Standard Edition 7 API Specification'
.fl
HEADER = '<b>Java(TM) SE 7</font>'
.fl
BOTTOM = '<font size="\-1">
.fl
<a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit a bug or feature</a><br/>
.fl
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
.fl
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
.fl
Other names may be trademarks of their respective owners.</font>'
.fl
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
.fl
GROUPEXT = '"Extension Packages" "javax.*"'
.fl
SRCDIR = '/java/jdk/1.7.0/src/share/classes'
.fl
\fP
.fi
.LP
Makefile の引数は、単一引用符で囲みます。
.LP
\f3注\fP
.RS 3
.TP 2
o
\-windowtitle \f2オプションを省略すると、\fP Javadoc ツールによってドキュメントタイトルがウィンドウタイトルにコピーされます。 \f2\-windowtitle\fP のテキストは基本的に \f2\-doctitle\fP のものと同じですが、HTML タグを含まない点が異なります。これは、HTML タグが raw テキストとしてウィンドウタイトル内に表示されるのを防ぐためです。
.TP 2
o
ここで行っているように \f2\-footer\fP オプションを省略すると、Javadoc ツールによってヘッダーのテキストがフッターにコピーされます。
.TP 2
o
この例では必要ありませんが、\-\f2classpath\fP と \-\f2link\fP も重要なオプションです。
.RE
.SH "トラブルシューティング"
.SS
一般的なトラブルシューティング
.RS 3
.TP 2
o
\f3Javadoc FAQ\fP \- 一般的なバグおよびトラブルシューティングのヒントは、
.na
\f2「Javadoc FAQ」\fP @
.fi
http://java.sun.com/j2se/javadoc/faq/index.html#B で参照できます。
.TP 2
o
\f3バグおよび制限事項\fP \- バグの一部は、「Important Bug Fixes and Changes」 でも参照できます。
.TP 2
o
\f3バージョン番号\fP \- 「バージョン番号」を参照してください。
.TP 2
o
\f3有効なクラスだけをドキュメント化\fP \- パッケージをドキュメント化するとき、Javadoc は、有効なクラス名で構成されているファイルのみを読み込みます。たとえば、ファイル名にハイフン「\-」を含めることで、javadoc によるファイルの解析を防ぐことができます。
.RE
.SS
エラーと警告
.LP
エラーおよび警告メッセージには、ファイル名と宣言行 (ドキュメンテーションコメント内の特定の行ではない) の行番号が含まれます。
.RS 3
.TP 2
o
\f2"error: cannot read: Class1.java"\fP Javadoc ツールはカレントディレクトリに Class1.java クラスをロードしようとしています。絶対パスまたは相対パスとともに表示されるクラス名は、この例の場合 \f2./Class1.java と同じです\fP。
.RE
.SH "環境"
.RS 3
.TP 3
CLASSPATH
Javadoc がユーザークラスのファイルを探すときに使うパスを指定する環境変数です。この環境変数は、 \f2\-classpath\fP オプションによってオーバーライドされます。ディレクトリは、次のようにコロンで区切ります。
.:/home/classes:/usr/local/java/classes
.RE
.SH "関連項目"
.RS 3
.TP 2
o
javac(1)
.TP 2
o
java(1)
.TP 2
o
jdb(1)
.TP 2
o
javah(1)
.TP 2
o
javap(1)
.TP 2
o
.na
\f2Javadoc のホームページ\fP @
.fi
http://java.sun.com/j2se/javadoc/index.jsp
.TP 2
o
.na
\f2How to Write Doc Comments for Javadoc\fP @
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
.TP 2
o
.na
\f2クラスパスの設定\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/tools/index.html#general
.TP 2
o
.na
\f2javac と javadoc がクラスを検索する方法\fP @
.fi
http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html#srcfiles (tools.jar)
.RE