Javadocとは？
Javadocは簡単に説明すると、Java言語のソースコードから「プログラムについて説明するドキュメント」を生成する仕組みです。
Javadoc用のコメントを記述すると、作ったプログラムに対するドキュメントをソースコードに埋め込んでくれます。
言葉だけで説明しても理解が難しいと思うので、具体的なコードを出して詳しく説明していきます。
例えば、値を2倍して結果を出力する以下のようなプログラムがあるとしましょう。
public class JavadocTest{
public static int doubleFunc(int number){
// 引数の10を2倍して返します
return number * 2;
}
public static void main(String[] args){
// numberにdouble関数の結果を代入します
int number = doubleFunc(10);
// 結果を出力します
System.out.println(number);
}
}
ソースコードには処理とコメントが記述されています。
コメントは、
// 引数の10を2倍して返します
のように、スラッシュ（/）2つで書かれている部分です。
スラッシュとアスタリスク（*）で囲んで、
/* 引数の10を2倍して返します */
とも書けます。
このソースコードに対して、コンピュータは以下の内容を読み取って処理します。
- クラスの名称は「JavadocTest」である
- 「JavadocTest」の中には、メソッド「main」と「double」がある
- 「main」は「String[] args」を受けて「void」を返す
- 「doubleFunc」は「int number」を受けて「int」を返す
コンピュータは処理を読み取るものの、コメントに書かれている内容やメソッドの中身はプログラムによって異なるので見ていないんです。
そこで、コンピュータに「このコメントはドキュメントに載せてね」と判断させるために用いられるのが「Javadoc用のコメント」になります。
- Javadocは、「プログラムについて説明するドキュメント」を生成する仕組み
- Javadoc用のコメントを記述すると、ドキュメントにコメントを反映させられる
Javadoc用のコメントの書き方
Javadoc用のコメントは、具体的にどのように記述すればいいのか知りたいです。
では、次にサンプルを見ながらコンピュータがどのように処理をするのか見ていきましょう。
Javadoc用のコメントは、スラッシュ（/）とアスタリスク（*）2つで始まるように「/**」で記述します。
/** * これがJavadoc用のコメントの書き方です。 */
これで、Javadoc用のコメントと認識されます。
また、Javadoc用のコメントの中で「@」は特殊な記号として認識されます。
「@author」と記述するとプログラムの制作者を意味し、「@version」と記述するとバージョンを意味するといった「Javadocタグ」が付けられます。
その他にもさまざまな種類のJavadocタグがあるので、後ほどご説明しますね。
Javadoc用のコメントを記述して、値を2倍して結果を出力するプログラムのソースコードを書き直すと、以下のようになります。
/**
* Javadoc用コメントのテストプログラム
* @author ポテパンスタイル
* @version 1.0.0
*/
public class JavadocTest{
/**
* doubleFuncメソッド
* 引数を2倍にして返す
* @param number 整数値
* @return 引数を2倍した整数値
*/
public static int doubleFunc(int number){
// 引数の10を2倍して返します
return number * 2;
}
/**
* mainメソッド
* doubleメソッドに引数を渡して結果を出力する
*/
public static void main(String[] args){
// numberにdouble関数の結果を代入します
int number = doubleFunc(10);
// 結果を出力します
System.out.println(number);
}
}
Javadoc用のコメントを追加したこのソースコードに対して、コンピュータは以下の内容を読み取って処理をします。
- クラスの名称は「JavadocTest」である
- 「JavadocTest」は「Javadocのテスト用クラス」である
- 「JavadocTest」を作ったのは「ポテパンスタイル」である
- 「JavadocTest」のバージョンは「1.0.0」である
- 「JavadocTest」の中には、メソッド「main」と「double」がある
- 「main」は「String[] args」を受けて「void」を返す
- 「main」は「mainメソッド」である
- 「main」は「doubleメソッドに引数を渡して結果を出力する」メソッドである
- 「doubleFunc」は「int number」を受けて「int」を返す
- 「doubleFunc」は「doubleFuncメソッド」である
- 「doubleFunc」は「引数を2倍にして返す」メソッドである
- 「doubleFunce」は「整数値」を受け取る
- 「doubleFunc」は「引数を2倍した整数値」を返す
以上のように、Javadocはソースコードから、
- ソースコードの構造から機械的に読み取れるもの
- 特定の書式で書かれたコメント
の2つを自動で抽出してまとめたドキュメントです。
このドキュメントを作成するときに使われるコマンド・プログラムとも言えます。
Javadocタグの種類と意味
Javadoc用のコメントの中には、「説明文」と「Javadocタグ」を記述することが可能です。
Javadocタグには以下の種類と意味があります。
| Javadocタグ
|
意味
|
| @author
|
作成者について指定します
|
| @version
|
バージョンについて指定します
|
| @see
|
「関連項目」として外部リンクやテキストを表示、他のフィールドやメソッドなどへの参照リンクについて指定します
|
| @deprecated
|
クラスやメソッドなどを「非推奨」として指定します
|
| @since
|
導入されたバージョンを指定します。「@version」タグは現在のバージョン、「@since」タグはどのバージョンから導入されているかを表す点が異なります
|
| @param
|
パラメータに関する説明を指定します
|
| @return
|
戻り値に関する説明を指定します
|
| @throws(@exception)
|
発生する可能性のある例外に関する説明を指定します
|
| {@link}
|
Javadocタグ中で、文字列を表示する場所の中に参照リンクを表示する場合に指定します
|
| {@linkplain}
|
「{@link}」タグと同じだが、「{@link}」の文字列がコードテキストに対して、「{@linkplain}」タグはプレーンテキストで表示されます
|
Javadocドキュメントの作成方法
Javadocコマンドを使用してソースコードからドキュメントを作成する場合、以下のように実行すればドキュメントが作成できます。
$ javadoc -d html JavadocTest.java
作成が正常にできると、htmlという名前のディレクトリが作成され、ディレクトリ内に「index.html」というファイルがあります。
Webブラウザで開いて内容を確認すると、以下のようなHTML形式のドキュメントが生成されます。
Javadocの意味と書き方まとめ
Javadocの意味と書き方をご紹介していきました。
Javadocは、クラスやメソッドなど、Java言語の構成要素とその説明が対応づけられているため、多人数で開発をする場合などに役立ちます。
また、Javadocはフォーマットが決まっており、メソッド全体についてのコメントを書くため 意味のない情報を書くことが少なくなります。
Javadocが必要になったときは、ぜひこの記事を読んで有効活用してくださいね。
