Javadocの書き方について

去年勉強した内容だが、まとめるのを忘れていたのでJavadocの書き方についてまとめてみる。他のプログラミング言語のAPIドキュメンテーションの記述方法は、Javadoc準拠になっているものが多いので基本として押さえておこうと思う。

Javadocとは

Javaでは、「Javadoc」と呼ばれるコメントを記述できる。これは、プログラムについて説明するドキュメントをソースコードに埋め込むためのものである。

Javadocは大変便利で、クラスの概要やメソッドの概要を記述しておくと、その情報からHTML形式のドキュメントファイルを生成してくれる。Java Platform SEのAPIリファレンスは実際に、この機能を使って生成されている。

Javadocの書き方

Javadoc内では、コメントを記入する際にクラスやメソッドの役割を示すためにタグを使用する。使用できるタグには以下の種類がある。

タグ名 説明
@author クラスの作成者情報を記載
@param メソッドの引数の説明
@return メソッドの返り値の説明
@throw 発生する例外クラスを指定
@see 他のAPIを参照する場合に記載
@deprecated 推奨されないAPIであることを示す
@serial 直列化されたフィールドの説明
@sesrialData 直列化された状態でのデータ型と順序を記載
@since 導入されたバージョンを記載
@version バージョンを記載

以下が具体的な書き方となる。

クラス宣言時

/**
 * 犬の鳴き声を画面出力
 * @author SmokyDog
 */
 public class DogVoiceDisplay{
     System.out.println("woof!woof!")
 }

メソッド宣言時

/**
 * 犬がクラッシュするアニメーションを行います
 * @param dog クラッシュさせたいDogオブジェクトのインスタンス
 * @return なし
 * @throws DisplayException 表示に問題があった場合に起こり得る例外
 */
public void doggyCrash(Animal dog){
    //何らかの処理
}

参考
【改訂版】Eclipseではじめるプログラミング(22):いまさら聞けない「Javadoc」と「アノテーション」入門
Java初心者のJavadoc入門