去年勉強した内容だが、まとめるのを忘れていたので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入門