Javadocの記述が不完全なときに警告を出そうとして、どのような設定があるか調べたメモです。
チーム開発でJavadocをどの程度書くかどうか、意識を統一するのにこの記事をご活用いただければと思います。
前編の記事
未指定の Javadoc タグ
"未指定の Javadoc タグ"をONにすると、メソッドに定義されていてJavadocに記載されていないパラメータや例外などがある場合に警告を出します。
メンバーの可視性を次のように設定
設定した可視性以上のJavadocのみ、"未指定の Javadoc タグ"の警告を出します。
オーバーライドしたメソッドの実装を無視
Javaでは、オーバーライドしたメソッドのJavadocは、子クラスの内容で親クラスの内容を上書きした内容となります。
以下の例では、子クラスでdescriptionと変数xの記述を上書きし、他のparamとreturnについては、親クラスの記述が引き継がれています。
"オーバーライドしたメソッドの実装を無視"をOFFにすると、オーバーライドしたメソッドであっても、未指定の Javadoc タグがある場合には警告を出します。
ただし、@Overrideアノテーションが付いている場合、警告は出ません。
詳しい仕様と仕様が策定された経緯につきましてはこちらをご覧ください。
メソッド型パラメータを無視
メソッド型パラメータとは、
ジェネリックメソッドにおいて、メソッドの戻り値の型の直前に書かれた<T>などの型の仮型パラメータのことです。
(参考:
Java ジェネリクス（クラス、メソッドを定義する） - Qiita
)
"メソッド型パラメータを無視"がONのときは、この<T>のためのJavadoc(@param <T>)がなくても警告を出しません。
OFFにすると、警告を出します↓
未指定の Javadoc コメント
"未指定の Javadoc コメント"をONにすると、Javadocが記載されていない場合に警告を出します。
"メンバーの可視性を次のように設定"を"Protected"にした時の表示です↓
メンバーの可視性を次のように設定
設定した可視性以上のJavadocのみ、警告を出します。
オーバーライドしたメソッドの実装を無視
"オーバーライドしたメソッドの実装を無視"をONにすると、オーバーライドしたメソッドにJavadocが無くても警告を出しません。
オーバーライドしたメソッドは、Javaでは親クラスのJavadocが使用されるため、指定しなくても問題ないことが多いかもしれません。
"オーバーライドしたメソッドの実装を無視"をOFFにすると、オーバーライドしたメソッドにも警告を出します。
"未指定の Javadoc タグ > オーバーライドしたメソッドの実装を無視"
の設定とは違い、こちらは@Overrideアノテーションのあるなしでの挙動の違いはありません。
オーバーライドしたメソッドに親と同じ内容のJavadocを書ときは、{@inheritDoc}タグを使うと便利です。
/** * {@inheritDoc} */ @Override public int calcA(int x, int y, int z) { return x + y + z + 1; }
参考: オーバーライドしたメソッドのJavadoc - 気付いたとき、気が向いたとき。by ykhr
環境
- eclipse 2019-12 (https://mergedoc.osdn.jp/ からPleiades All in One Eclipse(Mac 64 bit/Full Edition/Java)をダウンロードしました)
あとがき
"未指定の Javadoc タグ > オーバーライドしたメソッドの実装を無視" の設定が自分の想定と違った動作をしたので意外と苦戦しました。
