WEB+DB PRESS Vol.51 特集2「“巧い”メソッド設計」連動企画

第1回 Javadocリファレンス

この記事を読むのに必要な時間:およそ 9 分

Javadocタグ

Javadocタグは,Javadocツールで処理するための特別なキーワードです。大文字と小文字が区別されます。ドキュメントタグはブロックタグとインラインタグの2つに分類されます。ブロックタグは @(アットマーク)で始まり,タグセクションの行頭で使用します。インラインタグは波括弧で囲まれ,説明文中で使用します。

なおJDKのバージョンは1.5以降を想定しています。

表3 ドキュメントタグ一覧

タグ内容複数回使用概要ファイルパッケージクラスメソッドフィールド
@param 型パラメータ 説明ジェネリクスの型パラメータと説明を記述します。×××
@param 引数の名前 説明メソッドの引数の名前と説明を記述します。××××
@return 説明メソッドの戻り値の説明を記述をします。×××××
@throws クラス名 説明メソッドがスローする可能性のある例外について記述します。××××
@author 作者名パッケージまたはクラスの作成者の名前を記述します。××
@version バージョン情報ソフトウェアのバージョンを記述します。××
@see package.class#member リンクの表示名クラス、メソッド、フィールドへのリンク情報を記述します。
@see <a href="URL">リンクの表示名相対URLまたは絶対URLへのリンクを記述します。
@see "参照先テキスト"URLでアクセスできない関連項目へのリンク情報を記述します。
@since 導入バージョンパッケージ、クラス、フィールド、メソッドが導入されたバージョンを記述します。
@serial フィールドの説明デフォルトの直列化可能なフィールドの意味、取り得る値のリストを示します。×××××
@serial include | excludeパッケージを直列化された形式に表示するかどうかを指定します。××××
@serialField フィールド名 フィールドの型 説明serialPersistentFieldsフィールドによって宣言された直列化可能フィールドの説明を記述します。××××
@serialData 説明直列化された形式でのデータの型と順序を説明を記述します。×××××
@deprecated 説明そのクラス、メソッド、フィールドの使用が非推奨になったことを示します。×××
{@link package.class#member リンクの表示名}パッケージ、クラス、メンバーへのインラインリンクをコードとして表します。-
{@linkplain package.class#member リンクの表示名}パッケージ、クラス、メンバーへのインラインリンクを表します。-
{@docRoot}生成されるページから見た、生成ドキュメントのルートディレクトリへの相対パスを表します。-
{@code コード}コードをスタイルで表示します。-
{@literal テキスト}テキストをHTMLとして解釈せず、そのまま表示します。-
{@inheritDoc}実装しているインタフェースまたは継承したスーパークラスのドキュメントコメントをコピーします。-××××
{@value package.class#field}定数フィールドの値を表示します。-

ブロックタグについては慣習的に次の規約があります。

  • ブロックタグは表3ドキュメントタグ一覧の順番に記述する。
  • 同じタグは1ヵ所にグループ化して記述する。
  • 同じタグの中でも記述する順序がある。⁠詳細は各タグの説明を参照)

以下,それぞれのタグについて一言解説していきます。

@param 型パラメータ説明

ジェネリックスの型パラメータを説明します。JDK 1.5以降で使用します。型パラメータの意味は明白であるため省略されることが多いです。

@param 引数の名前

生成ドキュメントの[パラメータ]の項目に表示されます。名前には宣言の引数名と同じ名前を記述します。パラメータの説明には引数の型や,事前条件,意味などを記述します。説明の最初の文は体言止めにします。事前条件には引数の値の範囲やnullを許可するかなどの条件を記述します。また引数に副作用がある場合は明記しておいたほうがよいでしょう。

@paramタグを複数使用する場合はメソッド宣言の引数と同じ順序で記述します。引数がない場合は@paramタグを記述しません。

@return 説明

生成ドキュメントの[戻り値]の項目に表示されます。戻り値の説明の最初の文は体言止めで記述します。次の文以降で戻り値の型や値の範囲などの事後条件について記述します。@returnタグはコンストラクタやvoidのメソッドでは使用しません。

@throws クラス名 説明

生成ドキュメントの[例外]の項目に表示されます注4⁠。スローされる例外クラス名とその例外がどういう場合に発生するかを記述します。例外クラス名は単純名(パッケージを指定しないクラス名)で記述します。単純名で解決できない場合は「検索順序注5⁠」に従ってクラスを検索します。例外の説明は体言止めで記述します。@throwsタグは複数指定できます。

チェックされる例外(try-catchまたはthrowsが必要な例外)はメソッド宣言に記述されているすべての例外について@throwsタグを記述します。実行時例外(RuntimeExceptionとそのサブクラス)は,事前条件に違反していることを示す例外を記述します。ただしメソッド内部の実装に依存した例外は記述してはいけません。記述すると公開APIの一部となってしまい,実装の変更ができなくなります。

  • 例)× ArrayIndexOutOfBoundsException
  •     ○ IndexOutOfBoundsException

前者は,内部のデータ構造が配列であることを公開してしまいますが,後者であれば別のデータ構造をとることができます。

Errorとそのサブクラスについては@throwsタグに記述してはいけません。

注4)
例外を説明するタグに@exceptionタグがありますが @throwsタグとの違いはまったくありません。少ない文字数で記述できる@throwsを使ったほうがよいでしょう。
注5)
Javadocツールのリファレンスページ

@author 作者名

生成ドキュメントの[作成者]の項目に表示されます。このタグはデフォルトでは無効になっているため,javadocコマンドで-authorオプションを指定して有効化する必要があります。パッケージの作成者はそのパッケージの仕様に対しての主な貢献者(個人またはグループ⁠⁠,クラスの作成者はそのクラスの主な作成者を記述します。作成者を複数記述する場合は古いバージョンの作成者から順に記述します。

@version バージョン情報

生成ドキュメントの[バージョン]の項目に表示されます。このタグはデフォルトでは無効になっているため,javadocコマンドで-versionオプションを指定して有効化する必要があります。バージョンはCVSやSubversionのようなバージョン管理システムでファイルをチェックアウトしたときのバージョンを記述します。

/**
 * @version 1.51 2009/06/24
 */

@see package.class#member リンクの表示名

クラス,メソッド,フィールドへのリンク情報を記述します。

同一クラス内へのリンクの場合,パッケージ名とクラス名を省略できます。同一パッケージのクラスへのリンクの場合,パッケージ名を省略できます。リンクの表示名を省略した場合はpackage.class#memberが使われます。

ドキュメント化の対象ではないクラスにリンクする場合はjavadocコマンドの-linkオプションを指定します。

オーバーロードされたメソッドへのリンクを指定する場合にはメソッドの()を省略します。特定のメソッドだけにリンクしたい場合は引数の型を指定します。

複数指定する場合の記述の順序は慣習的に以下のようにします。

  1. 同一クラス内への参照
  2. 同一パッケージ内のクラスへの参照
  3. ほかのパッケージのクラスへの参照

同じクラス内での記述の順序は次のとおりにします。

  1. フィールド
  2. コンストラクタ
  3. メソッド
  4. ネストしたクラス

フィールドやメソッドが複数ある場合はアルファベット順かほかの論理的なまとまりで順序づけします。

コンストラクタやオーバーロードされたメソッドは引数の数の少ないものから順番に,引数が同数の場合はアルファベット順やほかの論理的な順序で記述します。

@see <a href="URL">リンクの表示名</a>

相対URLまたは絶対URLへのリンクを記述します。直接リンク先を指定できるため,作成するドキュメントに含まれるPDFやサンプルコードなどへのリンク,情報源となる外部サイトを指定します。

@see "参照先テキスト"

この形式では"参照先テキスト"はリンクとしては生成されません。タグへの引数には書籍や設計書の名前などURLではアクセスできない情報を指定します。参照の文字列は二重引用符で囲む必要があります。

著者プロフィール

小棚木章直(おだなぎあきなお)

(株)富士通ビー・エス・シーに勤務しているソフトウェアエンジニア。主にJava読書会で活動。アジャイル開発に興味があり,XPJUGのイベントに参加することも多い。最近はバグパターンをテーマにしている。