【Java】Javadocの書き方とHTMLドキュメントの生成方法

今回は、Javadocの書き方について説明します。この記事を読むことで、Javadocの書き方や実際に開発現場でよく使われている4つのJavadocタグ。またHTMLドキュメントの生成方法がわかるようになります。

Javadocの書き方
まとめ

Javadocの書き方

Javadocは、Java言語のソースコードから「プログラムについて説明するドキュメント」を生成する仕組みです。Javadocを書くことで、「何をするメソッドなのか」「引数にはどんな値を入れればいいのか」「エラーが出た時、どんな条件で例外が発生するのか」一目でわかるようになります。

javadocの書き方は下記になります。

/**
* これがJavadoc用のコメントの書き方です。
*/

実際にサンプルコードを見て、開発現場でよく使用する4つのJavadocタグについてみていきましょう！

サンプルコード

/**
 * 電卓クラス。
 * 足し算・引き算・掛け算・割り算を行うメソッドを提供します。
 *
 * @author GPTBLOG
 */
public class Calculator {

    /**
     * 2つの数値を足し算します。
     *
     * @param a 足す数1
     * @param b 足す数2
     * @return 計算結果
     */
    public int add(int a, int b) {
        return a + b;
    }

    /**
     * 2つの数値を引き算します。
     *
     * @param a 引かれる数
     * @param b 引く数
     * @return 計算結果
     */
    public int subtract(int a, int b) {
        return a - b;
    }

    /**
     * 2つの数値を掛け算します。
     *
     * @param a 掛ける数1
     * @param b 掛ける数2
     * @return 計算結果（a × b）
     */
    public int multiply(int a, int b) {
        return a * b;
    }

    /**
     * 2つの数値を割り算します。
     *
     * @param a 割られる数（分子）
     * @param b 割る数（分母）
     * @return 計算結果（a ÷ b）
     * @throws IllegalArgumentException 割る数が0の場合例外が発生
     */
    public double divide(int a, int b) {
        if (b == 0) {
            throw new IllegalArgumentException("0で割ることはできません");
        }
        return (double) a / b;
    }
}

@author → 作成者

@param → パラメータに関する説明

@return → 戻り値に関する説明

@throws → 発生する可能性のある例外に関する説明

基本的には説明文を書き、パラメータ（@param）、戻り値（@return）を書きます。必要があれば、作成者(@author)や例外(@throws)についても書きます。

私が今常駐している開発現場ではこの４つをよく使っていますが、他にもjavadocタグは存在します。

Javadocタグ - Javadocの記述

Javadocタグ

コマンドを使ってJavadocを出力する

サンプルコードを Calculator.java として保存し、ターミナルからJavadocをHTMLとして生成してみたいと思います。Javadocを出力するには、まずファイルのあるディレクトリに移動し、次のコマンドを入力します。

javadoc ファイル名

今回であれば…

javadoc Calculator.java

になります。

実際にコマンドを実行すると、複数のHTMLファイルとサブフォルダが生成されます。

フォルダ内にファイルやフォルダが散らかって見にくい場合は、以下のように出力先フォルダを指定して実行すると整理できます。

javadoc -d 出力先フォルダ名 ファイル名

フォルダ名をdocとして実行すると…

javadoc -d doc Calculator.java

docフォルダ内にJavadoc 関連のファイルとフォルダがまとめて生成されます。

生成されたJavadocはdoc/index.html(※) を開くとブラウザで確認できます！

※index.htmlはJavadoc全体のトップページ。クラス一覧、パッケージ一覧、ナビゲーションがまとまっていて、ここから目的のクラスに移動できます。

これが今回作ったサンプルコードのJavadocになります！

avadocタグまとめ

タグ	用途	使用例
`@param`	引数を説明	`@param a 足す数1`
`@return`	戻り値を説明	`@return 計算結果`
`@throws` / `@exception`	発生する可能性のある例外を説明	`@throws IllegalArgumentException 引数が不正な場合`
`@author`	作成者を記載	`@author` GPTBLOG
`@deprecated`	非推奨メソッドやクラスを示す	`@deprecated 代わりに newMethod を使ってください`
`@version`	クラスやファイルのバージョンを記載	`@version 1.0`
`@since`	メソッドやクラスがいつから利用可能かを示す	`@since 1.0`
`@see`（参照リンク）	関連クラスやメソッドへの参照を示す	`@see java.util.List`
`@see`（テキスト・外部リンク）	関連する参考情報やWebページへのリンクを示す	`@see <a href="https://example.com">公式ドキュメント</a>`
`{@link}`	コード内にハイパーリンクを作る（短文・インライン用）	`{@link java.util.List}` → リンクとして表示
`{@linkplain}`	コード内にハイパーリンクを作るが、表示は通常テキスト（読みやすい）	`{@linkplain java.util.List}` → 通常テキストでリンク