Skip to content

Commit e4080e0

Browse files
Anushreebasicsromani
Anushreebasics
authored and
romani
committed
Issue #17882: added comments for SNIPPET_* tokens
1 parent 30a2615 commit e4080e0

1 file changed

Lines changed: 105 additions & 6 deletions

File tree

‎src/main/java/com/puppycrawl/tools/checkstyle/api/JavadocCommentsTokenTypes.java‎

Lines changed: 105 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1072,7 +1072,7 @@ public final class JavadocCommentsTokenTypes {
10721072
* code snippets directly inside a Javadoc sentence.</p>
10731073
*
10741074
* <p><b>Example:</b></p>
1075-
* <pre>{ @code * Example showing { @snippet :java |
1075+
* <pre>{ @code * Example showing { @snippet :java
10761076
* System.out.println("hello");
10771077
* }}</pre>
10781078
*
@@ -1085,7 +1085,7 @@ public final class JavadocCommentsTokenTypes {
10851085
* |--JAVADOC_INLINE_TAG_START -> { @
10861086
* |--COLON -> :
10871087
* |--SNIPPET_BODY -> SNIPPET_BODY
1088-
* | |--TEXT -> java |
1088+
* | |--TEXT -> java
10891089
* | |--NEWLINE -> \n
10901090
* | |--LEADING_ASTERISK -> *
10911091
* | |--TEXT -> System.out.println("hello");
@@ -1521,7 +1521,35 @@ public final class JavadocCommentsTokenTypes {
15211521
public static final int FORMAT_SPECIFIER = JavadocCommentsLexer.FORMAT_SPECIFIER;
15221522

15231523
/**
1524-
* Attribute name in a {@code @snippet}.
1524+
* Attribute name in a {@code @snippet} tag.
1525+
*
1526+
* <p>
1527+
* <b>Note:</b> In the current Checkstyle AST, all snippet attributes (such as
1528+
* {@code lang=java}) appear as plain text under the {@code DESCRIPTION} node.
1529+
* There is <b>no</b> {@code SNIPPET_ATTR_NAME} node in the AST tree.
1530+
* All attribute content is represented as {@code TEXT}.</p>
1531+
*
1532+
* <p>
1533+
* <b>Example:</b>
1534+
* </p>
1535+
* <pre>{@code * @snippet lang=java}</pre>
1536+
*
1537+
* <p>
1538+
* <b>Tree:</b>
1539+
* </p>
1540+
* <pre>{@code
1541+
* JAVADOC_CONTENT -> JAVADOC_CONTENT
1542+
* |--LEADING_ASTERISK -> *
1543+
* |--TEXT ->
1544+
* `--JAVADOC_BLOCK_TAG -> JAVADOC_BLOCK_TAG
1545+
* `--CUSTOM_BLOCK_TAG -> CUSTOM_BLOCK_TAG
1546+
* |--AT_SIGN -> @
1547+
* |--TAG_NAME -> snippet
1548+
* `--DESCRIPTION -> DESCRIPTION
1549+
* `--TEXT -> lang=java
1550+
* }</pre>
1551+
*
1552+
* @see #SNIPPET_ATTRIBUTE
15251553
*/
15261554
public static final int SNIPPET_ATTR_NAME = JavadocCommentsLexer.SNIPPET_ATTR_NAME;
15271555

@@ -1597,17 +1625,88 @@ public final class JavadocCommentsTokenTypes {
15971625
public static final int INDEX_TERM = JavadocCommentsLexer.INDEX_TERM;
15981626

15991627
/**
1600-
* Single snippet attribute.
1628+
* Single attribute in a {@code @snippet} tag.
1629+
*
1630+
* <p>
1631+
* Represents a single attribute (e.g., {@code lang=java})
1632+
* in a {@code @snippet} tag.</p>
1633+
*
1634+
* <p><b>Note:</b> In the current Checkstyle AST, all snippet
1635+
* attributes appear as plain text under the {@code DESCRIPTION} node,
1636+
* not as a separate {@code SNIPPET_ATTRIBUTE} node.</p>
1637+
*
1638+
* <p><b>Example:</b></p>
1639+
* <pre>{@code * @snippet lang=java}</pre>
1640+
*
1641+
* <p><b>Tree:</b></p>
1642+
* <pre>{@code
1643+
* JAVADOC_CONTENT -> JAVADOC_CONTENT
1644+
* |--LEADING_ASTERISK -> *
1645+
* |--TEXT ->
1646+
* `--JAVADOC_BLOCK_TAG -> JAVADOC_BLOCK_TAG
1647+
* `--CUSTOM_BLOCK_TAG -> CUSTOM_BLOCK_TAG
1648+
* |--AT_SIGN -> @
1649+
* |--TAG_NAME -> snippet
1650+
* `--DESCRIPTION -> DESCRIPTION
1651+
* `--TEXT -> lang=java
1652+
* }</pre>
16011653
*/
16021654
public static final int SNIPPET_ATTRIBUTE = JavadocCommentsLexer.SNIPPET_ATTRIBUTE;
16031655

16041656
/**
1605-
* Collection of snippet attributes.
1657+
* Collection of attributes in a {@code @snippet} tag.
1658+
*
1659+
* <p>
1660+
* Represents all attributes (e.g., {@code lang=java region=main}) in a {@code @snippet} tag.
1661+
* </p>
1662+
*
1663+
* <p><b>Note:</b> In the current Checkstyle AST, all snippet attributes appear as
1664+
* plain text under the {@code DESCRIPTION} node, not as a separate
1665+
* {@code SNIPPET_ATTRIBUTES} node.</p>
1666+
*
1667+
* <p><b>Example:</b></p>
1668+
* <pre>{@code * @snippet lang=java region=main}</pre>
1669+
*
1670+
* <p><b>Tree:</b></p>
1671+
* <pre>{@code
1672+
* JAVADOC_CONTENT -> JAVADOC_CONTENT
1673+
* |--LEADING_ASTERISK -> *
1674+
* |--TEXT ->
1675+
* `--JAVADOC_BLOCK_TAG -> JAVADOC_BLOCK_TAG
1676+
* `--CUSTOM_BLOCK_TAG -> CUSTOM_BLOCK_TAG
1677+
* |--AT_SIGN -> @
1678+
* |--TAG_NAME -> snippet
1679+
* `--DESCRIPTION -> DESCRIPTION
1680+
* `--TEXT -> lang=java region=main
1681+
* }</pre>
16061682
*/
16071683
public static final int SNIPPET_ATTRIBUTES = JavadocCommentsLexer.SNIPPET_ATTRIBUTES;
16081684

16091685
/**
1610-
* Body content of a {@code @snippet}.
1686+
* Body content of a {@code @snippet} tag.
1687+
*
1688+
* <p>
1689+
* Represents the code or text content inside a {@code @snippet} tag in Javadoc.
1690+
* </p>
1691+
*
1692+
* <b>Example:</b>
1693+
* <pre>{@code * @snippet lang=java * System.out.println("hello");}</pre>
1694+
*
1695+
* <b>Tree:</b>
1696+
* <pre>{@code
1697+
* JAVADOC_CONTENT -> JAVADOC_CONTENT
1698+
* |--LEADING_ASTERISK -> *
1699+
* |--TEXT ->
1700+
* `--JAVADOC_BLOCK_TAG -> JAVADOC_BLOCK_TAG
1701+
* `--CUSTOM_BLOCK_TAG -> CUSTOM_BLOCK_TAG
1702+
* |--AT_SIGN -> @
1703+
* |--TAG_NAME -> snippet
1704+
* `--DESCRIPTION -> DESCRIPTION
1705+
* |--TEXT -> lang=java
1706+
* |--NEWLINE -> \n
1707+
* |--LEADING_ASTERISK -> *
1708+
* `--TEXT -> System.out.println("hello");
1709+
* }</pre>
16111710
*/
16121711
public static final int SNIPPET_BODY = JavadocCommentsLexer.SNIPPET_BODY;
16131712

0 commit comments

Comments
 (0)