Javadoc関連のチェックを行います。
パッケージ毎に package.html があるかどうかをチェックします。
Javadoc記述のルールがある現場でも、
パッケージドキュメンテーションは意外と見逃されています。
それは、JavadocをHTML化していないからです。
HTML化すればすぐに、パッケージドキュメンテーションも
書く必要がある事に気付くはずなんですが。
Javaファイルを識別する拡張子を設定します。
デフォルトは java です。
Javaファイルが存在するディレクトリ内にpackage.html が無い場合がチェック対象となります。
クラス(またはインターフェイス)のJavadoc定義をチェックします。
最低限、クラスのJavadocは書いておいた方がいいでしょう。
クラスはJavaの基本単位であり、
良いクラス設計は良いシステムを生むための第一歩となります。
クラスのJavadocには、そのクラスが実装している機能を簡潔に記述します。
機能がたくさんあるようならそのクラスは分割できますし
記述文に適していないクラス名が付いていたらそのクラスは改名する余地があります。
チェックを有効にするスコープ（アクセス識別子）を設定します。
ここで指定したスコープと同じかそれより制限の緩いクラスでチェックが有効になります。
デフォルトは private です。
この場合、全てのクラスでチェックが有効になります。
チェックを無効にするスコープを設定します。
ここで指定したスコープと同じかそれより制限の厳しいクラスでチェックが無効になります。
デフォルトは nothing です。
この場合、チェックを無効にするクラスはありません。
@author タグで有効なパターンを正規表現で指定します。
@version タグで有効なパターンを正規表現で指定します。
チェック対象を設定します。
クラスをチェック対象に入れます。
インターフェイスをチェック対象に入れます。
メソッドやコンストラクタのJavadoc定義をチェックします。
全メソッドのJavadocを書くことは正直大変で、
どの現場でも疎かになりがちです。
しかし、これをやる事でそのコードは格段に保守性が上がります。
コメントを書くこと自体が重要なのではなく
それによって適切なメソッド分割する事を実践していくからです。
「一つのメソッドで複数の事をしない」
これが大原則です。
メソッドが大きくなってきたら、すぐに分割する事を考えます。
まずは、1メソッド50行以内。この分かりやすい指針で始めましょう。
チェック対象にするスコープを設定します。
詳しくは JavadocType の欄を参考にして下さい。
RuntimeException （及びそのサブクラス）に対する@throws節の記述を許可するかどうかを設定します。
デフォルトは false です。
/**
* @throws RuntimeException ...
*/
private void func() {
...
}
true にします。throws句で定義された例外クラスのサブクラスに対する@throws節の記述を許可するかどうかを設定します。
デフォルトは false です。
/**
* @throws IOException ...
*/
private void func() throws Exception {
...
}
true にします。メソッドの引数で定義された変数の @param 節が存在しない事を許可するかどうかを設定します。
デフォルトは false です。
/**
*
*/
private void func(int i) {
...
}
i に対応する @param 節が存在しません。true にします。メソッドのthrows句で定義された例外の @throws 節が存在しない事を許可するかどうかを設定します。
デフォルトは false です。
void以外の戻り値を持つメソッドのJavadocに @return 節が存在しない事を許可するかどうかを設定します。
デフォルトは false です。
メソッドのJavadocそのものが存在しない事を許可するかどうかを設定します。
デフォルトは false です。
プロパティメソッドのJavadocそのものが存在しない事を許可するかどうかを設定します。
プロパティメソッドとは、いわゆるGetter/Setterメソッドの事を指します。
デフォルトは false です。
チェック対象を設定します。
メソッドをチェック対象に入れます。
コンストラクタをチェック対象に入れます。
変数のJavadoc定義をチェックします。
クラスやメソッドに比べれば、変数のJavadocはそれほど重要ではありません。
それよりも、適切な変数名を付ける事の方が大事です。
チェック対象にするスコープを設定します。
詳しくは JavadocType の欄を参考にして下さい。
Javadocコメントの妥当性をチェックします。
Sun の DocCheck というドックレットを利用しているようです。
まぁ、ここまでやらなくても良いような気もしますが…
DocCheckも(2006/8)現在まだベータ版ですし、導入は控えた方が無難です。
チェック対象にするスコープを設定します。
詳しくは JavadocType の欄を参考にして下さい。
最初の文だけをチェックします。
デフォルトは true です。
空のJavadocコメントをチェックします。
デフォルトは false です。
不完全なHTMLタグをチェックします。
デフォルトは true です。
必要・不必要なタグをチェックします。
プロジェクトでルールを決めたい場合に使用しましょう。
例えば author タグを必須にする等はよくあるルールです。
チェックするタグ名を指定します。
許可されるタグ値を、正規表現で指定します。
上記で指定したタグが発見されたときの警告レベルを指定します。
デフォルトは info です。
例えば、author タグを必須とするならば…
<module name="WriteTag"> <property name="tag" value="@author"/> <property name="tagFormat" value="\S"/> </module>
こんな感じにします。
逆に、incomplete タグが指定された箇所をチェックしたい場合は…
<module name="WriteTag"> <property name="tag" value="@incomplete"/> <property name="tagFormat" value="\S"/> <property name="severity" value="ignore"/> <property name="tagSeverity" value="warning"/> </module>
こんな感じに。