Javadocの対象となるコメントの記述方法

コメントの記述方法を確認しておきます。Javaとしてのコメントの記述方法と、その中でもJavadocの対象となるコメントの記述方法です。

Javaのコメント記述方法

Javaのソースコード中にコメントを記述する場合は次の二通りの方法があります。

(1)ブロックコメント

ブロックコメントでは「/*」から「*/」で囲まれた部分が全てコメントとなります。複数行を含むこともできますし、1行で使用することもできます。

/*
  コメント
  コメント
*/

/* コメント */

(2)単一行コメント

単一の行に対してコメントする場合は「//」も利用できます。この場合は「//」の後から改行までがコメントとなります。

// コメント

Javadocの対象となるコメント記述方法

Javadocを利用する場合でもJavaのソースコード中に記述することに違いはありませんのでJavaの規則に従いますが、Javadocでドキュメント生成の対象とする場合には次のように記述します。

/**
  コメント
  コメント
*/

/** コメント */

「/**」から「*/」までに書かれた部分がJavadocの対象となります。

開始が「/**」と通常のコメントの記述方法である「/*」と比べて「*」が1つ多いですが、「/*」の後にコメントとしての「*」が続けて書かれているものと同じなのでJavaのコメントであることに変わりはありません。Javaのコメントの中で特に「/**」で始まるものだけを対象にすると考えて下さい。

なおJavadocでは複数行のコメントを記述する場合に各行の先頭に「*」が記述されていた場合は破棄し、その後の文字列だけをコメントの対象とします。また「*」よりも前に記述されている空白やタブも合わせて破棄します。よってJavadoc用のコメントでは次のような記述方法がよく使われます。

/**
 * コメント
 * コメント
 * コメント
*/

上記は次のように記述した場合と同じようにJavadocでは扱われます。

/**
 コメント
 コメント
 コメント
*/

では次のページにて実際にソースコードに記述されたコメントからドキュメントを生成してみます。