JavadocMethod

CheckStyle公式ドキュメント

検証環境

Checkstyleバージョン：10.3.3
Javaバージョン：17

---

チェック概要

チェック追加バージョン
Checkstyle 3.0

メソッドまたはコンストラクタの Javadoc をチェックする。

paramタグが存在しないパラメータの検出はallowMissingParamTagsプロパティで抑制可能
戻り値があるがreturnタグが存在しないJavadocはallowMissingReturnTagプロパティで違反を抑制可能

メソッドシグネチャのthrowsもしくはメソッドの処理内のthrow newによって、例外がスローされることが宣言されているが、Javadocコメントにthrowsタグが存在しないことをチェックする場合はvalidateThrowsプロパティの有効化によって違反として検出可能となる。

以下の箇所では throw new はチェックされない

• tryブロックの中(catch付き)。
  tryブロックの中でスローされた例外がcatchブロックでキャッチできるかどうか判断できないため、tryブロックは完全に無視される。ただし、catchブロックやfinallyブロック、catchのないtryブロックはチェックされる
• ローカルクラス、匿名クラス、ラムダ式。
  いつ評価されるか分からないので、無視される。

throwsタグに記載する例外クラスについて、Checkstyleは例外型の階層に関する情報を持っていないため、ベースクラスの記述は別の例外型とみなされる。回避策としては、javadocで両方の型（親と正確な型）を指定する必要がある。

プロパティ

プロパティ	型	デフォルト値	説明	追加バージョン
allowed Annotations	String[]	Override	ドキュメントの欠落を許容するアノテーションを指定する	6.0
validateThrows	boolean	false	throwsタグの検証を行うかどうか	6.0
access Modifiers	AccessModifierOption[]	public, protected, package, private	Javadocコメントがチェックされるアクセス修飾子を指定	8.42
allowMissing ParamTags	boolean	false	メソッドにパラメータがあるにもかかわらず、Javadoc に一致する param タグがない場合に違反を無視するかどうか	3.1
allowMissing ReturnTag	boolean	false	メソッドが非void型を返し、Javadoc に return タグがない場合、違反を無視するかどうか	3.1
tokens	トークンの サブセット	METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF	チェック対象のトークン	3.0

〇AccessModifierOptionには以下の値が設定可能 + public + protected + package + private

〇トークンのサブセットには以下の値が設定可能

値	説明
ANNOTATION_FIELD_DEF	アノテーションフィールド宣言
COMPACT_CTOR_DEF	引数なしコンストラクタ宣言
CTOR_DEF	コンストラクタ宣言
METHOD_DEF	メソッド宣言

設定＋チェック実行結果

プロパティ設定なし

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod"/>
    </module>
</module>

チェック実行例

/**
 * 引数があるがJavadocに記載がないためNG
 * 
 * @throws IOException if some problem
 */
public void doSomething8(File file) throws IOException {
    if (file == null) {
        throw new IOException();
    }
}

プロパティ設定あり

allowedAnnotations

ドキュメントの欠落を許容するアノテーションをコンマ区切りで指定する

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod">
            <property name="allowedAnnotations" value="Test"/>
        </module>
    </module>
</module>

チェック実行例

/**
 * 「allowedAnnotations」に指定のアノテーションが付与されているのでチェック対象外
 */
@Test
public void doSomething8(File file) throws IOException {
    if (file == null) {
        throw new IOException();
    }
}

validateThrows

throwsタグの検証を行うかどうか（デフォルト：false）

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod">
            <property name="validateThrows" value="true"/>
        </module>
    </module>
</module>

チェック実行例

/**
 * 例外をスローしているがthrowsタグが欠落しているのでNG
 * @param file
 *         ファイル
 */
public void doSomething8(File file) throws IOException {
    if (file == null) {
        throw new IOException();
    }
}

accessModifiers

Javadocコメントがチェックされるアクセス修飾子をコンマ区切りで指定する

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod">
            <property name="accessModifiers" value="protected"/>
        </module>
    </module>
</module>

チェック実行例

/**
 * 「accessModifiers」に指定のアクセス修飾子ではないのでチェック対象外
 */
@Test
public void doSomething8(File file) throws IOException {
    if (file == null) {
        throw new IOException();
    }
}

allowMissingParamTags

パラメータが存在するがparamタグが存在しないJavadocを許容するかどうか（デフォルト：false）

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod">
            <property name="allowMissingParamTags" value="true"/>
        </module>
    </module>
</module>

チェック実行例

/**
 * 引数についてJavadocに記載がないが「allowMissingParamTags=true」なのでOK
 * 
 * @throws IOException if some problem
 */
public void doSomething8(File file) throws IOException {
    if (file == null) {
        throw new IOException();
    }
}

allowMissingReturnTag

戻り値があるがreturnタグが存在しないJavadocを許容するかどうか（デフォルト：false）

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod">
            <property name="allowMissingReturnTag" value="true"/>
        </module>
    </module>
</module>

チェック実行例

/**
 * 戻り値についてJavadocに記載がないが「allowMissingReturnTag=true」なのでOK
 * @param file
 *         ファイル
 */
public String doSomething8(File file) {
    if (file == null) {
        return "nullだよ";
    }
    return "aaa";
}

tokens

チェック対象のトークンをコンマ区切りで指定する

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod">
            <property name="tokens" value="CTOR_DEF"/>
        </module>
    </module>
</module>

チェック実行例

/**
 * 「tokens」にメソッド宣言が含まれていないのでチェック対象外
 */
@Test
public void doSomething8(File file) throws IOException {
    if (file == null) {
        throw new IOException();
    }
}