JavadocType

CheckStyle公式ドキュメント

検証環境

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

---

チェック概要

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

型定義のJavadocコメントをチェックする。
デフォルトでは、authorやversionのタグはチェックしない。
検証するスコープはScopeクラスを使用して指定し、デフォルトはScope.PRIVATE。 他のスコープを確認するには、プロパティscopeにScope定数のいずれかを設定する。
authorタグやversionタグのフォーマットを定義するには、authorFormatプロパティとversionFormatプロパティにそれぞれパターンを設定設定する。

内部クラスのauthorタグとversionタグは、チェックを行わない（外部クラスと同一であることが想定され、冗長な記述となるため）。

paramタグが存在しない型パラメータやレコードコンポーネントに対するチェックエラーの検出は、allowMissingParamTagsプロパティを定義することで抑制することができる。

プロパティ

プロパティ	型	デフォルト値	説明	追加バージョン
scope	Scope	private	Javadocコメントをチェックする可視性スコープを指定	3.0
excludeScope	Scope	null	Javadocコメントをチェックしない可視性スコープを指定	3.4
authorFormat	Pattern	null	@authorタグのパターンを指定	3.0
versionFormat	Pattern	null	@versionタグのパターンを指定	3.0
allowMissingParamTags	boolean	false	クラスが型パラメータを持つが、Javadocに一致するparamタグがない場合に、違反を無視するかどうか	3.0
allowUnknownTags	boolean	false	Javadocタグが認識されない場合の違反を無視するかどうか	5.1
allowedAnnotations	String[]	Generated	ドキュメントがなくても許容するアノテーションを指定する	8.15
tokens	トークンの サブセット	INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF, RECORD_DEF	チェック対象のトークン	3.0

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

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

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

値	説明
INTERFACE_DEF	インターフェース宣言
CLASS_DEF	クラス宣言
ENUM_DEF	Enum宣言
ANNOTATION_DEF	アノテーション宣言
RECORD_DEF	レコード宣言

設定＋チェック実行結果

プロパティ設定なし

設定ファイル記述方法

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

チェック実行例

// NG Javadocコメントがない
@SpringBootApplication
public class Application {}

// NG Javadocコメントがない
@Configuration
class DatabaseConfiguration {}

プロパティ設定あり

scope

Javadocコメントをチェックする可視性スコープを指定する。

設定ファイル記述方法

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

チェック実行例

// NG Javadocコメントがない
@SpringBootApplication
public class Application {}

// OK チェック対象外
@Configuration
class DatabaseConfiguration {}

excludeScope

Javadocコメントをチェックしない可視性スコープを指定する。

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocType">
            <property name="excludeScope" value="public"/>
        </module>
    </module>
</module>

チェック実行例

// OK チェック対象外
@SpringBootApplication
public class Application {}

// NG Javadocコメントがない
@Configuration
class DatabaseConfiguration {}

authorFormat

@authorタグのパターンを指定する。

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocType">
            <property name="authorFormat" value="[a-zA-Z]+$"/>
        </module>
    </module>
</module>

チェック実行例

// OK
/**
 * @author Bob 
 */
public class MyClass {
}

// NG
/**
 * @author ボブ 
 */
public class MyClass {
}

versionFormat

@versionタグのパターンを指定する。

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocType">
            <property name="versionFormat" value="[1-9\.]"/>
        </module>
    </module>
</module>

チェック実行例

// OK
/**
 * @version 1.0.0 
 */
public class MyClass {
}

// NG
/**
 * @version 1.0.0-SNAPSHOT 
 */
public class MyClass {
}

allowMissingParamTags

クラスが型パラメータを持つが、Javadoc に一致する param タグがない場合に、違反を無視するかどうか （デフォルト：false）

設定ファイル記述方法

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

チェック実行例

// OK 「allowMissingParamTags」がtrueなので、paramが欠落していても良い
/**
 * 
 */
public class MyClass<T> {
}

allowUnknownTags

認識されないJavadocタグの違反を無視するかどうか （デフォルト：false）

設定ファイル記述方法

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

チェック実行例

// OK 「allowMissingParamTags」がtrueなので、変なタグが存在していても良い
/**
 * @SomeTags
 */
public class MyClass<T> {
}

allowedAnnotations

ドキュメントがなくても許容するアノテーションを指定する。

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocType">
            <property name="allowedAnnotations" value="SpringBootApplication,Configuration"/>
        </module>
    </module>
</module>

チェック実行例

// OK allowedAnnotationsの記載のアノテーションが付与されているのでチェック対象外
@SpringBootApplication
public class Application {}

// OK allowedAnnotationsの記載のアノテーションが付与されているのでチェック対象外
@Configuration
class DatabaseConfiguration {}

tokens

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

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocType">
            <property name="tokens" value="ENUM_DEF"/>
        </module>
    </module>
</module>

チェック実行例

// OK enum以外チェック対象外
public class Application {}