Javadocコメントの書式
コメントの構成
Javadocに関係するコメントの構成について見てみよう。別のページで確認したように、コメントは次のように/**から*/の間に書く。
/**
*
* この間にコメントを書く。
*
*/
コメントの中は大きく分けると、「説明文」と「タグセクション」の2つに区分できる。
説明文は、クラスやメソッドなどについて簡単に説明する文章である。
/**
* このクラスはJavadoc説明用クラスである。
*/
説明文は複数行で書くことができる。コメントの開始部分から最初のタグセクションが現れるまでが説明文になる。ただし、説明文はHTML文として解釈されるため、単に行を変えて書いても改行されずに表示される。明示的に改行する場合は<br>を書く必要がある。
/**
* このクラスはJavadoc説明用クラスである。
* 複数行で書くことができる。
* @version 2.0
*/
タグセクションは、最初の文字が@で始まる。@versionや@authorなど多くのJavadocタグがあり、それぞれ異なる意味を持つ。Javadocタグの詳しい内容は別のページで詳しく見ていく。
タグセクションは、1つのコメントに複数種類を同時に書くことができる。
/**
* このクラスはJavadoc説明用クラスである。
* 複数行で書くことができる。
* @version 2.0
* @author devkuma
*/
タグセクションには、1つのコメントで1回しか使えないものと、複数回使えるものがある。複数回使えるものについては続けて説明する。
/**
* このクラスはJavadoc説明用クラスである。
* 複数行で書くことができる。
* @version 2.0
* @param string 名前
* @param int 年齢
*/
タグセクションを書いた後には「説明文」を書くことはできない。次は誤った例である。
/**
* このクラスはJavadoc説明用クラスである。
* 複数行で書くことができる。
* @version 2.0
* @param string 名前
* @param int 年齢
* タグセクションの後に説明文を書いてはいけない。
*/
それでは、簡単な例を試してみよう。
/**
* Javadocテスト用クラス
* 複数行で書くことができる。
*/
public class Sample02 {
/**
* サイズを設定する
*
* @param width 幅
* @param height 高さ
*/
public void setSize(int width, int height) {
}
}
上のソースコードをSample02.javaという名前で保存し、保存したディレクトリで次のように実行してみよう。
$ javadoc -d doc Sample02.java
docディレクトリにあるindex.htmlファイルをブラウザで確認してみよう。
クラスについての説明は2行にわたって書いたが、<br>を書いていないため、1行で表示されていることが分かる。
HTML文の作成
Javadocで書かれた文章はHTML文として解釈され、表示される。逆に言えば、タグではない文字を書く必要がある場合は文字参照で書かなければならない。たとえば<は<と書く。
HTML文であるため、HTMLタグを使用できる。
/**
* コメントは<b>HTML文</b>で書く。
*/
HTMLタグは使用できるが、クラスやパッケージ以外の部分で<h1>や<h2>などの見出しタグは使わないほうがよい。
簡単な例を試してみよう。
/**
* Javadoc<b>テスト</b>用クラス
* <a href="http://www.devkuma.com" target="_blank">リンク</a>を書く
* <p style="color : #ff0000">スタイルシート</p>を書く
*/
public class Sample03 {
/**
* <font color="#ff0000">サイズ</font>を設定する
*
* @param width 幅
* @param height <font color="#0000ff">高さ</font>
*/
public void setSize(int width, int height) {
}
}
上のソースコードをSample03.javaというファイル名で保存し、保存したディレクトリで次のように実行する。
$ javadoc -d doc Sample03.java
docディレクトリにあるSample03.htmlファイルをブラウザで確認してみよう。
このように、<b>タグによる強調、<a>タグによるリンク、<p>によるスタイルシート、<font color="#0000ff">による色の指定が正しく反映されていることを確認できる。
フィールドにコメントを書くときの注意点
Javaでは、同じデータ型の複数のフィールドを一度に宣言できる。
int width, height;
この形式に対してコメントを書くと、次のようになる。
/**
* 幅と高さを表す。
*/
int width, height;
この場合、2つの変数に同じコメントが適用される。結果として、次のように書いた場合と同じである。
/**
* 幅と高さを表す。
*/
int width;
/**
* 幅と高さを表す。
*/
int height;
場合によってはこの形式でも問題ないこともあるが、ほとんどの場合は適切なコメントにならない。そのため、Javadocを利用する場合はフィールドごとに宣言し、それぞれ別のコメントを書くようにする。
簡単な例を試してみよう。
/**
* Javadocテスト用クラス
*/
public class Sample04 {
/**
* 幅と高さを表す。
*/
public int width, height;
/**
* サイズを設定する
*
* @param width 幅
* @param height 高さ
*/
public void setSize(int width, int height) {
}
}
上のソースコードをSample04.javaというファイル名で保存し、保存したディレクトリで次のように実行する。
$ javadoc -d doc Sample04.java
docディレクトリにあるSample04.htmlファイルをブラウザで確認してみよう。
複数のフィールドを一度に宣言して1つのコメントを書くと、それぞれのフィールドに同じコメントが表示される。