Checkstyle Javaルール

CheckstyleのJavaルールについて1つずつまとめます

JavadocBlockTagLocation

Javadoc Comments

CheckStyle公式ドキュメント

検証環境

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

チェック概要

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

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

すべてのjavadocブロックタグは行の先頭に配置されるべきであり、行頭に配置されないタグはプレーンテキストとして扱われる。
テキストエリアへの意図的なタグの配置を認識するためには、@記号をエスケープするべきであり、エスケープされていないタグはすべて行頭に配置されるべきである。

タグをテキストとして明示的に配置する（@のエスケープ）には、HTMLエンティティ @で@記号をエスケープするか、{@code}の中に配置するなどの方法がある。

プロパティ

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

設定＋チェック実行結果

プロパティ設定なし

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocBlockTagLocation"/>
    </module>
</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;

プロパティ設定あり

tags

チェックするJavadocタグをコンマ区切りで指定する

設定ファイル記述方法

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocBlockTagLocation">
            <property name="tags" value="apiNote, implSpec, implNote"/>
        </module>
    </module>
</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 (OK：チェック対象外)
 * * @param (OK：チェック対象外)
+* @serial (OK：チェック対象外)
 * @see first @see second (OK：チェック対象外)
 */
public int field;