Javadoc用のコメントの書き方

Version 1.0, 1997年9月18日, 川口 浩司

前書き

JDKに付属している Javadoc というツールは、ソースリスト上のコメントから、自動的にドキュメントを作成してくれます。作成される書式は、APIのマニュアルと同じものです。

Javadocについては、Javasoftから以下のようなドキュメントが公開されています。（詳しくは Javadoc Home Page を参照してください）

ここでは、これらのドキュメントを元に、日本語での応用例を含めて、コメントの書き方について自分なりにまとめてみました。

コメントの様式

説明文

タグ

  1. タグの順序

    タグは次の順序で記述する。読みやすくするために、関連のあるタグごとに空行でブロック分けをすることが出来る。下の一覧でのブロック分けは、その一例である。 

    @author (必須、クラス・インターフェースのみに使用)
@version (必須、クラス・インターフェースのみに使用)

@param (メソッドのみ)
@return (メソッドのみ)
@exception

@see
@since
@deprecated
  2. @author 作成者名

    クラスの作成者（または更新者）を記述する。
    authorが複数いる場合は、1人1タグが望ましい。最初にクラスの作成者を記述し、以下は修正していった順に追加していくようにする。

  3. @version バージョン

    クラスのバージョンを記述する。

  4. @param 名前 説明

    メソッドのパラメータの名前と説明を記述する。
    パラメーターの名前には小文字を使い、<code>タグは使用しない。 メソッドの意味が明らかな場合でも、@paramは全てのパラメータについて必要である。 複数記述する場合、宣言されている順番で記述すること。

  5. @return 説明

    戻り値の説明を記述する。void以外の全てのメソッドに必要である。

  6. @exception 名前 説明

    メソッドの発生する例外の名前と、その原因を記述する。
    @exceptionが複数ある場合は、例外名のアルファベット順で記述する。

  7. @see 参照先

    参照先を記述する。複数の指定が可能である。
    クラス名の後に「#」を使って、フィールド、メソッド、コンストラクタを付けることができる。オーバーロードメソッド等の場合は、区別のために引数リストが必要である。

  8. @since バージョン

    どのバージョンから追加されたかを記述する。

  9. @deprecated 理由

    使用が推奨されていない場合に記述する。

補足

KAWAGUCHI, Koji <koji@k-kawaguchi.com>