Parse error when Javadoc contains @snippet with code example that uses Java annotation #14446
Description
I have read check documentation: there are few Checks
I have downloaded the latest checkstyle from: https://checkstyle.org/cmdline.html#Download_and_Run
I have executed the cli and showed it below, as cli describes the problem better than 1,000 words
https://blogs.oracle.com/javamagazine/post/java-javadoc-snippet
https://openjdk.org/jeps/413
C:\DEV\checkstyle>javac JsonSerializableStringConverter.java
C:\DEV\checkstyle>type checkstyle.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN" "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="SuppressWarningsFilter"/>
<property name="charset" value="UTF-8"/>
<property name="severity" value="warning"/>
<property name="fileExtensions" value="java, properties, xml"/>
<module name="TreeWalker">
<module name="RequireEmptyLineBeforeBlockTagGroup"/>
<module name="NonEmptyAtclauseDescription"/>
<module name="AtclauseOrder">
<property name="tagOrder" value="@param, @return, @throws, @deprecated"/>
<property name="target" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/>
</module>
<module name="SingleLineJavadoc"/>
</module>
</module>
C:\DEV\checkstyle>type JsonSerializableStringConverter.java
package com.company.example;
/**
* Some comment describing stuff:
*
* {@snippet :
* import jakarta.persistence.Converter;
* @Converter
* public static class SomeSpecificClassConverter extends SomeBaseConverter {
* // Some stuff here
* }
*}
*
* Note: it supports {@code null} values.
*/
public abstract class JsonSerializableStringConverter {
// Contents omitted
}
C:\DEV\checkstyle>set RUN_LOCALE="-Duser.language=en -Duser.country=US"
C:\DEV\checkstyle>java %RUN_LOCALE% -jar checkstyle-10.13.0-all.jar -c checkstyle.xml JsonSerializableStringConverter.java
Starting audit...
[WARN] C:\DEV\checkstyle\JsonSerializableStringConverter.java:8: Javadoc comment at column 0 has parse error. Details: mismatched input ' *' expecting JAVADOC_INLINE_TAG_END while parsing JAVADOC_INLINE_TAG [AtclauseOrder]
[WARN] C:\DEV\checkstyle\JsonSerializableStringConverter.java:8: Javadoc comment at column 0 has parse error. Details: mismatched input ' *' expecting JAVADOC_INLINE_TAG_END while parsing JAVADOC_INLINE_TAG [NonEmptyAtclauseDescription]
[WARN] C:\DEV\checkstyle\JsonSerializableStringConverter.java:8: Javadoc comment at column 0 has parse error. Details: mismatched input ' *' expecting JAVADOC_INLINE_TAG_END while parsing JAVADOC_INLINE_TAG [RequireEmptyLineBeforeBlockTagGroup]
[WARN] C:\DEV\checkstyle\JsonSerializableStringConverter.java:8: Javadoc comment at column 0 has parse error. Details: mismatched input ' *' expecting JAVADOC_INLINE_TAG_END while parsing JAVADOC_INLINE_TAG [SingleLineJavadoc]
Audit done.
C:\DEV\checkstyle>If I comment or remove the @Converter annotation inside Javadoc snippet like this:
/**
* Some comment describing stuff:
*
* {@snippet :
* import jakarta.persistence.Converter;
* //@Converter
* public static class SomeSpecificClassConverter extends SomeBaseConverter {
* // Some stuff here
* }
*}
*
* Note: it supports {@code null} values.
*/
public abstract class JsonSerializableStringConverter {
// Contents omitted
}
then Checkstyle produces no warnings:
Starting audit...
Audit done.
Which makes it seem that annotations inside javadoc @snippets are not supported.
Possibly part of #11455 ?
Expectation: Checkstyle checks not failing when annotations are used inside Javadoc @snippet.