JavadocTagContinuationIndentation: missing support to arbitrary indentation in <pre> tags #13048
Description
I have read check documentation: https://checkstyle.org/config_javadoc.html#JavadocTagContinuationIndentation
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
$ javac Test.java
$ cat test-checkstyle.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name = "Checker">
<module name="TreeWalker">
<module name="JavadocTagContinuationIndentation"/>
</module>
</module>
$ cat Test.java
/**
* Test class.
*
* @apiNote
* This is the predefined indentation applied by Eclipse formatter to api/impl taglets.
* <pre>
* Since <pre> blocks retain leading whitespace, in order to avoid extra-indentation from being
* added by the javadoc renderer, its content herein has to stick to the left margin of the comment
* area. Unfortunately, checkstyle seems not to properly evaluate the context (<pre> block) of
* this content, and reports an error:
* "JavadocTagContinuationIndentation: Line continuation have incorrect indentation level,
* expected level should be 4"</pre>
*/
public class Test {
public static void main(String[] args) {
}
}
$ java -jar checkstyle-10.10.0-all.jar -c test-checkstyle.xml Test.java
Starting audit...
[ERROR] Test.java:7: Line continuation have incorrect indentation level, expected level should be 4. [JavadocTagContinuationIndentation]
[ERROR] Test.java:8: Line continuation have incorrect indentation level, expected level should be 4. [JavadocTagContinuationIndentation]
. . .
[ERROR] Test.java:12: Line continuation have incorrect indentation level, expected level should be 4. [JavadocTagContinuationIndentation]
Audit done.
Checkstyle ends with 6 errors.CURRENT BEHAVIOR
Since <pre> blocks retain leading whitespace, in order to avoid extra-indentation from being added by the javadoc generator, I have to stick their contents to the left margin of the comment area (like in Test.java here above) — here it is the intended result:
Unfortunately, checkstyle seems not to properly evaluate the context (i.e., it is unable to detect such contents are in a pre-formatted block which should be excluded from indentation enforcement), and raises errors of non-continuous indentation.
BTW, if, conversely, I conform the indentation of the pre-formatted block to the checkstyle rule this way...
/**
* Test class.
*
* @apiNote
* This is the predefined indentation applied by Eclipse formatter to api/impl taglets.
* <pre>
* Since <pre> blocks retain leading whitespace, in order to avoid extra-indentation from being
* added by the javadoc renderer, its content herein has to stick to the left margin of the comment
* area. Unfortunately, checkstyle seems not to properly evaluate the context (<pre> block) of
* this content, and reports an error:
* "JavadocTagContinuationIndentation: Line continuation have incorrect indentation level,
* expected level should be 4"</pre>
*/
public class Test_extraindent {
public static void main(String[] args) {
}
}...the resulting HTML rendering is —unsurprisingly— unacceptably over-indented (the same happens when rendered directly from source code in the Javadoc view of Eclipse IDE):
EXPECTED BEHAVIOR
Because of their inherent semantics, pre-formatted blocks should be allowed arbitrary indentation: once checkstyle detects an opening <pre> tag, it should automatically disable the JavadocTagContinuationIndentation check until it reaches its corresponding closing </pre> tag.
NOTE: Checks is part of Google style https://checkstyle.sourceforge.io/google_style.html#a7.1.3