(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は書きましょう。 キチンと書いておくことで、引き継いだあとの問い合わせが減るし、数年後のトラブル対応とかでも、コメントを見ると思い出すきっかけになります。
他人のためではなく自分のため、自分の身を守るためにコメントはしっかり書きましょう。