良く使うJavadocコメントの書き方

●Javadocコメント記述

まずは基本で下記の様に書く

/** ~ */

ここで書いた内容が、Javadocを生成した時にHTMLになる。

Eclipseを使っていれば、わざわざ生成せずともマウスオーバーなどでどの様に表示されるか確認できる。

加えてEclipseでは、Javadocコメントを書く宣言部分だけではなく、その参照先でも確認できるので、書いておくと非常に便利。


●継承元のJavadocコメントと同じになる
※v1.4
{@inheritDoc}
@param arg {@inheritDoc}


●クラス、メソッド、フィールドへのリンク
※v1.2
※@seeと違って文中で使える。
※ラベルが付けられる。

{@link クラス名#メソッド名(引数の型, …)またはクラス名#フィールド名 ラベル}

上記だとコードフォントになる様なので、ラベルを付ける場合は下記が良い。

{@linkplain クラス名#メソッド名(引数の型, …)またはクラス名#フィールド名 ラベル}
※v1.4

例
{@link java.lang.Object#equals(Object)}
→クラス名の前にパッケージ名も指定できる。

{@linkplain Object#equals(Object) オブジェクトクラスの比較メソッド}
→ラベルを付けた場合


●非推奨タグ
※v1.0
※「使用すべきではありません。」等と表示される。
※Eclipse上で取り消し線が引かれて見える様になるので、視覚的に分かり易い。
※JSP等は取り消し線が反映されないので使用箇所を検索して確認が必要。

@deprecated コメント

下記の様にして使うと良い。
@deprecated 代わりに{@link クラス名#メソッド名(引数の型, …)またはクラス名#フィールド名 ラベル}を使用してください。


●バージョン系タグ
※各プロジェクトでルールがあればそれに従う。
※日付とJavaのバージョンを記載できると、いつどのJavaのバージョンで動作確認されたかが分かり易くなる。ライブラリ依存などもあるがそこまで書かなくてもいいだろう。
※バージョン毎に言語仕様やパッケージが増えるので、書いておけば有意義。
※アプリとしてのバージョンは、SubversionやGit等のバージョン管理システムで管理すれば良い。

@since 初版のバージョンを書く
※v1.1
@version 改版のバージョンを書く
※v1.0

タグを続けて書くと、改行されて順番通りに表示される。

例
@since 2019-01-22 Java1.4.2_19
@version 2020-01-22 Java1.6.0_45
@version 2020-06-20 Java1.8.0_112