Checkstyle チェック項目ーJavadoc Comments

Checkstyleチェック項目:Javadoc Comments

CheckStyle公式ドキュメント

ver 10.3.1

AtclauseOrder

JavadocブロックタグまたはJavadocタグの順序をチェックする。

プロパティ

プロパティ デフォルト値 説明
violateExecution OnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか
target トークンの サブセット CLASS_DEF, COMPACT_CTOR_DEF, CTOR_DEF, ENUM_DEF, INTERFACE_DEF, METHOD_DEF, RECORD_DEF, VARIABLE_DEF 対象となるブロックタグを指定する
tagOrder String[] @author, @deprecated, @exception, @param, @return, @see, @serial, @serialData, @serialField, @since, @throws, @version タグの順番を指定する

チェック設定例

プロパティ設定なし

<module name="AtclauseOrder"/>

プロパティ設定あり

<module name="JavadocBlockTagLocation">
    <property name="tagOrder" value="@throws, @author, @deprecated, @exception, @param, @return, @see, @serial, @serialData, @serialField, @since, @version"/>
</module>

チェック実行例

プロパティ設定なし

// OK
/**
* Some javadoc.
*
* @author Some javadoc.
* @version Some javadoc.
* @param Some javadoc.
* @return Some javadoc.
* @throws Some javadoc.
* @exception Some javadoc.
* @see Some javadoc.
* @since Some javadoc.
* @serial Some javadoc.
* @serialField
* @serialData
* @deprecated Some javadoc.
*/
class MyClass implements Serializable {
}

// NG
/**
* Some javadoc.
*
* @since Some javadoc. // OK
* @version Some javadoc. // NG tagOrderの順番と異なる
* @deprecated
* @see Some javadoc. // NG tagOrderの順番と異なる
* @author Some javadoc. // NG tagOrderの順番と異なる
*/
class MyClass implements Serializable {
}

プロパティ設定あり

// NG
/**
* Some javadoc.
*
* @author Some javadoc.
* @version Some javadoc.
* @param Some javadoc.
* @return Some javadoc.
* @throws Some javadoc. // NG tagOrderの順番と異なる
* @exception Some javadoc.
* @see Some javadoc.
* @since Some javadoc.
* @serial Some javadoc.
* @serialField
* @serialData
* @deprecated Some javadoc.
*/
class MyClass implements Serializable {
}

InvalidJavadocPosition

Javadoc が正しい位置に配置されているかどうかをチェックする。
Documentation Comment Specification for the Standard Doclet で指定されているように、Javadoc はモジュール、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールド宣言の直前に置かれた場合のみ、正しく認識される。
メソッドの内部などそれ以外の位置では、このチェックでは無効と見なされる。

プロパティ

なし

チェック設定例

<module name="InvalidJavadocPosition"/>

チェック実行例

// NG アノテーションの上に記述する
@SuppressWarnings("serial")
/**
 * This comment looks like javadoc but it at an invalid location.
 * Therefore, the text will not get into TestClass.html and the check will produce a violation.
 */
public class TestClass {
}

JavadocBlockTagLocation

Javadocのブロックタグが行頭にのみ現れるかどうかをチェックする。
ブロックタグは、@記号で始まり、空白が前にあるトークンの事を指す。
このチェックでは、先頭のアスタリスクと空白、コメントやインラインタグ {@code} と {@literal} 内のブロックタグは無視される。

プロパティ

プロパティ デフォルト値 説明
tags String[] author, deprecated, exception, hidden, param, provides, return, see, serial, serialData, serialField, since, throws, uses, version チェックするJavadocタグを指定する
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか

チェック設定例

プロパティ設定なし

<module name="JavadocBlockTagLocation"/>

プロパティ設定あり

<module name="JavadocBlockTagLocation">
    <property name="tags" value="apiNote, implSpec, implNote"/>
</module>

チェック実行例

プロパティ設定なし

/**
 * Escaped tag &#64;version
 * Plain text with {@code @see}
 * A @custom tag
 * 
 * email@author
 * (@param in parentheses)
 * '@param in single quotes'
 * @since 1.0
 * text @return (NG:行頭にない)
 * * @param (NG:行頭にない)
+* @serial (NG:行頭にない)
 * @see first @see second (NG:行頭にない)
 */
public int field;

プロパティ設定あり

/**
 * Escaped tag &#64;version
 * Plain text with {@code @see}
 * A @custom tag
 * 
 * email@author
 * (@param in parentheses)
 * '@param in single quotes'
 * @since 1.0
 * text @return (OK:チェック対象外)
 * * @param (OK:チェック対象外)
+* @serial (OK:チェック対象外)
 * @see first @see second (OK:チェック対象外)
 */
public int field;

JavadocContentLocation

プロジェクト内のすべての Javadoc コメントで、Javadocコンテンツが同じ位置から始まるかどうかをチェックする。
先頭のアスタリスクやスペースは、コンテンツの開始位置としてカウントされないため、無視される。

プロパティ

プロパティ デフォルト値 説明
location JavadocContentLocationOption second_line Javadoc コンテンツの配置に関するポリシーを指定

〇JavadocContentLocationOptionには以下の値が設定可能

説明
FIRST_LINE Javadocのコンテンツが/**と同じ行から始まる場合のポリシー
SECOND_LINE Javadocのコンテンツが/**の次の行から始まる場合のポリシー

チェック設定例

プロパティ設定なし

<module name="JavadocContentLocationCheck"/>

プロパティ設定あり

<module name="JavadocContentLocationCheck">
    <property name="location" value="first_line"/>
</module>

チェック実行例

プロパティ設定なし

/** 最初の行からコメントを
  * 書いているのでNG
  */
/**
  * 2行目からコメントを書いているのでOK
  */
/** 1行コメントは対象外 */

プロパティ設定あり

/** 最初の行からコメントを
   * 書いているのでOK
   */
/**
  * 2行目からコメントを書いているのでNG
  */
/** 1行コメントは対象外 */

JavadocMethod

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

プロパティ

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

〇AccessModifierOptionには以下の値が設定可能

  • public
  • protected
  • package
  • private

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

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

チェック設定例

プロパティ設定なし

<module name="JavadocMethod"/>

プロパティ設定あり

<module name="JavadocMethod">
    <property name="accessModifiers" value="public"/>
    <property name="allowMissingParamTags" value="true"/>
</module>

チェック実行例

プロパティ設定なし

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

プロパティ設定あり

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

JavadocMissingLeadingAsterisk

Javadocが各行の先頭にアスタリスクを持つかどうかをチェックする。

プロパティ

プロパティ デフォルト値 説明
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか

チェック設定例

プロパティ設定なし

<module name="JavadocMissingLeadingAsterisk"/>

プロパティ設定あり

<module name="JavadocMissingLeadingAsterisk">
    <property name="violateExecutionOnNonTightHtml" value="true"/>
</module>

チェック実行例

// NG 行頭にアスタリスクがない
/** あいう
    えお */ 
class MyClass {}

JavadocMissingWhitespaceAfterAsterisk

先頭のアスタリスクの後に少なくとも1つの空白があるかどうかをチェックする。

プロパティ

プロパティ デフォルト値 説明
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか

チェック設定例

プロパティ設定なし

<module name="JavadocMissingWhitespaceAfterAsterisk"/>

プロパティ設定あり

<module name="JavadocMissingWhitespaceAfterAsterisk">
    <property name="violateExecutionOnNonTightHtml" value="true"/>
</module>

チェック実行例

// NG アスタリスクの後ろに空白がない
/**
*コメント
*/
int invalidJavaDoc;

JavadocPackage

Javaパッケージがコメント用に使用されるJavadocファイルを持っているかどうかをチェックする。
デフォルトでは、package-info.java ファイルのみを許可するが、 package.html ファイルを許可するように設定することも可能。
両方のファイルが存在する場合、Javadocツールで許可されていないため、違反となる。

プロパティ

プロパティ デフォルト値 説明
allowLegacy boolean false package.htmlファイルを使用できるようにするかどうか
fileExtensions String[] .java 処理するファイルのファイルタイプ拡張子を指定する

チェック設定例

プロパティ設定なし

<module name="JavadocPackage"/>

プロパティ設定あり

<module name="JavadocPackage">
    <property name="allowLegacy" value="true"/>
</module>

チェック実行例

プロパティ設定なし

package-info.javaがない場合NG

プロパティ設定あり

package.htmlがない場合NG


JavadocParagraph

Javadocの段落をチェックする。
以下のチェックが行われる。

  • 2つの段落の間にそれぞれ1行の空白行がある
  • 最初の段落以外の各段落は、最初の単語の直前に<p>があり、その後に空白がない

プロパティ

プロパティ デフォルト値 説明
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか
allowNewlineParagraph boolean true <p>タグを最初の単語の直前に置くかどうか

チェック設定例

プロパティ設定なし

<module name="JavadocParagraph"/>

プロパティ設定あり

<module name="JavadocParagraph">
    <property name="allowNewlineParagraph" value="false"/>
</module>

チェック実行例

プロパティ設定なし

/**
 * コメント!
 *
 * <p>pタグの後ろにすぐコメントを記述する
 * <p>pタグの前には1行の空行が必要(NG)
 *
 * <p>
 * pタグの後で改行しない(NG)
 *
 * <p> pタグの後ろにスペースを挿入しない(NG)
 *
 */
public class MyClass {
}

プロパティ設定あり

/**
 * コメント!
 *
 * <p>pタグの後ろにすぐコメントを記述する
 * <p>pタグの前には1行の空行が必要(NG)
 *
 * <p>
 * pタグの後で改行してもよい
 *
 * <p> pタグの後ろにスペースを挿入してもよい
 *
 */
public class MyClass {
}

JavadocStyle

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

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

プロパティ

プロパティ デフォルト値 説明
scope Scope private Javadocコメントをチェックする可視性スコープを指定
excludeScope Scope null Javadocコメントをチェックしない可視性スコープを指定
checkFirstSentence boolean true 最初の文の文末が適切かどうかをチェックするかどうか
endOfSentenceFormat Pattern `"([.?!][ \t\n\r\f<]) ([.?!]$)"`|文末のマッチング形式を指定
checkEmptyJavadoc boolean false Javadocが空かどうかをチェックするかどうか
checkHtml boolean true 不完全なHTMLタグをチェックするかどうか
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 チェック対象のトーク

〇 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="JavadocStyle"/>

プロパティ設定あり

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

チェック実行例

プロパティ設定なし

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

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

プロパティ設定あり

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

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

JavadocTagContinuationIndentation

ブロックタグの継続行のインデントをチェックする。 継続行とは、タグのある行を越えて記述が続くことを指す。 デフォルトのインデントは最低4だが、プロパティで変更することが可能。

プロパティ

プロパティ デフォルト値 説明
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか
offset int 4 新しいインデントレベルに使用するスペース数

チェック設定例

プロパティ設定なし

<module name="JavadocTagContinuationIndentation"/>

プロパティ設定あり

<module name="JavadocTagContinuationIndentation">
    <property name="offset" value="2"/>
</module>

チェック実行例

プロパティ設定なし

/**
 * @tag comment
 *  Indentation spacing is 1. (NG)
 *   Indentation spacing is 2. (NG)
 *     Indentation spacing is 4.
 */
public class MyClass {
}

プロパティ設定あり

/**
 * @tag comment
 * Indentation spacing is 0. (NG)
 *   Indentation spacing is 2.
 *  Indentation spacing is 1. (NG)
 */
public class MyClass {
}

JavadocType

型定義のJavadocコメントをチェックする。
デフォルトでは、作者やバージョンのタグはチェックしない。
検証するスコープはScopeクラスを使用して指定し、デフォルトはScope.PRIVATE

プロパティ

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

〇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="JavadocType"/>

プロパティ設定あり

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

チェック実行例

プロパティ設定なし

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

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

プロパティ設定あり

// OK
@SpringBootApplication
public class Application {}

// OK
@Configuration
class DatabaseConfiguration {}

JavadocVariable

変数が Javadoc コメントを持つかどうかをチェックする。
serialVersionUIDフィールドは無視される。

プロパティ

プロパティ デフォルト値 説明
scope Scope private Javadocコメントをチェックする可視性スコープを指定
excludeScope Scope null Javadocコメントをチェックしない可視性スコープを指定
ignoreNamePattern Pattern null 無視する変数名を定義する正規表現
tokens トークンの サブセット ENUM_CONSTANT_DEF チェック対象のトーク

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

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

チェック設定例

プロパティ設定なし

<module name="JavadocVariable"/>

プロパティ設定あり

<module name="JavadocVariable">
    <property name="scope" value="public"/>
</module>

チェック実行例

プロパティ設定なし

public class Test {
    // NG Javadocコメントがない
    private int a;

    // OK
    /**
     * Some description here
     */
    private int b;
    
    // NG Javadocコメントがない
    protected int c;
    
    // NG Javadocコメントがない
    public int d;
}

プロパティ設定あり

public class Test {
    // OK privateメソッドはチェック対象外
    private int a;

    // OK
    /**
     * Some description here
     */
    private int b;
    
    // OK protectedメソッドはチェック対象外
    protected int c;
    
    // NG Javadocコメントがない
    public int d;
}

MissingJavadocMethod

メソッドまたはコンストラクタのJavadocコメントが欠落していないかどうかをチェックする。
検証するスコープはScopeクラスを使用して指定し、デフォルトは Scope.PUBLIC

プロパティ

プロパティ デフォルト値 説明
minLineCount int -1 Javadocの欠落を許可するメソッドの最小行数
allowedAnnotations String[] Override Javadocの欠落を許可するアノテーション
scope Scope public Javadocコメントをチェックする可視性スコープを指定
excludeScope Scope null Javadocコメントをチェックしない可視性スコープを指定
allowMissingPropertyJavadoc boolean false プロパティ(セッターとゲッター)のアクセサー・メソッドにJavadocがないことを許可するかどうか
ignoreMethodNamesRegex Pattern null チェック対象外とするメソッド名の正規表現
tokens トークンの サブセット METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF チェック対象のトーク

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

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

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

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

チェック設定例

プロパティ設定なし

<module name="MissingJavadocMethod"/>

プロパティ設定あり

<module name="MissingJavadocMethod">
    <property name="scope" value="private"/>
</module>

チェック実行例

プロパティ設定なし

public class MyClass {
    // NG Javadocコメントがない
    public MyClass() {}
    
    // NG Javadocコメントがない
    public void foo() {}
    
    // OK
    /**
     * Some description here.
     */
    public void foo2() {}

    // OK @overrideアノテーションが付与されているのでチェック対象外
    @Override
    public String toString() {
        return "Some string";
    }

    // OK privateメソッドはチェック対象外
    private void foo3() {}
    
    // OK protectedメソッドはチェック対象外
    protected void foo4() {}
    
    // OK package-privateメソッドはチェック対象外
    void foo5() {}
}

プロパティ設定あり

public class MyClass {
    // NG Javadocコメントがない
    private void foo() {}
}

MissingJavadocPackage

package-info.javaファイルにJavadocコメントがないかどうかをチェックする。

プロパティ

なし

チェック設定例

<module name="MissingJavadocPackage"/>

チェック実行例

// OK
/**
* Provides API classes
*/
package com.checkstyle.api;

// NG Javadocコメントがない
/*
* Block comment is not a javadoc
*/
package com.checkstyle.api;

MissingJavadocType

クラス、enum、インターフェース、およびアノテーション・インターフェース定義のJavadocコメントが欠落していないかどうかをチェックする。
検証するスコープはScopeクラスを使用して指定し、デフォルトは Scope.PUBLIC。

プロパティ

プロパティ デフォルト値 説明
scope Scope public Javadocコメントをチェックする可視性スコープを指定
excludeScope Scope null Javadocコメントをチェックしない可視性スコープを指定
skipAnnotations String[] Generated ドキュメントの欠落を許可するアノテーション
tokens トークンの サブセット INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF, RECORD_DEF チェック対象のトーク

〇 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="MissingJavadocType"/>

プロパティ設定あり

<module name="MissingJavadocType">
    <property name="scope" value="private"/>
</module>

チェック実行例

プロパティ設定なし

// NG Javadocコメントがない
public class PublicClass {
}

// OK privateクラスはチェック対象外
private class PrivateClass {
}
// OK protectedクラスはチェック対象外
protected class ProtectedClass {
}
// OK package-privateクラスはチェック対象外
class PackagePrivateClass {
}

プロパティ設定あり

// NG Javadocコメントがない
public class PublicClass {
}

// NG Javadocコメントがない
private class PrivateClass {
}
// NG Javadocコメントがない
protected class ProtectedClass {
}
// NG Javadocコメントがない
class PackagePrivateClass {
}

NonEmptyAtclauseDescription

ブロックタグの後に記述があるかどうかをチェックする。

プロパティ

プロパティ デフォルト値 説明
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか
javadocTokens Javadocトークンの サブセット PARAM_LITERAL, RETURN_LITERAL, THROWS_LITERAL, EXCEPTION_LITERAL, DEPRECATED_LITERAL チェック対象のJavadocトーク

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

説明
PARAM_LITERAL param
RETURN_LITERAL return
THROWS_LITERAL throws
EXCEPTION_LITERAL exception
DEPRECATED_LITERAL deprecated

チェック設定例

プロパティ設定なし

<module name="NonEmptyAtclauseDescription"/>

プロパティ設定あり

<module name="NonEmptyAtclauseDescription">
    <property name="javadocTokens" value="PARAM_LITERAL,RETURN_LITERAL"/>
</module>

チェック実行例

プロパティ設定なし

/**
* コメント
*
* @param a Some javadoc
* @param b // NG 説明がない
* @deprecated // NG 説明がない
* @throws Exception // NG 説明がない
*/
public int method(String a, int b) throws Exception {
    return 1;
}

プロパティ設定あり

/**
* コメント
*
* @param a Some javadoc
* @param b // NG 説明がない
* @deprecated
* @throws Exception
*/
public int method(String a, int b) throws Exception {
    return 1;
}

RequireEmptyLineBeforeBlockTagGroup

Javadocにブロックタグがある場合、その前に1行の空行があるかどうかをチェックする。

プロパティ

プロパティ デフォルト値 説明
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか

チェック設定例

プロパティ設定なし

<module name="RequireEmptyLineBeforeBlockTagGroup"/>

プロパティ設定あり

<module name="RequireEmptyLineBeforeBlockTagGroup">
    <property name="violateExecutionOnNonTightHtml" value="true"/>
</module>

チェック実行例

/**
 * コメント
 * @return something (NG:1行空行が必要)
 */
public boolean foo() {
    return false;
}

SingleLineJavadoc

Javadocブロックが1行に収まるかどうか、ブロックタグを含まないかどうかをチェックする。
少なくとも1つのブロックタグを含むJavadocコメントは、数行でフォーマットされる必要がある。

プロパティ

プロパティ デフォルト値 説明
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか
ignoredTags String[] {} チェック対象外とするブロックタグを指定
ignoreInlineTags boolean true インラインタグを無視するかどうか

チェック設定例

プロパティ設定なし

<module name="SingleLineJavadoc"/>

プロパティ設定あり

<module name="SingleLineJavadoc">
    <property name="ignoredTags" value="@inheritDoc, @see"/>
    <property name="ignoreInlineTags" value="false"/>
</module>

チェック実行例

プロパティ設定なし

// NG ブロックタグを含む場合、Javadocは複数行である必要がある
/** @see Math */
public int foo() {
  return 42;
}

// OK
/**
 * @return 42
 */
public int bar() {
  return 42;
}

// OK
/** {@link #equals(Object)} */
public int baz() {
  return 42;
}

プロパティ設定あり

// OK
/** @see Math */
public int foo() {
  return 42;
}

// OK
/**
 * @return 42
 */
public int bar() {
  return 42;
}

// NG Javadocは複数行である必要がある
/** {@link #equals(Object)} */
public int baz() {
  return 42;
}

SummaryJavadoc

Javadocの要約文に、使用を推奨しない語句が含まれていないかチェックする。
{@inheritDoc}タグのみを含む場合、チェックはスキップされ、空でない{@code {@return}}を含む@Summaryは許容される。
最初の文が含まれていないJavadocはチェックNGとなる。

プロパティ

プロパティ デフォルト値 説明
violateExecutionOnNonTightHtml boolean false JavadocTight-HTMLルールに違反している場合、違反を表示するタイミングを制御するかどうか
forbiddenSummaryFragments Pattern "^$" 禁止されたsummaryの文言の正規表現を指定
period String "." Javadocの最初の文の末尾のピリオド記号を指定

チェック設定例

プロパティ設定なし

<module name="SummaryJavadocCheck"/>

プロパティ設定あり

<module name="SummaryJavadocCheck">
    <property name="period" value="。"/>
</module>

チェック実行例

プロパティ設定なし

// NG
/**
 * {@summary  }
 */
public String foo(){
    return "";
}

// OK
/**
 * {@summary <p>This is summary for bar.<p/>}
 */
public void bar(){}

プロパティ設定あり

// NG
/**
 * Comment!
 */
public void bar(){}

// OK
/**
 * Comment。
 */
public void bar(){}

WriteTag

ユーザー定義のJavadocタグが、定義されたフォーマットで Javadoc コメントに存在することをチェックする。

プロパティ

プロパティ デフォルト値 説明
tag String null タグの名称を指定
tagFormat Pattern null タグの内容にマッチする正規表現を指定
tagSeverity SeverityLevel info タグが検出され、出力されたときの重要度を指定
tokens トークンの サブセット INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF, RECORD_DEF チェック対象のトーク

〇SeverityLevelには以下の値が設定可能

  • ignore
  • info
  • warning
  • error

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

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

チェック設定例

プロパティ設定なし

<module name="WriteTag"/>

プロパティ設定あり

<module name="WriteTag">
    <property name="tag" value="@since"/>
</module>

チェック実行例

プロパティ設定なし

プロパティ設定がない場合チェックは実行されない

プロパティ設定あり

// NG クラスのJavadocコメントに@sinceタグが必要
/**
* Some class
*/
public class Test {
  /** some doc */
  void foo() {}
}