'\" t
.\"
.\" Copyright 2000-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 "2006 年 9 月 4 日" "Java SE 6" "ユーザーコマンド"
.hw javadoc
.SH "名前"
javadoc \- Java API ドキュメントジェネレータ
.RS 3
.LP
.LP
Java ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている Javadoc の例は、Sun Solaris を使用した場合のものです。
.LP
.SH "形式"
.B javadoc
[
.I options
] [
.I packagenames
] [
.I sourcefilenames
] [
.I \-subpackages pkg1:pkg2:...
] [
.I @argfiles
]
.LP
.LP
引数を指定する順序は任意です。Javadoc ツールでの、処理対象の \f2.java\fP ファイルを決定する方法の詳細については、「ソースファイルの処理」を参照してください。
.TP 15
.I options
このドキュメントで指定されているコマンド行オプションです。
.B javadoc
のオプションの一般的な使用法については、「使用例」を参照してください。
.TP
.I packagenames
.BR "java.lang java.lang.reflect java.awt"
などの、スペースで区切られた
一連のパッケージ名です。ドキュメント化するパッケージごとに別個に
指定する必要があります。
.B javadoc
ツールはこれらのパッケージ名を探すとき、
.B \-sourcepath
を使用します。
.B javadoc
ツールは、サブパッケージを再帰的に処理することはありません。
アスタリスク (\f3*\f1) などのワイルドカードは使うことができません。
「1 つ以上のパッケージのドキュメント化」の
例を参照してください。
.TP
.I sourcefilenames
スペースで区切られた一連のファイル名です。パス、および
アスタリスク (\f3*\f1) などのワイルドカードを含めることができます。
.B javadoc
ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、
その拡張子を除いた名前が実際に有効なクラス名
.fi
(http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625
の
.na
「\f2Identifiers\fP」を参照) であるすべてのファイルです。
したがって、ハイフンを含む名前 (X-Buffer など) や、
その他の無効な文字を含む名前を付けることによって、
それらのファイルをドキュメント化の対象から除外できます。
これは、テスト用のファイルや、テンプレートから生成されたファイルの場合に便利です。
.B javadoc
ツールは、ソースファイル名の前に指定されたパスを使用して、
ソースファイル名を探します。この場合、
.B -sourcepath
は使用しません。たとえば、
.B Button.java
を渡すことは
.BR ./Button.java
と指定することと同じです。完全パスを付けたソースファイル名の
例は「
.BR /home/src/java/awt/Graphics*.java
」のようになります。「1 つ以上のクラスのドキュメント化」の例を
参照してください。また、「パッケージとクラスのドキュメント化」の
例のように、パッケージ名とソースファイル名を組み合わせることもできます。
.TP
.I \-subpackages pkg1:pkg2:...
指定されたパッケージ内のソースファイルからドキュメントを生成し、
再帰的にサブパッケージを処理します。 パッケージ名または
ソールファイル名を指定するための代替手段です。
.TP
.I @argfiles
Javadoc オプション、パッケージ名、およびソースファイル名を
任意の順序で並べたリストが含まれる 1 つ以上のファイルです。
このファイルの中では、ワイルドカード (*) および
.B \-J
オプションは指定できません。
.SH "機能説明"
.B javadoc
ツールは、一連の Java ソースファイルの宣言およびドキュメント
コメントを解析し、デフォルトでは public クラスと protected クラス、
入れ子クラス（匿名の内部クラスを除く）、インタフェース、コンストラクタ、メソッド、および
フィールドについて説明した一連の HTML ページを生成します。また、API (アプリケーションプログラミングインタフェース) ドキュメントの生成や、一連のソースファイルの実装ドキュメントの生成に使用できます。
.LP
.B javadoc
ツールは、パッケージ全体、個々のソースファイル、またはその両方に対して
実行できます。
.B javadoc
ツールをパッケージ全体に対して実行する場合は、最上位ディレクトリから再帰的にたどるために -subpackages を使用するか、パッケージ名の明示的なリストを渡します。
個々のクラスに対して javadoc を実行する場合は、一連の
ソース (\f3.java\f1) ファイル名を渡します。具体的な例は、
このページの最後で示します。
次に、Javadoc によるソースファイルの処理について説明します。
.LP
.SS
ソースファイルの処理
.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 の接尾辞を取り除くと、実際に有効なクラス名になっている (有効な文字については、
.fi
http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625
の
.na
「\f2Identifiers\fP」を参照)
.TP 2
o
ソースツリーのルートから相対的なディレクトリパスが、区切り文字をドットに変換すると、実際に有効なパッケージ名になっている
.TP 2
o
パッケージ文には有効なパッケージ名が含まれる (前項目で指定)
.RE
.LP
.LP
\f3リンクの処理\fP \-
実行時に、
.B javadoc
ツールはその実行の一部として記述されているパッケージ、クラス、
およびメンバの名称にクロスリファレンスリンクを自動的に
追加します。リンクは、次の箇所に現われます。
.LP
.TP 2
\(bu
宣言 (戻り値の型、引数の型、フィールドの型)
.TP 2
\(bu
@see タグから生成される [関連項目] のセクション
.TP 2
\(bu
{@link} タグから生成されるインラインテキスト
.TP 2
\(bu
@throws タグから生成される例外の名称
.TP 2
\(bu
インタフェースのメンバに対する [定義] リンクと、クラスのメンバに対する [オーバーライド] リンク
.TP 2
\(bu
パッケージ、クラス、およびメンバを記述した一覧表
.TP 2
\(bu
パッケージとクラスの継承ツリー
.TP 2
\(bu
索引
.LP
\-link と \-linkoffline オプションを使用して、
コマンド行に含まれていない、個別に生成されるクラスの既存のテキストに
ハイパーリンクを追加できます。
.LP
\f3その他の処理についての詳細\fP \-
javadoc ツールは、実行のたびにひとつの完全なドキュメントを生成します。javadoc は、
追加生成を行えません。つまり、以前に実行した javadoc の結果を変更したり、
それらを直接取り込むことはできません。しかし、前述のようにほかの
実行の結果にリンクすることは可能です。
.LP
実装上の理由から、
.B javadoc
ツールは実行に java コンパイラを必要とし、java コンパイラに依存しています。
.B javadoc
ツールは
.B javac
の一部を呼び出して、宣言をコンパイルし、メンバの実装は無視します。
.B javadoc
ツールは、クラス階層を含むクラスの豊富な内部表現、および「使用」関係を
構築し、そこから HTML を生成します。
.B javadoc
ツールは、ソースコードのドキュメンテーションコメントから、ユーザの
提供するドキュメントも取得します。
.LP
.B javadoc
ツールは、メソッド本体のない純粋なスタブファイルである
.B .java
ソースファイル上で実行されます。つまり、API の作成時には、コードを
記述する前の設計の早い段階でドキュメンテーションコメントを記述し、
.B javadoc
を実行できます。
.LP
コンパイラに依存することによって、HTML 出力が、実際の実装に正確に対応
することが保証されます。実際の実装は、明示的でなく暗黙的に
ソースコードに依存している場合があります。たとえば、
.B javadoc
ツールは、
.B .class
ファイル内には存在するが、ソースコード内には存在しない
デフォルトコンストラクタ (「Java Language Specification」のセクション 8.6.7: http://java.sun.com/docs/books/jls/second_edition/html/names.doc.html#36154)
をドキュメント化します。
.LP
多くの場合、
.B javadoc
ツールでは、ソースファイルのコードが不完全またはエラーを
含んでいる場合でもドキュメントを生成できます。
このため、デバッグやトラブルシューティングが完了する前に
ドキュメントを生成できます。 たとえば、Java 言語仕様によると、
抽象メソッドを含むクラスはそれ自体を抽象と宣言しなければなりません。
このエラーを検出すると、javac コンパイラの場合は、このエラーで
停止しますが、javadoc ツールは警告を出さずに処理を進めます。
javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。
ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、
DocCheck ドックレットを使用してください。
.LP
.B javadoc
ツールがドキュメント用の内部構造を構築するときは、参照する
クラスをすべてロードします。このため、ブートストラップクラス、
拡張機能、またはユーザクラスにかかわらず、
.B javadoc
ツールは、参照するクラスをすべて検出できなければなりません。
一般的に、作成する
クラスは、拡張機能としてロードされるか、
.BR javadoc
ツールのクラスパス内にある必要があります。
.SS "Javadoc ドックレット"
.B javadoc
ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。
.B javadoc
ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み型」
ドックレットがあり、これによって HTML 形式の API
ドキュメントを生成します。標準ドックレット
の修正やサブクラス化を行なったり、HTML、XML、MIF、RTF などの好みの
出力形式を生成する独自のドックレットを記述することも可能です。
ドックレットとその使用法については、次を参照してください。
.LP
.TP 2
\(bu
.B Javadoc
ドックレット
.TP 2
\(bu
.B -doclet
コマンド行オプション
.LP
.B -doclet
コマンド行オプションでカスタムドックレットが指定されていない場合、
.B javadoc
ツールは、デフォルトの標準ドックレットを使用します。
.B javadoc
ツールには、どのドックレットが使われているかには関係なく使用できる
コマンド行オプションがあります。標準ドックレットでは、これらの
ほかに、いくつかのコマンド行オプションが追加されます。どちらの
オプションについても、後述の「オプション」で説明します。
.SS 関連ドキュメントおよびドックレット
.TP 2
\(bu
Javadoc に施された機能強化 - Javadoc に追加された改良点の詳細
.TP 2
\(bu
Javadoc FAQ - 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法
.TP 2
\(bu
Javadoc のドキュメンテーションを作成するには - Sun で
一般的なドキュメンテーションコメントの記述方法の詳細
.TP 2
\(bu
API 仕様を記述するための要件 - Java 2 プラットフォーム仕様を記述する際に
使用された標準要件。 この情報は、ソースファイルのドキュメンテーションコメント
形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも
役立ちます。 検証可能なアサーションを満たすパッケージ、クラス、
インタフェース、フィールド、およびメソッドについての要件を定めています。
.TP 2
\(bu
ドキュメンテーションコメントの仕様 - ドキュメンテーションコメントの
オリジナル仕様については、『Java Language Specification』
(James Gosling、Bill Joy、Guy Steele 共著) の初版の
第 18 章「Documentation Comments」を参照してください。
この章は、第 2 版では削除されました。
.TP 2
\(bu
DocCheck ドックレット - ソースファイル内のドキュメンテーションコメントを検査し、
見つかったエラーや不規則な箇所を一覧にしたレポートを生成します。
これは Sun Doc チェックユーティリティの一部です。
.TP 2
\(bu
MIF ドックレット - MIF、FrameMaker、および PDF 形式での API ドキュメントの
生成を自動化します。 MIF は Adobe FrameMaker の互換形式です。
.SS "用語"
.LP
.LP
「\f2ドキュメンテーションコメント\fP」、「\f2doc コメント\fP」、「\f2主説明\fP」、「\f2タグ\fP」、「\f2ブロックタグ\fP」、および「\f2インラインタグ\fP」の用語については、「ドキュメンテーションコメント」で説明します。以下のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。
.RS 3
.TP 3
生成されるドキュメント
.B javadoc
ツールが Java ソースコード内の doc コメントから生成したドキュメント
のことです。デフォルトの生成ドキュメントは HTML 形式で、標準
ドックレットによって作成されます。
.LP
.TP 3
名前
Java 言語での名前、つまりパッケージ、クラス、インタフェース、
フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、
.BR java.lang.String.equals(java.lang.Object)
のように完全修飾することも、
.BR equals(Object)
のように部分修飾することもできます。
.LP
.TP 3
ドキュメント化されるクラス
.B javadoc
の実行によって完全なドキュメントが生成されるクラスと
インタフェースです。ドキュメント化するには、ソースファイルが
使用可能でなければならず、ソースファイル名またはパッケージ名の
どちらかを
.B javadoc
コマンドに渡さなければなりません。ドキュメント化されるクラスは、
.B javadoc
の実行で組み込まれるクラス、つまり「組み込みクラス」とも呼ばれます。
.LP
.TP 3
含まれるクラス
対応するソースファイル名またはパッケージ名が javadoc コマンドに
渡されるクラスおよびインタフェースのことです。
.LP
.TP 3
除外されるクラス
javadoc コマンドにソースファイル名またはパッケージ名が
渡されないクラスとインタフェースです。
.LP
.TP 3
参照クラス
ドキュメント化されるクラスとインタフェースの定義
(実装) またはドキュメンテーションコメント内で明示的に参照される
クラスとインタフェースです。参照の例としては、
戻り値の型、パラメータの型、キャストの型、
拡張されるクラス、実装されるインタフェース、
インポートされるクラス、メソッド本体で使用される
クラス、@see、{@link}、{@linkplain}、
および {@inheritDoc} タグなどがあります
(この定義は 1.3
.fi
(http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses)
から
変更されていることに注意)。
javadoc ツールは動作中、
.B javadoc
のブートクラスパスと
クラスパス内にある参照されているクラスを
すべてメモリにロードするためです。
参照されているクラスが見つからなかった
場合は、[クラスが見つかりません] という警告が表示されます。
.B javadoc
ツールは、クラスの存在とそのメンバの完全修飾名を決定するのに十分な情報を、
.B .class
ファイルから引き出すことができます。
.LP
.TP 3
外部参照クラス
参照されるクラスのうち、
.B javadoc
を実行してもドキュメントが生成されないクラスです。
つまり、これらのクラスは、コマンド行で
.B javadoc
ツールに渡されていません。
生成ドキュメント内でこれらのクラスにリンクしている箇所は、
「外部参照」または「外部リンク」と呼ばれます。 たとえば、
.B java.awt
パッケージに対してだけ
.B javadoc
を実行した場合、Object などの
.BR java.lang
内のすべてのクラスは、外部参照クラスになります。外部参照クラスには、
.B \-link
および
.B \-linkoffline
オプションを使ってリンクすることができます。
外部参照クラスには、通常そのソースコメントを
.B \javadoc
ツールの実行で利用できないという重要な特徴があります。
この場合、それらのコメントを継承することはできません。
.SH "ソースファイル"
.B javadoc
ツールは、クラスの Java 言語ソースファイル (\f3.java\f1)、パッケージコメントファイル、
概要コメントファイル、およびその他の処理されないファイルの 4 種類の
「ソース」ファイルを基にして、出力を生成します。また、ドキュメント化しないがソースツリーに存在する場合があるテストファイルやテンプレートについても説明します。
.SS "クラスソースコードファイル"
各クラスまたはインタフェース、およびそのメンバは、
.B .java
ファイルの中にそれ自身のドキュメンテーションコメントを
持つことができます。ドキュメンテーションコメントの詳細については、
「ドキュメンテーションコメント」の節を参照してください。
.SS "パッケージコメントファイル"
各パッケージは、独自のドキュメンテーションコメントを
持つことができ、「ソース」ファイルに保持します。
.B javadoc
ツールは、生成するパッケージの要約ページにこのコメントをマージします。
通常、このコメントには、パッケージ全体に適用される
ドキュメントを含めます。
.LP
パッケージコメントファイルを作成する場合、コメントの格納先として、次の 2 つのファイルのいずれかを選択できます。
.LP
.RS 3
.TP 2
o
\f2package\-info.java\fP \- パッケージ宣言、パッケージ注釈、パッケージコメント、および Javadoc タグを格納できます。このファイルは JDK 5.0 で導入されたものであり、package.html よりも推奨されています。
.TP 2
o
\f2package.html\fP \- 格納できるのはパッケージコメントと Javadoc タグだけです。パッケージ注釈は格納できません。
.RE
.LP
.LP
各パッケージは、単一の \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
.ft 3
.nf
/**
* Provides the classes necessary to create an
* applet and the classes an applet uses
* to communicate with its applet context.
* <p>
* The applet framework involves two entities:
* the applet 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
*/
package java.lang.applet;
.fi
.ft 1
.LP
コメント区切り文字の \f2/**\fP と \f2*/\fP は記述する必要がありますが、中間行の行頭のアスタリスクは省略してもかまいません。
.LP
.LP
\f4package.html\fP \- このファイルには、次の構造のパッケージコメントを格納できます。コメントは \f2<body>\fP 要素内に配置します。
.LP
.LP
File: \f2java/applet/package.html\fP
.LP
.LP
.ft 3
.nf
<HTML>
<BODY>
Provides the classes necessary to create an applet and the
classes an applet uses to communicate with its applet context.
<p>
The applet framework involves two entities: the applet
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
</BODY>
</HTML>
.fi
.ft 1
.LP
.LP
これは単なる通常の HTML ファイルであり、パッケージ宣言を含んでいない点に注意してください。パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に HTML で記述されています。ただし、ほかのコメントと異なる点が 1 つだけあります。それは、このドキュメンテーションコメントには、コメント区切り文字である \f2/**\fP と \f2*/\fP、および行頭のアスタリスクを含めてはならない、ということです。コメントを書く場合は、最初の文をパッケージの概要とし、\f2<body>\fP と最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージタグを含めることはできますが、ほかのドキュメンテーションコメントと同様、全てのブロックタグは説明のあとに置かなければなりません。パッケージコメントファイルに \f2@see\fP タグを追加する場合は、完全指定の名前を使用する必要があります。詳細は、
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#packagecomments
の
.na
「\f2example of \fP\f2package.html\fP」を参照してください。
.LP
.LP
\f3パッケージコメントファイルの処理\fP \- Javadoc ツールは、実行時にパッケージコメントファイルを自動的に検索し、このファイルを見つけると次の処理を行います。
.LP
.RS 3
.TP 2
o
処理できるようにコメントをコピーする (\f2package.html\fP の場合であれば、\f2<body>\fP と \f2</body>\fP HTML タグの間にある内容をすべてコピーする。\f2<head>\fP を含め、そこに \f2<title>\fP やソースファイルの著作権記述などの情報を配置することもできるが、生成後のドキュメンテーションにはそれらは一切表示されない)
.TP 2
o
パッケージタグがあれば、すべて処理する
.TP 2
o
生成したパッケージの概要ページの最後に、処理したテキストを挿入する (例: パッケージの概要)
.TP 2
o
パッケージの概要ページの先頭に、パッケージコメントの最初の文をコピーする。さらに、概要ページのパッケージリストに、パッケージ名とパッケージコメントの最初の文を追加する (例: 概要の要約)。文の末尾は、クラスやメンバの主説明の最初の文の末尾と同じ規則によって判断される
.RE
.LP
.SS "概要コメントファイル"
ドキュメント化する各アプリケーションまたはパッケージのセットは、
独自の概要ドキュメンテーションコメントを持つことができ、それは
「ソース」ファイルに保持されます。
.B javadoc
ツールは、生成する概要ページにこのコメントをマージします。通常、この
コメントには、アプリケーションまたはパッケージのセット全体に
当てはまるドキュメントを含めます。
.LP
概要コメントファイルを作成する場合、ファイルに好きな名前を付けて、
好きな場所に置くことができますが、通常はファイル名を
.B overview.html
にして、ソースツリーの一番上の階層に置きます。
たとえば、
.B java.applet
パッケージのソースファイルが
.B /home/user/src/java/applet
ディレクトリに含まれているとすると、
.BR /home/user/src/overview.html
に概要コメントファイルを作成することができます。
.LP
異なるパッケージのセットに対して javadoc を複数回実行する場合は、同じ 1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。
たとえば、内部ドキュメンテーション用に \-private を指定して javadoc を 1 回実行したあと、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメントファイルの 1 文目で、そのドキュメンテーションを公開用または内部用として記述できます。
.LP
概要コメントファイルの内容は、前に述べたパッケージコメントファイルと
同様、HTML で記述された 1 つの大きなドキュメント
コメントです。詳細は、前述の説明を参照してください。繰り返しに
なりますが、このコメントを書く場合は、最初の文をアプリケーション
またはパッケージのセットの要約にし、
.B <body>
と最初の文の間にタイトルまたはその他のテキストを含めてはなりません。
概要タグを含めることができます。どのドキュメンテーションコメントに
ついても、{\f3@link\f1}
以外のタグは、説明のあとに置く必要があります。
.B @see
タグを追加する場合は、完全指定の名前を使用する必要があります。
.LP
.BR javadoc
ツールの実行時に、
.B \-overview
オプションを使って概要コメントファイル名を指定します。ファイルは、
パッケージコメントファイルと同じように処理されます。
.TP 2
\(bu
.B <body>
タグと
.B </body>
タグとの間にあるすべての内容を処理のためにコピーする
.TP 2
\(bu
存在する概要タグを処理する
.TP 2
\(bu
概要の要約などの Javadoc が生成する概要ページの最後に、
処理されたテキストを挿入する
.TP 2
\(bu
概要ページの先頭に、概要コメントの最初の文をコピーする
.SS "その他の処理されないファイル"
ソースには、
.B javadoc
ツールで生成先のディレクトリにコピーする、その他の任意のファイルを
含めることができます。一般に、このようなファイルには、
サンプルのグラフィックファイル、Java ソース
(\f3.java\f1) およびクラス (\f3.class\f1) ファイル、内容が
通常の Java ソース
ファイルのドキュメンテーションコメントの影響を受けない
独立した HTML ファイルなどがあります。
.LP
処理されないファイルを含めるには、それらのファイルを
.BR doc-files
というディレクトリに置きます。このディレクトリは、任意のパッケージ
ディレクトリの下に作成できます。パッケージごとにこのようなサブ
ディレクトリを 1 つ持つことができます。このサブディレクトリには、
イメージ、サンプルコード、ソースファイル、
.B .class
ファイル、アプレット、および HTML ファイルを入れることができます。
たとえば、ボタンの画像
.B button.gif
を
.B java.awt.Button
クラスドキュメントに含めたい場合は、そのファイルを
.B /home/user/src/java/awt/doc-files/
ディレクトリに置きます。
.BR doc-files
ディレクトリを
.B /home/user/src/java/doc-files
に置くことはできません。これは、
.B java
はパッケージではなく、そのディレクトリそのものにソースファイルが
入っていないからです。
.LP
これらの処理されないファイルへのリンクは
すべて明示的に記述する必要があります。これは、
.B javadoc
ツールがファイルを見ずに、単にディレクトリとその内容物を生成先に
コピーするだけだからです。たとえば、
.B Button.java
ドキュメンテーションコメント内のリンクは、次のようになります。
.LP
.ft 3
.nf
/**
* This button looks like this:
* <img src="doc-files/Button.gif">
*/
.fi
.ft 1
.SH "テストファイルおよびテンプレートファイル"
一部の開発者から、テストファイルおよびテンプレートファイルを
対応するソースファイルの近くのソースツリーに保存したいという要望がありました。
つまり、これらのソースファイルと同じディレクトリまたはサブディレクトリに
保存したいということです。
.LP
個別のソースファイル名で明示的に渡して
.B Javadoc
ツールを実行する場合は、
テストファイルおよびテンプレートファイルを意図的に除外して、
処理されないようにすることができます。ただし、パッケージ名または
ワイルドカードで渡す場合は、以下のルールに従って、これらのテストファイル
およびテンプレートファイルが
処理されないようにする必要があります。
.LP
テストファイルとテンプレートファイルの違いは、
テストファイルは、正当でコンパイル可能なソースファイルであるのに対して、
テンプレートファイルは、そうではないという点です。ただし、
テンプレートファイルも「.java」で終わることができます。
.TP
テストファイル \-
開発者の多くは、あるパッケージのコンパイル可能で実行可能な
テストファイルをそのパッケージのソースファイルと同じ
ディレクトリに配置したいと考えています。
しかしテストファイルは、名前なしパッケージなど、
ソースファイルパッケージとは別のパッケージに属させたいとも
考えています (そのため、テストファイルには package ステートメントがないか、
またはソースとは別の package ステートメントがあります)。
このような状況では、コマンド行で指定されているソースのパッケージ名を指定して
そのソースがドキュメント化されているときに、
テストファイルは警告またはエラーを引き起こします。
そのようなテストファイルはサブディレクトリに配置する必要があります。
たとえばソースファイルのテストファイルを
.B com.package1
に追加する場合は、それらのテストファイルを、ハイフンが含まれるため
パッケージ名としては無効になる
サブディレクトリに配置します。
.LP
.RS 5
com/package1/test-files/
.RE
.LP
こうすると、
.B Javadoc
ツールでは警告なしで
test ディレクトリをスキップします。
.LP
テストファイルに doc コメントが含まれる場合、
次のようにワイルドカードを含んだテストソースファイル名で渡して
テストファイルのドキュメントを生成するように、
.B Javadoc
ツールを別個に実行できるように設定できます。
\f2com/package1/test\-files/*.java\fP.
.TP
ソースファイルのテンプレート\-
テンプレートファイルの名前は「.java」で終わることもありますが、
テンプレートファイルはコンパイルできません。
ソースディレクトリに保持したいソースファイルの
テンプレートがある場合は、
このファイル名にハイフン (Buffer-Template.java など) や
その他の不正な Java 文字を使用します。
こうすることで、処理されないようになります。
これは、
.B Javadoc
ツールが処理するのは、「.java」接尾辞を除いた名前が
正規のクラス名であるソースファイルだけであるためです (「識別子」http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625 参照)。
.SS "生成されるファイル"
デフォルトでは、
.B javadoc
は、HTML 形式のドキュメントを生成する標準ドックレットを
使います。
このドックレットは、以下の種類のファイルを生成します。以下の
各 HTML「ページ」は、それぞれ別のファイルに対応します。
.B javadoc
が生成するファイルの名前には、クラスやインタフェースの名前に
ちなんだものと、そうでないもの (\f3package-summary.html\f1 など)
の 2 種類があります。後者のグループには、前者のグループの名前と
ファイル名が競合しないように、ハイフンが含まれています。
.SS "基本内容ページ"
.TP 2
\(bu
ドキュメント化する各クラスまたは各インタフェースに対し、1 つのクラス
ページまたはインタフェースページ (\f3classname.html\f1)
.TP 2
\(bu
ドキュメント化する各パッケージに対し、1 つのパッケージ
ページ (\f3package-summary.html\f1)。
.B javadoc
ツールによって、ソースツリーのパッケージディレクトリ内の
.B package.html
または
package\-info.java
というファイル内のすべての HTML テキストが含められる
.TP 2
\(bu
パッケージのセット全体に対して 1 つの概要
ページ (\f3overview-summary.html\f1)。これは、生成される
ドキュメントの先頭ページになる。
.B javadoc
ツールによって、
.B -overview
オプションで指定されたファイル内のすべての HTML テキストが含められる。
このファイルが作成されるのは、
.B javadoc
に 2 つ以上のパッケージ名を渡した
場合だけであることに注意する。詳細は、以下の「HTML フレーム」節を参照
.SS "相互参照ページ"
.TP 2
\(bu
パッケージのセット全体に対して 1 つのクラス階層ページ
(\f3overview-tree.html\f1)。これを表示するには、ナビゲーション
バーの [概要] をクリックしてから、[階層ツリー] をクリックする
.TP 2
\(bu
各パッケージに対して 1 つのクラス階層
ページ (\f3package-tree.html\f1)。
特定のパッケージページ、クラスページ、またはインタフェースページを
表示し、[階層ツリー] をクリックすると、そのパッケージの階層が
表示される
.TP 2
\(bu
各パッケージに対して 1 つの [使用]
ページ (\f3package-use.html\f1)と、
各クラスおよびインタフェースに対して別に 1 つの [使用]
ページ(\f3class-use/classname.html\f1)。このページは、特定のクラス、
インタフェース、またはパッケージのなんらかの部分を使っている
パッケージ、クラス、メソッド、コンストラクタ、およびフィールドを
記述する。クラスまたはインタフェース A について考えると、
その[使用] ページには、A のサブクラス、A として宣言された
フィールド、A を返すメソッド、A 型のパラメータを持つメソッド
およびコンストラクタが表示される。このページには、パッケージ、
クラス、またはインタフェースに移動してから、ナビゲーションバー
の [使用] リンクをクリックすることによってアクセスできる
.TP 2
\(bu
非推奨 API ページ (\f3deprecated-list.html\f1)。推奨されない
名前すべての一覧が含まれている (非推奨名は、通常は改良された API が
存在するために使用が推奨されていない API の名前で、たいていはそれに
置き換わる名前が提示されている。非推奨 API は、将来の実装では
削除される可能性がある)
.TP 2
\(bu
定数フィールド値ページ (\f3constant-values.html\f1) 。
static フィールドの値が表示される。
.TP 2
\(bu
直列化形式ページ (\f3serialized-form.html\f1)。直列化可能クラス
および外部化可能クラスの情報用。これらの各クラスには、直列化
フィールドおよびメソッドに関する説明がある。これらの情報は、API を
使う開発者ではなく、再実装者に必要な情報である。ナビゲーションバーに
リンクがない場合、任意の直列化されたクラスに移動して、
クラスの [関連項目] セクション内の [直列化された形式] をクリック
するとこの情報を取得できる
標準ドックレットは、直列化された形式のページを自動的に生成する。
ここには、Serializable を実装する public または非 public の
クラスが組み込まれており、さらに、
.B readObject
メソッド、
.B writeObject
メソッド、直列化されたフィールド、
および @serial タグ、@serialField タグ、@serialData タグからの
ドキュメンテーションコメントが組み込まれている。
直列化が可能な public クラスを除外するには、
そのクラスまたはそのクラスが属するパッケージを @serial exclude タグで
指定する。直列化が可能な package private クラスを含めるには、
そのクラスまたはそのクラスが属するパッケージを @serial include タグで
指定する。 1.4 では、
\-private
オプションを指定せずに javadoc を実行することで、public クラスおよび
private クラスに完全な直列化形式を生成することができる。
.TP 2
\(bu
索引 (\f3index-*.html\f1)。すべてのクラス名、
インタフェース名、コンストラクタ名、フィールド名、およびメソッド名を
アルファベット順に並べてある。索引は、Unicode を扱えるように
国際化されており、1 つのファイルとして生成するか、または先頭
文字 (英語の場合 A から Z) ごとに別のファイルとして生成できる
.SS "サポートファイル"
.TP 2
\(bu
ヘルプページ (\f3help-doc.html\f1)。ナビゲーションバーおよび
上記のページについて説明する。
.BR \-helpfile
を使って、デフォルトの
ヘルプファイルに置き換わる独自のカスタムヘルプファイルを提供する
こともできる
.TP 2
\(bu
1 つの
.B index.html
ファイル。表示用 の HTML フレームを作成する。このファイルは、
フレーム付きの最初のページを表示する場合にロードする。このファイル
自体は、テキスト内容を含まない
.TP 2
\(bu
複数のフレームファイル (\f3*-frame.html\f1)。パッケージ、クラス、
およびインタフェースの一覧を含む。HTML フレームを表示するときに
使われる
.TP 2
\(bu
パッケージリストファイル (\f3package-list\f1)。
.B \-link
オプションおよび
.B \-linkoffline
オプションで使われる。これは、HTML ファイルではなくテキストファイル
のため、リンクではアクセスできない
.TP 2
\(bu
スタイルシートファイル (\f3stylesheet.css\f1)。生成されるページ上に
表示される限られた色数、フォントファミリ、フォントサイズ、フォントの
スタイルおよび配置を制御する
.TP 2
\(bu
コピー先ディレクトリにコピーしたいファイル (イメージ、サンプル、
ソースファイルなど) が入っている doc ファイルのディレクトリ。
.B javadoc
ツールはこのようなファイルを処理しない。つまり、このようなファイル内の
.B javadoc
タグはすべて無視される。ソースツリーに存在しない限り、この
ディレクトリは生成されない
.SS "HTML フレーム"
.B javadoc
ツールは、下の図に示すように、2 つか 3 つの HTML フレームを生成します。
1 つのパッケージしかない場合 (またはパッケージがない場合) は、パッケージの一覧を省略することによって最低限必要な数のフレームを作成します。
ソースファイル (*\f3.java\f1) または単一のパッケージ名を引数として
.B javadoc
コマンドに渡す場合は、左側の列にクラスの一覧を表示する
フレーム (C) 1 つだけが作成されます。
.B javadoc
に複数のパッケージ名を渡す場合は、概要ページ (Detail) に加えて、
すべてのパッケージの一覧を表示する第 3 のフレーム (P) が
作成されます。この概要ページのファイル名は
.BR overview-summary.html
です。したがって、このファイルが作成されるのは、2 つ以上のパッケージ
名を渡した場合だけです。[フレームなし] リンクをクリックするか、
.BR overview-summary.html
から表示するようにすると、フレームを省略できます。
.LP
HTML フレームに慣れていない場合は、フレームには、印刷および
スクロール用の「フォーカス」が必要であることに注意する
必要があります。フレームにフォーカスを与えるには、そのフレームを
クリックします。すると、多くのブラウザでは、矢印キーおよびページキー
を使ってそのフレームをスクロールしたり、[印刷] メニュー
コマンドを使ってそのフレームを印刷したりできるようになります。
.LP
.ft 3
.nf
------------ ------------
|C| Detail | |P| Detail |
| | | | | |
| | | |-| |
| | | |C| |
| | | | | |
| | | | | |
------------ ------------
javadoc *.java javadoc java.lang java.awt
.fi
.ft 1
.LP
HTML フレームが必要かどうかによって、次のどちらかのファイルを
開始ページとしてロードします。
.LP
.TP 2
\(bu
.B index.html
(フレームあり)
.TP 2
\(bu
.B overview-summary.html
(フレームなし)
.SS "生成されるファイル構造"
生成されるクラスファイルおよびインタフェースファイルは、Java ソース
ファイルおよびクラスファイルと同じディレクトリ階層で組織
されます。この構造は、1 つのサブパッケージにつき 1 つのディレクトリ
で構成されます。
.LP
たとえば、
.B java.applet.Applet
クラスに対して生成されるドキュメントは、
.BR java/applet/Applet.html
に格納されます。生成先のディレクトリの名前が apidocs だと
すると、java.applet パッケージのファイル構造もこれに従います。
前述したように、「frame」という語を名前に含むファイルは、
すべて左上または左下のフレームに表示されます。それ
以外の HTML ファイルは、すべて右側のフレームに表示されます。
.LP
注: ディレクトリは、太字 (bold) で示してあります。
アスタリスク (*) は、
.B javadoc
への引数がパッケージ名でなくソースファイル名 (*\f3.java\f1) の
ときに、省略されるファイルおよびディレクトリを示しています。また、
引数がソースファイル名のときには、
.B package-list
は作成されますが、空です。
.B doc-files
ディレクトリは、ソースツリー内に存在しない限り、生成先に表示されません。
.LP
.RE
.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
.LP
.SS "生成される API 宣言"
javadoc ツールは、各クラス、インタフェース、フィールド、コンストラクタ、
およびメソッドの説明の初めで宣言を生成します。
この宣言は、その API 項目の宣言です。たとえば、
ブール型クラスの宣言は次のようになります。
.LP
.LP
\f2public final class Boolean\fP
.br
\f2extends Object\fP
.br
\f2implements Serializable\fP
.LP
.LP
Boolean.valueOf メソッドの宣言は次のようになります。
.LP
.LP
\f2public static Boolean valueOf(String s)\fP
.LP
.LP
javadoc ツールは修飾子
.BR public
、
.BR protected
、
.BR private
、
.BR abstract
、
.BR final
、
.BR static
、
.BR transient
、
および
.BR volatile
を組み込むことができますが、
.BR synchronized
と
.BR native
は組み込むことができません。
.BR synchronized
と
.BR native
修飾子は実装の詳細と見なされ、API 仕様の一部とは見なされません。
.LP
キーワード
.BR synchronized
に依存するよりも、「複数のスレッドによって単一の
.BR Enumeration
を並行して使用してはならない」というように、並行処理のセマンティックスを
コメント説明の中でドキュメント化するべきです。ドキュメントでは、
これらのセマンティックスの達成方法を説明すべきではありません。別の
例を挙げると、
.BR Hashtable
はスレッドに対して安全でなければなりませんが、エクスポートされるその
メソッドすべてを同期させることによってこれを実現すると明記する必要
はないということです。バケットレベルで内部的に同期をとる権限を留保して、
より高度な並行性を提供すべきです。
.LP
.SH "ドキュメンテーションコメント"
.LP
.LP
オリジナルの「ドキュメンテーションコメントの仕様」は、「関連項目」を参照してください。
.LP
.SS
ソースコードへのコメントの挿入
.LP
.LP
ソースコードの任意の宣言 (クラス、インタフェース、メソッド、コンストラクタ、
またはフィールド) の前に、ドキュメンテーションコメント (doc コメント)
を記述することができます。 各パッケージにドキュメンテーションコメントを
作成でき、構文は若干異なりますが、概要にもドキュメンテーションコメントを
作成できます。 ドキュメンテーションコメントは、Javadoc コメントとも呼ばれます。
ドキュメンテーションコメントは、コメントの始まりを示す文字列
.B /**
と、コメントの終わりを示す文字列
.B */
の間にある文字で構成されます。 行頭のアスタリスクは、各行に記述できます。詳細は、以下で説明します。 Linux ではテキストは、複数行にわたって記述できます。
.LP
.RS
.ft 3
.nf
/**
* This is the typical format of a simple documentation comment
* that spans two lines.
*/
.fi
.ft 1
.RE
.LP
次のように、コメントは 1 行にまとめることもできます。
.LP
.RS
.ft 3
.nf
/** This comment takes up only one line. */
.fi
.ft 1
.RE
.LP
コメントの配置 - ドキュメンテーションコメントが認識されるのは、クラス、
インタフェース、コンストラクタ、メソッド、またはフィールド
宣言の前に置かれた場合だけです (クラス、メソッド、およびフィールドの
例を参照)。メソッドの本体に置かれたドキュメント
コメントは無視されます。
.B javadoc
ツールは、宣言文ごとに 1 つのドキュメンテーションコメントだけを
認識します。
.LP
よく発生する間違いは、重要な文をクラスコメントとクラス宣言の間に
入れてしまうことです。
.B javadoc
はクラスコメントを無視するため、注意してください。
.LP
.RS
.ft 3
.nf
/**
* This is the class comment for the class Whatever.
*/
import com.sun; // MISTAKE - Important not to put statements here
public class Whatever {
}
.fi
.ft 1
.RE
.LP
コメントの説明のあとにタグが続く - コメントの開始区切り文字である
.B /**
のあとからタグセクションまでが説明になります。 タグセクションは、
先頭文字が
.B @
である行から始まります (行の先頭のアスタリスクおよび空白文字
は除く)。 説明を記述せず、コメントだけのタグを記述することもできます。
説明は、タグセクション以降に続けることはできません。
タグの引数は複数の行にまたがって記述できます。 タグの数に
制限はありません。何回も記述できるタグと、1 回しか記述できない
タグがあります。 次の例の
.B @see
からタグセクションが始まります。
.LP
.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
.LP
標準タグとインラインタグ: タグは、javadoc ツールが処理できる、
doc コメント内の特別なキーワードです。javadoc ツールには、@tag として現れる
標準タグと、中括弧内に
.B {\f3@tag\f1}
として現れるインラインタグがあります。解釈
させるためには、先頭のアスタリスク、空白、コメント区切り文字 (/**) を
除いては標準タグが行の先頭であるように配置する必要があります。つ
まり、ユーザはテキスト内の任意の位置で @ 文字を使用でき、
この文字はタグの始めとは解釈されません。@ 文字で行を開
始してこれが解釈されないようにしたい場合は、HTML エンティティの
@ を使用してください。各スタンドアロンタグには関連するテキストがあり
ます。これは、そのタグの後から次のタグの直前まで、または doc コメント
の最後までの任意のテキストです。関連付けられたテキストは、
複数行にまたがって記述できます。
インラインタグは、そのテキストが許
可される位置にはどこでも指定でき、解釈の対象となります。次の例は、
標準タグ
.BR @deprecated
とインラインタグ
.BR {@link}
が含まれています。
.LP
.RS
.ft 3
.nf
/**
* @deprecated As of JDk 1.1, replaced by {@link #setBounds(int,int,int,int)}
*/
.fi
.ft 1
.RE
.LP
コメントは HTML で記述します。テキストは HTML で
記述しなければなりません。
これは、HTML のエンティティを使う必要があること、
および HTML タグを使用できること
を意味します。HTML は、使用するブラウザがサポートする
任意のバージョンを使うことが
できます。標準ドックレットは、階層式スタイルシートと
フレームを含むほかの部分 (ドキュメンテーションコメント
以外) は、HTML 3.2 に準拠したコードを生成するように記述
されています
(フレームセット対応のため、生成される各
ファイルは、「HTML 4.0」で始まる)。
.LP
たとえば、より小さい (<) およびより大きい (>) という
記号は、
.B <
と
.BR >
と記述する必要があります。同様に、アンパサンド (&) は、
.BR &
と記述する必要があります。次の例で
は、ボールドの HTML タグ <b> を示します。
.LP
次に doc コメントを示します。
.LP
.RS
.ft 3
.nf
/**
* This is a <b>doc</b> comment.
* @see java.lang.Object
*/
.fi
.ft 1
.RE
.LP
行頭のアスタリスク -
.B javadoc
は、doc コメントを解析するときに、各行の先頭にある
文字アスタリスク (*) をすべて破棄し
ます。また、最初のアスタリスク (*) より前の空白と
タブも破棄します。1.4 からは、行頭のアスタリスクを省略した場合、行頭の空白は削除されません。これにより、<PRE> タグの中の doc コメントに、サンプルコードをインデントを残したままで直接ペーストすることができます。空白は一般的に、タブよりも均一にブラウザで解釈されます。インデントは、区切り文字 /** や <PRE> タグではなく、左マージンに相対的です。
.LP
最初の文 - 各 doc コメントの最初の文は、宣言されている
エンティティに関する簡潔かつ完全
な説明を含む要約文でなければなりません。
この文は、空白、タブ、または行末記
号が続いている最初のピリオド、あるいは最初のスタンドアロンタグで終了します。
.B javadoc
ツールは、HTML ページの最初にあるメンバ要約に、この最初の文をコピーします。
.LP
複数フィールドの宣言 -
.B java
では、単一の文で複数のフィールドを宣言できます。
しかし、この文のドキュメンテ
ーションコメントは 1 つだけで、このコメントが
すべてのフィールドにコピーされます。
したがって、フィールドごとに個々の
ドキュメンテーションコメントを付けたい場合は、
各フィールドを異なる文で宣言しなければなりません。
たとえば、次のドキュメンテー
ションコメントは単一の宣言としては意味を成さず、
2 つの宣言として処理するべき
です。
.LP
.RS
.ft 3
.nf
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this
.fi
.ft 1
.RE
.LP
.B javadoc
ツールは、上記コードから次のドキュメントを生成します。
.LP
.RS
.ft 3
public int x
.fi
.ft 1
The horizontal and vertical distances of point
(x,y).
.ft 3
.nf
public int y
.fi
.ft 1
The horizontal and vertical distances of point
(x,y).
.RE
.LP
ヘッダタグを使用するときは注意してください。
メンバ用のドキュメントコ
メントを書くときは、
.B <H1>
や
.BR <H2>
などの HTML ヘッダタグを使用しないでください。これは、
.B javadoc
が全ドキュメントを構造化して生成するため、
これらの構造化タグを使用すると、
ドキュメントの書式が乱れる可能性があるためです。
しかし、クラスやパッケージの
コメントでは、これらのヘッダタグを使用して構造化を指示してください。
.LP
メソッドコメントの自動コピー
.LP
.LP
Javadoc ツールには、次の 2 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラスは、ドキュメンテーションコメントを継承しません。
.LP
.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その例外が宣言されている場合にかぎり\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
.LP
ドキュメンテーションコメントを実際にコピーに利用するには、継承したメソッドのソースファイルが \-sourcepath で指定したパスだけに置かれていることが必要になります。コマンド行で、クラスもパッケージも渡す必要はありません。この点は、クラスが ドキュメント化されるクラスでなければならなかった 1.3.x 以前のリリースと異なります。
.LP
.LP
\f3クラスおよびインタフェースからの継承\fP \- クラスおよびインタフェースから継承する次の 3 つの場合に、コメントの継承が行われます。
.LP
.RS 3
.TP 2
o
クラスのメソッドがスーパークラスのメソッドをオーバーライドしている
.TP 2
o
インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドしている
.TP 2
o
クラスのメソッドがインタフェースのメソッドを実装している
.RE
.LP
.LP
最初の 2 つのケース (メソッドがオーバーライドしている場合) では、
.B javadoc
ツールは、オーバーライドしているメソッドのドキュメント内に
「オーバーライド」という小見出しを生成し、コメントが継承されているかどうかにかかわらず、オーバーライドされている
メソッドへのリンクを書き込みます。
.LP
3 つ目のケース (特定のクラスのメソッドがインタフェースの
メソッドを実装している場合) では、
.B javadoc
ツールは、実装している
メソッドのドキュメント内に「定義」という小見出しを生成し、コメントが継承されているかどうかにかかわらず、
実装されているメソッドへのリンクを書き込みます。
.LP
メソッドの説明が継承されるアルゴリズム - あるメソッドに
ドキュメンテーションコメントが記述されていない場合、または {@inheritDoc} タグがある場合、
.B javadoc
ツールは、次のようなアルゴリズムを使用して適切なコメントを検索します。
このアルゴリズムは、もっとも適切なドキュメンテーションコメントを
検索できるように設計されており、スーパークラスよりも
インタフェースが優先されるようになっています。
.TP 4
1.
直接に実装されている (または、拡張されている) インタフェースを、
メソッドの宣言で implements (または extends) キーワードのあとに
登場する順序で、1 つずつ調べる。 このメソッドについて
最初に見つかったドキュメンテーションコメントを採用する
.TP 4
2.
手順 1 でドキュメンテーションコメントが見つからなかった場合は、
直接実装されている (または、拡張されている) インタフェースの
それぞれに対して、このアルゴリズム全体を再帰的に適用する (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ)
.TP 4
3.
手順 2 でドキュメンテーションコメントが見つからなかった場合で、
このクラスが Object 以外のクラスである (インタフェースではない) 場合は、
次のように処理する
.sp 1n
.nf
.ft 3
a. スーパークラスにこのメソッドについてのドキュメンテーションコメントが記述されていれば、そのコメントを採用する
b. 手順 3a でドキュメンテーションコメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を適用する
.ft 1
.fi
.LP
.SS "javadoc のタグ"
.LP
.B javadoc
ツールは、
.B java doc
コメント内に埋め込まれた特殊なタグを解析します。これらの
特殊な doc タグを使うと、
書式の整った完全な API ドキュメントをソース
コードから自動的に生成できます。
タグは、単価記号 (\f3@\f1) で始まり、大文字小文字が
区別されます。これらのタグは、
以下に示すとおりに、大文字と小文字を区別して入力する
必要があります。タグは、行
の先頭 (ただし先行する空白と省略可能なアスタリスクは除く) から
始めなければなり
ません。慣習上、同じ名前のタグは 1 個所にまとめて記述します。
たとえば、
.B @see
タグが複数ある場合は、すべてを 1 個所にまとめて記述します。
.LP
タグは次の 2 種類あります。
.LP
\(bu
スタンドアロンタグ - 説明のあとのタグセクションだけに
置くことができます。 このタグは、@tag のように中括弧で囲みません。
.LP
\(bu
インラインタグ - コメントの説明内またはスタンドアロンタグの
コメント中の任意の場所に置くことができます。 インラインタグは、{@tag} の
ように中括弧で囲みます。
.LP
今後のリリースで導入されるタグについては、
.fi
http://java.sun.com/j2se/javadoc/proposed\-tags.html
の
.na
「\f2Proposed Tags\fP」を参照してください。
.LP
.LP
現時点で有効なタグは、次のとおりです。
.LP
.RS 3
.LP
.LP
.TS
center;
cbp-1 cbp-1
l l.
タグ 導入された JDK/SDK のバージョン
@author 1.0
{@code} 1.5
{@docRoot} 1.3
@deprecated} 1.0
@exception 1.0
{@inheritDoc} 1.4
{@link} 1.2
{@linkplain} 1.4
{@literal} 1.5
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
{@value} 1.4
@version 1.0
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-42
.LP
.LP
カスタムタグについては、\-tag オプションを参照してください。
.TP
.BI @author " name-text"
.B \-author
オプションが使われている場合、
生成されるドキュメントに、指定された
name-text を持つ Author エントリを追加します。
1 つの doc コメントに複数の
.B @author
タグを含めることができます。
.B @author
タグごとに 1 つ、またはタグごとに複数の名前を
指定できます。前者の場合は、
.B javadoc
ツールは、名前と名前の間にコンマ (\f3,\f1) とスペースを挿入します。
後者の場合、テキスト全体が
解析されることなく生成されるドキュメントにコピーされるだけです。
このため、コンマ以外
の現地仕様の名前区切り文字を使う場合は、1 行に複数の名前を指定します。
.LP
詳細については、「タグを使用できる場所」および
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@author
の
.na
\f2@author タグのドキュメント\fPを参照してください。
.LP
.TP 3
@deprecated\ deprecated\-text
.RS 3
.LP
.LP
注: JDK 5.0 から、@Deprecated 注釈を使って特定のプログラム要素を非推奨にできるようになりました。
.LP
この API は (動作はするが) 使用すべきでないことを示す
コメントを追加します。
.B javadoc
は、deprecated-text を説明の前に移動してイタリックにし、
その前にボールドの警告
「推奨されません。」を追加します。このタグはすべての doc コメント (概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、フィールド) で有効です。
.LP
.RS
deprecated-text の最初の文では、少なくともユーザにどのようなときに
その API が推奨されないか、およびそれに代わる API を提示する
必要があります。
.B javadoc
は、最初の文だけを要約セクションと索引にコピーします。
あとに続く文で、なぜその API が推奨されないかを
説明することもできます。代わりの API を
指し示す {\f3@link\f1} タグ (
.B javadoc
1.2 以降の場合) を含める必要があります。
.LP
詳細については、
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@deprecated
の
.na
\f2@deprecated タグのドキュメント\fPを参照してください。
.LP
.TP 2
\(bu
.B javadoc
1.2 以降では、{\f3@link\f1} タグを使用してください。これにより、
必要な場所にインラインで
リンクが作成されます。たとえば、次のように使います。
.LP
.RS
.ft 3
.nf
/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int,int,int,int)}
*/
.fi
.ft 1
.RE
.LP
.TP 2
\(bu
.B javadoc
1.1 では、各
.B @deprecated
タグに
.B @see
タグ (インラインにできない) を作成するのが標準の形式です。
.LP
推奨されないタグについての詳細は、「
.B @deprecated
タグ」 を参照してください。
.RE
.TP
.B {@code text}
<code>{@literal}</code> と同等です。
.LP
テキストを HTML マークアップまたは
入れ子になった javadoc タグとして解釈せずに、
テキストをコードフォントで表示します。
これにより doc コメントでは、
パラメータの種類 ( <Object> )、不等号 ( 3 < 4 )、
または矢印 ( <- ) などで、HTML エンティティ ( < および > ) ではなく、
通常の山括弧 (< および >) を使用できます。
たとえば doc コメントのテキスト
.LP
.RS 5
{@code A<B>C}
.RE
.LP
は、生成された HTML ページで、次のようにそのまま表示されます。
.LP
.RS 5
A<B>C
.RE
.LP
注目すべき点として、<B> は太字であると解釈されませんが、
コードフォントになります。
.LP
コードフォントなしで同じ機能を実現するには、
{@literal} を使用します。
.RE
.TP
.B {@docRoot}
生成された任意のページを起点とした、ドキュメントの (出力先)
ルートディレクトリの相対パスを表します。このタグは、著作権ページ
または会社のロゴなど、生成されるすべてのページから参照するファイル
を取り込むときに使います。通常は、各ページの最下部から著作権
ページにリンクします。
.RS
.LP
この \f2{@docRoot}\fP タグは、コマンド行からも、ドキュメンテーションコメントの中でも使用できます。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
.TP 4
1.
コマンド行では、次のようにヘッダ (header)、フッタ (footer)、
またはページの最下部 (bottom)を定義します。
.sp 1n
.B javadoc \-bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
.LP
注 - Makefile の中で {\f3@docRoot\f1}をこのように利用する場合、
一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする
必要があります。 たとえば、Inprise MAKE バージョン 5.2 を
Windows 上で実行する場合は、{{\f3@docRoot\f1}} のように、
中括弧を二重にする必要があります。さらに、\-bottom などの
オプションに対する引数を、単一引用符ではなく、
二重引用符で囲む必要があります。href
引数の値を囲む引用符は省略します。
.TP
2.
doc コメントには次のように記述します。
.sp 1n
.nf
.ft 3
/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/
.ft 1
.fi
.LP
このタグが必要な理由は、生成されるドキュメントが、サブパッケージと
同じ階層のディレクトリに格納されるためです。たとえば、次のように指定します。
.LP
.ti +5n
.B <a href="{@docRoot}/copyright.html">
.LP
次のように解決されます。
.LP
.ti +5n
\f3<a href=".\|.\|/.\|.\|/copyright.html">\f1 .\|.\|. java/lang/Object.java の場合
.sp 1n
および
.sp 1n
.ti +5n
\f3<a href=".\|.\|/.\|.\|/.\|.\|/copyright.html">\f1 .\|.\|. java/lang/ref/Reference.java の場合
.RE
.TP
.BI @exception " class-name description"
.B @exception
タグは、
.BR @throws
と同義です。
.TP
{\f3@inheritDoc\f1}
最も近いスーパークラスから現在の ドキュメンテーションコメントに、ドキュメントを継承します。 この機能により、コメントは継承ツリーの上位に移動し、開発者はコピーしたテキストに記述を追加することができます。
.LP
このタグは、ドキュメンテーションコメントの次の位置でのみ有効です。
.RS 3
.TP 2
o
メソッドの主説明ブロック内。この場合、主説明は、上位階層のクラスまたはインタフェースからコピーされる
.TP 2
o
メソッドの @return、@param、@throws タグのテキスト引数内。この場合、タグテキストは、上位階層の対応するタグからコピーされる
.RE
.LP
継承階層でコメントを見つける方法に関する正確な説明について、「メソッドコメントの自動コピー」を参照してください。このタグが見つからない場合、コメントは、この節で説明するルールに応じて、自動的に継承されるかどうかが決まります。
.LP
.TP 3
{@link\ package.class#member\ label}
表示テキスト label とのインラインリンクを挿入します。\f2label\fP は、参照クラスの指定されたパッケージ、クラス、またはメンバの名前のドキュメンテーションを指し示します。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
.LP
このタグは、
.B @see
タグとよく似ています。どちらのタグも、package.class#member および
.BI label
の参照の仕方が同じで、有効な構文もまったく同じです。
大きな違いは、{\f3@link\f1} は、リンクを [関連項目] セクションに
置くのではなく、インラインリンクを生成するということです。
また、インラインテキストのほかの部分と区別するために、
{\f3@link\f1} タグの最初と最後に中括弧を記述します。
ラベルの中で「}」を使う必要がある場合は、HTML
エンティティの「}」を使います。
.LP
1 つの文の中で使用できる {@link} タグの数に制限はありません。
このタグは、ドキュメンテーションコメントの説明部分、または
.BR @deprecated
、
.BR @return
、
.BR @param
などの任意のタグのテキスト部分で使うことができます。
.LP
たとえば、次のコメントでは、
.B getComponentAt(int, int)
メソッドを参照しています。
.LP
.ft 3
.nf
Use the {\f3@link #getComponentAt(int, int) getComponentAt\f1} method.
.fi
.ft 1
.LP
標準ドックレットでは、上記のコメントから次の HTML が
生成されます (このコメントが同じパッケージの別のクラスを参照している場合)。
.LP
.ft 3
.nf
Use the
<a href="Component.html#getComponentAt(int, int)">getComponentAt</a>method.
.fi
.ft 1
.LP
この HTML は、Web ページ上では次のように表示されます。
.LP
.ft 3
.nf
Use the getComponentAt method.
.fi
.ft 1
.LP
{\f3@link\f1} を、ドキュメント化の対象にしていないクラスにまで
拡張するには、
.BR \-link
オプションを使用します。
.LP
詳細については、
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#{@link}
の
.na
\f2{@link} タグのドキュメント\fPを参照してください。
.RE
.TP
{@linkplain package.class#member label}
リンクのラベルがコードフォントではなくプレーンテキストで
表示されている点以外は、
{\f3@link\f1} と同じです。 ラベルがプレーンテキストで
記述されている場合に便利です。次の例を参照してください。
.LP
.ft 3
.nf
Refer to {\f3@linkplain\f1 add() the overridden method}.
.fi
.ft 1
.LP
これは以下のように表示されます。
.LP
.ft 3
.nf
Refer to the overridden method.
.fi
.ft 1
.LP
.TP
.B {@literal text}
テキストを HTML マークアップまたは
入れ子になった javadoc タグとして解釈せずに、
テキストをコードフォントで表示します。
これにより doc コメントでは、
パラメータの種類 ( <Object> )、不等号 ( 3 < 4 )、
または矢印 ( <- ) などで、HTML エンティティ ( < および > ) ではなく、
通常の山括弧 (< および >) を使用できます。
たとえば doc コメントのテキスト
.LP
.RS 5
{@literal A<B>C}
.RE
.LP
は、生成された HTML ページはブラウザで次のようにそのまま表示されます。
.LP
.RS 5
A<B>C
.RE
.LP
注目すべき点として、<B> は太字であると解釈され、
コードフォントになりません。
.LP
コードフォントで同じ機能を実現するには、
{@code} を使用します。
.TP
.BI @param " parameter-name description"
指定した parameter-name と指定した description を使用して
パラメータを「Parameters」セクションに追加します。
doc コメントを記述するときは、description を複数行に
続けることができます。このタグは、
メソッド、コンストラクタ、またはクラスの
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
\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
\fP
.fi
詳細については、
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@param
の
.na
\f2@param タグのドキュメント\fPを参照してください。
.LP
.TP 3
@return\ description
「戻り値」セクションを追加して、\f2description\fP のテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーションコメントでのみ有効です。
.LP
詳細については、
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@return
の
.na
\f2@return タグのドキュメント\fPを参照してください。
.LP
.TP 3
@see\ reference
「関連項目」見出しを追加し、\f2reference\fP を指すリンクか、またはテキストエントリを書き込みます。1 つのドキュメンテーションコメントには、任意の数の \f2@see\fP タグを指定できます。すべての \f2@see\fP タグの内容は、同じ見出しの下にグループ化されます。\f2@see\fP タグには、次の 3 種類の形式があります。もっともよく使われるのは、3 番目の形式です。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。パッケージ、クラス、またはメンバに対するインラインリンクを文中に挿入する方法は、\f2{@link}\fP を参照してください。
.RS 3
.TP 3
@see "string"
string のテキストエントリを追加します。
リンクは生成されません。string は、書籍、または
URL ではアクセスできない情報の参照先です。
.B javadoc
ツールは、最初の文字が二重引用符 (") かどうかを調べて、
上の 2 つの形式とこの形式とを区
別します。次に例を示します。
.LP
.RS
.ft 3
.nf
@see "The Java Programming Language"
.fi
.ft 1
.LP
これは次のようなテキストを生成します。
.LP
.ft 3
.nf
関連項目:
"The Java Programming Language"
.fi
.ft 1
.RE
.TP
\f3@see <a href="\f2URL#value\f3">\f2label\f3</a>\f1
.IR URL#value
で定義されたとおりにリンクを追加します。
.I URL#value
は、相対 URL または絶対 URL です。
.B javadoc
ツールは、最初の文字として、小なり括弧 (\f3<\f1) を探すことで、
このリンクをその他の場合と区別します。
.LP
.RS
.ft 3
.nf
@see <a href="spec.html#section">Java Spec</a>
.fi
.ft 1
.LP
これは次のようなリンクを生成します。
.LP
.ft 3
.nf
関連項目:
Java Spec
.fi
.ft 1
.RE
.TP
.BI @see " package.class#member label"
参照される Java 言語で指定された名前のドキュメントを指す、
表示テキスト label を持つ
リンクを追加します。label は省略可能です。label を省略した場合は、
該当する名前が
適切に短くされて (「名前の表示方法」を参照)、
表示テキストとして代わりに表示されます。-noqualifier を使用すると、表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストを指定する場合に使います。
.LP
.RS
バージョン 1.2 では、ラベルではなく、名前だけが
HTML タグ
.B <code>
に囲まれて自動的に表示されます。バージョン 1.2.2 以降は、
.B <code>
は常に、ラベルが使用されているかどうかにかかわらず、
表示可能なテキストを囲みます。
.TP 2
\(bu
.I package.class#member
には、Java 言語で有効な任意の名前、つまりパッケージ、
クラス、インタフェース、
コンストラクタ、メソッド、またはフィールドの名前を指定します
。ただし、メンバ名の前の
ドットは、ハッシュ文字 (#) で置き換えます。
指定した名前が、ドキュメント化されるクラス
にある場合、
.B javadoc
ツールは該当する名前へのリンクを自動的に作成します。
外部参照クラスへのリンクを作成する
には、
.B \-link
オプションを使います。参照されるクラスに属していない名前の
ドキュメントを参
照するには、ほかの 2 つの形式の
.B @see
タグを使います。1 番目の引数については、「名前の指定」 で
詳しく説明します。
.TP 2
\(bu
.I label
は省略可能なテキストで、
リンクのラベルとして表示されます。label には空白を含
めることができます。label を省略した場合は、
.I package.class.member
が、現在のクラスおよびパッケージに応じて
適切に短くされて表示されます。「名前の表示方法」を参照してください。
.TP 2
\(bu
空白文字は
.I package.class#member
と
.IR label
の間の区切り文字です。括弧内の空白文字は、
ラベルの開始を意味しないため、
メソッドのパラメータ間のデリミタとして使うことができます。
.LP
例-この例では、Character クラスの
.B @see
タグが String クラスの equals メソッドを参照しています。
タグには、名前 \f3String#equals(Object)\f1 とラベル \f3equals\f1 の
両方の引数が含まれています。
.LP
.ft 3
.nf
/**
* @see String#equals(Object) equals
*/
.fi
.ft 1
.LP
標準ドックレットは、次のような HTML を生成します。
.LP
.ft 3
.nf
<dl>
<dt><b>関連項目:</b>
<dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals</code></a>
</dl>
.fi
.ft 1
.LP
これは、ブラウザでは次のように表示され、
ラベルがリンクテキストになります。
.LP
.ft 3
.nf
関連項目:
equals
.fi
.ft 1
.LP
.B 名前の指定:
この
.I package.class#member
の名前は、
.BR java.lang.String#toUpperCase()
のように完全指定することも、
.B String#toUpperCase()
や
.BR #toUpperCase()
などのように完全指定しないことも可能です。
完全指定しない場合、
.B javadoc
ツールは、通常の Java コンパイラの検索順序で検索を行います。
詳細は、以下の「
.BR @see
の検索順序」を参照してください。指定する名前では、
メソッドの複数の引数の型の間など、
括弧内に空白を含めることができます。
.LP
短い部分修飾名を指定することの利点は、入力する
文字数が減ることと、ソースコードが
読みやすくなることです。以下の表に示すのは、さまざまな
形式の名前です。Class には
クラスかインタフェース、Type にはクラス、インタフェース、
配列、または基本データ型、
method にはメソッドまたはコンストラクタを指定できます。
.LP
.LP
.TS
box;
lp-1.
@see package.class#member の一般的な形式
_
現在のクラスのメンバを参照する
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)
_
T{
現在の、またはインポートされたパッケージの別のクラスを参照する
T}
@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
T{
@see Class#constructor(Type argname, Type argname,...)
T}
@see Class.NestedClass
@see Class
_
別のパッケージの要素を参照する (完全修飾)
@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
T{
@see package.Class#constructor(Type argname, Type argname,...)
T}
@see package.Class.NestedClass
@see package.Class
@see package
.TE
.LP
上の表に対する注を以下に示します。
.LP
.TP 2
\(bu
クラスまたはパッケージを省いた最初の形式のセットでは、
.B javadoc
ツールは現在のクラス階層だけで検索を行います。
.B javadoc
ツールは、現在のクラスかインタフェースのメンバ、スーパークラスか
スーパーインタフェースの 1 つ、または
親クラスかインタフェースの 1 つ (検索手順 1 〜 3) を検索します。
現在のパッケージのほかの部分やほかのパッケージ (検索手順 4 〜 5) は
検索しません。
.TP 2
\(bu
メソッドまたはコンストラクタが、getValue のように
括弧を付けずに名前として入力され、
かつ同じ名前のフィールドがない場合は、
.B javadoc
ツールは正確にリンクを作成しますが、括弧と引数を追加するように
促す警告メッセージを出力
します。このメソッドをオーバーロードした場合、
.B javadoc
ツールは、指定されたメソッドではなく、検索で見つかった
最初のメソッドにリンクします。
.TP 2
\(bu
入れ子の内部クラスは、どの形式の場合でも、単に
.BR inner
という形ではなく、
.BR outer.inner
という形で指定しなければなりません。
.TP 2
\(bu
すでに述べたとおり、クラスとメンバを区切るのに、ドット (\f3.\f1) ではなく
ハッシュ文字 (\f3#\f1) が
使われていることに注意してください。ドットは、クラス、
入れ子のクラス、パッケージ、および
サブパッケージを区切るのにも使われます。
ただし、
.B javadoc
ツールでは一般に許容範囲が広く、
あいまいさがなければ、ドットでも正しく解析されます。
その場合でも警告は表示されます。
.LP
.B @see の検索順序:
.B javadoc
は、ソースファイル (\f3.java\f1)、パッケージ
ファイル (\f3package.html\f1 か \f3package\-info.java\f1)、または
概要ファイル (\f3overview.html\f1) 内で使われる
.B @see
タグを処理します。
あとの 2 つのファイルでは、
.BR @see
を使って指定する名前を完全修飾する必要があります。
ソースファイルでは、完全修飾名
と部分修飾名のどちらを指定することもできます。
.LP
.B javadoc
ツールが、完全修飾されていない
.B .java
ファイルで
.B @see
タグを見つけた場合、指定された名前を Java コンパイラと
同じ順序で検索します。ただし、
.B javadoc
ツールは、一部の名前空間のあいまいさは検出しません。これは、
.B javadoc
ツールが、ソースコードにこれらのエラーが存在していないことを
前提として動作するためです。
検索順序は、「Java Language Specification」第 2 版の第 6 章「Names」で
正式に定義されています。具体的には、検索は次の順序で行われます。
.LP
.TP 4
1.
現在のクラスまたはインタフェース
.PD 0
.TP 4
2.
名前を囲むクラスとインタフェース。もっとも近いものを最初に検索
.TP 4
3.
スーパークラスとスーパーインタフェース。もっとも近いものを最初に検索
.TP 4
4.
現在のパッケージ
.TP 4
5.
インポートされるパッケージ、クラス、
およびインタフェース。import 文の順序に従って検索
.PD
.LP
.B javadoc
ツールは、一致する名前が見つかるまで、各クラスについて
手順 1 〜 3 を繰り返して検索を続け
ます。つまり、現在のクラスとそのクラスを囲む
クラス E を検索したあと、E のスーパクラスを
検索し、最後に E を囲むクラスを検索します。手順 4 と 5 では、
.B javadoc
ツールは、1 つのパッケージ内でのクラスまたはインタフェースの検索を、
なんらかの決まった順
序で行うわけではありません (この検索順序はコンパイラに依存します)。
手順 5 では、
.B javadoc
ツールは、
.BR java.lang
を検索します。これは、
.BR java.lang
がすべてのプログラムによって自動的にインポートされるためです。
.LP
.B javadoc
ツールは、必ずしもサブクラスを検索するわけではなく、Javadoc ツールの
実行中にほかのパッケージ
のドキュメントが生成される場合でも、ほかのパッケージの
検索は行いません。
たとえば、
.B @see
タグが
.B java.awt.event.KeyEvent
クラスにあって、
.B java.awt
パッケージにある名前を参照する場合、
.B javadoc
は、そのクラスがインポートしない限りそのパッケージを検索しません。
.LP
.B 名前の表示方法:
.I label
が省略された場合は、
.I package.class.member
が表示されます。通常、package.class.member は、現在の
クラスおよびパッケージに
応じて適切に短くされます。「短くされる」とは、
.B javadoc
ツールが必要最小限の名前を表示するということです。
たとえば、String.toUpperCase() メソッドが同じ
クラスのメンバへの参照と、別のクラスのメンバへの
参照を含んでいる場合、クラス名は後者の場合だけ表示されます。
.LP
パッケージ名を広域的に削除するには、\-noqualifier を使用します。
.br
.LP
.TP 4
.TS
box, center;
cbp-1 | cbp-1 | cbp-1
l | l | l .
参照の種類 T{
String.toUppercase() での例
T} 表示
_
T{
@see タグが同じクラス、同じパッケージのメンバを参照している
T} T{
@see String#toLowerCase()
T} T{
toLowerCase() (パッケージおよびクラス名は省略)
T}
_
T{
@see タグが異なるクラス、同じパッケージのメンバを参照している
T} T{
@see Character#toLowerCase(char)
T} T{
Character.toLowerCase(char) (パッケージ名は省略し、クラス名を含む)
T}
_
T{
@see タグが異なるクラス、異なるパッケージのメンバを参照している
T} T{
@see java.io.File#exists()
T} T{
java.io.File.exists() (パッケージ名とクラス名を含む)
T}
.TE
.LP
\f3@see の例\fP
.br
右側のコメントは、\f2@see\fP タグが別のパッケージ (\f2java.applet.Applet\fP など) のクラス内にある場合に、名前がどのように表示されるかを示しています。
.nf
\f3
.fl
See also:
.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
.I @see
を、ドキュメント化の対象にしていないクラスにまで拡張するには、
.I -link
オプションを使用します。
.LP
詳細については、
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@see
の
.na
\f2@see タグのドキュメント\fPを参照してください。
.RE
.TP 3
.BI @serial " field-description" | include | exclude
デフォルトの直列化可能フィールドの doc コメントで使用します。
.RS
.LP
省略可能な field-description は、
フィールドの doc コメントを拡張します。
この説明では、フィールドの意味および
取り得る値のリストを指定しなければなりません。
必要な場合には、複数の行にまたがって説明を記述することができます。
標準ドックレットは、この情報を、直列化された形式のページに追加します。
.LP
クラスを直列化したあとしばらくしてから直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。
.LP
.BR include
と
.BR exclude
引数は、直列化された形式のページにクラスまたはパッケージを含めるべきか、
あるいはこれらの引数を除くべきかを指定します。
これらは、次のように動作します。
.LP
.TP 2
\(bu
.BR Serializable
を実装する public クラスまたは protected クラスは、
そのクラス (またはそのパッケージ) が
.BR @serial
.BR exclude
とマークされていない限り含められます。
.TP 2
\(bu
.BR Serializable
を実装する private クラスまたは package\-private クラスは、
そのクラス (またはそのパッケージ) が
.BR @serial
.BR include
とマークされていない限り除かれます。
.LP
例:
.BR javax.swing
パッケージは、(package.html または \f2package\-info.java\fP 内で)
.BR @serial
.BR exclude
とマークされます。
public クラスである
.BR java.sercurity.BasicPermission
は、
.BR @serial
.BR exclude
とマークされます。package\-private クラスである
.BR java.util.PropertyPermissionCollection
は、
.BR @serial
.BR include
とマークされます。
.LP
クラスレベルのタグ
.BR @serial
は、パッケージレベルの
.BR @serial
をオーバーライドします。
.LP
これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の第 1.6 節「クラスの直列化可能なフィールドおよびデータの文書化」を参照してください。また、
.fi
http://java.sun.com/products/jdk/serialization/faq/#javadoc_warn_missing
の
.na
「\f2直列化の FAQ\fP」も参照してください。この FAQ には、「\-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。直列化形式仕様にクラスを含める場合には、
.fi
http://java.sun.com/j2se/javadoc/writingapispecs/serialized\-criteria.html
の
.na
「\f2Sun の仕様\fP」も参照してください。
.LP
.RE
.TP
.BI @serialField " field-name field-type field-description"
Serializable クラスの serialPersistentFields メンバの ObjectStreamField コンポーネント
をドキュメント化します。各 ObjectStreamField コンポーネントに対して
.B @serialField
タグを 1 つ使う必要があります。
.TP
.BI @serialData " data-description"
.I data-description
は、直列化された形式でのデータの型と順序を
説明するテキストです。 このデータには、
特に、writeObject メソッドによって書き込まれる省略可能な
データ、および Externalizable.writeExternal メソッドによって
書き込まれるすべてのデータ (基底クラスを含む) が含まれます。
.TP
.B @serialData
タグは、writeObject、readObject、writeExternal、および readExternal の各メソッドの
doc コメントで使用できます。
.LP
.TP 3
@since\ since\-text
生成ドキュメントに「導入されたバージョン」見出しを追加し、指定された \f2since\-text\fP を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、\f2since\-text\fP に示されたソフトウェアリリース以降、存在していることを意味します。次に例を示します。
.nf
\f3
.fl
@since 1.5
.fl
\fP
.fi
Java プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。
.RE
.TP
.BI @throws " class-name description"
.B @throws
タグと
.B @exception
タグは同義です。生成されるドキュメンテーションに、
.I class-name
および
.I description
テキストを持つ [例外] 小見出しを追加します。
.I class-name
は、該当するメソッドによって
スローされる可能性のある例外の名前です。このタグは、doc コメントまたはコンストラクタでのみ有効です。このクラスが完全
修飾されていない場合、
.B javadoc
ツールは検索順序に従ってクラスを探します。
同じまたは異なる例外の doc コメントで、
複数の @throws タグを使用できます。
.LP
すべてのチェック済み例外がドキュメント化されるようにするために、
@throws タグが throws 節内の例外用に存在しない場合は、
@throws タグのあるドキュメントであるかのように、
.B Javadoc
ツールによって例外が HTML 出力に説明なしで
自動的に追加されます。
.LP
オーバーライドされたメソッドで明示的に例外が宣言されている場合に限って、
オーバーライドされたメソッドからサブクラスへ
@throws ドキュメントがコピーされます。
インタフェースメソッドから実装メソッドにコピーされる場合も
同様です。{@inheritDoc} を使用して、継承ドキュメントに対して
強制的に @throws を適用することも可能です。
.LP
詳細は
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@exception
の
.na
\f2@throws タグのドキュメント\fPを参照してください。
.TP
.B {@value package.class#field}
{@value} が静的フィールドの doc コメントで
引数なしで使用されている場合、その定数の値が表示されます。
.LP
.RS 5
.nf
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "<script>"
.fi
.RE
.LP
任意の doc コメント内で引数
.B package.class#field
ありで使用されている場合は、指定した定数の値が表示されます。
.LP
.RS 5
.nf
/**
* Evaluates the script starting with {@value #SCRIPT_START}.
*/
public String evalScript(String script) {
}
.fi
.RE
.LP
引数 package.class#field は、@see 引数と同一の形式になります。
ただし、メンバが静的フィールドになければならない点が異なります。
.LP
これらの定数での値は、「定数フィールド値」ページにも表示されます。
.TP
.BI @version " version-text"
\-version オプションが使われている場合、生成ドキュメントに「バージョン」小見出しを追加して、指定された \f2version\-text\fP を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のバージョン番号を保持するように意図されています。これに対し、@since は、このコードが導入されたバージョン番号を保持します。\f2version\-text\fP には、特別な内部構造はありません。バージョンタグを使用できる場所を調べるには、「タグを使用できる場所」を参照してください。
.LP
1 つのドキュメンテーションコメントに複数の \f2@version\fP タグを含めることができます。必要に応じて、\f2@version\fP タグごとに 1 つのバージョン番号を指定することも、タグごとに複数のバージョン番号を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (\f2,\fP) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要がある場合は、1 つのタグに複数の名前を指定できます。
.LP
詳細については、
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@version
の
.na
\f2@version タグのドキュメント\fPを参照してください。
.SS "タグを使用できる場所"
以下では、タグを使用できる場所について説明します。@see、@since、@deprecated、{@link}、{@linkplain} および {@docroot} のタグは、すべての doc コメントで使用できます。
.SS "概要ドキュメントタグ"
概要タグは、概要ページのドキュメント
コメント (通常は \f3overview.html\f1
という名前のソースファイル内にある) で使用できるタグです。
ほかのドキュメント
コメントと同様に、これらのタグは、説明のあとで使う必要があります。
.LP
注:バージョン 1.2 では、概要ドキュメント内の {\f3@link\f1} タグに
バグがあります。テキストは適切に表示されますが、
リンクが設定されません。
現在のところ、{\f2@docRoot\f1} タグは、
概要ドキュメント内では動作しません。
.LP
.LP
.TS
;
cbp-1
l .
概要タグ
@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-20
.LP
.SS "パッケージドキュメントタグ"
パッケージタグは、パッケージのドキュメント
コメント (\f3package.html\f1 または \f2package\-info.java\fP という
名前のソースファイルに存在) で使用できるタグです。
ここで使用できる @serial タグは、include または
exclude 引数を指定したものだけです。
.LP
.LP
.TS
;
cbp-1
l .
パッケージタグ
@see
@since
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-22
.LP
.SS "クラスおよびインタフェースドキュメントタグ"
次に示すのは、クラスまたはインタフェースのドキュメント
コメントで使用できるタグです。
ここで使用できる @serial タグは、
include または exclude 引数を指定したものだけです。
.LP
.LP
.TS
;
cbp-1
l .
クラスおよびインタフェースタグ
@see
@since
@deprecated
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}
.TE
.LP
次は、クラスコメントの例です。
.LP
.RS
.ft 3
.nf
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.13, 06/08/06
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
.fi
.ft 1
.RE
.SS "フィールドドキュメントタグ"
次に示すのは、フィールドのドキュメンテーションコメントで
使用できるタグです。
.LP
.LP
.TS
;
cbp-1
l .
フィールドタグ
@see
@since
@deprecated
@serial
@serialField
{@link}
{@linkplain}
{@docRoot}
{@value}
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-24
.LP
次は、フィールドコメントの例です。
.LP
.RS
.ft 3
.nf
/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;
.fi
.ft 1
.RE
.SS "コンストラクタおよびメソッドドキュメントタグ"
次に、コンストラクタまたはメソッドのドキュメンテーションコメント内で表示できるタグを示します。ただし、@return はコンストラクタでは表示できず、{@inheritDoc} は
表示に制限があります。@serialData タグは特定の直列化メソッドの doc コメントでのみ使用できます。
.LP
.LP
.TS
;
cbp-1
l .
メソッドおよびコンストラクタタグ
@see
@since
@deprecated
@param
@return
@throws and @exception
@serialData
{@link}
{@linkplain}
{@inheritDoc}
{@docRoot}
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-28
.LP
次はメソッドの doc コメントの例です。
.LP
.RS
.ft 3
.nf
/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>.
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>.
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
...
}
.fi
.ft 1
.RE
.SH "オプション"
.B javadoc
ツールは、ドックレットを使って出力を決定します。
.B javadoc
ツールは、
.B \-doclet
オプションでカスタムドックレットが指定されている場合以外は、
デフォルトの標準ドック
レットを使います。
.B javadoc
ツールには、任意のドックレットとともに使用できるコマンド行
オプションがあります。これらのオプ
ションについては、後述の「javadoc のオプション」で説明します。
標準ドックレットでは、こ
のほかに、いくつかの追加のコマンド行オプションが提供されます。
これらのオプションに
ついては、後述の「標準ドックレットが提供するオプション」で
説明します。どのオプション
名も大文字と小文字を区別しません。ただし、オプションの引数では
大文字と小文字が区
別されることがあります。
.LP
オプションを以下に示します。
.LP
.RS 3
.LP
.LP
.TS
center;
li l li
l li li
li l li
l li li
li l l
l l li
li l li
l l l
l li l
l l li
li l l
li l l
l l l
li l l
li l l
l l li
li l l
l l l
l l l
l li l
l li l.
-1.1 -header -private
-author -help -protected
-bootclasspath -helpfile -public
-bottom -J -quiet
-breakiterator -keywords -serialwarn
-charset -link -source
-classpath -linkoffline -sourcepath
-d -linksource -splitindex
-docencoding -locale -stylesheetfile
-docfilessubdirs -nocomment -subpackages
-doclet -nodeprecated -tag
-docletpath -nodeprecatedlist -taglet
-doctitle -nohelp -tagletpath
-encoding -noindex -title
-exclude -nonavbar -use
-excludedocfilessubdir -noqualifier -verbose
-extdirs -nosince -version
-footer -notimestamp -windowtitle
-group -notree
-overview
-package
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-123
.LP
.RE
.LP
\f2下線付き\fPで示されたオプションは、Javadoc の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、下線付きでないオプションを提供します。
.LP
.SS "Javadoc のオプション"
.TP
.BI \-overview " path/filename"
.B javadoc
に対して、
.I path/filename
で指定された「ソース」ファイルから
概要ドキュメント用のテキスト
を取得し、概要ページ (\f3overview-summary.html\f1) に配置することを
指示します。
.I path/filename
は、
.BR \-sourcepath
への相対パスです。
.LP
.RS
.I filename
と
.IR path
には、それぞれ任意の名前と場所を指定できますが、通常は、
.B overview.html
という名前を付けて、ソースツリー内の最上位の
パッケージディレクトリを含むディレクトリ
に配置します。この場所では、
.B \-sourcepath
がこのファイルを指すので、パッケージを
ドキュメント化する際に path が必要ありません。
たとえば、java.lang パッケージのソースツリーが
.BR /src/classes/java/lang/
の場合、概要ファイルを
.BR /src/classes/overview.html
に配置できます。「使用例」を参照してください。
.LP
.IR path/filename
で指定するファイルについては、
「概要コメントファイル」を参照してください。
.LP
概要ページが作成されるのは、
.B javadoc
に 2 つ以上のパッケージ名を渡した場合だけです。
詳細は、「HTML フレーム」
節を参照してください。
.LP
概要ページのタイトルは、
.B \-doctitle
によって設定されます。
.RE
.TP
.B \-public
public なクラスとメンバだけを表示します。
.TP
.B \-protected
protected および public なクラスとメンバだけを表示します。
これはデフォルトの動作です。
.TP
.B \-package
パッケージ、および protected と public な
クラスとメンバだけを表示します。
.TP
.B \-private
すべてのクラスとメンバを表示します。
.TP
.B \-help
オンラインヘルプを表示します。
.B javadoc
とドックレットのコマンド行オプションの一覧が表示されます。
.TP
.BI \-doclet " class"
ドキュメントの生成に使う
ドックレットを起動するためのクラスファイルを指定します。
完全指定の名前を指定してください。
ドックレットでは、出力の内容と形式を定義します。
.B \-doclet
オプションが使われていない場合、
.B javadoc
は標準ドックレットを使ってデフォルトの HTML 形式を生成します。
このクラスには、
start(Root) メソッドが含まれていなければなりません。
この起動クラスへのパスは、
.B \-docletpath
オプションによって定義されます。
.LP
たとえば、MIF ドックレットを呼び出すには、次のように指定します。
.LP
.RS
.ft 3
.nf
-doclet com.sun.tools.doclets.mif.MIFDoclet
.fi
.ft 1
.LP
特定のドックレットを実行した完全な例については、
.fi
http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet
の
.na
「\f2Running the MIF Doclet\fP」を参照してください。
.RE
.TP
.BI \-docletpath " classpathlist"
.B \-doclet
オプションで指定されているドックレットクラスファイル、
およびそれに依存する jar ファイルへのパスを指定します。
起動クラスファイルが jar ファイル内にある場合、
例に従って、その jar ファイルへのパスを指定します。
絶対パス、または現在のディレクトリからの相対パスを指定できます。
.IR classpathlist
には、複数のパスまたは jar ファイルを含める
ことができます。その場合、各パスまたは jar ファイルを Solaris ではコロン (\f3:\f1)で、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
特定のドックレットを実行した完全な例については、
.fi
http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet
の
.na
「\f2Running the MIF Doclet\fP」を参照してください。
.RE
.LP
.TP
.B \-1.1
この機能は、javadoc 1.4 から削除されました。代替の機能は
存在しません。このオプションは、javadoc 1.1 で生成される
ドキュメントの外観と機能 (サポートされなくなった、入れ子になったクラスを
含む) を備えたドキュメントを作成するためのものでした。
このオプションが必要であれば、代わ
りに javadoc 1.2 または 1.3 を使用してください。
.TP 3
\-source release
受け付けるソースコードのバージョンを指定します。\f2release\fP には次の値を指定できます。
.LP
.TS
;
l l.
1.5 T{
Javadoc は、JDK 1.5 で導入された総称機能および他の言語機能を含んだコードを受け付けます。-source フラグを指定しないと、コンパイラはデフォルトとして 1.5 の動作をします。
T}
1.4 T{
Javadoc は、JDK 1.4 で導入された、アサーションを含むコードを受け付けます。
T}
1.3 T{
Javadoc は、JDK 1.3 以降に導入されたアサーション、総称機能、または他の言語機能をサポートしません。
T}
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-14
.LP
javac でコードをコンパイルするときに使用した値に対応する \f2release\fP の値を使用します。
.LP
.TP
.BI \-sourcepath " sourcepathlist"
.B javadoc
コマンドにパッケージ名または \-subpackages
を渡す際に、
ソースファイル (.java) 検索用のパスを指定します。
.BI sourcepathlist
には、コロン (\f3:\f1)
で区切った複数のパスを含めることができます。
.B Javadoc
ツールは、指定されたパス以下のすべての
サブディレクトリを検索します。 このオプションを使って、
ドキュメント化されるソースファイルの位置だけでなく、
それ自体はドキュメント化されていないが、ドキュメント化
されているソースファイルから継承されたコメントをもつ
ソースファイルの位置も確認できます。
.LP
.B \-sourcepath
オプションは、
.B javadoc
コマンドを使ってパッケージ名を指定するときにだけ使用でき、
.B javadoc
コマンドに渡される
.B .java
ファイルは検索できないことに注意してください。
.B .java
ファイルを検索するには、
そのディレクトリに移動するか、
各ファイルの前にそのパスを付けます (「1 つ以上
のパッケージのドキュメント化」を参照)。
.B \-sourcepath
が省略された場合は、
.B javadoc
はクラスパスを使ってソースファイルを検索します (
.B \-classpath
を参照)。 したがって、
.B \-sourcepath
のデフォルトは
.B \-classpath
の値です。
.B -classpath
を省略してパッケージ名を
.BR javadoc
に渡した場合、
.BR javadoc
は、ソースファイルの現在のディレクトリ (およびサブディレクトリ) を
検索します。
.LP
.RS
.I sourcepathlist
では、ドキュメント化するパッケージ名の
ソースツリーのルートディレクトリを
設定します。たとえば、ソースファイルが次の
場所にある
.B com.mypackage
という名前のパッケージをドキュメント化するとします。
.LP
.RS
.ft 3
.nf
/home/user/src/com/mypackage/*.java
.fi
.ft 1
.RE
.LP
この場合、次のようにしてソースパスを
.BR /home/user/src
、つまり
.BR com.mypackage
を含むディレクトリに指定し、それからパッケージ名
.BR com.mypackage
を指定します。
.LP
.RS
.ft 3
.nf
% javadoc \-sourcepath /home/user/src/ com.mypackage
.fi
.ft 1
.RE
.LP
これは、ソースパスの値とパッケージ名をつなげて、
ドットをスラッシュ (/) に変えると、以下のパッケージのフルパス
になることに注目すると覚えやすいでしょう。
.LP
.RS
.ft 3
.BR /home/user/src/com/mypackage
.RE
.LP
2 つのソースパスを指定するには、次のようにします。
.LP
.RS
.ft 3
.nf
% javadoc \-sourcepath /home/user/src/:/home/user2/src com.mypackage
.fi
.ft 1
.RE
.LP
.RE
.TP
.BI \-classpath " classpathlist"
.B javadoc
が参照されるクラスの検索を行うパスを指定します。
参照されるクラス (\f3.class\f1) とは、
ドキュメント化されるクラスとそれらのクラスによって
参照される任意のクラスのことです。
.B javadoc
は、指定されたパス以下のすべてのサブディレクトリで
検索を行います。
.I classpathlist
には、パス間をコロン (\f3:\f1) で区切って複数のパスを
含めることができます。
.B javadoc
ツールは、指定されたパス以下の
すべてのサブディレクトリを検索します。
.IR classpathlist
の指定
については、クラスパスのドキュメントを参照してください。
.LP
.RS
.B \-sourcepath
を省略した場合は、
.B javadoc
ツールは、クラスファイル (下位互換用) とともに、
.B \-classpath
を使ってソースファイルを検索します。このため、
異なるパス内のソースファイルおよびクラスファイルを検索する場合は、
.B \-sourcepath
と
.BR \-classpath
の両方を使います。
.LP
たとえば、
.BR com.mypackage
をドキュメント化したい場合に、パッケージのクラスがディレクトリ
.BR /home/user/src/com/mypackage
にあり、このパッケージが
.BR /home/user/lib
内のライブラリを使う場合は、次のように指定します。
.LP
.RS
.ft 3
.nf
% javadoc \-classpath /home/user/lib \-sourcepath /home/user/src com.mypackage
.fi
.ft 1
.RE
.LP
ほかのツールと同様に、
.BR \-classpath
を指定しない場合は、CLASSPATH 環境変数が
設定されていれば、
.B javadoc
ツールはこの環境変数を使います。
どちらも設定されていない場合
は、
.B javadoc
ツールは現在のディレクトリでクラスを検索します。
.LP
.B javadoc
ツールが拡張機能クラスおよびブートストラップクラスと通信する際に、
.B -classpath
を使ってユーザクラスを検索する方法についての
詳細は、「クラスの検索方法」を
参照してください。
.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:...
ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソースコードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。各 package 引数は、任意の最上位サブパッケージ (java など) または完全指定のパッケージ (javax.swing など) になります。ソースファイルを含める必要はありません。引数は、コロンで区切られます (すべてのオペレーティングシステム)。ワイルドカードは不要です (使用不可)。パッケージの検索場所を指定するには、\-sourcepath を使用します。このオプションは、「ソースファイルの処理」で説明したとおり、ソースツリーにあるがパッケージには属していないソースファイルを処理しないので役立ちます。
.LP
次に例を示します。
.nf
\f3
.fl
% \fP\f3javadoc \-d docs \-sourcepath /home/user/src \-subpackages java:javax.swing\fP
.fl
.fi
このコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。
.LP
\f2\-exclude\fP とともに \f2\-subpackages\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 は除外されます。
.RE
.TP
.BI \-bootclasspath " classpathlist"
ブートクラスが存在するパスを指定します。
ブートクラスとは、Java プラットフォームクラスのことです。
.B bootclasspath
は、
.B javadoc
ツールがソースファイルとクラスファイルを探すときに
使う検索パスの一部です。詳細は、
「Javac と Javadoc がクラスを検索する方法」 を
参照してください。
.I classpathlist
内の複数の
クラスパスリストは、コロン (:) で区切ります。
.TP
.BI \-extdirs " dirlist"
拡張機能クラスが存在するディレクトリを指定します。
拡張機能クラスは、Java 拡張機能
機構を使うすべてのクラスです。拡張機能ディレクトリ (
.B extdirs
) は、
.B javadoc
ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。
詳細は、上の
.B \-classpath
を参照してください。
.I dirlist
内の複数のディレクトリは、
コロン (:) で区切ります。
.TP
.B \-verbose
.B javadoc
の実行中に詳細なメッセージを表示します。冗長オプションを
指定しない場合は、ソースファイルのロード時、ドキュメントの
生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時に
メッセージが表示されます。冗長オプションを指定した場合は、
各 java ソースファイルの解析に要したミリ秒数などの
追加メッセージを表示します。
.TP
.BI \-quiet
エラーメッセージ以外、および警告メッセージ以外の
メッセージを除外し、
エラーメッセージおよび警告メッセージだけを
表示して見つけやすくします。
また、バージョン文字列の表示も抑制します。
.LP
.TP 3
\-breakiterator\
英語言語というロケール固有のアルゴリズムではなく、\f2java.text.BreakIterator\fP の国際化された文境界を使用して、英文の最初の文の終わりを判断します (他のすべてのロケールはすでに \f2BreakIterator\fP を使用)。「\f2最初の文\fP」とは、パッケージ、クラス、またはメンバの主説明での最初の文のことです。この文は、パッケージ、クラス、またはメンバの要約にコピーされ、アルファベット順のインデックスにコピーされます。
.LP
JDK 1.2 以降、BreakIterator クラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、1.2 以降では、\f2\-breakiterator\fP オプションは英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。
.RS 3
.TP 2
o
英文のデフォルトの文区切りアルゴリズム \- 空白または HTML ブロックタグ (\f2<P>\fP など) が続くピリオドで停止する
.TP 2
o
breakiterator 文区切りアルゴリズム \- 一般に、次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止する。このアルゴリズムでは、ほとんどの省略表記が処理される (「The serial no. is valid」は処理されるが「Mr. Smith」は処理されない)。HTML タグや、数字または記号で始まる文では停止しない。HTML タグに埋め込まれている場合でも、「../filename」の最後のピリオドで停止する
.RE
.RS 3
.LP
.LP
注: 1.5.0 からは、1.4.x に設けられていた breakiterator 警告メッセージを削除し、デフォルトの文区切りアルゴリズムを変更していません。つまり、\-breakiterator オプションは、1.5.0 ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャーリリース」(1.5.0) でデフォルトを変更するという、以前の目的とは逆になっています。つまり、ソースコードを変更せず、1.4.x での breakiterator 警告を除去していない場合でも、1.5.0 からは何もする必要がなく、警告は消滅しています。この逆戻りの理由は、breakiterator をデフォルトにするメリットよりも、デフォルトにするために必要となる、互換性のないソースの変更の方が負担が大きかったためです。これに費やした作業や混乱が無駄になり残念です。
.LP
.TP
.BI \-locale " language_country_variant"
.B 重要:
\-locale オプションは、標準ドックレットやその他のドックレット
によって提供されるオプションよりも前に (左側に)
指定する必要があります。そうでなければ、ナビゲーションバーは
英語で表示されます。順序に依存するコマンド行オプションは、
このオプションのみです。
.LP
.RS
.B javadoc
がドキュメントを生成するときに使うロケールを指定します。
引数には、java.util.Locale のドキュメントで説明されている
ロケールを指定します。
たとえば、en_US (英語、米国)、en_US_WIN (Windows で使われる英語) などを
指定します。
.LP
ロケールを指定すると、
.B javadoc
は指定されたロケールのリソースファイルを選択して
メッセージ (ナビゲーションバー、リストと表の見出し、
ヘルプファイルの目次、
.BR stylesheet.css
のコメントなどの文字列) に
使います。また、アルファベット順にソートされるリストのソート順、
および最初の文の末尾を決定する文の区切り文字も、
指定したロケールによって決まります。このオプションは、
ドキュメント化されるクラスのソースファイル内で
指定されている doc コメントテキストの
ロケールを決定するものではありません。
.RE
.TP
.BI \-encoding " name"
ソースファイルのエンコーディング名 (EUCJIS/SJIS など) を指定します。
このオプションが指定されていない場合は、プラットフォームの
デフォルトコンバータが使われます。
.LP
\-docencoding および \-charset も参照してください。
.TP
.BI \-J flag
.BR javadoc
を実行する実行システム java に flag を直接渡します。J と flag の間に
空白を入れてはなりません。たとえば、生成される
ドキュメントを処理するために、システムで 32M バイトを
確保する必要がある場合は、Java の
.B \-Xmx
オプションを次のように呼び出します。\-Xms はオプションです。初期メモリのサイズのみを設定するため、必要な最小メモリを知っている場合に便利です。
.LP
.RS
.ft 3
.nf
% javadoc \-J\-Xmx32m \-J\-Xms32m com.mypackage
.fi
.ft 1
.RE
.LP
使用している javadoc のバージョンを確認するには、
次のように java の「-version」オプションを呼び出します。
.LP
.RS
.ft 3
.nf
% javadoc -J-version
java version "1.2"
Classic VM (build JDK-1.2-V, green threads, sunwjit)
.fi
.ft 1
.RE
.LP
(標準ドックレットのバージョン番号は出力ストリームに表示されます。)
.SS "標準ドックレットが提供するオプション"
.TP
.BI \-d " directory"
生成された HTML ファイルを保存するディレクトリを
指定します (d は「生成先 (destination)」の意味)。このオプションを
省略すると、生成されたファイルは現在のディレクトリに保存されます。
値
.I directory
には、絶対ディレクトリまたは現在の作業
ディレクトリからの相対ディレクトリを指定できます。
1.4 では、javadoc の実行時に
自動的に生成先ディレクトリが作成されます。
.LP
たとえば、
次の例は、com.mypackage パッケージのドキュメントを生成し、
結果を
.B /home/user/doc/
ディレクトリに保存します。
.LP
.RS
.ft 3
.nf
% javadoc \-d /home/user/doc com.mypackage
.fi
.ft 1
.RE
.TP
.B \-use
ドキュメント化されるクラスとパッケージごとに 1 つの [使用] ページを
含めます。このページには、ドキュメント化されるクラスまたは
パッケージの API を使っているパッケージ、クラス、メソッド、
コンストラクタ、およびフィールドが記述されます。たとえば、クラス
C およびクラス C を使うものは、C のサブクラス、C として
宣言されているフィールド、C を返すメソッド、および、型 C の
パラメータを持つメソッドとコンストラクタがページに含ま
れます。
.LP
.RS
たとえば、String について、[使用] ページに何が表示されるかを
見てみましょう。
.B java.awt.Font
クラスの
.B getName()
メソッドは、String 型を返します。
このため、
.B getName()
は String を使うので、[使用] ページの String で
このメソッドを見つけることができます。
.LP
このページでは API の使用だけがドキュメント化され、実装はドキュメント化されません。
あるメソッドが実装内に String を使っているが、引数として
文字列をとったり、文字列を返したりしない
場合は、String の「使用」とはみなされません。
.LP
生成された [使用] ページにアクセスするには、目的のクラスまたは
パッケージを表示して、ナビゲーションバーの [使用] リンクを
クリックします。
.RE
.TP
.B \-version
生成されるドキュメントに
.B @version
テキストを含めます。このテキストは、デフォルトでは省略されます。
使用している javadoc ツールのバージョンを確認するには、
.B \-J\-version
オプションを使用します。
.TP
.B \-author
生成されるドキュメントに
.B @author
テキストを含めます。
.TP
.B \-splitindex
索引ファイルをアルファベットごとに複数のファイルに分割し、
文字ごとに 1 つのファイルと、アルファベット以外の文字で始まる
索引エントリ用のファイルを 1 つ作成します。
.TP
.BI \-windowtitle " title"
HTML の
.B <title>
タグで使うタイトルを指定します。指定したタイトルは、
ウィンドウタイトルと、該当するページに対して作成されたブラウザの
ブックマーク (よくアクセスする場所) に表示されます。
タイトルには HTML タグを含めないでください。タイトルに HTML タグが
含まれていると、ブラウザによるタグの解釈が不適切になる
可能性があります。
.I title
の中で引用符を使う場合は、引用符を
エスケープする必要があります。
.B -windowtitle
が省略されている場合、
.B javadoc
ツールはこのオプションの代わりに -doctitle の値を使います。
.LP
.RS
.ft 3
.nf
% javadoc -windowtitle "Java 2 Platform" com.mypackage
.fi
.ft 1
.RE
.TP
.BI \-doctitle " title"
概要ファイルの最上部近くに配置するタイトルを指定します。
タイトルは中央揃えされ、レベル 1 の見出しとして上部
ナビゲーションバーのすぐ下に置かれます。
.I title
には、HTML タグと
空白を含めることができますが、これらを含める場合は全体を引用符で囲
まなければなりません。
.I title
の中で引用符を使う場合は、引用符をエスケープする必要があります。
.LP
.RS
.ft 3
.nf
% javadoc -doctitle "Java<sup><font size=\"-2\">TM</font></sup>" com.mypackage
.fi
.ft 1
.RE
.TP
.BI \-title " title"
このオプションは、現在は存在しません。
.B javadoc
1.2 のベータ版にだけ存在しました。このオプションは、
ウィンドウタイトルではなくドキュメントタイトルを定義することを
明確にするため、
.BR \-doctitle
に名前が変更されました。
.TP
.BI \-header " header"
各出力ファイルの上部に配置するヘッダテキストを指定します。ヘッダは、
上部ナビゲーションバーの右側に配置されます。
.I header
には、HTML タグと
空白を含めることができますが、これらを含める場合は全体を引用符で
囲まなければなりません。header の中で引用符を使う場合は、引用符を
エスケープする必要があります。
.nf
\f3
.fl
% \fP\f3javadoc \-header "<b>Java 2 Platform </b><br>v1.4" com.mypackage\fP
.fl
.fi
.LP
.TP
.BI \-footer " footer"
各出力ファイルの下部に配置するフッタテキストを指定します。フッタは、
下部ナビゲーションバーの右側に配置されます。
.I footer
には、HTML タグと
空白を含めることができますが、これらを含める場合は全体を引用符で
囲まなければなりません。
.I footer
の中で引用符を使う場合は、引用符をエスケープする必要があります。
.TP
.BI \-bottom " text"
各出力ファイルの最下部に配置するテキストを指定します。
このテキストは、下部ナビゲーションバーの下のページの最下部に
配置されます。
.I text
には、HTML タグと空白を含めることができますが、
これらを含める場合は全体を引用符で囲まなければなりません。
.I text
の中で引用符を使う場合は、引用符をエスケープする必要があります。
.TP
.BI \-link " extdocURL"
.B javadoc
ツールにより生成された既存の
外部参照クラスのドキュメンテーションへのリンクを作成します。
引数は 1 つです。
.TP
\(bu
.I extdocURL
は、javadoc によって生成され、リンク先として指定する
外部ドキュメントがあるディレクトリの絶対 URL または相対 URL です。 あとで例を示します。 このディレクトリ内に package-list ファイルが存在して
いなければなりません。存在しない場合は、\-linkoffline を使用します。
.B javadoc
ツールは package-list ファイルからパッケージ名を読み取り、それを
.I extdocURL
のパッケージにリンクします。 javadoc ツールを実行すると、
.I extdocURL
値は作成された <A HREF> リンクにそのままコピーされます。 したがって、
.I extdocURL
はファイルではなく、
.I extdocURL
の URL である必要があります。
.LP
ドキュメントを任意の Web サイト上のドキュメントにリンクするには
.I extdocURL
の絶対リンクを、相対ロケーションだけを指定するには
相対リンクを使用できます。相対リンクを使用する場合、生成先ディレクトリ (\-d で指定) からの相対パスを、
リンク先パッケージがあるディレクトリに渡す必要があります。
.LP
通常、絶対リンクを指定する場合は、http: リンクを使用します。
ただし、Web サーバをもたないファイルシステムに
リンクする場合は、file: リンクを使用できます。
ただし、この方法は、生成されたドキュメントに
アクセスしようとする
すべてのユーザが同じファイルシステムを共有している
場合以外は使用しないでください。
.LP
すべての場合、すべてのオペレーティングシステムで、絶対 URL と相対 URL、「http:」ベースと「file:」ベースにかかわらず、スラッシュを区切り文字として使用します
.fi
(http://www.ietf.org/rfc/rfc1738.txt
の
.na
\f2URL Memo\fP で指定)。
.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 実行時に複数の \-link オプションを指定して、
複数のドキュメントへのリンクを作成することもできます。
.LP
\-linkoffline または \-link の選択
.LP
\-link を使用する場合:
.TP 3
\(bu
外部 API ドキュメントへの相対パスを使用している
.TP 3
\(bu
外部 API ドキュメントへの絶対 URL を使用している (プログラムがその URL に接続し、読み取りを行うことが
シェルによって許可されている場合)
.LP
\-linkoffline を使用する場合:
.TP 3
\(bu
外部 API ドキュメントへの絶対 URL を使用している
(プログラムがその URL に接続し、読み取りを行うことが
シェルによって許可されていない場合)。このような状況は、
リンク先のドキュメントがファイアウォールの
向こう側にある場合に発生します。
.LP
外部ドキュメントへの絶対リンクの使用例 -
java.lang、java.io、および他の Java 2 プラットフォームパッケージ
(\f2http://java.sun.com/j2se/1.5.0/docs/api\fP) に
リンクしたい場合があります。
次のコマンドは、
Java 2 プラットフォームパッケージへのリンクを持つ
com.mypackage パッケージのドキュメントを生成します。
生成されたドキュメントには、たとえばクラスツリー内の
Object クラスへのリンクが含まれています
(\-sourcepath や \-d などの他のオプションは表示されません)。
.LP
.RS
.ft 3
.nf
% \fP\f3javadoc \-link http://java.sun.com/j2se/1.5.0/docs/api com.mypackage\fP
.fi
.ft 1
.RE
.LP
外部 ドキュメントへの相対リンクの使用例 -
.B javadoc
ツールの異なる実行で生成されたドキュメントを持つ
2 つのパッケージがあり、それらが別々の
相対パスをもっているとします。
この例では、2 つのパッケージを
com.apipackage (API)、com.spipackage
(SPI - Service Provide Interface) とします。 ドキュメントの置き場所は docs/api/com/apipackage および
docs/spi/com/spipackage です。
API パッケージドキュメントはすでに生成され、ドキュメントが現在の
ディレクトリ内にある場合、次のように実行することで、
API ドキュメントにリンクした SPI パッケージをドキュメント化できます。
.LP
.RS
.ft 3
.nf
% javadoc \-d ./spi \-link ../api com.spipackage
.fi
.ft 1
.RE
.LP
\-link 引数が生成先ディレクトリの相対パス (docs/spi) で
あることに注意してください。
.LP
詳細 -
\-link オプションを使うと、コードからは参照されていても、
Javadoc の現在の実行ではドキュメント化されないクラスにリンク
できるようになります。 リンクから有効なページに
移動できるようにするには、それらの HTML ページが
ある場所を調べ、その場所を
.I extdocURL
に指定する必要があります。
このオプションを使うと、たとえば、サードパーティのドキュメントから、
http://java.sun.com にある java.* のドキュメントにリンクすることができます。
.LP
今回の実行で
.B javadoc
によって生成されるドキュメント内の
API だけを対象にリンクを作成する場合は、
\-link オプションを省略します。 \-link オプションが
指定されていない場合、
.B javadoc
ツールは、外部参照されたドキュメントへのリンクを
作成しません。これは、そのドキュメントが
存在するかどうか、あるいは存在していてもどこに
存在しているのかを判別できないからです。
.LP
このオプションは、生成ドキュメント内の複数の場所に
リンクを作成できます。
.LP
また、このオプションを使うと、複数のパッケージ群の間にクロスリンクを作成することもできます。つまり、ある一式のパッケージに対して javadoc を実行したあと、別の一式のパッケージに対して javadoc を実行し、これら 2 つのパッケージ群の間にクロスリンクを作成できます。
.LP
\f3クラスの参照方法\fP - 外部参照クラスへのリンクを、テキストラベルだけではなく実際に表示するには、次の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するだけでは十分ではありません。\f2import\fP 文または宣言で参照する必要があります。次に、クラス \f2java.io.File\fP を参照する方法の例を示します。
.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
.B パッケージリスト:
.B \-link
オプションでは、javadoc ツールによって生成された
.BR package-list
という名前のファイルが、このオプションで指定する URL に存在している
必要があります。
.BR package-list
ファイルは、その場所でドキュメント化されているパッケージの
名前のリストを含む単純なテキストファイルです。
前の例では、
.B javadoc
ツールは、指定された URL にある
.BR package-list
という名前のファイルを探し、パッケージ名を読み込んで、
その URL にあるそれらのパッケージへのリンクを作成しました。
.LP
たとえば、Java プラットフォーム v5.0 API のパッケージリストは以下にあり、
.na
\f2http://java.sun.com/j2se/1.5.0/docs/api/package\-list\fP
.RE
.LP
次のような内容で始まっています。
.LP
.RS
.ft 3
.nf
java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
その他 ...
.fi
.ft 1
.RE
.LP
.B \-link
オプションを指定せずに
.B javadoc
ツールを実行した場合、ドキュメントの生成時に外部参照
クラスに属する名前を
見つけると、
.B javadoc
はその名前をリンクを持たない形で出力します。一方、
.B \-link
オプションが指定されている場合、
.B javadoc
ツールは、指定された
.IR extdocURL
の場所にある
.B package-list
ファイルから、該当する名前のパッケージを探します。パッケージ名が
見つかった場合は、その
.IR extdocURL
を名前の前に付けます。
.LP
すべてのリンクが正しく機能するためには、外部参照の
ドキュメントのすべてが、指定された URL に
存在していなければなりません。
.B javadoc
ツールは、
.B package-list
が存在するかどうかを調べるだけで、指定された URL に
目的のページが存在するかどうかはチェックしません。
.LP
.B 複数のリンク:
複数の
.B \-link
オプションを提供して、外部で生成されたドキュメントに任意数のリンクを設定できます。Javadoc 1.2 には、複数の
.B -link
コマンドを提供できないというバグがあります。このバグは、
1.2.2 で修正されました。
.LP
リンクする外部ドキュメントごとに別のリンクオプションを指定します。
.LP
.RS
.ft 3
.nf
% javadoc \-link extdocURL1 \-link extdocURL2 ... \-link extdocURLn com.mypackage
.fi
.ft 1
.RE
.LP
.BR extdocURL1、
.BR extdocURL2、...
.BR extdocURLn
は、それぞれ外部ドキュメントの
ルートを指し、各ルートには、
.BR package-list
という名前のファイルが含まれています。
.LP
クロスリンク - まだ生成されていない 2 つ以上のドキュメントを
クロスリンクする場合は、「ブートストラッピング」が必要になることに
注意してください。言い換えると、どのドキュメントの
.B package-list
も存在していない場合、最初のドキュメントに対して
.B javadoc
ツールを実行した時点では、2 番目のドキュメントの
.B package-list
はまだ存在していません。したがって、外部リンクを作成するには、
2 番目のドキュメントを
生成したあと、最初のドキュメントを生成し直す必要があります。
.LP
この場合、最初に行うドキュメント生成の目的は、
.B package-list
を作成することです。パッケージ名をすべて把握している場合は、
.B package-list
を手動で作成することもできます。次に、2 番目のドキュメントと
その外部リンクを生成します。
.B javadoc
ツールは、必要な外部の
.B package-list
ファイルが存在しない場合は、警告を表示します。
.TP
.BI \-linkoffline " extdocURL packagelistLoc"
このオプションは、
.BR \-link
オプションを変えたものです。どちらも、javadoc で
生成された外部参照クラスのドキュメントへのリンクを作成します。
.B Javadoc
ツールが「オフライン」で、Web 上のドキュメントに
リンクする場合は、Web 接続経由ではドキュメントに
アクセスできないため、
.B \-linkoffline
オプションを使用します。
.LP
厳密には、外部ドキュメントの \f2package\-list\fP ファイルにアクセスできないとき、またはこのファイルが \f2extdocURL\fP で指定された場所とは異なる場所 (通常、\f2packageListLoc\fP で指定可能なローカルな場所) に存在するとき、\f2\-linkoffline\fP を使用します。したがって、\f2extdocURL\fP に WWW 上でしかアクセスできない場合は、\f2\-linkoffline\fP を指定することにより、ドキュメントの生成時に javadoc ツールが Web に接続できなければならないという制約がなくなります。
.LP
さらに、ドキュメントを更新するための「ハッキング」としての使用も可能です。パッケージのセット全体に対して javadoc を実行したあと、変更した一部のパッケージだけに対して javadoc を実行します。こうして、更新されたファイルを、オリジナルのファイルセットに挿入できるようにします。例をあとで示します。
.LP
.BR \-linkoffline
オプションには 2 つの引数があります。1 つは
<a href> リンクに埋め込む文字列、もう 1 つは
.BR package-list:
の検索場所を示します。
.LP
.RS
.TP 2
\(bu
.I extdocURL
は、\f3javadoc\f1 によって生成され、リンク先として指定する
外部ドキュメントがあるディレクトリの絶対
URL または相対 URL です。 相対リンクの場合、
生成先ディレクトリ (\-d で指定) からの相対パスを、
リンク先パッケージのルートに渡す必要があります。 詳細は、
.B \-link
オプションの
.I extdocURL
を参照してください。
.TP 2
\(bu
.I packagelistLoc
には、外部ドキュメントの
.B package-list
ファイルが入っているディレクトリのパスまたは
URL を指定します。 URL (http: または file:)
またはファイルパスを指定できます。
また、絶対パスと相対パスのどちらでもかまいません。
相対パスの場合は、javadoc が実行される現在の
ディレクトリからの相対パスとして指定します。
.BR package-list
というファイル名は含めないでください。
.LP
.B javadoc
の 1 回の実行で、複数の
.B \-linkoffline
オプションを指定できます。
1.2.2 より前のバージョンでは、複数のオプションは指定できませんでした。
.LP
外部ドキュメントへの絶対リンクを使った例 -
.BR java.lang
、
.BR java.io
、およびその他の Java 2 プラットフォームパッケージ (\f2http://java.sun.com/j2se/1.5.0/docs/api\fP)
にリンクしたくても、Web にアクセスできない
場合について考えてみます。
.BR package-list
ファイルをブラウザで開き (\f2http://java.sun.com/j2se/1.5.0/docs/api/package\-list\fP)、
ローカルディレクトリに保存します。
次に、2 番目の引数
.I packagelistLoc
でそのローカルコピーを指定します。このとき
パッケージリストファイルは現在のディレクトリ
「.」に保存されています。 次のコマンドは、
Java 2 プラットフォームパッケージへのリンクを含む、
com.mypackage パッケージのドキュメントを生成します。
生成されたドキュメントには、たとえばクラスツリー内の
Object クラスへのリンクが含まれています
(\-sourcepath などの他の必要なオプションは表示されません)。
.LP
.RS
.ft 3
.nf
% \fP\f3javadoc \-linkoffline http://java.sun.com/j2se/1.5.0/docs/api . com.mypackage\fP
.fi
.ft 1
.RE
.LP
外部ドキュメントへの相対リンクを使った例 -
.B \-linkoffline
を相対パスで指定するのはあまり一般的ではありません。通常は、
.B \-link
で十分だからです。
.B \-linkoffline
を使用している場合、
.BR package-list
ファイルは通常ローカルで、相対リンクを使用している場合は、
リンク先のファイルもローカルであるのが普通です。
そのため、
.B \-linkoffline
に 2 つの異なる引数のパスを
与える必要はありません。 2 つの引数が同じである場合、
.B \-link
を使用できます。
.B \-link
の相対リンクの使用例を参照してください。
.LP
package-list ファイルの手動作成 -
.BR package-list
ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルのコピーを自分で作成し、
.I packagelistLoc
でそのパスを指定することができます。
com.apipackage が最初に作成されたときに
com.spipackage のパッケージリストが存在しなかった、
以前の場合がその例です。
この方法は、パッケージ名はわかっているものの、
まだ公開されていない、新しい外部ドキュメントにリンクする
ドキュメントを生成する場合に便利です。
また、Javadoc 1.0 または 1.1 では package-list ファイルが
生成されないため、この方法で、これらのバージョンで
生成されたパッケージの package-list ファイルを生成できます。
2 つの会社が未公開の package-list ファイルを
共有することもできるため、クロスリンクを設定した
ドキュメントを同時にリリースすることも可能です。
.LP
複数のドキュメントにリンク -
.B \-linkoffline
は、参照先の生成ドキュメントごとに 1 つずつ指定します。
次の例では、わかりやすくするために
オプションごとに行を分けています。
.LP
.RS
.ft 3
.nf
.ta 18n
% javadoc \-linkoffline docURL1 packagelistURL1 \\
\-linkoffline docURL2 packagelistURL2 \\
.ft 1
...
.fi
.RE
.LP
.B ドキュメントの更新:
.B \-linkoffline
オプションのもう 1 つの用途は、プロジェクトで多数のパッケージを使い、
すでにツリー全体に対して
.B javadoc
を実行してある場合に、次の実行では、すばやく細かい
変更を行なってから、ソース
ツリーの一部に対してだけ
.B javadoc
を実行し直したい場合に便利です。これは、
変更がドキュメンテーションコメントに対し
てであり、シグニチャに対してではない場合にだけ正常に
処理されるので、ハッキング
のようなものです。ソースコードに対してシグニチャを追加、
削除または変更した場合は、索引、パッケージツリー、
継承されるメンバのリスト、[使用] ページなどの場所
で壊れたリンクが表示されます。
.LP
まず、新しい実行のため、新規の
生成先ディレクトリ (update) を作成します。オリジナルの生成先ディレクトリを html とします。もっとも簡単な例として、html の親に移動します。
.B \-linkoffline
の 1 番目の引数に現在のディレクトリ「.」を
設定し、2 番目の引数に package-list
を検索する場所である html への相対パスを設定します。更新したいパッケージのパッケージ名のみを渡します。
.LP
.RS
.ft 3
.nf
% javadoc \-d update \-linkoffline . html com.mypackage
.fi
.ft 1
.RE
.LP
.B javadoc
の実行が終了したとき、
.B update/com/package
内に生成されたクラス (概要や索引ではない) で、
html/com/package 内にあるオリジナルのファイルを上書きコピーします。
.TP
\-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\f4すべての\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
.BI \-group " groupheading packagepattern:packagepattern:..."
概要ページの複数のパッケージを指定のグループに分け、
グループ単位で表を作成
します。各グループは、それぞれ別の
.B \-group
オプションで指定します。これらのグループは、
コマンド行で指定した順序でページに
表示されます。パッケージは、1 つのグループ内では
アルファベット順に並べられます。各
.B \-group
オプションでは、
.I packagepattern
式のリストに一致する
パッケージが、見出し
.IR groupheading
を持つ 1 つの表にまとめて表示されます。
.RS
.TP 2
\(bu
.I groupheading
には任意のテキストを指定でき、空白を含めることができます。
指定したテキストは、グループの表見出しになります。
.TP 2
\(bu
.I packagepattern
には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (*)を指定できます。
アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。ワイルドカードとして許容されるのは、アスタリスクだけです。1 つのグループには、
コロン (:) で区切った複数のパターンを含めることができます。
.LP
注: パターンやパターンリスト内でアスタリスクを
使う場合は、"java.lang*:java.util"
のように、パターンリストを引用符で囲む必要があります。
.LP
.B \-group
オプションが 1 つも指定されていない場合は、すべての
パッケージが、[パッケージ]
という見出しを持つ 1 つのグループに入れられます。
ドキュメント化されるパッケージの
中に、指定したグループのどのグループにも入らない
パッケージがある場合、このような
パッケージは [その他のパッケージ] という見出しを
持つ独立したグループに入れられます。
.LP
たとえば、次のようにオプションを指定すると、
ドキュメント化される 4 つのパッケージは、
コアパッケージ、拡張機能パッケージ、
およびその他のパッケージに分かれます。
\f3java.lang*\f1 では、後続のドットがないことに
注意してください。\f3java.lang.*\f1 のようにドットを
入れると、
.B java.lang
パッケージは含まれないことになります。
.LP
.RS
.ft 3
.nf
% javadoc \-group "Core Packages" "java.lang*:java.util"
\-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new
.fi
.ft 1
.RE
.LP
この結果、次のようなグループ化が行われます。
.LP
.RS
.ft 3
.nf
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new
.fi
.ft 1
.RE
.RE
.TP
.B \-nodeprecated
推奨されない API をドキュメントに生成することを禁止します。
これは、
.B \-nodeprecatedlist
オプションを指定した場合の動作に加えて、
ドキュメントのほかの部分を通じて、
推奨されない API を生成しないことと同じです。
このオプションは、コードを記述していて、
推奨されないコードを無視したい場合に便利です。
.TP
.B \-nodeprecatedlist
推奨されない API のリストを含む
ファイル (\f3deprecated-list.html\f1) の生成を禁止
します。また、このページへのリンクを
ナビゲーションバーに生成することを禁止します。
ただし、ドキュメントのほかの部分では、
推奨されない API の生成を続行します。この
オプションは、推奨されない API がソースコードに
含まれておらず、ナビゲーションバーを
すっきりと見せたい場合に便利です。
.TP
.B \-nosince
生成されるドキュメントから、
.BR @since
タグに関連した「Since」セクションを削除します。
.TP
.B \-notree
生成されるドキュメントからクラスおよびインタフェース
階層を省略します。これらのページには、ナビゲーションバーの「ツリー」ボタンからアクセスできます。
デフォルトでは、階層が作成されます。
.TP
.B \-noindex
生成されるドキュメントから索引を省略します。
デフォルトでは、
索引が作成されます。
.TP
.B \-nohelp
各出力ページの最上部と最下部の
ナビゲーションバーから [ヘルプ] リンクを
省略します。
.TP
.B \-nonavbar
生成されるページの最上部と最下部に表示される
ナビゲーションバー、ヘッダ、
およびフッタの生成を禁止します。
このオプションは、bottom オプションには影響しません。
.B \-nonavbar
オプションは、印刷するためだけに
ファイルを PostScript または PDF に変換する
場合など、内容だけが重要でナビゲーションの
必要性がない場合に便利です。
.TP
.BI \-helpfile " path/filename"
上部と下部のナビゲーションバーの [ヘルプ] リンクの
リンク先となる代替ヘルプファイル
.I path/filename
のパスを指定します。このオプションが指定されていない場合、
.B javadoc
は、javadoc にハードコードされているヘルプファイル
.B help-doc.html
を自動的に作成します。このオプションを使えば、
デフォルトの設定をオーバーライドでき
ます。ファイル名にはどのような
名前も指定でき、\f3help-doc.html\f1 には限定されま
せん。
.B javadoc
は、それに従って、ナビゲーションバーにある
リンクに調整を加えます。
次に例を示します。
.LP
.RS
.RS
.ft 3
.nf
% javadoc \-helpfile /home/doc/myhelp.html java.awt
.fi
.RE
.RE
.ft 1
.TP
.BI \-stylesheetfile " path/filename"
代替 HTML スタイルシートファイルのパスを指定します。
このオプションが指定されてい
ない場合、
.B javadoc
ツールは、内部的にハードコードされている
スタイルシートファイル
.BR stylesheet.css
を自動的に作成します。このオプションを使えば、
デフォルトの設定をオーバーライドできます。
filename にはどんなファイル名でも指定でき、
.BR stylesheet.css
には限定されません。
次に例を示します。
.LP
.RS
.RS
.ft 3
.nf
% javadoc \-stylesheetfile /home/user/mystylesheet.css com.mypackage
.fi
.ft 1
.RE
.RE
.TP
.B \-serialwarn
.B @serial
タグがない場合、コンパイル時に警告を生成します。デフォルトでは、
.B javadoc
1.2.2 (およびそれ以降) は
.B @serial
の警告を生成しません。
(これは、以前のバージョンとは逆です。)
.B @serial
の警告を生成するには、
このオプションを使用してください。このオプションは、デフォルトの
直列化可能なフィールドと writeExternal メソッドを正しく
ドキュメント化するのに役立ちます。
.TP
.BI \-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 タグについては、
.fi
http://www.w3.org/TR/REC\-html40/charset.html#h\-5.2.2
の
.na
\f2HTML の標準\fP (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 オプションを組み込むことをお勧めします。今回の実行で出力されないタグは、\f2X\fP を付けて無効にします。
.LP
コロン (\f4:\fP) は常に区切り文字になります。\f2tagname\fP でコロンを使用するには、「タグ名でのコロンの使用」を参照してください。
.LP
\f2\-tag\fP オプションは、タグの見出し「\f2taghead\fP」を太字で出力します。その次の行には、このオプションの引数で指定したテキストが続きます。以下の例を参照してください。ブロックタグと同様、この引数のテキストにはインラインタグを含めることができます。このインラインタグも解釈されます。出力は、引数を 1 つ取る標準のタグ (\f2@return\fP、\f2@author\fP など) の出力とよく似ています。\f2taghead\fP を省略すると、\f2tagname\fP が見出しとして表示されます。
.LP
\f3タグの配置\fP \- 引数の \f4Xaoptcmf\fP 部分は、ソースコード内のタグを配置できる位置と、\f2X\fP を使ってこのタグを無効にできるかどうかを特定します。タグの配置位置を制限しない場合は \f4a\fP を指定します。それ以外の文字の組み合わせも可能です。
.br
\f4X\fP (タグの無効化)
.br
\f4a\fP (すべての位置)
.br
\f4o\fP (概要)
.br
\f4p\fP (パッケージ)
.br
\f4t\fP (型すなわちクラスおよびインタフェース)
.br
\f4c\fP (コンストラクタ)
.br
\f4m\fP (メソッド)
.br
\f4f\fP (フィールド)
.LP
シングルタグの例 -
ソースコードの任意の場所で使用できる
タグのタグオプションの例を示します。
.LP
.RS
.TP 3
\-tag todo:a:"To Do:"
.RE
.LP
コンストラクタ、メソッド、およびフィールドだけで @todo を
使用させるには、次のようにします。
.LP
.RS
.ft 3
.nf
\-tag todo:cmf:"To Do:"
.fi
.ft 1
.RE
.LP
上記では、末尾のコロン (:) がパラメータの
区切り記号ではなく、表示のとおり、
見出しテキストの一部であることに注意してください。
次のように、@todo タグを含むソースコードに
どちらかのタグオプションを使用します。
.LP
.RS
.ft 3
.nf
@todo The documentation for this method needs work.
.fi
.ft 1
.LP
タグ名にコロンを使用する \-
コロン (:) をバックスラッシュでエスケープすると、
コロンをタグ名に使用することができます。
.LP
.RS 5
.nf
/**
* @ejb:bean
*/
.RE
.fi
.LP
でこのタグオプションを使用すると、
.LP
.RS 5
.nf
\-tag ejb\\:bean:a:"EJB Bean:"
.RE
.LP
となります。
.fi
.ft 1
.RE
.LP
タグ名のスペルチェック (タグの無効化) - 開発者は、ソースコードの中で出力できないカスタムタグを使用することがあります。その場合、ソースタグに存在するすべてのタグをリストし、出力するタグを有効化し、出力しないタグを無効化することが重要です。 X を使用するとタグを無効化でき、これがない場合はタグが有効となります。 この文字の存在によって、
.B Javadoc
ツールは、検出したタグが未知のタグで、おそらく綴り間違いであると判断できます。 この場合、警告メッセージが表示されます。
.LP
すでに存在する、配置を指定する引数の値に X を追加した場合、タグを有効にしたいときに X を削除できます。 たとえば、@todo が出力したくないタグの場合、次のようにします。
.LP
.RS
.ft 3
.nf
\-tag todo:Xcmf:"To Do:"
.fi
.ft 1
.RE
.LP
または、次のようにより簡単にすることもできます。
.LP
.RS
.ft 3
.nf
\-tag todo:X
.fi
.ft 1
.RE
.LP
\-tag todo:X の構文は、@todo がタグレットで
定義されている場合も有効です。
.LP
タグの順序 -
\-tag (および \-taglet) オプションの順序に従って
タグが出力されます。 カスタムタグと標準タグを
混在させることができます。 標準タグのタグオプションは、
順序を決定するためだけのプレースホルダです。
これらは標準タグ名だけを使用します
(標準タグの小見出しは変更できません)。
これを次の例に示します。
.LP
\-tag がない場合、\-taglet の場所によってその順序が決まります。
この 2 つが両方ある場合は、コマンド行の最後に使用された方が
順序を決定します (これは、タグとタグレットが、
コマンド行で使用された順に処理されるためです)。
たとえば、\-taglet と \-tag が両方とも todo という
名前である場合、コマンド行の最後で使用された
方が順序を決定します。
.LP
タグの完全なセットの例 -
この例では、出力の Parameters と Throws の間に
To Do を挿入します。 「X」を使用して、@example が
ソースコード内の今回の実行で出力されないタグで
あることを指定できます。 @argfile を使用すると、
次のように行の継続文字なしで、
引数ファイルの異なる行にタグを配置できます。
.LP
.RS
.ft 3
.nf
\-tag param
\-tag return
\-tag todo:a:"To Do:"
\-tag throws
\-tag see
\-tag example:X
.fi
.ft 1
.RE
.LP
javadoc がドキュメンテーションコメントを解析する際に、
検出されたタグのうち、標準タグでもなく、
\-tag や \-taglet で渡されるタグでもないものは、
不明なタグとして認識し、警告がスローされます。
.LP
標準タグは、最初、デフォルトの順序で
リスト内部的に格納されます。
\-tag オプションを使用すると、このタグがリストに追加されます。
標準タグはデフォルトの位置から移動します。
そのため、標準タグで \-tag オプションが省略されると、
デフォルトの位置に配置されたままになります。
.LP
競合の回避 -
固有のネームスペースを細かく分けるには、
パッケージに使用されている com.mycompany.todo
という名前のように、ドット (.) を区切り記号とする名前を使います。
Sun は今後もドットを含まない標準タグを作成します。
ユーザが作成したタグは、Sun が定義した同じ
名前のタグの動作をオーバーライドします。
つまり、ユーザが @todo という名前のタグまたは
タグレットを作成していた場合、そのあとで Sun が
同じ名前の標準タグを作成しても、ユーザが定義した
動作はそのまま維持されます。
.LP
\f3注釈 vs. Javadoc タグ\fP \- 一般に、追加する必要のあるマークアップが、ドキュメンテーションに影響を与えたりドキュメンテーションを生成したりするためのものである場合、そのマークアップは javadoc タグにすべきです。それ以外の場合は注釈にすべきです。
.na
「\f2Comparing Annotations and Javadoc Tags\fP」
.fi
(http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#annotations) を参照してください。
.LP
\-taglet オプションを使用して、より複雑な
スタンドアロンタグやカスタムインラインタグを
作成することができます。
.TP
\-taglet class
タグのドキュメントの生成に使うタグレットを起動するための
クラスファイルを指定します。
クラスの完全修飾名を指定してください。
このタグレットは、カスタムタグが持っているテキスト引数の
数も定義します。 タグレットはこれらの引数を受け取り、
処理し、出力を生成します。 タグレットの例の詳細については、
タグレットの概要を参照してください。
.LP
タグレットはスタンドアロンタグまたはインラインタグに
使用すると便利です。 タグレットでは任意の
数の引数を持つことができ、カスタムの動作を実装できます。
たとえば、テキストを太字にしたり、箇条書き形式にしたり、
テキストをファイルに書き出したり、
他のプロセスを起動したりすることができるのです。
.LP
タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガするなどの副作用は得られます。
.LP
タグレットへのパスを指定するには、
.B \-tagletpath
オプションを使用します。
生成されたページの Parameters と Throws の間に
To Do タグレットを挿入する例を示します。
.LP
.RS
.ft 3
.nf
\-taglet com.sun.tools.doclets.ToDoTaglet
\-tagletpath /home/taglets
\-tag return
\-tag param
\-tag todo
\-tag throws
\-tag see
.fi
.ft 1
.RE
.LP
.B \-taglet
オプションを
.B \-tag
オプションの代わりに使用することもできますが、
その結果、読みにくくなります。
.TP
\-tagletpath tagletpathlist
taglet クラスファイル (.class) を探すための検索パスを指定します。
.I tagletpathlist
には、コロン (:) で
区切って複数のパスを含めることができます。
.B Javadoc
ツールは、指定されたパス以下のすべての
サブディレクトリを検索します。
.TP
\-docfilessubdirs
doc-files ディレクトリを、下の階層を含めてコピー
できるようにします。 つまり、サブディレクトリとすべての
コンテンツが、生成先ディレクトリに再帰的にコピーされます。
たとえば、
.BR doc-files/example/images
ディレクトリとその中のファイルがコピーされます。
サブディレクトリを除外するためのオプションもあります。
.TP
\-excludedocfilessubdirs name1:name2:...
doc-files のサブディレクトリで、指定された
名前のものを除外します。 このオプションを使用すると、
SCCS およびその他のソースコード管理の
サブディレクトリをコピーしないようにできます。
.TP
\-noqualifier all | packagename1:packagename2:...
修飾パッケージ名を、出力のクラス名の前から削除します。
\-noqualifier の引数は
all (すべてのパッケージ修飾子を削除)、
またはコロンで区切られたパッケージリストの
いずれかで、修飾子として削除されます。
ワイルドカードも使用できます。
パッケージ名はクラス名またはインタフェース名が
表示されたところから削除されます。
.LP
次の例では、すべてのパッケージ修飾子を省略します。
.LP
.RS
.ft 3
.nf
\-noqualifier all
.fi
.ft 1
.RE
.LP
次の例では、パッケージ修飾子 java.lang
および java.io を省略します。
.LP
.RS
.ft 3
.nf
\-noqualifier java.lang:java.io
.fi
.ft 1
.RE
.LP
次の例では、java および com.sun から
始まる (javax を除く)
サブパッケージのパッケージ修飾子を削除します。
.LP
.RS
.ft 3
.nf
\-noqualifier java.*:com.sun.*
.fi
.ft 1
.RE
.LP
パッケージ修飾子が上記の動作に従って表示される場合、名前は適切に短くされます。詳細は「名前の表示方法」を参照してください。この規則は、
\-noqualifier が
使用されているかどうかにかかわらず存在します。
.TP
.BI \-notimestamp
タイムスタンプが抑制されます。
各ページ先頭近くにある、生成された HTML 内の
HTML コメントでタイムスタンプが隠されます。
.B Javadoc
を 2 つのソースベースで実行し、それらに対して
diff を実行するときにこのオプションを使用すると、
タイムスタンプによって diff が発生しなくなるので
便利です (このオプションを使用しないと、
各ページで diff になります)。
タイムスタンプには
.B Javadoc
のバージョン番号が含まれており、
次のようになります。
.LP
.RS 5
<!-- Generated by javadoc (build 1.5.0-internal)
on Tue Jun 22 09:57:24 PDT 2004 -->
.RE
.TP
\-nocomment
記述およびすべてのタグを含むコメント
本文全体を抑制し、宣言だけを生成します。
このオプションにより、元は異なる目的のためだった
ソースファイルを再利用し、
新しいプロジェクトのためのスケルトンを
作成できるようになりました。
.SS コマンド行引数ファイル
.BR javadoc
のコマンド行を短くしたり簡潔にしたりするために、
.BR javadoc
コマンドに対する引数 (\-J オプションを除く) が
入った 1 つ以上のファイルを指定することができます。
このことを利用すれば、どのオペレーティングシステム
上でも、任意の長さの
.BR javadoc
コマンドを作成できます。
.LP
引数ファイルには、javac オプションとソースファイル名を
自由に組み合わせて記述できます。
また、Javadoc オプションに対する引数だけを記述してもかまいません。
ファイル内の各引数は、空白文字または改行で区切ります。
ファイル名に空白が含まれている場合は、そのファイル名全体を二重引用符で囲む必要があります。
.LP
.LP
引数ファイル内のファイル名は、
現在のディレクトリから見た相対パスになります。
引数ファイルの位置から見た相対パスではありません。
引数ファイル内のファイル名リストでは、
ワイルドカード (*) は使用できません。
たとえば、*.java とは指定できません。
引数ファイル内の引数で @ 文字を使用して、
複数のファイルを再帰的に解釈することはサポートされていません。
また、\-J オプションもサポートされていません。
このオプションは起動ツールに渡されますが、
起動ツールでは引数ファイルをサポートしていないからです。
.LP
.BR javadoc
を実行するときに、各引数ファイルのパスとファイル名の
先頭に @ 文字を付けて渡します。
.BR javadoc
は、@ 文字で始まる引数を見つけると、
そのファイルの内容を展開して引数リストに挿入します。
.LP
引数ファイルを 1 つ指定する例
.LP
argfile という名前の引数ファイルにすべての
Javadoc 引数を格納し、次のように使用することができます。
.LP
.RS
.ft 3
.nf
% javadoc @argfile
.fi
.ft 1
.RE
.LP
この引数ファイルには、次の例で示されている
2 つのファイルの内容を両方とも入れることができます。
.LP
引数ファイルを 2 つ指定する例
.LP
Javadoc オプション用に 1 つ、パッケージ名またはソースファイル名用に
1 つというように、2 つの引数ファイルを作成し、
次のようにして使用することができます。
なお、このあとのリストでは、行の継続文字を使用していません。
.LP
以下の内容を含む options という名前のファイルを作成します。
.LP
.RS
.ft 3
.nf
\-d docs-filelist
\-use
\-splitindex
\-windowtitle 'Java 2 Platform v1.3 API Specification'
\-doctitle 'Java<sup><font size="-2">TM</font></sup> 2\\
Platform 5.0 API Specification'
\-header '<b>Java 2 Platform </b><br><font size="-1">5.0</font>'
\-bottom 'Copyright 1993-2000 Sun Microsystems, Inc. All Rights Reserved.'
\-group "Core Packages" "java.*"
\-overview /java/pubs/ws/1.5/src/share/classes/overview-core.html
\-sourcepath /java/pubs/ws/1.5/src/share/classes
.fi
.ft 1
.RE
.LP
以下の内容を含む packages という名前のファイルを作成します。
.LP
.RS
.ft 3
.nf
com.mypackage1
com.mypackage2
com.mypackage3
.fi
.ft 1
.RE
.LP
そのあと、次のコマンドを使用して javadoc を実行します。
.LP
.RS
.ft 3
.nf
% javadoc @options @packages
.fi
.ft 1
.RE
.LP
パス付きの引数ファイルの例
.LP
引数ファイルには、パスを指定できます。
ただし、そのファイル内に指定されたファイル名は、
現在の作業ディレクトリから見た相対パスになります。
つまり、下の例の場合は、path1 や
path2 から見た相対パスではありません。
.LP
.RS
.ft 3
.nf
% javadoc @path1/options @path2/packages
.fi
.ft 1
.RE
.LP
オプションの引数の例
.LP
次に、javadoc オプションに対する引数だけを引数ファイルに
格納する例を示します。 ここでは、\-bottom オプションを
例に取り上げます。そのオプションには、
かなり長い引数を指定することがあるからです。
まず、このオプションのテキスト引数になる
次のような内容を含む、bottom という名前の
ファイルを作成します。
.LP
'<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">
Submit a bug or feature</a><br><br>Java is a
trademark or registered trademark of
Sun Microsystems, Inc. in the US and other
countries.<br>Copyright 1993-2000 Sun
Microsystems, Inc. 901 San Antonio Road,<br>Palo
Alto, California, 94303, U.S.A.
All Rights Reserved.</font>'
.LP
そのあと、次のようにして
.B javadoc
ツールを実行します。
.LP
.TP 3
% javadoc \-bottom @bottom @packages
.LP
また、引数ファイルの先頭に
\-bottom オプションを組み込んでおけば、次のようにして実行できます。
.LP
.RS
.ft 3
.nf
% javadoc @bottom @packages
.fi
.ft 1
.RE
.TP
.SH 実行
.SS Javadoc の実行
バージョン番号 -
.LP
javadoc のバージョン番号は
.BR javadoc \-J\-version
を使用することで確認できます。
標準ドックレットのバージョン番号は出力ストリームに
表示されます。
これは \-quiet オプションでオフにできます。
.LP
プログラムから利用できる public インタフェース -
Java 言語で書かれたプログラム内から
.B javadoc
ツールを呼び出します。
このインタフェースは
.BR com.sun.tools.javadoc.Main
(javadoc は再入)
にあります。 詳細は、「標準ドックレット」
を参照してください。
.LP
\f3ドックレットの実行\fP \-
下記の説明は、標準 HTML ドックレットを呼び出すためのものです。カスタムドックレットを呼び出すには、\-doclet および \-docletpath オプションを使用します。特定のドックレットを実行した完全な例については、
.na
「\f2Running the MIF Doclet\fP」
.fi
(http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet) を参照してください。
.LP
.SH "使用例"
.B javadoc
は、パッケージ全体に対して実行することも、
個々のソースファイルに対して実行することも
できます。各パッケージ名は、それぞれの
パッケージ名に対応するディレクトリ名を
持ちます。次の例では、ソースファイルは
.BR /home/src/java/awt/*java
にあります。生成先ディレクトリは
.BR /home/html
です。
.SS "1 つ以上のパッケージのドキュメント化"
パッケージをドキュメント化するには、その
パッケージのソースファイル (*\f3.java\f1)
が、パッケージと同じ名前を持つディレクトリ
内に存在していなければなりません。
パッケージ名が複数の識別子で構成されている
(java.awt.color のように、各識別子はドットで
区切られている) 場合は、後続の各識別子が下位の
サブディレクトリに対応して
いなければなりません (java/awt/color など)。
1 つのパッケージのための複数のソースファイルを、
異なる場所にある 2 つのディレクトリツリーに分けて
格納することも可能です
(
.BR src1/java/awt/color
と
.BR src2/java/awt/color
など)。
ただし、その場合は、\-sourcepath によって、
その両方の場所を指定しなければなりません。
.LP
.B javadoc
を実行するには、cd コマンドを使って
ディレクトリを変更するか、
または
.B \-sourcepath
オプションを使用します。
それぞれの例を次に示します。
.TP 2
\(bu
.B ケース 1 - 1 つ以上のパッケージからの起動を再帰的に実行 -
この例では javadoc が任意のディレクトリから実行できるように、
.BR \-sourcepath
を使用し、再帰的処理のために -subpackages (1.4 の新オプション) を使用します。 これは、java のサブパッケージ (
.BR java.net
および
.BR java.lang
をルートとするパッケージを除く) を処理します。
これによって
.BR java.lang.ref (
.BR java.lang
のサブパッケージ) が
除外されることに注意してください。
.LP
.RS
.ft 3
.nf
% javadoc \-d /home/html \-sourcepath /home/src \-subpackages java \-exclude java.net:java.lang
.fi
.ft 1
.RE
.LP
他のパッケージツリーを処理するには、
.BR java:javax:org.xml.sax
のように、その名前を
.BR \-subpackages
引数に追加します。
.TP 2
\(bu
.B ケース 2 - ルートソースディレクトリに移ってから明示的なパッケージを実行 -
完全修飾パッケージの
親ディレクトリに移動します。
次に、ドキュメント化する
1 つ以上のパッケージ名を指定して
.BR javadoc
を実行します。
.LP
.RS
.ft 3
.nf
% cd /home/src/
% javadoc \-d /home/html java.awt java.awt.event
.fi
.ft 1
.RE
.TP 2
\(bu
.B ケース 3 - 任意のディレクトリから実行。ソースファイルは 1 つのディレクトリツリー内にある - このケースでは、現在のディレクトリがどこであってもかまいません。 トップレベルのパッケージの親ディレクトリを
.B \-sourcepath
に指定し、ドキュメント化する 1 つ以上のパッケージ名を指定して、
.B javadoc
を実行します。
.LP
.RS
.ft 3
.nf
% javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
.fi
.ft 1
.RE
.TP 2
\(bu
.B ケース 4 - 任意のディレクトリから実行。ソースファイルは複数のディレクトリツリー内にある - これはケース 3 と似ていますが、パッケージが複数のディレクトリツリーに存在します。 各ツリーのルートへのパスを
.B \-sourcepath
に指定し (コロンで区切る)、ドキュメント化する 1 つ以上のパッケージ名を指定して、javadoc を実行します。 1 つのパッケージのすべてのソースファイルが、1 つのルートディレクトリの下に存在しなければならない、ということはありません。ソースパスとして指定された場所のどこかで見付かれば十分です。
.LP
.RS
.ft 3
.nf
% javadoc \-d /home/html \-sourcepath /home/src1:/home/src2 java.awt java.awt.event
.fi
.ft 1
.RE
.LP
結果: どちらのケースでも、パッケージ
.B java.awt
と
.B java.awt.event
の public および protected
なクラスとインタフェースを対象に、HTML 形式の
ドキュメントが生成され、指定
された生成先ディレクトリ (\f3/home/html\f1) に HTML ファイルが
保存されます。2 つ
以上のパッケージが生成されるので、ドキュメントは、
パッケージのリスト、クラスのリスト、
およびメインページの 3 つのフレームを持つことになります。
.SS "1 つ以上のクラスのドキュメント化"
.B javadoc
ツールを実行する 2 番目の方法は、1 つ以上のソースファイル (
.B .java
) を渡すことです。
.B javadoc
は、次の 2 つのどちらかの方法で実行できます。
1 つは、(cd によって) ディレクトリを
変更する方法、もう 1 つは
.B .java
ファイルへのパスを完全指定する方法です。
相対パスは、現在のディレクトリからの相対パスです。
ソースファイルを渡した場合、
.B \-sourcepath
オプションは無視されます。
アスタリスク (*) の
ようなコマンド行ワイルドカードを使用すると、
クラスのグループを指定できます。
.TP 2
\(bu
.B ケース 1 ソースディレクトリへの移動:
.B .java
ファイルのあるディレクトリに移動します。
次に、ドキュメント化する 1 つ以上の
ソースファイルの名前を指定して
.BR javadoc
を実行します。
.LP
.RS
.ft 3
.nf
% cd /home/src/java/awt
% javadoc \-d /home/html Button.java Canvas.java Graphics*.java
.fi
.ft 1
.RE
.LP
.RS 2
この例では、クラス Button と Canvas、
および先頭が Graphics で始まるクラスの
HTML 形式のドキュメントが生成されます。
.BR javadoc
の引数として渡されているのは、
パッケージ名ではなくソースファイルなので、
ドキュメントは、クラスのリストと
メインページの 2 つのフレームを持つことになります。
.RE
.TP 2
\(bu
.B ケース 2 パッケージのルートディレクトリへの移動:
これは、同じルート内にある複数のサブパッケージのソースファイルを個々に
ドキュメント化する場合に便利です。パッケージの
ルートディレクトリに移動し、各ソースファイルを
ルートからのパスで指定します。
.LP
.RS
.ft 3
.nf
% cd /home/src/
% javadoc \-d /home/html java/awt/Button.java java/applet/Applet.java
.fi
.ft 1
.RE
.LP
.RS 2
この例では、Button クラスおよび Applet クラス
用の HTML 形式のドキュメント
が生成されます。
.RE
.TP 2
\(bu
.B ケース 3 すべてのディレクトリから:
このケースでは、現在のディレクトリがどの
ディレクトリでも問題はありません。
ドキュメント化する
.B .java
ファイルへの絶対パスまたは
相対パスを指定して
.BR javadoc
を実行します。
.LP
.RS
.ft 3
.nf
% javadoc \-d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java
.fi
.ft 1
.RE
.LP
.RS 2
この例では、クラス
.B Button
および先頭が
.BR Graphics
で始まるクラスの HTML 形式
のドキュメントが生成されます。
.RE
.SS "パッケージとクラスのドキュメント化"
パッケージ全体と個々のクラスを同時にドキュメント
化できます。次に示すのは、上に示
した 2 つの例を組み合わせた例です。
.B \-sourcepath
は、パッケージへのパスに対しては使用できますが、
個々のクラスのパスに対しては使用
できません。
.LP
.RS
.ft 3
.nf
% javadoc \-d /home/html \-sourcepath /home/src java.awt /home/src/java/applet/Applet.java
.fi
.ft 1
.RE
.LP
この例では、パッケージ
.B java.awt
とクラス
.B Applet
の HTML 形式のドキュメントが
生成されます。
.B javadoc
は、Applet のパッケージ名を、
.B Applet.java
ソースファイル内のパッケージの宣言 (宣言がある場合) から決定します。
.SS "使用例"
.B javadoc
ツールには、多くの便利なオプションがあり、
その中のいくつかは、ほかのオプションよりもよく
使われます。以下は、makefile 変数を使って Java プラット
フォーム API 上で
.B javadoc
ツールを実行するために使う効果的なコマンドです。
ここでは 180M バイトのメモリを使用して、
Java 2 Platform, Standard Edition, v1.2 に
存在する、約 1500 個の public および protected
クラスについてドキュメントを生成します。
.LP
同じ例を 2 回掲載します。最初の例はコマンド行から実行するもので、2 番目の例は Makefile から実行するものです。 オプションの引数に絶対パスを使用しているため、任意のディレクトリからこの
.B javadoc
コマンドを実行できます。
.SS コマンド行の例
次のコマンド行の例は 900 文字を超えているため、
DOS などのシェルには大きすぎます。
この制限を回避するには、コマンド行
引数ファイルを使用します。
または、シェルスクリプトを記述します。
.LP
.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 2 Platform 5.0 API Specification' \\
.fl
\-doctitle 'Java<sup><font size="\-2">TM</font></sup> 2 Platform 5.0 API Specification' \\
.fl
\-header '<b>Java 2 Platform </b><br><font size="\-1">5.0</font>' \\
.fl
\-bottom '<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit
.fl
a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems,
.fl
Inc. in the US and other countries.<br>Copyright 1993\-1999 Sun Microsystems, Inc.
.fl
901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</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
.LP
上記のコマンドで、packages は、
処理対象のパッケージ名 (
.BR java.applett
.BR java.lang など) が
入っているファイルの名前です。 各オプションの、
単一引用符で囲まれた引数の内側には、
改行文字を挿入できません。 たとえば、
この例をコピー＆ペーストする場合は、
.B \-bottom
オプションから改行文字を削除してください。
さらに、このあとの「注」も参照してください。
.SS Makefile の例
ここでは、GNU Makefile の例を示します。
Windows の Makefile の例については、
.na
「\f2creating a makefile for Windows\fP」
.fi
(http://java.sun.com/j2se/javadoc/faq/index.html#makefiles) を参照してください。
.LP
.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 2 Platform v1.2 API Specification'
.fl
DOCTITLE = 'Java<sup><font size="\-2">TM</font></sup> 2 Platform v1.2 API Specification'
.fl
HEADER = '<b>Java 2 Platform </b><br><font size="\-1">v1.2</font>'
.fl
BOTTOM = '<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit
.fl
a bug or feature</a><br><br>Java is a trademark or registered trademark
.fl
of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993\-1999
.fl
Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.
.fl
All Rights Reserved.</font>'
.fl
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
.fl
GROUPEXT = '"Extension Packages" "javax.*"'
.fl
SRCDIR = '/java/jdk/1.2/src/share/classes'
.fl
\fP
.fi
.LP
.LP
Makefile の引数は、単一引用符で囲みます。
.SS 注
.TP 2
\(bu
.B \-windowtitle
オプションを省略すると、
.B Javadoc
ツールによってドキュメントタイトルが
ウィンドウタイトルにコピーされます。
.B \-windowtitle
のテキストは、基本的に
.B \-doctitle
と同じです。ただし、HTML タグは使用しません。
HTML タグは、ウィンドウタイトルにそのままの
テキストとして表示されてしまいます。
.TP 2
\(bu
この例のように
.B \-footer
オプションを省略すると、
.B Javadoc
ツールによってヘッダテキストが
フッタにコピーされます。
.TP 2
\(bu
この例では必要ありませんが、
.B \-classpath
および
.BR \-link
も重要なオプションです。
.LP
.SH トラブルシューティング
.SS 一般的なトラブルシューティング
.TP 2
\(bu
Javadoc FAQ - よく問題となるバグや
トラブルシューティングの
ヒントは
.na
「\f2Javadoc FAQ\fP」
.fi
(http://java.sun.com/j2se/javadoc/faq/index.html#B) にあります。
.TP 2
\(bu
バグおよび制限事項 - また、バグの一部は、
.na
「\f2Important Bug Fixes and Changes\fP」
.fi
(http://java.sun.com/j2se/1.5.0/fixedbugs/index.html) でも参照できます。
.TP 2
\(bu
バージョン番号 - バージョン番号を参照してください。
.TP 2
\(bu
有効なクラスだけをドキュメント化 -
javadoc がパッケージをドキュメント化するとき、
有効なクラス名で構成されているファイルだけを
読み込むようになりました。
ファイル名にハイフン (-) などを含めることで、
javadoc がファイルを解析しないようにできます。
.SS エラーと警告
エラーメッセージおよび警告メッセージには、
ファイル名と宣言行に対する行番号が
含まれますが、doc コメントの特定の
行に対する行番号は含まれません。
.TP 2
\(bu
"error: cannot read: Class1.java" -
.B Javadoc
ツールは現在のディレクトリの
.BR Class1.java
クラスを読み込もうとしています。
クラス名は、絶対パスまたは相対パスで表示されます。
この場合、./Class1.java と同じです。
.LP
.SH "環境"
.TP 20
.SB CLASSPATH
環境変数は、
.B javadoc
がユーザクラスファイルを探すときに使う、パスを指定します。環境変数は、
.B \-classpath
オプションによってオーバーライドされます。ディレクトリは
コロンで分割します。たとえば、
次のとおりです。
.RS 15
.sp 1n
.B .:/home/classes:/usr/local/java/classes
.RE
.br
.ne 11
.SH "関連項目"
.LP
.RS 3
.TP 2
o
javac
.TP 2
o
java
.TP 2
o
jdb
.TP 2
o
javah
.TP 2
o
javap
.TP 2
o
.fi
http://java.sun.com/j2se/javadoc/index.jsp
の
.na
「\f2Javadoc Home Page\fP」
.TP 2
o
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
の
.na
「\f2How to Write Doc Comments for Javadoc\fP」
.TP 2
o
クラスパスの設定
.TP 2
o
javac と javadoc がクラスを検索する方法 (tools.jar)
.RE
.LP
.LP
Javadoc は、Sun Microsystems, Inc の商標です (\f2javadoc\fP コマンド自体には商標シンボルは不要)。