(Java)Javadocの書き方

最近、社内用のユーティリティクラス群を作る機会があって、わりとまじめにJavadocを書いたので、書き方をまとめておく。

クラス(メソッド)見出し

「/**」直後の最初の文は、生成したJavadocの見出し(メソッド一覧やクラス一覧)に使われる。
“最初の文”の判断は、最初のピリオド「.」+空白文字(改行やブランク)が来るまで。
もしくは最初のブロックタグ(@author等のJavadocタグ)が来るまで。

Javadocメモ(Hishidama's Javadoc Memo)

コメント中の段落

<p>タグを1つ置くことで段落が作れる。普通のHTMLみたいに<p>タグで囲む必要はない。

コメント中の改行

<br>タグを使うことで改行される。逆に使わないと、自動改行される以外は1行で表示される。

コメント中のコード

<pre>{code (コード) }</pre>という書き方をすることで、(コード)部分の内容をそのままJavadocに表示する。この書き方をすることで<>などのHTML特殊文字を変換することなく、そのまま書くことができる。 Javaのコードはもちろん、HTMLやXMLなんかの記述も出来て便利。

実際の例

/**
 * 最初のピリオドまでクラス見出し.
 * <p>
 * クラス説明クラス説明クラス説明クラス説明クラス説明<br>
 * クラス説明クラス説明クラス説明クラス説明クラス説明<br>
 * クラス説明クラス説明クラス説明クラス説明クラス説明。
 * <pre>{@code
 * SampleClass sample = new SampleClass();
 * String str = sample.method("あいうえお");
 * }</pre>
 * @see <a href="http://docs.oracle.com/javase/jp/7/api/java/lang/Object.html">Object (Java Platform SE 7)</a>
 */
public class SampleClass {

    /**
     * 最初のピリオドまでメソッド見出し.
     * <p>
     * メソッド説明メソッド説明メソッド説明メソッド説明<br>
     * メソッド説明メソッド説明メソッド説明メソッド説明<br>
     * メソッド説明メソッド説明メソッド説明メソッド説明。
     * <pre>{@code
     * // pre + @codeで使い方の説明など
     * SampleClass sample = new SampleClass();
     * String str = sample.method("あいうえお");
     * }</pre>
     * 
     * @param s 引数の説明
     * @return 戻り値の説明
     */
    public String method(String s) {
        // 特に意味はない
        return "さんぷる";
    }

}

コメント

みなさん、Javadocは書きましょう。 キチンと書いておくことで、引き継いだあとの問い合わせが減るし、数年後のトラブル対応とかでも、コメントを見ると思い出すきっかけになります。

他人のためではなく自分のため、自分の身を守るためにコメントはしっかり書きましょう。