【Java】javadocとは - 生成コマンドやコメント・タグの書き方
- 作成日:2022/02/05
クラス・メソッドの仕様書を自動で作成してくれるjavadocについて解説します。
javadocとは
javadocとはソースコードの仕様書を自動で作成してくれる仕組みです。
どんなものを生成してくれるのかというと、こんなものです。
自動生成した仕様書はWebページで開けます。 結構奇麗な見た目ですね。このようなものが勝手にできるなんて便利な機能があったものです。
コマンドプロンプトからの生成方法
基本として、コマンドプロンプトのjavadocコマンドで仕様書を自動生成する方法を解説します。
eclipseなどIDEによってはマウスのクリックだけでjavadocを生成できる場合もあります。
コマンドプロンプトを開き、ソースファイルがある場所で、次のようなコマンドを実行します。
javadoc -private -d 出力フォルダ ファイル名.java
例えば、App.javaというソースファイルの仕様書をdocOutフォルダに出力したい場合は次のようになります。
javadoc -private -d docOut App.java
このコマンドを実行すると、docOutフォルダが自動生成され、その中に様々なファイルが作成されます。 その中のindex.htmlというファイルをWebページで開いてください。
先ほど紹介した仕様書が表示されます。 クラスが複数ある場合は、クラス名.htmlというファイル内に仕様が書かれていますが、 index.htmlから移動できます。
javadocコマンドのオプション例
javadocコマンドのオプションは色々あります。 公式HPで全てを確認できますが、 今回使用したのは以下となります。
| オプション | 解説 | サンプル |
|---|---|---|
| -private | 全クラス・メソッドを表示する | javadoc -private App.java |
| -d 出力先フォルダ名 | 出力先フォルダを新規作成して指定する | javadoc -d docOut App.java |
先ほどの例のように、オプションは複数追加することができます。
コメントの書き方
Javaでコメントを書く場合、1行コメントの場合は「//」で、複数行コメントする場合は「/*～*/」で囲みます。
/*
日付：20XX/02/01
著者:PG
バージョン:ver1.00
*/
class Parent{
//食事するメソッド
void eat(String str){
System.out.println(str);
}
}
ただし、これは人間が読むためのコメントであり、コンピュータはこのコメントを無視します。 javadocを作成するときも同様に無視されます。
javadocで生成される仕様書にコメントを追加したい場合は「/**～*/」を使います。
/**
* 日付：20XX/02/01
* @author PG
* @version ver1.00
*/
class Parent{
/**
* 食事するメソッド
* @param str 文字列
*/
void eat(String str){
System.out.println(str);
}
}
4～5行目のように、「/**～*/」の間の行には先頭に「*」を入れます。追加したコメントはjavadocで生成した仕様書に次のように反映されます。
これは1例ですが、追加したコメントは全て適所に追加されています。
javadocタグ
javadocには特別な意味をもつタグが用意されています。 タグを追加することで、よりわかりやすい仕様書ができるわけです。
主に次のようなタグがあります。
| タグ | 解説 | 例 |
|---|---|---|
| @author 名前 | 作成者を示すタグ | @author 田中 |
| @version テキスト | バージョンを示すタグ | @version Ver1.00 |
| @deprecated 説明 | APIが非推奨を示すタグ | @deprecated 使用されていないため使用を避けること |
| @param 名前 説明 | 引数を示すタグ | @deprecated nowDate 現在の日付 |
| @return 説明 | 戻り値を示すタグ | @return String型の配列を返す |
これらのタグはコメントと同じように「/**～*/」の間に記述して、先頭に「*」を入れて使います。
コマンドプロンプトでjavadocの仕様書を生成する場合、
@authoと@versionは-author及び-versionというオプションをつけてコンパイルしないと反映されません。
(例)
javadoc -author -version -private -d 出力先 ファイル名.java
注意することは、javadocタグはコメントのように記述しますが、間違った使い方をするとコンパイルエラーとなることです。以下のソースコードを見てください。
/**
* 日付：20XX/02/01
* @author PG
* @version ver1.00
*/
class Parent{
/**
* 食事するメソッド
* @param str 文字列
*/
void eat(){
System.out.println("sample");
}
}
javadocタグを幾つか使っていますが、10行目のタグは間違えです。 eatメソッドは引数を受け取らないので、@paramタグは使えません。
アノテーションについて
Javaには@マークを使う「アノテーション」という、コンピュータに注釈を指示する仕組みがあります。 javadocタグもアノテーションだとも言えますが、javadocタグは通常のアノテーションとは記述方法が少し異なります。
javadocタグは、「/**～*/」に囲まれた間に記述しますが、アノテーションはクラスやメソッドの上に直接書きます。
/**
* 日付：20XX/02/01
* @author PG
* @version ver1.00
*/
class Parent{
@Deprecated
void eat() {
System.out.println("食べる");
}
}
4～5行目がjavadocタグで、9行目がアノテーションを使った例です。
また、javadoc内で使うアノテーションと通常のアノテーションではよく使われるものが違います。 3つほど例をあげるとこんな感じです。
| 通常よく使う | javadocでよく使う(一例) |
|---|---|
| @Override | @author |
| @Deprecated | @version |
| @SuppressWarnings | @param |
ひとくくりにアノテーションというと初心者は混乱するかもしれません。 なので、javadocタグはあくまでjavadocで使うアノテーションで、通常よく使うアノテーションとは区別して覚えると良いかもしれませんね。