." Copyright 2002-2006 Sun Microsystems, Inc.  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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

." CA 95054 USA or visit www.sun.com if you need additional information or

." have any questions.

."

.TH javadoc 1 "04 May 2009"

." Generated from HTML by html2man (author: Eric Armstrong)

.SH "名前"

javadoc \- Java API ドキュメントジェネレータ

Java ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている Javadoc の例は、Sun Solaris を使用した場合のものです。

.LP

.RE

.SH "形式"

.LP

.LP

\f4javadoc\fP\f2\ [\ \fP\f2options\fP\f2\ ]\ [\ packagenames\ ]\ [\ sourcefilenames\ ]\ [\ \-subpackages\fP\ \f2pkg1:pkg2:...\fP\f2\ ]\ [\ \fP\f2@argfiles\fP\f2\ ]\fP

.LP

.LP

引数を指定する順序は任意です。Javadoc ツールでの、処理対象の \f2.java\fP ファイルを決定する方法の詳細については、「ソースファイルの処理」を参照してください。

.LP

.RS 3

.LP

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

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

.LP

.RE

.SH " 説明"

.LP

.LP

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

.LP

.LP

Javadoc ツールは、パッケージ全体、個々のソースファイル、またはその両方に対して実行できます。javadoc ツールをパッケージ全体に対して実行する場合は、最上位ディレクトリから再帰的にたどるために \f2\-subpackages\fP を使用するか、パッケージ名の明示的なリストを渡します。個々ソースファイルに対して javadoc を実行する場合は、一連のソース (\f2.java\fP) ファイル名を渡します。具体的な例は、このドキュメントの最後に紹介します。次に、Javadoc によるソースファイルの処理について説明します。

ソースファイルの処理

.LP

.LP

Javadoc ツールは、末尾に \f2.java\fP の付いたファイル以外に、ソースファイルで説明する他のファイルも処理します。個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、どの \f2.java\fP ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。 パッケージ名を渡すほうが簡単だからです。ソースファイル名を明示的に指定しなくても、Javadoc ツールは 3 つの方法で実行できます。この方法は、(1) パッケージ名を渡す、(2) \f2\-subpackages\fP を使用する、(3) ソースファイル名にワイルドカードを使用する (\f2*.java\fP) という方法です。これらの方法を使用する場合、Javadoc ツールは、\f2.java\fP ファイルが次のすべての要件を満たしている場合にかぎり、このファイルを処理します。

.LP

.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

.LP

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

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

.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

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

索引 

.RE

.LP

.LP

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

.LP

.LP

\f3その他の処理についての詳細\fP \- Javadoc ツールは、実行するたびに 1 つの完全なドキュメントを作成します。 ドキュメントを追加生成することはできません。 つまり、Javadoc ツールの以前の実行結果を修正したり、その内容を直接組み入れたりすることはできません。ただし、前述のように、以前の実行結果に対してリンクを追加することはできます。

.LP

.LP

実装上の理由から、Javadoc ツールは、処理を実行するために java コンパイラを必要とし、java コンパイラに依存しています。Javadoc ツールは \f2javac\fP の一部を呼び出すことにより、宣言をコンパイルし、メンバーの実装は無視します。Javadoc ツールは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、その情報から HTML を生成します。さらに、Javadoc ツールは、ソースコードのドキュメンテーションコメントから、ユーザーの提供したドキュメントも取得します。

.LP

.LP

Javadoc ツールは、メソッド本体のない純粋なスタブファイルである \f2.java\fP ソースファイルに対しても、実行することができます。したがって、API の作成時には、実装を記述する前の設計の早い段階で、ドキュメンテーションコメントを記述して javadoc ツールを実行できます。

.LP

.LP

コンパイラに依存することによって、HTML 出力は、実際の実装に正確に対応します。 実際の実装は、明示的なソースコードにではなく、暗黙のソースコードに依存する場合があります。たとえば、Javadoc ツールは、\f2.class\fP ファイル内に存在するが、ソースコード内には存在しない

.na

\f2デフォルトコンストラクタ\fP @

.fi

http://java.sun.com/docs/books/jls/second_edition/html/names.doc.html#36154 (Java 言語仕様のセクション 8.6.7) をドキュメント化します。

.LP

.LP

通常、Javadoc ツールでは、ソースファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。このため、デバッグやトラブルシューティングを完了する前にドキュメントを生成できます。たとえば、Java 言語仕様によると、抽象メソッドを含むクラスは、それ自体抽象として宣言されなければなりません。このエラーを検出すると、javac コンパイラは停止しますが、Javadoc ツールは警告を出さずに処理を続行します。Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。

.LP

.LP

Javadoc ツールは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、Javadoc ツールは、ブートストラップクラス、拡張機能、またはユーザークラスにかかわらず、すべての参照クラスを検索できなければなりません。詳細は、

.na

\f2「クラスの検索方法」\fP @

.fi

http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.htmlを参照してください。通常、作成するクラスは、拡張機能としてロードするか、Javadoc ツールのクラスパス内に置く必要があります。

.LP

.SS 

Javadoc のドックレット

.LP

.LP

Javadoc ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。Javadoc ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み」ドックレットがあります。 標準ドックレットは、HTML 形式の API ドキュメントを生成します。標準ドックレットを修正またはサブクラス化することや、HTML、XML、MIF、RTF などの好みの出力形式を生成する独自のドックレットを記述することも可能です。ドックレットとその使用法については、次の項目を参照してください。

.LP

.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

.LP

\f2\-doclet\fP コマンド行オプションでカスタムドックレットが指定されていない場合、Javadoc ツールは、デフォルトの標準ドックレットを使用します。javadoc ツールには、使用されているドックレットに関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらのほかに、いくつかのコマンド行オプションが追加されます。どちらのオプションについても、このあとの「オプション」で説明します。

.LP

.SS 

関連ドキュメントおよびドックレット

.LP

.RS 3

.TP 2

o

.na

\f2Javadoc に施された機能強化\fP @

.fi

http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html \- Javadoc で追加された改良点の詳細 

.na

\f2Javadoc FAQ\fP @

.fi

http://java.sun.com/j2se/javadoc/faq/index.html \- 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法 

o

.na

\f2How to Write Doc Comments for Javadoc\fP @

.fi

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html \- ドキュメンテーションコメントの記述方法に関する Sun の規約 

o

.na

\f2Requirements for Writing API Specifications\fP @

.fi

http://java.sun.com/j2se/javadoc/writingapispecs/index.html \- Java 2 プラットフォーム仕様を記述する際に使用された標準要件。この情報は、ソースファイルのドキュメンテーションコメント形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも役立ちます。検証可能なアサーションを満たすパッケージ、クラス、インタフェース、フィールド、およびメソッドについての要件を定めています。 

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 \- ソースファイル内のドキュメンテーションコメントをチェックし、検出されたエラーや不正のレポートを生成します。Sun Doc Check ユーティリティーの一部です。Sun Doc Check ユーティリティーの一部です。 

o

.na

\f2MIF ドックレット\fP @

.fi

http://java.sun.com/javadoc/mifdoclet \- MIF、FrameMaker、PDF の書式で API ドキュメントを自動生成します。MIF は Adobe FrameMaker の交換書式です。 

.RE

.LP

.SS 

用語

.LP

.LP

\f2「ドキュメンテーションコメント」\fP、\f2「doc コメント」\fP、\f2「主説明」\fP、\f2「タグ」\fP、\f2「ブロックタグ」\fP、および\f2「インラインタグ」\fPの用語については、「ドキュメンテーションコメント」で説明します。次のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。

.LP

生成ドキュメント (generated document) 

javadoc ツールが Java ソースコード内のドキュメンテーションコメントから生成したドキュメントのことです。デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。 

名前 (name) 

Java 言語で書かれたプログラム要素の名前、つまりパッケージ、クラス、インタフェース、フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、\f2java.lang.String.equals(java.lang.Object)\fP のように完全修飾することも、\f2equals(Object)\fP のように部分修飾することもできます。 

ドキュメント化されるクラス (documented classes) 

javadoc ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。ドキュメント化するには、ソースファイルが使用可能でなければならず、ソースファイル名またはパッケージ名を javadoc コマンドに渡され、アクセス修飾子 (public、protected、package\-private または private) によってフィルタ処理されないようにしなければなりません。ドキュメント化されるクラスは、javadoc ツールの出力に組み込まれるクラス、つまり「包含クラス」とも呼ばれます。 

包含クラス (included classes) 

ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。「ドキュメント化されるクラス」 と同じ。 

除外クラス (excluded classes) 

ツールの実行によって詳細なドキュメントが生成されないクラスおよびインタフェースのことです。 

参照クラス (referenced classes) 

ドキュメント化されるクラスおよびインタフェースの定義 (実装) またはドキュメンテーションコメントの中で明示的に参照されているクラスおよびインタフェースのことです。参照の例としては、戻り値の型、パラメータの型、キャストの型、拡張されたクラス、実装されたインタフェース、インポートされたクラス、メソッド本体で使用されるクラス、@see、{@link}、{@linkplain}、{@inheritDoc} タグなどがあります。この定義は 

.na

\f21.3\fP @

http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses から変更されています。javadoc ツールを実行するときは、Javadoc のブートクラスパスおよびクラスパス内にあるすべての参照クラスをメモリーにロードする必要があります。参照クラスが見つからない場合は、「クラスが見つかりません」という警告が表示されます。Javadoc ツールは、クラスの存在とそのメンバーの完全指定の名前を判別するのに必要なすべての情報を、.class ファイルから引き出すことができます。 

外部参照クラス (external referenced classes) 

参照クラスのうち、javadoc ツールの実行中にドキュメントが生成されないクラスのことです。つまり、これらのクラスは、コマンド行で Javadoc ツールに渡されていません。生成ドキュメント内でこれらのクラスにリンクしている箇所は、「外部参照」または「外部リンク」と呼ばれます。たとえば、\f2java.awt\fP パッケージに対してだけ Javadoc ツールを実行した場合、\f2Object\fP などの \f2java.lang\fP 内のすべてのクラスが外部参照クラスになります。外部参照クラスにリンクするには、\f2\-link\fP および \f2\-linkoffline\fP オプションを使用します。外部参照クラスには、通常そのソースコメントを javadoc ツールの実行で利用できないという重要な特徴があります。この場合、それらのコメントを継承することはできません。 

.RE

.LP

.SH "ソースファイル"

.LP

.LP

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

.LP

.SS 

クラスソースコードファイル

.LP

.LP

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

.LP

.SS 

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

.LP

.LP

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

.LP

.LP

パッケージコメントファイルを作成する場合、コメントの格納先として、次の 2 つのファイルのいずれかを選択できます。

\f2package\-info.java\fP \- パッケージ宣言、パッケージ注釈、パッケージコメント、および Javadoc タグを格納できます。このファイルは JDK 5.0 で導入されたものであり、package.html よりも推奨されています。 

\f2package.html\fP \- 格納できるのはパッケージコメントと Javadoc タグだけです。 パッケージ注釈は格納できません。 

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

.LP

.LP

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

.LP

.LP

File:\f2java/applet/package\-info.java\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

..

.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

.nf

\f3

.fl

.fl

 * Provides the classes necessary to create an

.fl

.fl

.fl

.fl

.fl

.fl

.fl

.fl

.fl

.fl

.fl

.fl

.fl

.fl

.fl

\fP

.br

.di

.nr a| \n(dn

.nr a- \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

.35

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

.fc

.nr T. 1

.T# 1

.35

.rm a+

.TE

.if \n-(b.=0 .nr c. \n(.c-\n(d.-42

.LP

.LP

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

.LP

.LP

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

.LP

.LP

File:\f2java/applet/package.html\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

.nf

\f3

.fl

.fl

.fl

Provides the classes necessary to create an applet and the

.fl

.fl

.fl

.fl

.fl

.fl