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 つを選択することができます。@seeclassname の中のホワイトスペースは重要です。引数が 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) {
       ...
    }

オプション

javadocdoclets を使用して出力フォーマットを決定します。もし、-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