javadoc - Java API ドキュメントジェネレーター
Java ソースファイルから API ドキュメンテーションの HTML ページを生成します。
形式
javadoc [ options ] [ package | source.java ]*
機能説明
javadoc は、Java ソースファイル等から宣言とドキュメンテーションコメントを解析し
HTMLページを生成します。デフォルトでは、public, protected なクラス、インナークラス、インタフェース、コンストラクタ、メソッドおよびフィールドに関する記述。javadoc
の引数として、一連の Java パッケージ名または Java ソースファイルを渡すことができます。
javadoc は、それが遭遇する各 .java ファイルおよび各パッケージに対して、1
つの .html ファイルを生成します。さらに、クラス階層 (tree.html) と階層のメンバのインデックス
(AllNames.html) を生成します。
javadoc がクラスとメンバの宣言を解析するとき、それらのシグネチャも取得します。それ以外にも、ソースコードに
doc コメントを入れてさらに詳しいドキュメンテーションを追加することができます。
javadoc Doclets
doclets を使用して javadoc が生成する内容やフォーマットをカスタマイズすることができます。詳細は
JDKに含まれている Javadoc Doclets の詳細な解説を読んでね。
-doclet コマンドラインオプションを指定しない場合、javadoc はデフォルトの doclet を使用して
HTML 形式のドキュメントを生成します。
ソースコードコメント
ソースコードにはドキュメンテーションコメントを入れることができます。doc コメントは、始まりが
/** 、終わりが */ に囲まれた文字より構成されています。テキストは 1 行または複数の行に分かれます。javadoc
が doc コメントを解析するとき、各行の先頭の文字 * は破棄されます。 コメントの始まりの行以外のコメント行では、*
の前の空白およびタブも破棄されます。これらのコメントには HTML タグが含まれる可能性があります。以下に
doc コメントを示します:
/**
* This is a <b>doc</b> comment.
*/
各 doc コメントの最初の文は要約文にし、続いて簡潔に、しかし実際の宣言を完全に説明します。この文は、あとに空白、タブや行終了文字が続く最初のピリオド、または最初のタグ行で (次に定義するように)終了します。javadoc はこの最初の文を
.html ファイルの上部のメンバサマリーにコピーします。
ドキュメンテーションコメントは、クラス、インタフェース、コンストラクタ、メソッドおよびフィールド宣言の直前に置かれたときだけ認識されます。
docコメント内に HTML タグを埋め込むとき、<h1> や <h2> のようなヘッディングタグは使用してはいけません。なぜなら、javadoc
は一つの構造化されたドキュメントを作成するからです。ヘッディングタグによって、これらの構造的なドキュメントのフォーマットを作成するのを妨害してしまうからです。
ドキュメンテーションコメントの仕様については、Java Language Specification
の第 18 章「ドキュメンテーションコメント」(James Gosling、Bill Joy、Guy Steele
共著)を参照してください。
タグ付きパラグラフ
javadoc は、特別なタグが Java doc コメント内に組み込まれた際に、それを識別し、解析します。これらの
doc タグにより、完全でよくフォーマットされた API を、ソースコードから自動的に生成することができます。タグは記号
@ で始めます。
タグは行の先頭から始めなければなりません。同じ名前のタグは 1 つの docコメント内でまとめてください。たとえば、javadoc
がリストの最後を示すことができるように、すべての @author タグを1 つにしてください。
タグは次の 3 つのカテゴリに分かれます:クラス/インタフェースタグ、フィールドタグ、そしてコンストラクタ/メソッドタグです。各々、次の節で箇条書きにして説明しています。
クラスおよびインタフェースドキュメンテーションタグ
@author name-text
- "Author" エントリを作成します。このテキストには特別な内部構造はありません。doc
コメントには
@author タグが複数あることもあります。
@version version-text
- "Version"エントリを追加します。このテキストには特別な内部構造はありません。
@version タグは、1 つの doc コメントに対し 1 つです。バージョンとは通常、特定の機能を含むソフトウェア
(JDKなど) のバージョンを参照します。
@see classname
- クラスに "See Also" エントリを追加します。クラスとメンバはjavadoc によって自動的にハイパーリンク形式になります。クオートで囲まれた文字列は、URL参照を持たないbooks
や他のエントリーとして使われます。たとえば、以下のとおりです:
@see java.lang.String
@see String
@see String#equals
@see java.lang.Object#wait(int)
@see Character#MAX_RADIX
@see <a href="spec.html">Java Spec</a>
@see "The Java Programming Language"
文字 # は、クラス名をフィールド名、メソッド名およびコンストラクタ名の1つから分離します。
メソッド名およびコンストラクタ名の後に括弧で囲んだ引数タイプのリストを挿入することにより、オーバーロードする複数のメソッドおよびコンストラクタから
1 つを選択することができます。@see の classname の中のホワイトスペースは重要です。引数が
1 つ以上ある場合、引数の間にあるブランクは 1 つでなければなりません。 たとえば、以下のとおりです:
@see java.io.File#File(java.io.File, java.lang.String)
doc コメントには複数の @see タグが含まれることがあります。
@since since-text
- "Since" エントリを追加します。このテキストには特別な内部構造はありません。このタグは、特定の変更または機能が、since-text
によって指定されるソフトウェア (JDKなど) のリリース番号以来、継続して存在することを意味します。
@deprecated deprecated-text
- 将来、使われなくなる(使わなくなる)かもしれない APIに対して デプリケートコメントを追加します。APIが置き換わる様な場合にも使われます。たとえば、以下のとおりです:
@deprecated Replaced by setBounds(int, int, int, int).
もし、メンバーが旧式で置き換えることがない様な場合、 @deprecated の引き数は
"No replacement" となります。
このタグの詳細は JDKのドキュメントの @deprecated に付いて書かれている部分を 参照して下さい。
クラスコメントの例:
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version %I%, %G%
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
フィールドドキュメンテーションタグ
フィールドコメントに含めることができるのは @see , @since ,
@deprecated タグ (前に説明) だけです。
フィールドコメントの例:
/**
* The X-coordinate of the window.
*
* @see window#1
*/
int x = 1263732;
コンストラクタおよびメソッドドキュメンテーションタグ
@see タグを入れることができます。上記参照。
@param parameter-name description
- "Parameters" セクションにパラメータを加えます。説明は次の行に続くこともあります。
@return description
- 返り値の説明を含む "Returns" セクションを追加します。
@exception fully-qualified-class-name description
or
@throws fully-qualified-class-name description
- "Throws" エントリを追加します。これにはメソッドがスローする例外の名前が含まれ
ます。例外はクラスドキュメンテーションにリンクされます。
@throws タグは
@exception の類語として使われるかも知れません。
@see classname
- メソッドにハイパーリンクされた "See Also" エントリを追加します。このタグについては上述しています。
@since since-text
- このタグについては上述しています。
@deprecated deprecated-text
- このタグについては上述しています。
メソッド doc コメントの例:
/**
* 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) {
...
}
オプション
javadoc は doclets を使用して出力フォーマットを決定します。もし、-doclet
オプションが使われなかった場合、デフォルトで用意されている doclets を使用します。Javadoc
は、コマンドラインオプションで指定することによって、いかなる docletをも使用することができます。
Javadoc オプション
- -doclet filename
- 指定した doclets ファイルをもとにHTML 形式のドキュメントを生成します。もし、-doclet
オプションが使われなかった場合、デフォルトで用意されている doclets を使用します。
- -public
- public クラスおよびメンバだけを表示します。
- -protected
- protected と public のクラスとメンバだけを表示します。これがデフォルトです。
- -package
- package、protected、public のクラスおよびメンバだけを表示します。
- -private
- すべてのクラスとメンバを表示します。
- -Jflag
- flag を直接ランタイムシステムに渡します。たとえば、作成されたドキュメンテーションを保持するために
32 メガバイトのメモリを確実に確保しておく必要がある場合、このフラグを次のように使用します:
- javadoc -J-mx32m -J-ms32m <classes> ...
- -encoding name
- UCJIS/SJIS などのソースファイルのエンコーディング名を指定します。このオプションを指定しない場合、プラットフォームのデフォルトのコンバータが使用されます。
- -overview path
- path によって指定されたファイルを Overviewドキュメントとして指定します。
Javadoc は、Overviewファイル中のボディー HTML タグ (<body>, </body>)で囲まれた部分を取ります。それは
HTMLとして解釈され、パッケージインデックスファイル (packages.html) にアルファベット順にリンク形式でリストされます。
- -sourcepath path
- ソースファイルを探すための検索パスを指定します。このオプションは、クラスファイルのローディングに影響ありません。ユーザが指定する
sourcepath は、javadoc コマンドへの引数としてパッケージまたはクラスを指定するかどうかに依存します。
パッケージのドキュメントを生成する場合、ドキュメントを作成する対象となる最上位の親パッケージを含むのソースツリーのディレクトリを
sourcepath に指定します。sourcepath のデフォルトは、カレントの classpath ディレクトリとなります。たとえば、そのソースファイルが以下に示すディレクトリに位置しており、
java.lang という名前のパッケージをドキュメント化したい場合:
/myapp/src/share/java/lang/*.java
java が最上位の親パッケージであるため、 sourcepath には、java を含んでいるディレクトリを指定するのが適切です。
-sourcepath /myapp/src/share
個々のクラスのドキュメントを生成する場合には、ドキュメントを作成する対象のクラスを含むソースツリーのディレクトリを
sourcepath に指定します。パッケージのドキュメント化時に使用した sourcepath の場合とは異なることに注意してください。たとえば、そのソース
ファイルが以下に示すディレクトリに位置しており、 java.lang.String という名前のクラスをドキュメント化したい場合:
/myapp/src/share/java/lang/String.java
sourcepath にString.java クラスを含んでいるディレクトリを指定します。
-sourcepath /myapp/src/share/java/lang
既に、指定するはずのディレクトリに移動している場合には、sourcepath オプションを省略することができます。
- -classpath path
- NOTE: -classpathオプションは使用しないで下さい。なぜなら通常は -sourcepath
オプションを使用するからです。
javadoc が .java ファイルを調べるためのパスを指定します。また、javadoc
が自分の .class ファイルをロードするディレクトリを指定します。(ソースパスを別に指定する場合は、-sourcepath
を使用してください。) 各pathの要素は最上位のパッケージを含むディレクトリにすることが必要です。デフォルト、または
CLASSPATH 環境 変数の設定をオーバーライドします。path
は、コロン(UNIX版)やセミコロン(Windows版)で分割します。以下に 2 つパスを指定した例を示します。初めのパスは現在のディレクトリ(.)です:
javadoc -classpath .:/home/opus/myclasses myPackage.MyClass
-classpath オプションは、javadoc ラッパースクリプトを直接呼び出す場合は不要です。通常、classpath
を指定する場合、これを sourcepath の前に置く必要があります。しかし、ラッパースクリプトを使用する場合、これら
2 つのオプションの順番は問題になりません。
classpath のデフォルト値は、現在のディレクトリに CLASSPATH
環境 変数で設定された位置を加えたものです。
標準 Doclet のためのオプション
- -linkall
- 全てのクラスが参照するための API ドキュメントのリンクを生成します。例えば、 -linkall
オプション無しで java.awt パッケージの Graphics.java ファイルを指定した場合:
javadoc /home/me/java/awt/Graphics.java
Graphics.toString メソッドの HTML は javadoc によって以下の様に生成されます。
<pre>
public String toString()
</pre>
String クラスへのリンクが作られていません。もし、-linkall オプションを指定したなら:
javadoc -linkall /home/me/java/awt/Graphics.java
以下の様に String クラスへのリンクが生成されます。
<pre>
public <a href="java.lang.String.html#_top_">String</a> toString()
</pre>
- -version
- @version タグを入れます。デフォルトでは省略されます。
- -author
- @author タグを入れます。デフォルトでは省略されます。
- -noindex
- パッケージ索引を省略します。デフォルトでは生成します。
- -notree
- クラス / インタフェース階層を省略します。デフォルトでは生成します。
- -nodeprecatedlist
- デプリケーテッド API のリストファイル(deprecatedlist.html)を生成しません。
- -nohelp
- それそれのページの上下にあるナビゲーションバーに HELP リンクを生成しません。
- -helpfile path
- HELPリンクにリンクされるヘルプファイルのパスを指定します。
- -d directory
- javadoc が HTML ファイルを格納する宛先ディレクトリを指定します。("d"
は"destination" を表す) ディレクトリは現在作業しているディレクトリに対して、絶対または相対パス指定です。たとえば、java.lang
パッケージにドキュメンテーションを作成し (探すためには CLASSPATH を使用して)、-d
オプションで指定したディレクトリに結果を格納するには、以下の様に指定します:
javadoc -d /home/opus/public_html/doc java.lang
- -nodeprecated
- @deprecated タグを含むパラグラフを除外します。
- -docencoding name
- 出力 HTML ファイルのエンコーディング名を指定します。
- -breakindex
- インデックスファイルを複数のファイルに分ける。アルファベット毎のファイルとアルファベットで始まらないインデックスのためのファイル。
- -title title
- パッケージインデックスファイルのタイトルを指定します。タイトルは、上のナビゲーションバーの下にセンタリングされて置かれます。クオートを使用することでHTMLタグやスペースを含めることができます。エスケープ文字を使用してクォーテーションも
title に含めることができます。
- -header header
- それぞれ出力するファイルのヘッダーを挿入します。ヘッダーは、上のナビゲーションバーの右端に置かれます。クオートを使用することでHTMLタグやスペースを含めることができます。エスケープ文字を使用してクォーテーションも
header に含めることができます。
- -footer footer
- それぞれ出力するファイルのフッターを挿入します。フッターは、下のナビゲーションバーの右端に置かれます。クオートを使用することでHTMLタグやスペースを含めることができます。エスケープ文字を使用してクォーテーションも
footer に含めることができます。
- -bottom text
- それぞれ出力するファイルの最後にテキストを挿入します。テキストは、下のナビゲーションバーの下に置かれます。クオートを使用することでHTMLタグやスペースを含めることができます。エスケープ文字を使用してクォーテーションもtext
に含めることができます。
サンプル
それぞれのパッケージは、それに対応するディレクトリ名を持ちます。以下の例では、ソースファイルは/home/ws/src/java/awt/*java
に位置しています。格納先のディレクトリは /home/ws/html です。
1 つ以上のパッケージのドキュメント作成
パッケージのドキュメント化は、ソースファイル(*.java)が、パッケージと同じ名前を持つディレクトリーに置かれていなければなりません。もし、パッケージが(ドットによって分けられた)いくつかの識別子によって構成されているなら、識別子と同じディレクトリーにソースファイルが置かれていなければなりません。つまり、すべての
java.awt クラスはディレクトリー java/awt/ になければなりません。
最初に、最上位のパッケージの親ディレクトリに移動します (または sourcepath オプションにそのディレクトリを与えます)。次に、1
つ以上のパッケージ名を与えて javadoc を実行します。
% cd /home/ws/src/
% javadoc -d /home/ws/html java.awt java.awt.event
パッケージ java.awt および java.awt.event の public クラスに対して HTML フォーマットのドキュメンテーションを作成し、それを指定したディレクトリ(/home/ws/html )に置きます。
1 つ以上のクラスのドキュメント作成
クラスを保持するディレクトリに移動します (または sourcepath オプションにそのディレクトリを与えます)。次に、1
つ以上のクラス名を与えて javadoc を実行します。
% cd /home/ws/src/java/awt
% javadoc -d /home/ws/html Button.java Canvas.java
2 つのクラスに対して HTML フォーマットのドキュメンテーションを作成します。
環境変数
- CLASSPATH
- ユーザ定義クラスへのパスをシステムに指定します。ディレクトリはコロン(UNIX版)やセミコロン(Windows版)で分割します。たとえば、
UNIXの場合
.:/home/me/classes:/usr/local/java/classes.jar
Windowsの場合
.;C:\home\me\classes;C:\java\classes.jar
|