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

第1回 Javadocリファレンス

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

@since 導入バージョン

生成ドキュメントの[導入されたバージョン]の項目に表示されます。ここでのバージョンはバージョン管理システムのバージョンではなく,ソフトウェアのリリースバージョンを記述します。複数のソフトウェアで使用されている場合にはそれぞれのバージョンを指定します。

@serial フィールドの説明

生成ドキュメントの[直列化された形式]-[直列化されたフィールド]の項目に表示されます注6,注7⁠。最初のリリース後にフィールドを追加した場合は追加したバージョンを@sinceタグを使って示します。

注6)
直列化可能フィールドはprivateで宣言されていてもAPIとして公開されるため,Serializableの実装には注意してください。
注7)
『Effective Java第2版』/Joshua Bloch著/柴田 芳樹 訳/ISBN978-4-89471-499-1/ピアソン・エデュケーション/2008年/279ページ

@serial include

package privateクラスやprivateクラスを[直列化された形式]のページに表示することを示します。ただしパッケージがexclude指定されている場合は表示されません。

@serial exclude

publicクラスやprotectedクラスを[直列化された形式]のページに表示しないことを示します。パッケージでexclude指定するとパッケージのすべてのクラスが表示されません。

@serialField フィールド名 フィールドの型 説明

生成ドキュメントの[直列化された形式]-[直列化されたフィールド]の項目に表示されます。ObjectStreamField配列の各要素の対して@serialFieldタグを記述する必要がありますリスト6注8⁠。

リスト6 @serialField フィールド名 フィールドの型 説明

/**
 * @serialField id int会員のID番号。正の値だけ取り得ます。
 * @serialField name String会員の名前。この値はnullになることがあります。
 */
private static final ObjectStreamField[] serialPersistentFields = {
    new ObjectStreamField("id", int.class),
    new ObjectStreamField("name", String.class)
};
注8)
serialPersistentFieldsフィールドはprivateフィールドですが,そのドキュメントコメントはAPIとして公開されます。

@serialData 説明

生成ドキュメントの[直列化された形式]-[直列化メソッド]-[シリアルデータ]の項目に表示されます。このタグはwriteObjectメソッド,readObjectメソッド,writeExternalメソッド,readExternalメソッド,writeReplaceメソッド,およびreadResolveメソッドで使用します注9⁠。

注9)
writeObjectメソッド,readObjectメソッドはprivateメソッドですが,APIとして公開されます。

@deprecated 説明

最初の文に非推奨になった時期と代替手段のリンク先({@link}を使う)を記述します。その後の文で非推奨になった理由を説明します。最初の文は概要セクションと索引にコピーされます。

JDK 5.0以降で作成する場合は@Deprecatedアノテーションと@deprecatedタグの両方を使いますリスト7⁠。@deprecatedタグは単なるドキュメンテーションであり,プログラムとしての影響力はありません(javacで警告が出ますが,言語仕様上は意味をなしません⁠⁠。一方,@Deprecatedアノテーションはコンパイル時も実行時にも非推奨として認識できますが,代替手段を示すことができません。

リスト7 @deprecated

/**
 * @deprecated 1.2以降では{@link hoge()}を使用してください。indexはまったく使っていないため,引数なしのメソッドに移行してください。
 */
 @Deprecated
 public void hoge(int index)

{@link package.class#member リンクの表示名}

パッケージ,クラス,メンバーへのインラインリンクを表します。{@link}タグは@seeタグと同じようにリンクを作成しますが,[関連項目]ではなく,説明文中にインラインで作成されます。また{@link}タグは何度でも,どこでも使用できます。リンクの表示名を省略した場合はpackage.class#memberが使われます。ドキュメント化の対象ではないクラスにリンクする場合はjavadocコマンドの-linkオプションを指定します。

{@linkplain package.class#member リンクの表示名}

パッケージ,クラス,メンバーへのインラインリンクを表します。{@link}タグとの違いはリンクの表示名を<code>スタイルではなく通常のテキストで表示することです。

{@docRoot}

生成されるページから見た,生成ドキュメントのルートディレクトリへの相対パスを表します。このタグは著作権表示や会社のロゴなどすべてのページから参照されるファイルを組み込むときに使います。ドキュメントコメント本文中でも使えますが,ヘッダやフッタの定義に使うとより効果的です。

{@code コード}

コードを<code>スタイルで表示します。このタグはJDK 1.5から導入されました。{@code}タグは<code>{@literal}</code>と同等です。{@code}タグを使うと不等号記号をそのまま使えます。

例){@code index > 0} ⇒ <code>index &gt; 0</code>

{@code}は次のものを記述するときに使います。

  • Java言語のキーワード
  • パッケージ名
  • クラス名
  • メソッド名
  • インタフェース名
  • フィールド名
  • 引数名
  • コードのサンプル

{@literal テキスト}

テキストをHTMLとして解釈せず,そのまま表示します。このタグはJDK 1.5から導入されました。{@literal}タグを使うと不等号記号をそのまま使えます。

{@inheritDoc}

実装しているインタフェースまたは継承したスーパークラスのドキュメントコメントをコピーします。メソッドの主説明,@returnタグ,@paramタグ,@throwsタグで利用できます。インタフェースとスーパークラスの両方にドキュメントコメントが記述されている場合はインタフェースのコメントが優先されて継承されます。継承するドキュメントはドキュメント化対象のクラスまたはjavadocコマンドの-sourcepathで指定したパスのクラスである必要があります。

{@inheritDoc}タグを使う上で注意点が3つあります。

1つめはコピーされるのはJavadocドキュメントからではなく,ソースコードのドキュメントコメントからであるということです。たとえば,JDKのObject#toString()のコメントを{@inheritDoc}でコピーする場合,JDK付属のソースから英語のコメントがコピーされます。

2つめはインタフェースまたはスーパークラスのメソッドのドキュメントコメントがそのままコピーされるということです。そのため,リスト8リスト9のように継承元と矛盾を生じることがあります注10⁠。

リスト8 スーパークラスのコメント

/**
 * @return 値が設定されていない場合,このメソッドはnullを返します。
 */

リスト9 サブクラスのコメント

/**
 * @return {@inheritDoc}
 * このメソッドはnullを返すことはありません。
 */

3つめは例外はthrowsに宣言されているものだけが継承されることですリスト10⁠。実行時例外は自動的には継承されないため,必要であればその例外の@throwsタグの説明だけを継承するようにします。ここでも継承元と矛盾しないように注意してください。

リスト10 @throwsタグ

/**
 * @throws IllegalArgumentException {@inheritDoc}
 */
注10)
『プログラミング言語 第4版⁠⁠/Ken Arnold, James Gosling, David Holmes著/柴田芳樹 訳/ISBN978-4-89471-716-9/ピアソン・エデュケーション/2007年/426ページ

{@value package.class#field}

生成ドキュメントの[フィールドの詳細]に定数の説明の一部として定数値が表示されます。定数フィールドのドキュメントコメントで{@value}の引数を省略した場合は,そのフィールドの値を表示します。

引数を指定した場合は定数フィールド以外の場所でも利用でき,その定数フィールドの値を表示します。

著者プロフィール

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

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