Issue #17882: add Javadoc for CUSTOM_BLOCK_TAG of JavadocCommentsTokenTypes to new AST format

Aryant-Tripathi · romani · commit bbf23fc801db · 2025-10-25T20:09:03.000-07:00
diff --git a/config/jsoref-spellchecker/whitelist.words b/config/jsoref-spellchecker/whitelist.words
@@ -893,6 +893,7 @@ Mycheckstyle
 mycompany
 mycompanychecks
 mycustom
+mycustomtag
 myfile
 myname
 myproject
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/api/JavadocCommentsTokenTypes.java b/src/main/java/com/puppycrawl/tools/checkstyle/api/JavadocCommentsTokenTypes.java
@@ -464,7 +464,25 @@ public final class JavadocCommentsTokenTypes {
     public static final int SERIAL_FIELD_BLOCK_TAG = JavadocCommentsLexer.SERIAL_FIELD_BLOCK_TAG;
 
     /**
-     * Custom or unrecognized block tag.
+     * {@code @customBlock} Javadoc block tag.
+     *
+     * <p>This type represents any block tag that is not explicitly recognized by Checkstyle,
+     * such as a project-specific or malformed tag.</p>
+     *
+     * <p><b>Example:</b></p>
+     * <pre>{@code * @mycustomtag This is a custom block tag.}</pre>
+     * <b>Tree:</b>
+     * <pre>{@code
+     * JAVADOC_BLOCK_TAG -> JAVADOC_BLOCK_TAG
+     * `--CUSTOM_BLOCK_TAG -> CUSTOM_BLOCK_TAG
+     *     |--AT_SIGN -> @
+     *     |--TAG_NAME -> customBlock
+     *     |--TEXT ->
+     *     `--DESCRIPTION -> DESCRIPTION
+     *         `--TEXT ->  This is a custom block tag.
+     * }</pre>
+     *
+     * @see #JAVADOC_BLOCK_TAG
      */
     public static final int CUSTOM_BLOCK_TAG = JavadocCommentsLexer.CUSTOM_BLOCK_TAG;
 
