資料６．JavaDocの書き方と出力

資料６．JavaDocの書き方と出力

JavaDocとは

JavaDocとは、Javaのソースコードに書いた特殊なコメントをもとに、HTML形式のAPI仕様書を自動生成する仕組みです。JDKに付属する javadoc コマンドがその変換を行います。

Javaの標準ライブラリのAPIリファレンス（Oracle公式ドキュメント）も、JavaDocによって生成されています。自分で作ったクラスやメソッドにJavaDocコメントを書いておくと、同じ形式のHTML文書を簡単に生成できます。

JavaDocは通常のコメント（// 〜 や /* 〜 */）とは異なり、/** で始まり */ で終わるコメントブロックです。

JavaDocコメントの書き方

クラスへのコメント

クラス宣言の直前に書きます。クラスの目的・概要を記述します。

/**
 * 2つの整数の計算を行うクラス。
 * 足し算・引き算・掛け算・割り算をサポートする。
 *
 * @author 山田太郎
 * @version 1.0
 */
public class Calc {
    // ...
}

フィールドへのコメント

フィールド宣言の直前に書きます。そのフィールドが何を表すかを記述します。

public class Circle {

    /** 円の半径（単位：cm） */
    public double radius;

}

メソッドへのコメント

メソッド宣言の直前に書きます。処理の概要に加え、引数・戻り値・例外を専用のタグで記述します。

/**
 * 2つの整数を割り算し、結果を返す。
 *
 * @param a 割られる数
 * @param b 割る数（0以外の値を指定すること）
 * @return aをbで割った結果（double型）
 * @throws ArithmeticException bが0の場合にスローされる
 */
public double divide(int a, int b) {
    if (b == 0) {
        throw new ArithmeticException("0で割ることはできません");
    }
    return (double) a / b;
}

主なJavaDocタグ一覧

@param・@return・@throws は順序が決まっています。@param（複数可）→ @return → @throws の順で記述してください。

完成例

クラスとメソッド両方にJavaDocコメントを書いた例です。

/**
 * 商品の価格計算を行うクラス。
 *
 * @author 山田太郎
 * @version 1.0
 */
public class PriceCalc {

    /** 消費税率 */
    private static final double TAX_RATE = 0.10;

    /**
     * 税込み価格を計算して返す。
     *
     * @param price 税抜き価格（0以上の整数）
     * @return 税込み価格（小数点以下切り捨て）
     */
    public int calcTax(int price) {
        return (int)(price * (1 + TAX_RATE));
    }

    /**
     * 複数個まとめて購入した場合の税込み合計金額を返す。
     *
     * @param price 税抜き単価
     * @param count 購入数量（1以上の整数）
     * @return 税込み合計金額
     * @throws IllegalArgumentException countが1未満の場合
     */
    public int calcTotal(int price, int count) {
        if (count < 1) {
            throw new IllegalArgumentException("数量は1以上にしてください");
        }
        return calcTax(price) * count;
    }
}

コマンドラインでのJavaDoc出力

JDKに付属の javadoc コマンドを使ってHTML文書を生成します。

基本的なコマンド

ソースファイルを直接指定する場合です。

javadoc -d doc -encoding UTF-8 -charset UTF-8 PriceCalc.java

コマンド実行後、doc フォルダが作成され、その中の index.html をブラウザで開くとAPIドキュメントが表示されます。

パッケージを使っている場合

ソースファイルがパッケージに属している場合は、プロジェクトのルートディレクトリ（srcフォルダの親）で以下のコマンドを実行します。

javadoc -d doc -encoding UTF-8 -charset UTF-8 -sourcepath src -subpackages パッケージ名

-subpackages を指定すると、指定したパッケージとその配下のサブパッケージが一括で対象になります。

複数ファイルをまとめて処理する場合

パッケージを使っていない場合でも、ワイルドカードで複数ファイルをまとめて指定できます。

javadoc -d doc -encoding UTF-8 -charset UTF-8 *.java

EclipseでのJavaDoc出力

Eclipseのメニューから手順に沿ってダイアログ操作するだけで、JavaDocを生成できます。

手順

1. メニューバーの 「プロジェクト」 をクリックする。
2. 「Javadoc の生成...」 を選択する。
3. Javadocの生成ウィザードが開く。「Javadoc コマンド」 欄に javadoc.exe のパスが設定されていることを確認する（通常は自動設定される）。
4. 「Javadoc を生成するプロジェクト」 欄で、対象のプロジェクトにチェックが入っていることを確認する。
5. 「宛先」 欄で出力先フォルダを指定する（デフォルトはプロジェクト内の doc フォルダ）。
6. 「次へ」 をクリックし、「文書タイトル」などを必要に応じて入力する。
7. さらに 「次へ」 をクリックし、「VM オプション」に -encoding UTF-8 -charset UTF-8 と入力する（文字化け防止のため推奨）。
8. 「完了」 をクリックすると、JavaDocが生成される。

手順7の「VM オプション」の入力欄は「次へ」を2回押した先の画面にあります。日本語を含むコメントを書いている場合は必ず指定してください。

生成されたドキュメントを開く

生成完了後、プロジェクトの doc フォルダ内に index.html が作成されます。Eclipseのパッケージ・エクスプローラーから doc/index.html を右クリックし、「次で開く」→「Webブラウザー」 を選択すると、生成されたAPIドキュメントをそのまま確認できます。