👩💻
#12 【入門】Javadocまとめ
Javadocとは
Javaのクラスやフィールド、メソッドに記述したコメントからドキュメントを生成するツールです。
Javadocに要素の説明や引数、戻り値に関する情報などコメントを記載することで、HTML形式のドキュメントを生成することができます。
利点
- 可読性の向上
- IDEでメソッドにカーソルを合わせたときJavadocが表示されるようになる
- コマンドを使い、各説明をHTMLファイルに出力したAPIドキュメントを作成できる
書き方
要素の宣言前、「/** ～ */」の間にコメントを記述します。
主なタグ
| タグ | 用途 |
|---|---|
| @author 名前 | クラスやメソッドの作成者を記述する。 |
| @deprecated 説明 | 非推奨（廃止）されたクラスやフィールド、メソッドであることを示す。非推奨になった理由などを記述する。 |
| @param 引数名 説明 | メソッドのパラメータについて説明を記述する。 |
| @return 説明 | メソッドの戻り値について説明を記述する。 |
| @since バージョン | クラスやメソッドが作成されたバージョンを記述する。 |
| @throws 例外クラス 説明 | メソッドでスローされる例外についての説明を記述する。(@exceptionタグと同じ使い方) |
| @version バージョン | クラスやメソッドの現在のバージョンを記述する。 |
| {@link} | Javadocタグの中で文字列を表示する場所の中に参照リンクを表示したい場合に使用する。 タグ内部は{@link package.class#member label}の形式で記述する。 |
記述例
/**
* Calculatorクラスは、基本的な計算を行うためのクラスです。
* 詳細な情報については、{@link sample.Calculator} を参照してください。
*
* @author Tarou
* @version 1.0
*/
public class Calculator {
/**
* addメソッド
* 2つの整数を加算して結果を返します。
*
* @param a 加算する整数
* @param b 加算する整数
* @return 加算結果
*/
public static int add(int a, int b) {
return a + b;
}
/**
* mainメソッド
* addメソッドを呼び出します。
*
* @param args コマンドライン引数
*/
public static void main(String[] args) {
int result = add(5, 3);
System.out.println("加算結果: " + result);
}
}
javadocコマンドを実行する
コマンド例
親カレントリまで移動しjavadocコマンドを実行します。
javadoc -encoding UTF-8 -d ../docs -author -version Calculator.java
※ 「Calculator.java」からドキュメントを生成します。
※「-encoding UTF-8」で文字コードを指定します。
※ 「-d」オプションで「../docs」を出力先ディレクトリに指定しています。
※ 「-author」「-version」オプションで「@author」「@version」の情報をそれぞれドキュメントに追加しています。
APIドキュメントを確認する
コマンド実行後、「-d ../docs」配下に生成された「index.html」ファイルをブラウザで開くとドキュメントを確認することができます。
最後に
今回はJavadocとよく使われるタグについて説明しました。
効率よく開発を行えるよう、読みやすいコメントをつけていきたいですね！
Discussion