JavadocStyle

CheckStyle公式ドキュメント

検証環境

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

---

チェック概要

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

Javadocコメントが適切に形成されていることを確認するために、コメントをチェックする。
以下のチェックを行う。

• 最初の文が適切な句読点で終わるようにする（デフォルトでは「.」、「?」、「!」）
• 説明のないJavadocステートメントのテキストをチェックする 空のJavadoc、@paramや@returnのようなタグだけを持つJavadocの両方が含まれる
• テキストに不完全なHTMLタグがないかどうかをチェックする HTMLタグに対応する終了タグがあるかどうかを確認し、ない場合は「Unclosed HTML tag found:」エラーを発行する 終了タグが前の開始タグなしで見つかった場合、「Extra HTML tag found: 」エラーを発行する
• パッケージのJavadocコメントが整形式であり、package-info.javaファイルが存在することをチェックする
• 許可されたHTMLタグであるかどうかをチェックする

このチェックは、Sunから提供されているDocCheck docletによるチェックを模したものとなっている。

プロパティ

プロパティ	型	デフォルト値	説明	追加バージョン
scope	Scope	private	Javadocコメントをチェックする可視性スコープを指定	3.2
excludeScope	Scope	null	Javadocコメントをチェックしない可視性スコープを指定	3.4
checkFirstSentence	boolean	true	最初の文の文末が適切かどうかをチェックするかどうか	3.2
endOfSentenceFormat	Pattern	"([.?!][ \t\n\r\f<])|([.?!]$)"	文末のマッチング形式を指定	5.0
checkEmptyJavadoc	boolean	false	Javadocが空かどうかをチェックするかどうか	3.4
checkHtml	boolean	true	不完全なHTMLタグをチェックするかどうか	3.2
tokens	トークンの サブセット	ANNOTATION_DEF, ANNOTATION_FIELD_DEF, CLASS_DEF, CTOR_DEF, ENUM_CONSTANT_DEF, ENUM_DEF, INTERFACE_DEF, METHOD_DEF, PACKAGE_DEF, VARIABLE_DEF, RECORD_DEF, COMPACT_CTOR_DEF	チェック対象のトークン	3.2

〇 Scopeには以下の値が設定可能
public を指定すると、public な修飾子を持つ項目のみがチェックされる。
protected を指定すると、public および protected 修飾子のみをチェックする。

• nothing
• public
• protected
• package
• private
• anoninner

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

値	説明
ANNOTATION_DEF	アノテーション宣言
ANNOTATION_FIELD_DEF	アノテーションフィールド宣言
CLASS_DEF	クラス宣言
COMPACT_CTOR_DEF	引数なしコンストラクタ宣言
CTOR_DEF	コンストラクタ宣言
ENUM_CONSTANT_DEF	Enum定数宣言
ENUM_DEF	Enum宣言
INTERFACE_DEF	インターフェース宣言
METHOD_DEF	メソッド宣言
PACKAGE_DEF	パッケージ宣言
RECORD_DEF	レコード宣言
VARIABLE_DEF	フィールド・ローカル変数宣言

設定＋チェック実行結果

プロパティ設定なし

設定ファイル記述方法

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

チェック実行例

public class MyClass {
    // OK
    /**
     * Some description here.
     */
    private void methodWithValidCommentStyle() {}

    // NG 文末にピリオド、クエスチョンマーク、エクスクラメーションマークのいずれも存在しない
    /**
     * Some description here
     */
    private void methodWithInvalidCommentStyle() {}
}

プロパティ設定あり

scope

Javadocコメントをチェックする可視性スコープ。
デフォルト「private」なのですべてのアクセス修飾子がチェック対象となる。

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocStyle">
            <property name="scope" value="public"/>
        </module>
    </module>
</module>

チェック実行例

public class MyClass {
    // NG 文末にピリオド、クエスチョンマーク、エクスクラメーションマークのいずれも存在しない
    /**
     * Some description here
     */
    public void test1() {}

    // OK privateメソッドはチェック対象外
    /**
     * Some description here
     */
    private void test2() {}
}

excludeScope

Javadocコメントをチェックしない可視性スコープ。
デフォルト「null」なのですべてのアクセス修飾子がチェック対象となる。

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocStyle">
            <property name="excludeScope" value="package"/>
        </module>
    </module>
</module>

チェック実行例

public class MyClass {
    // NG 文末にピリオド、クエスチョンマーク、エクスクラメーションマークのいずれも存在しない
    /**
     * Some description here
     */
    public void test1() {}

    // OK privateメソッドはチェック対象外
    /**
     * Some description here
     */
    private void test2() {}
}

checkFirstSentence

最初の文の文末が適切かどうかをチェックするかどうか（デフォルト：true）

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocStyle">
            <property name="checkFirstSentence" value="false"/>
        </module>
    </module>
</module>

チェック実行例

public class MyClass {
    // OK 文末はチェックしない
    /**
     * Some description here
     */
    public void test1() {}
}

endOfSentenceFormat

文末のマッチング形式

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocStyle">
            <property name="endOfSentenceFormat" value="([!][ \t\n\r\f<])\|([!]$)"/>
        </module>
    </module>
</module>

チェック実行例

public class MyClass {
    // NG 文末にピリオドが存在しない
    /**
     * Some description here?
     */
    public void test1() {}

    // OK
    /**
     * Some description here.
     */
    public void test2() {}
}

checkEmptyJavadoc

Javadocが空かどうかをチェックするかどうか（デフォルト：false）

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocStyle">
            <property name="checkEmptyJavadoc" value="true"/>
        </module>
    </module>
</module>

チェック実行例

public class MyClass {
    // NG Javadocに何も記述がないのでNG
    /**
     * 
     */
    public void test1() {}

    // OK
    /**
     * Some description here.
     */
    public void test2() {}
}

checkHtml

不完全なHTMLタグをチェックするかどうか（デフォルト：true）

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocStyle">
            <property name="checkHtml" value="false"/>
        </module>
    </module>
</module>

チェック実行例

public class MyClass {
    // OK 不正なHTMLタグのチェックはしないので「<p」はチェックNGとはならない
    /**
     * Some description here.
     * 
     * <p
     */
    public void test1() {}
}

tokens

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

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocStyle">
            <property name="tokens" value="CLASS_DEF"/>
        </module>
    </module>
</module>

チェック実行例

public class MyClass {
    // OK メソッドはチェック対象外
    /**
     * Some description here.
     * 
     * <p
     */
    public void test1() {}
}