コメントの構成

Javadocに対応したコメントの構成について確認します。他のページで確認したとおり、コメントは次のように「/**」から「*/」までの間に記述します。

/**
 *
 *  この間にコメントを記述する
 *
 */

コメントの中は大きく分けると「説明文」と「タグセクション」の二つに区分することができます。

説明文はクラスやメソッドなどに対して簡潔に説明した文となります。

/**
 *  このクラスはJavadoc説明用のクラスです。
 */

説明文には複数の分を記述することができます。コメントの先頭部分から最初のタグセクションが現れるまでが説明文となります。ただし、説明文はHTML文として解釈されるため単に別の行に記述しても改行はされずに表示されます。明示的に改行する場合は<br>を記述します。

/**
 *  このクラスはJavadoc説明用のクラスです。
 *  複数行に渡って記述することが可能です。
 *  @version 2.0
 */

タグセクションは先頭の文字が「@」で始まります。「@version」や「@author」など多くのjavadocタグが用意されており、それぞれ別の意味を持ちます(javadocタグの詳細は別のページで詳しく見ていきます)。

タグセクションは1つのコメントの中に複数の種類を同時に記述することができます。

/**
 *  このクラスはJavadoc説明用のクラスです。
 *  複数行に渡って記述することが可能です。
 *  @version 2.0
 *  @author Javadrive
 */

タグセクションにはコメント中に1度しか使用できないものや、複数回使用できるものがあります。複数回使用する場合は続けて記述するようにします。

/**
 *  このクラスはJavadoc説明用のクラスです。
 *  複数行に渡って記述することが可能です。
 *  @version 2.0
 *  @param string 名前
 *  @param int 年齢
 */

タグセクションが記述された後に「説明文」を記述することはできません。次のような記述は誤りです。

/* (誤った例) */

/**
 *  このクラスはJavadoc説明用のクラスです。
 *  複数行に渡って記述することが可能です。
 *  @version 2.0
 *  @param name 名前
 *  @param old 年齢
 *  説明文をタグセクションの後に記述はできません。
 */

サンプル

では簡単な例で試してみます。

Sample01.java

/**
 * Javadocテスト用クラス
 * 複数行のコメントが記述できます
 */
public class Sample01{
  /**
   * サイズの設定
   * @param width 幅
   * @param height 高さ
   */
  public void setSize(int width, int height){

  }
}

では上記のソースコードを「Sample01.java」の名前で保存し、その保存したディレクトリで次のように実行して下さい。

javadoc -d doc Sample01.java

「doc」ディレクトリ内にある「index.html」ファイルをブラウザで見てください。

クラスに対する説明文は2行に渡って記述していますが、<br>を記述していませんので表示上は続けて表示されます。