javadoc - Java API ドキュメンテーションジェネレータ

Java ソースファイルから API ドキュメンテーションの HTML ページを生成します。

機能説明

javadoc [ options ] [ package | source.java ]*

説明

javadoc は、Java ソースファイルセットにおける宣言とドキュメンテーションコメントを解析し、デフォルトでは、public もしくは protected なクラス、インタフェース、構築子、メソッドおよびフィールドを記述した HTML ページを作成します。javadoc の引数として、一連の Java パッケージ名または Java ソースファイルを渡すことができます。
javadoc は、それが遭遇する各 .java ファイルおよび各パッケージに対して、1 つの .html ファイルを生成します。さらに、クラス階層 (tree.html) と階層のメンバのインデックス (AllNames.html) を生成します。
javadoc がクラスとメンバの宣言を解析するとき、それらのシグナチャも取得します。それ以外にも、ソースコードに doc コメントを入れてドキュメンテーションを追加することができます。

ソースコードコメント

ソースコードにはドキュメンテーションコメントを入れることができます。doc コメントは、コメントの始まりに /** 、コメントの終わりに */ を付けて、それではさむ文字よりなっています。テキストは 1 行または複数の行に分かれます。javadoc が doc コメントを解析するとき、各行の先頭の文字 * は破棄されます。最初の行以外の行では、* の前の空白およびタブもまた、破棄されます。これらのコメントには HTML タグが含まれる可能性があります。次に doc コメントを示します:
/**
 * This is a <b>doc</b> comment.
 */
各 doc コメントの最初の文は要約文にし、その文でエンティティ宣言を簡潔に、しかし完全に説明します。この文は、あとに空白、タブまたは行終了文字が続く最初のピリオド、または最初のタグ行で (次に定義するように)、終了します。javadoc は最初の文を .html ファイルの上部のメンバ要約にコピーします。
ドキュメンテーションコメントは、クラス、インタフェース、構築子、メソッドおよびフィールド宣言の直前に置かれたときだけ認識されます。
docコメント内に HTML タグを埋め込むとき、<h1> や <h2> のようなヘッディングタグは使用しません。なぜなら、javadoc は構造化されたドキュメント全体を作成し、これらの構造的なタグが作成するドキュメントのフォーマットを妨害してしまうからです。
ドキュメンテーションコメントの仕様については、Java 言語仕様の第 18 章「ドキュメンテーションコメント」(James Gosling、Bill Joy、Guy Steele 共著)を参照してください。

タグ付きパラグラフ

javadoc は、特別なタグがJava doc コメント内に組み込まれたとき、識別し、解析します。これらの doc タグにより、完全で、よくフォーマットされた API をソースコードから自動的に生成することができます。タグは記号 @ で始めます。
行の先頭はタグで始めます。同じ名前のタグは 1 つの docコメント内ではまとめてください。たとえば、javadoc がリストの最後を示すことができるように、すべての @author タグを１つにしてください。
タグは次の 3 つのカテゴリに分かれます: クラス/インタフェースタグ、フィールドタグ、および構築子/メソッドタグです; 各々は次の節で箇条書きにして説明しています。

クラスおよびインタフェースドキュメンテーションタグ

@author name-text
"Author" エントリを作成します。このテキストには特別な内部構造はありません。doc コメントには @author タグが複数あることもあります。

@version version-text
"Version"エントリを追加します。このテキストには特別な内部構造はありません。@version タグは、1 つの doc コメントに対し 1 つ以下です。バージョンとは通常、特定の機能を含むソフトウェア (JDKなど) のバージョンを指します。

@since since-text
"Since" エントリを追加します。このテキストには特別な内部構造はありません。このタグは、特定の変更または機能が、since-text によって指定されるソフトウェア (JDKなど) のリリース番号以来、継続して存在することを意味します。

@see classname
クラスにハイパーリンクする "See Also" エントリを追加します。たとえば、次のとおりです。
    @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>
文字 # は、クラス名をフィールド名、メソッド名および構築子名の1つから分離します。メソッド名および構築子名の後に括弧で囲んだ引数タイプのリストを挿入することにより、オーバーロードする複数のメソッドおよび構築子から１つを選択することができます。@see の classname の中のホワイトスペースは重要です。引数が 1 つ以上ある場合、引数の間にあるブランクは 1 つにします。たとえば、次のとおりです。
    @see java.io.File#File(java.io.File, java.lang.String)
doc コメントには複数の @see タグが含まれることがあります。
クラスコメントの例
/**
 * 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 タグ (前に説明) だけです。
フィールドコメントの例:
    /**
     * 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
"Throws" エントリを追加します。これにはメソッドがスローする例外の名前が含まれます。例外はクラスドキュメンテーションにリンクされます。
@see classname
メソッドにハイパーリンクしている "See Also" エントリを追加します。このタグについては上述しています。

メソッド 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) {
       ...
    }

オプション

-classpath path
javadoc が .java ファイルを調べるためのパスを指定します。また、javadoc が自分の .class ファイルをロードするディレクトリを指定します。(ソースパスを別に指定する場合は、-sourcepath を使用してください。) 各pathの要素は最上位のパッケージを含むディレクトリにすることが必要です。デフォルト、または CLASSPATH 環境変数の設定をオーバーライドします。pathには、コロンで分けられたパスを複数入れることができます。次に 2 つパスを指定した例を示します。初めのパスは現在のディレクトリ(.)です:
javadoc -classpath .:/home/opus/javasrc
-classpath オプションは、javadoc ラッパースクリプトを直接呼び出す場合は不要です。通常、classpath を指定する場合、これを sourcepath の前に置く必要があります。しかし、ラッパースクリプトを使用する場合、これら 2 つのオプションの順番は問題になりません。
classpath のデフォルト値は、現在のディレクトリにクラスの位置を加えたものです。
-public
public クラスおよびメンバだけを表示します。

-protected
protected と public のクラスとメンバだけを表示します。これがデフォルトです。

-package
package、protected、public のクラスおよびメンバだけを表示します。

-private
すべてのクラスとメンバを表示します。

-J flag
flag を直接ランタイムシステムに渡します。たとえば、作成されたドキュメンテーションを保持するために 32 メガバイトのメモリを確実に確保しておく必要がある場合、このフラグを次のように使用します:
javadoc -J-mx32m -J-ms32m ltclassesgt ...
-encoding name
EUCJIS/SJIS などのソースファイルのエンコーディング名を指定します。このオプションを指定しない場合、プラットフォームのデフォルトのコンバータが使用されます。

-docencoding name
出力 HTML ファイルのエンコーディング名を指定します。

-version
@version タグを入れます。デフォルトでは省略されます。

-author
@author タグを入れます。デフォルトでは省略されます。

-noindex
パッケージ索引を省略します。デフォルトでは生成します。

-notree
クラス / インタフェース階層を省略します。デフォルトでは生成します。

-d directory
javadoc が HTML ファイルを格納する宛先ディレクトリを指定します。("d" は "destination" を表す) ディレクトリは現在作動しているディレクトリに対して、絶対または相対指定です。たとえば、java.lang パッケージにドキュメンテーションを作成し (探すためには CLASSPATH を使用して)、-d オプションで指定したディレクトリに結果を格納するには、次のようにします。
javadoc -d /home/opus/public_html/doc java.lang
-verbose
verbose オプションを指定しない場合、ソースファイルのローディング時、ドキュメンテーションの生成時 (1 つのソースファイルに 1 つのメッセージ)、およびソート時にメッセージが現われます。verbose オプションにより、各 Java ソースファイルを解析するためにかかったミリ秒の数などの追加メッセージを表示します。

-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 オプションを省略することができます。
-nodeprecated
@deprecated タグ付きのパラグラフを除外します。

注意: -doctype オプションは利用できなくなりました。HTML ドキュメンテーションだけが作成できます。

例

各パッケージは、それに対応するディレクトリ名を持ちます。次の例では、ソースファイルは /home/ws/src/java/awt/*java に位置しています。格納先のディレクトリは /home/ws/html です。
1 つ以上のパッケージのドキュメント作成
最初に、最上位のパッケージの親ディレクトリに移動します (またはそのディレクトリに 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
ユーザ定義クラスへのパスをシステムに指定します。ディレクトリはコロンで分割します。たとえば、次のとおりです。
.:/home/avh/classes:/usr/local/java/classes

参照

javac, java, jdb, javah, javap,