Javadocの書き方｜タグ一覧(@param,@return)と生成コマンド

Javadocとは、ソースコードに書いた専用のコメントから、HTML形式のAPI仕様書を自動で作るJava標準の仕組みです。 コメントは /** で始めて */ で閉じ、1文目に要約、続けて詳しい説明、最後に @param や @return などのタグを並べます。仕様書を作るコマンドは javadoc -d docs -sourcepath src -encoding UTF-8 パッケージ名 です。

この記事では、全タグの一覧表、要素別のコピペ用テンプレート、javadocコマンドのオプション、文字化け対策、ビルドツールやIDEでの生成手順、新しい書き方（{@snippet} とMarkdownコメント）、警告・エラーの直し方をまとめます。コマンドの出力は OpenJDK 21.0.10 の javadoc で実行したものです。Markdownコメントと外部スニペットは JDK 25.0.4.1 の javadoc で確認しました。タグの仕様は、Oracle公式の「JavaDoc Documentation Comment Specification（JDK 25）」と javadoc コマンドのマニュアルを今回開いて確認しています。

Javadocの早見表

Javadocコメントの基本の形

通常のコメントとの違い

/** のようにアスタリスクが2つで始まるコメントだけがJavadocとして読み取られます。書く場所は、クラス・インタフェース・record・enum・コンストラクタ・メソッド・フィールドの宣言の直前です。アノテーションがある場合は、アノテーションよりも前に書きます。

コメントの3つの部分

/**
 * 在庫を取り出し、残りの数を返します。        ← (1) 要約（最初の1文）
 *
 * <p>在庫が足りない場合は例外になります。      ← (2) 詳しい説明（HTMLが使える）
 *
 * @param code 備品コード                      ← (3) ブロックタグ
 * @param quantity 取り出す数
 * @return 取り出したあとの在庫数
 * @throws IllegalStateException 在庫が足りない場合
 */
public int take(String code, int quantity) { ... }

各行の先頭のアスタリスクとその前の空白は、生成時に取り除かれます。

書くときに気をつける文字

説明文はHTMLとして扱われるため、次の文字はそのまま書くとエラーや警告の原因になります。

タグ一覧：ブロックタグ

ブロックタグは、説明のあとに行頭から書くタグです。JDK 25の仕様書に載っている全16種を、書ける場所と導入バージョン付きでまとめます。「書ける場所」の略号は、モ=モジュール、パ=パッケージ、型=クラス・インタフェース・record・enum、コ=コンストラクタ、メ=メソッド、フ=フィールド です。

「慣習的な順」は、広く使われている並べ方（作成者 → バージョン → 引数 → 戻り値 → 例外 → 参照 → 追加バージョン → 直列化 → 非推奨）を番号にしたものです。今回確認した仕様書には並び順の規定は見当たらず、どの順で書いても生成結果の見出し順は javadoc が整えます。チーム内でそろえておくと、ソースを読むときに探しやすくなります。

よく使う5つのタグの書き方

タグ一覧：インラインタグ

インラインタグは、波かっこで囲んで文中に書くタグです。全12種を一覧にします。

リンクの参照先の書き方

{@link} と @see の参照先は同じ形式です。

今回の実行では、{@link Map} と書いた箇所が、JDK 21のAPIドキュメント（docs.oracle.com）へのリンクとして出力されました。標準ライブラリのクラスは、特に設定しなくてもリンクになります。

そのまま使えるテンプレート集

次の3ファイルは、実際に javadoc を実行して警告なしで生成できたものです。src/com/example/stock/ に置いて使います。

クラス・コンストラクタ・メソッド・フィールドのテンプレート

// src/com/example/stock/StockService.java
package com.example.stock;

import java.util.HashMap;
import java.util.Map;

/**
 * 備品の在庫数を管理するクラスです。
 *
 * <p>在庫はメモリ上の {@link Map} に保持します。
 * 使い方は次のとおりです。
 *
 * {@snippet :
 * StockService service = new StockService();
 * service.add("pen", 10);
 * int left = service.take("pen", 3);   // @highlight substring="take"
 * }
 *
 * @author RJC Sample
 * @version 1.2
 * @since 1.0
 * @see Item
 */
public class StockService {

    /** 1回の操作で扱える最大数（{@value}）。 */
    public static final int MAX_QUANTITY = 1000;

    private final Map<String, Integer> stock = new HashMap<>();

    /**
     * 空の在庫でサービスを作成します。
     */
    public StockService() {
    }

    /**
     * 在庫を追加します。
     *
     * @param code 備品コード。{@code null} は指定できません
     * @param quantity 追加する数。1以上 {@value #MAX_QUANTITY} 以下
     * @throws IllegalArgumentException {@code quantity} が範囲外の場合
     * @throws NullPointerException {@code code} が {@code null} の場合
     */
    public void add(String code, int quantity) {
        if (code == null) throw new NullPointerException("code");
        if (quantity < 1 || quantity > MAX_QUANTITY) throw new IllegalArgumentException("quantity");
        stock.merge(code, quantity, Integer::sum);
    }

    /**
     * 在庫を取り出し、残りの数を返します。
     *
     * @param code 備品コード
     * @param quantity 取り出す数
     * @return 取り出したあとの在庫数
     * @throws IllegalStateException 在庫が足りない場合
     * @see #add(String, int)
     * @since 1.1
     */
    public int take(String code, int quantity) {
        int now = stock.getOrDefault(code, 0);
        if (now < quantity) throw new IllegalStateException("在庫不足");
        stock.put(code, now - quantity);
        return now - quantity;
    }

    /**
     * {@return 指定した備品の在庫数} 登録がない場合は0です。
     *
     * @param code 備品コード
     */
    public int count(String code) {
        return stock.getOrDefault(code, 0);
    }

    /**
     * 在庫数を返します。
     *
     * @param code 備品コード
     * @return 在庫数
     * @deprecated 1.2 から {@link #count(String)} を使ってください。
     */
    @Deprecated(since = "1.2")
    public int getCount(String code) {
        return count(code);
    }
}

recordのテンプレート

recordでは、構成要素（かっこの中の項目）をクラスのコメントの @param で説明します。型パラメータは @param <T> と書きます。

// src/com/example/stock/Item.java
package com.example.stock;

/**
 * 備品1件を表すレコードです。
 *
 * @param code 備品コード
 * @param name 備品名
 * @param <T> 付加情報の型
 * @param extra 付加情報
 * @since 1.0
 */
public record Item<T>(String code, String name, T extra) {
}

パッケージのテンプレート

パッケージの説明は、package-info.java という名前のファイルに書きます。

// src/com/example/stock/package-info.java
/**
 * 備品の在庫を管理するクラスをまとめたパッケージです。
 *
 * @since 1.0
 */
package com.example.stock;

要素別に書くタグの早見表

継承元の説明を引き継ぐinheritDoc

オーバーライドしたメソッドでは、{@inheritDoc} と書くと親の説明を取り込めます。インタフェース Repo の save に説明・@param・@return を書き、実装クラス側で次のように書いて生成しました。

    /**
     * {@inheritDoc}
     *
     * <p>この実装では再起動すると内容が消えます。
     */
    @Override
    public int save(String name) {
        return 1;
    }

生成結果（-locale ja_JP を指定）には、親の「備品名を保存します。」に続いて「この実装では再起動すると内容が消えます。」が表示され、「パラメータ: name - 備品名」「戻り値: 採番したID」も親から引き継がれました。コメントを書かずにオーバーライドした場合も、不足している部分は親の説明が自動で使われます。追記したい内容があるときだけ {@inheritDoc} を使うと、重複を減らせます。

javadocコマンドで生成する

基本のコマンド

javadoc -d docs -sourcepath src \
  -encoding UTF-8 -docencoding UTF-8 -charset UTF-8 \
  -author -version \
  com.example.stock

実行時の出力（OpenJDK 21.0.10、抜粋）:

Loading source files for package com.example.stock...
Constructing Javadoc information...
Creating destination directory: "out1/"
Building index for all the packages and classes...
Standard Doclet version 21.0.10+7-Ubuntu-124.04
Building tree for all the packages and classes...
Generating out1/com/example/stock/Item.html...
Generating out1/com/example/stock/StockService.html...
Generating out1/com/example/stock/package-summary.html...
（中略）
Generating out1/index.html...
Generating out1/help-doc.html...

出力先の index.html をブラウザで開くと、仕様書を確認できます。生成されたHTMLには <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> が入っていました。

対象の指定方法

オプションが増えてきたら、1行に1つずつ書いたテキストファイルを @ファイル名 で渡すと便利です。

-d docs
-sourcepath src
-encoding UTF-8
-docencoding UTF-8
-charset UTF-8
-locale ja_JP
-windowtitle "在庫API"

このファイルを渡して生成すると、index.html のタイトルが <title>在庫API</title> になりました。

主なオプション一覧

確認できた動作をいくつか挙げます。

• -author と -version を付けないと、@author と @version は出力されません。付けた場合だけ「Author:」「Version:」の項目が出ました。
• privateなフィールドは既定では出力されません。-private を付けると、stock フィールドも出力されました。
• -locale ja_JP を付けると、見出しが「パラメータ:」「戻り値:」「例外:」「関連項目:」「導入されたバージョン:」になり、HTMLの lang 属性も ja になりました。付けない場合は、今回の環境では英語（Parameters: など）でした。
• {@return 指定した備品の在庫数} は、英語ロケールでは「Returns 指定した備品の在庫数.」、-locale ja_JP では「指定した備品の在庫数を返します。」 と出力されました。日本語で書くなら -locale ja_JP と組み合わせると自然な文になります。

文字化けを防ぐ3つのオプション

日本語のコメントで文字化けやエラーが出るときは、文字コードの指定を確認します。関係するオプションは3つです。

ソースがUTF-8なら -encoding UTF-8 -docencoding UTF-8 -charset UTF-8 の3つをそろえて指定するのが確実です。

ソースと指定が合わないときのエラーを再現する

Shift_JIS（CP932）で保存したソースを -encoding UTF-8 で読ませると、次のエラーで終了しました（終了コード1）。

sj/demo/Sj.java:4: error: unmappable character (0x8D) for encoding UTF-8

同じソースに -encoding MS932 -docencoding UTF-8 -charset UTF-8 を指定すると正常に生成でき、HTMLには日本語が正しく入りました。

反対に、UTF-8のソースをShift_JISとして読ませた場合です。既定の文字コードがMS932の環境を再現するため、Linux上で -J-Dfile.encoding=MS932 を付け、-encoding を省略して実行しました。

src/com/example/stock/package-info.java:2: error: unmappable character (0x86) for encoding windows-31j

症状別の対処表

JDK 18以降は既定の文字コードがUTF-8になったため（一般に知られた仕様で、今回Windows上では未実行です）、新しいJDKでは -encoding を省略しても動くことが増えました。それでも、JDKのバージョンや環境が変わっても同じ結果になるよう、3つのオプションを明示しておくと安心です。

Maven・Gradle・Eclipse・IntelliJで生成する

Gradle

Gradle 8.14.3 で、次の build.gradle を使って gradle javadoc javadocJar を実行し、生成できることを確認しました。

plugins {
    id 'java'
}

java {
    withJavadocJar()   // build時に stock-javadoc.jar も作る
}

tasks.withType(JavaCompile).configureEach {
    options.encoding = 'UTF-8'
}

javadoc {
    options.encoding = 'UTF-8'       // ソースの文字コード（-encoding）
    options.docEncoding = 'UTF-8'    // 出力HTMLの文字コード（-docencoding）
    options.charSet = 'UTF-8'        // HTMLのmeta charset（-charset）
    options.locale = 'ja_JP'
    options.author = true
    options.version = true
    options.addStringOption('Xdoclint:all,-missing', '-quiet')
}

javadoc.options を見ると、-encoding 'UTF-8'、-docencoding 'UTF-8'、-charset 'UTF-8'、-locale 'ja_JP'、-Xdoclint:all,-missing に加えて、-notimestamp と -quiet、-doctitle 'stock API' が自動で付いていました。

Maven

Mavenでは maven-javadoc-plugin を使います。公式サイトで確認した最新版は 3.12.0 です。今回の環境ではプラグインを取得できなかったため、以下の設定とコマンドは未実行です。

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.12.0</version>
      <configuration>
        <encoding>UTF-8</encoding>
        <docencoding>UTF-8</docencoding>
        <charset>UTF-8</charset>
        <locale>ja_JP</locale>
        <doclint>all,-missing</doclint>
      </configuration>
    </plugin>
  </plugins>
</build>

出力先は target ディレクトリの下です。プラグインのバージョンによって場所が変わるため、実行時のログで確認してください。

EclipseとIntelliJ IDEA

IDEからの生成は今回未実行です。一般に知られた手順を表にまとめます。メニュー名はバージョンによって少し変わることがあります。

どちらのIDEも内部では javadoc コマンドを呼び出しているので、指定するオプションはコマンドラインと同じです。コメントの入力は、宣言の上で /** と入力してEnterキーを押すと、引数に合わせた @param や @return のひな形が補完されます。

新しい書き方：snippetとMarkdownコメント

サンプルコードを載せるsnippet（Java 18以降）

{@snippet} は、サンプルコードを載せるためのタグです。<pre>{@code ...}</pre> と比べて、< や > をそのまま書け、強調表示やコピーボタンが付きます。

インライン形式（コメントの中に直接書く）は、テンプレートの StockService に入れたとおりです。JDK 21 で生成したHTMLでは、次のように出力されました。

<pre class="snippet"><code>StockService service = new StockService();
service.add("pen", 10);
int left = service.<span class="bold">take</span>("pen", 3);
</code></pre>

// @highlight substring="take" と書いた行のコメントは消え、take が太字になっています。

外部形式では、パッケージのディレクトリに snippet-files というフォルダを作り、その中のファイルから一部を取り込みます。

// src/demo/snippet-files/CalcDemo.java
import demo.Calc;

public class CalcDemo {
    public static void main(String[] args) {
        // @start region="avg"
        double avg = Calc.average(new int[] {80, 90});   // @highlight substring="average"
        System.out.println(avg);
        // @end
    }
}

コメント側は {@snippet file="CalcDemo.java" region="avg"} と書きます。JDK 25 で生成すると、@start から @end の間の2行だけが取り込まれました。サンプルを実際のソースファイルとして持てるので、コンパイルして確かめたコードを仕様書に載せられます。

スラッシュ3つのMarkdownコメント（Java 23以降）

Java 23 で、/// で始まる行にMarkdownで書けるコメントが加わりました（JEP 467）。JDK 25.0.4.1 の javadoc で次のコードを生成して確認しました。

package demo;

/// 数値の計算をまとめたクラスです。
///
/// 使える操作は次のとおりです。
///
/// - 合計: [#sum(int\[\])]
/// - 平均: [平均を求める][#average(int\[\])]
///
/// | メソッド | 戻り値 |
/// |---------|--------|
/// | `sum` | `int` |
/// | `average` | `double` |
///
/// ```java
/// int total = Calc.sum(new int[] {1, 2, 3});
/// ```
///
/// @since 2.0
public final class Calc {

    private Calc() {
    }

    /// 配列の合計を返します。
    ///
    /// 空の配列を渡すと **0** を返します。
    ///
    /// @param values 合計する値。`null` は指定できません
    /// @return 合計
    /// @throws NullPointerException `values` が `null` の場合
    public static int sum(int[] values) {
        int s = 0;
        for (int v : values) s += v;
        return s;
    }

    /// 配列の平均を返します。
    ///
    /// {@snippet file="CalcDemo.java" region="avg"}
    ///
    /// @param values 平均を求める値
    /// @return 平均。要素が0個のときは [Double#NaN]
    public static double average(int[] values) {
        return values.length == 0 ? Double.NaN : (double) sum(values) / values.length;
    }
}

生成結果では、箇条書きが <ul>、表が <table>、コードブロックが <pre><code class="language-java">、太字が <strong> になり、[#sum(int\[\])] は sum(int[]) へのリンクになりました。

気をつける点が2つあります。

• 配列の角かっこは \[\] とエスケープする。エスケープせずに [平均を求める][#average(int[])] と書いたところ、error: reference not found になりました。
• JDK 22以前の javadoc は /// をコメントとして扱いません。同じソースを JDK 21 の javadoc に渡すと、warning: no comment が出て説明は出力されませんでした。チームで使うJDKが23以上にそろってから採用するとよいでしょう。

よく出る警告・エラーと直し方

わざと不備のあるコメントを書いて、JDK 21 の javadoc を実行しました。出力された主なメッセージ（ソースの引用行と一部のメッセージは省略）と直し方です。

bad/demo/Bad.java:7: error: malformed HTML
bad/demo/Bad.java:7: error: element not closed: b
bad/demo/Bad.java:15: error: @param name not found
bad/demo/Bad.java:18: error: exception not thrown: java.io.IOException
bad/demo/Bad.java:19: error: reference not found
bad/demo/Bad.java:21: warning: no @param for value
bad/demo/Bad.java:31: warning: no @return
bad/demo/Bad.java:37: error: invalid use of @return
bad/demo/Bad.java:43: error: unknown tag: String
bad/demo/Bad.java:43: error: semicolon missing
bad/demo/Bad.java:45: warning: @param "a" has already been specified
bad/demo/Bad.java:11: warning: no comment
bad/demo/Bad.java:9: warning: use of default constructor, which does not provide a comment
10 errors
6 warnings

検査の強さを調整する

おすすめの進め方は、最初は -Xdoclint:all,-missing で書式の誤りだけを直し、コメントがそろってきたら -missing を外す流れです。CIで品質を保ちたいときは -Werror を加えます。

独自タグを定義する

@custom.todo のような独自のブロックタグは、-tag 名前:場所:見出し で定義します。場所の a は「すべての場所」の意味です。-tag custom.todo:a:"Todo:" を指定して生成すると、「Todo:」の見出しの下にタグの内容が出力されました。見出しを日本語にする場合、今回の環境ではコマンドラインに直接書くと見出しが正しく表示されず、UTF-8で保存したオプションファイル（@opts.txt）に書くと正しく出力されました。

読みやすいJavadocを書くコツ

よくある質問

Q. @paramや@returnは必ず書く必要がありますか？ A. 文法上は省略しても生成できますが、既定の検査（doclint）では warning: no @param for value や warning: no @return が表示されます。公開するAPIでは書いておくと、使う人が引数の範囲や戻り値の意味をすぐ確認できます。短いメソッドなら {@return 説明} を使うと、要約と戻り値の説明を1回で書けます。

Q. privateなメソッドにもJavadocを書くべきですか？ A. 既定の設定ではprivateな要素はHTMLに出力されませんが、/** */ の形で書いておくと、IDEでメソッド名にカーソルを合わせたときに説明が表示されます。処理の意図が伝わりにくい箇所には書いておくと、読む人の助けになります。HTMLにも出したいときは -private を付けます。

Q. @throwsと@exceptionはどちらを使えばよいですか？ A. 意味は同じです。仕様書では @exception は @throws と同等の別名とされています。メソッド宣言の throws と同じ語になる @throws にそろえると読みやすくなります。

Q. 生成したHTMLの見出しを日本語にできますか？ A. -locale ja_JP を付けると、「パラメータ:」「戻り値:」「例外:」などの日本語の見出しになります。Gradleでは options.locale = 'ja_JP' で指定できます。

まとめ

• Javadocは、専用のコメントからHTMLの仕様書を作る仕組み。コメントは /** で始め、1文目が要約、続けて説明、最後にブロックタグを書く
• よく使うタグは @param・@return・@throws・@see・@since・@deprecated と、文中の {@code}・{@link}
• recordの構成要素はクラスのコメントの @param で説明する
• 生成は javadoc -d docs -sourcepath src -encoding UTF-8 -docencoding UTF-8 -charset UTF-8 パッケージ名。@author と @version は -author -version を付けたときだけ出力される
• 文字化けやエラーは -encoding（ソース）・-docencoding（出力）・-charset（meta） の3つをそろえて防ぐ
• {@snippet}（Java 18以降）とMarkdownコメント ///（Java 23以降） で、サンプルコードや表を書きやすくなった
• 警告やエラーはメッセージと行番号から原因を特定し、-Xdoclint で検査の強さを調整する

株式会社RJCでは、Javadocをはじめとするドキュメントの書き方を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。