Javadoc コメントにコード例を記述する方法

2024-04-02

概要

複数行コード例の書き方

Javadoc コメント内で複数行のコード例を記述するには、以下の2つの方法があります。

方法1: @code タグを使う

@code タグを使ってコードブロックを囲みます。
コードブロック内には、インデントなしでコードを記述します。

例：

/**
 * 文字列を反復処理するメソッド。
 *
 * @param str 処理対象の文字列
 * @return 反復処理後の文字列
 */
public static String repeatString(String str) {
    // コード例

    @code
    for (int i = 0; i < str.length(); i++) {
        System.out.print(str.charAt(i));
    }
    @endcode

    return str;
}

方法2: HTML の <pre> タグを使う

/**
 * 文字列を反復処理するメソッド。
 *
 * @param str 処理対象の文字列
 * @return 反復処理後の文字列
 */
public static String repeatString(String str) {
    // コード例

    <pre>
    for (int i = 0; i < str.length(); i++) {
        System.out.print(str.charAt(i));
    }
    </pre>

    return str;
}

ポイント

コード例は、見やすくするためにインデントすることをおすすめします。
コード例内にコメントを含める場合は、// や /* ではなく、`

/**
 * 文字列を反復処理するメソッド。
 *
 * @param str 処理対象の文字列
 * @return 反復処理後の文字列
 */
public static String repeatString(String str) {
    // コード例

    @code
    for (int i = 0; i < str.length(); i++) {
        // 文字列の i 番目の文字を出力
        System.out.print(str.charAt(i));
    }
    @endcode

    return str;
}

/**
 * 配列の要素をすべて出力するメソッド。
 *
 * @param arr 処理対象の配列
 */
public static void printArray(int[] arr) {
    // コード例

    <pre>
    for (int i = 0; i < arr.length; i++) {
        // 配列の i 番目の要素を出力
        System.out.print(arr[i] + " ");
    }
    System.out.println();
    </pre>
}

public class Main {
    public static void main(String[] args) {
        // 文字列の反復処理
        String str = "Hello, world!";
        repeatString(str);

        // 配列の要素の出力
        int[] arr = {1, 2, 3, 4, 5};
        printArray(arr);
    }
}

repeatString メソッド：文字列を反復処理し、各文字を出力する
printArray メソッド：配列の要素をすべて出力する
main メソッド：上記2つのメソッドを呼び出す

コード例は、@code タグと <pre> タグの両方を使って記述しています。どちらの方法を使うかは、お好みに合わせてください。

Javadoc コメントにおける複数行コード例のその他の方法

ソースコードの抜粋を直接埋め込む

コード例が短い場合は、ソースコードを直接 Javadoc コメントに埋め込むこともできます。

/**
 * 文字列を反復処理するメソッド。
 *
 * @param str 処理対象の文字列
 * @return 反復処理後の文字列
 */
public static String repeatString(String str) {
    // コード例

    for (int i = 0; i < str.length(); i++) {
        System.out.print(str.charAt(i));
    }

    return str;
}

この方法は、コード例が短く、シンプルな場合に有効です。

画像ファイルを使う

/**
 * 文字列を反復処理するメソッド。
 *
 * @param str 処理対象の文字列
 * @return 反復処理後の文字列
 */
public static String repeatString(String str) {
    // コード例

    ![コード例](https://example.com/code_example.png)

    return str;
}

この方法は、コード例が複雑で、テキストで表現するのが難しい場合に有効です。