Would like custom javadoc tags to be handled like {@literal}

[martin.desruisseaux]

Hello

When applying Checkstyle on the javadoc of a project with the rules documented on the Javadoc comment page, for example:

<module name="AtclauseOrder"/>

The parsing fails under the following conditions:

• The javadoc uses a custom inline taglet.
• The text inside the custom taglet contains < and > characters but is not HTML (in my case, it is Java code snippet).

I verified that Checkstyle correctly understand that text inside {@code} and {@literal} inline taglets shall not be interpreted as HTML. Is there any way to tell Checkstyle to do the same for a custom taglet? In Checkstyle 7.6.1, I currently get the following error messages (translated from French):

[ERROR] (…snip…): Javadoc comment can not be parsed. Details: no viable alternative at input '<T> targetClass = ...;' [AtclauseOrder]
[ERROR] (…snip…): Javadoc comment can not be parsed. HTML closing element 'MyType' not found. [AtclauseOrder]
[ERROR] (…snip…): Javadoc comment can not be parsed: Unknown ANTLR parser error: null [AtclauseOrder]

Martin

[Roman Ivanov]

Hi,

I need to see full javadoc to answer your question . You have bad javadoc content.

Please read http://checkstyle.sourceforge.net/writingjavadocchecks.html#Limitations

http://checkstyle.sourceforge.net/writingjavadocchecks.html#Tight-HTML_rules

please make sure that javadoc content is parse-able - http://checkstyle.sourceforge.net/writingjavadocchecks.html#Tool_to_print_Javadoc_tree_structure

please share output.

Please share your problem is the way we usually reproduce problems - http://checkstyle.sourceforge.net/report_issue.html#How_to_report_a_bug

​thanks,

Roman Ivanov

[Martin Desruisseaux]

Hello Roman

Thanks for your reply. My javadoc is correct. Attached is a test case that reproduce the problem with the following command line:

java -jar checkstyle-7.6.1-all.jar -c config.xml Test.java 

The issue is that Checkstyle tries to parse the {@preformat} taglet content as HTML. This is okay if that taglet has been registered with the -tag option on the Javadoc command line [1]. But this is not expected if the tag has been registered by the taglet API [2] instead, which is my case.

Regards,

    Martin

[1] http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#tag
[2] https://docs.oracle.com/javase/8/docs/jdk/api/javadoc/taglet/com/sun/tools/doclets/Taglet.html

[Roman Ivanov]

you found new bug - https://github.com/checkstyle/checkstyle/issues/4164

workaround is to place spaces around "<" if that is acceptable in your case.

​

[Martin Desruisseaux]

I didn't noticed the difference in behaviour with the spaces. Thanks for
the tip!

Martin