Javadocの記述が不完全なときに警告を出そうとして、どのような設定があるか調べたメモです。
チーム開発で、Javadocをどの程度書くかどうか、意識を統一するのにこの記事をご活用いただければと思います。
Javadocの警告設定
Javadocの書き方がよくないときに警告を出す設定の場所は、
設定 > Java > コンパイラー > Javadoc
です。
Javadocコメントを処理
"Javadocコメントを処理"をONにすると、Javadocとメソッドが連携されます。 変数名を選択したときにJavadocのparamの変数名もハイライトされます。
ONのとき↓
OFFのとき↓
また、ONにすると、変数のリネーム時にJavadocのparamの変数も同時に変更されます。
ONのとき↓
OFFのとき↓
誤った形式の Javadoc コメント
"誤った形式の Javadoc コメント"をONにすると、波かっこが閉じていないときなどに警告を出します。
メンバーの可視性を次のように設定
設定した可視性以上のJavadocのみ、警告を出します。
可視性をProtectedにしたときに、PublicとProtedtedメソッドのにのみ警告が出て、パッケージとPrivateのメソッドに警告は出ません↓(タグ引数の検証をONにしたときの警告)
タグ引数の検証 (@param, @throws, @exceptions, @see, @link)
"タグ引数の検証"をONにすると、@param, @throws, @exceptions, @see, @linkに
指定されたクラスやメソッドが存在しないときに警告を出します。
min1という引数はメソッドに存在しないため、警告が出ます↓
Nowhere.nomthodという存在しないクラスとメソッドを参照しているので警告が出ます↓
不可視参照をレポート
"不可視参照をレポート"をONにすると、 不可視なメソッドなどを参照をしたときに警告を出します。不可視な参照とは、例えば他のクラスのprivateなメソッドや定数です。
他のクラス(SamplePrivateクラス)のprivateな定数(DEFAULT_NAME)を参照しているので、警告が出ます↓
使用すべきでない参照をレポート
"使用すべきでない参照をレポート"をONにすると、非推奨(Deprecated)となったメソッドや変数を参照したときに警告します。
タグ記述の欠落
"タグ記述の欠落"の設定では、
@param 変数名や@returnなどのタグのあとの記述が無いときに警告を出します。
@return タグの検証ではその名の通り、@returnタグの後に何も書かれていなければ警告を出します。その他のタグの後には何も書かれていなくても警告を出しません。
全ての標準タグを検証にすると、全ての標準タグにおいて、タグの記述がない場合に警告を出します。標準タグとは
javadoc - Java API ドキュメントジェネレータ
に記載されているタグです。
後編
長くなったので続きます。
環境
- eclipse 2019-12 (https://mergedoc.osdn.jp/ からPleiades All in One Eclipse(Mac 64 bit/Full Edition/Java)をダウンロードしました)
