-
-
Notifications
You must be signed in to change notification settings - Fork 3.8k
Description
I have read check documentation: https://checkstyle.org/checks/javadoc/javadocparagraph.html
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
Detected at: #15503 (comment)
In JavadocParagraph's implementation, we're only checking for P
tags which aren't closed, i.e we're checking only for <p>
which doesn't have corresponding </p>
.
There is a difference in parsed AST when P
have its corresponding closing tag and when it doesn't have it. As explained in the above referenced comment, AST for P
when it is not closed looks like this:
| | | |--HTML_ELEMENT -> HTML_ELEMENT [4:3]
| | | | `--P_TAG_START -> P_TAG_START [4:3]
and when it is properly closed, it looks like this:
| | | |--HTML_ELEMENT -> HTML_ELEMENT [4:3]
| | | | `--PARAGRAPH -> PARAGRAPH [4:3]
| | | | |--P_TAG_START -> P_TAG_START [4:3]
A new PARAGRAPH
appears between the token.
What we do in the Check's implementation:
checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocParagraphCheck.java
Lines 147 to 156 in d07072b
@Override | |
public void visitJavadocToken(DetailNode ast) { | |
if (ast.getType() == JavadocTokenTypes.NEWLINE && isEmptyLine(ast)) { | |
checkEmptyLine(ast); | |
} | |
else if (ast.getType() == JavadocTokenTypes.HTML_ELEMENT | |
&& JavadocUtil.getFirstChild(ast).getType() == JavadocTokenTypes.P_TAG_START) { | |
checkParagraphTag(ast); | |
} | |
} |
We check if after HTML_ELEMENT
is there a P_TAG_START
token? This token is for opening paragraph tag ( <p>
). If yes then move further.
This case is only valid for <p>
tags which does not have their corresponding </p>
, so when we encounter a proper pair of paragraph tag (<p></p>
), our check ignores that paragraph as a new token ( PARAGRAPH
) appears between HTML_ELEMENT
& P_TAG_START
.
Example:
$ cat .\javadocparagraph_config.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="JavadocParagraph"/>
</module>
</module>
$ cat .\InvalidParagraphTagPosition.java
/**
* Some summary.
*
* <p> Some Javadoc.
*
* <p> Some Javadoc. </p> // false-negative
*/
public class InvalidParagraphTagPosition {
/**
* some javadoc.
* <p>
*
* <p></p> // false-negative
*/
int a;
/**
* Some Javadoc.<P>
* Some Javadoc.<P></P> // false-negative
*/
int b;
}
$ java -jar .\checkstyle-10.18.1-all.jar -c .\javadocparagraph_config.xml .\InvalidParagraphTagPosition.java
Starting audit...
[ERROR] C:\checkstyle testing\.\InvalidParagraphTagPosition.java:4: <p> tag should be placed immediately before the first word, with no space after. [JavadocParagraph]
[ERROR] C:\checkstyle testing\.\InvalidParagraphTagPosition.java:11: <p> tag should be placed immediately before the first word, with no space after. [JavadocParagraph]
[ERROR] C:\checkstyle testing\.\InvalidParagraphTagPosition.java:11: <p> tag should be preceded with an empty line. [JavadocParagraph]
[ERROR] C:\checkstyle testing\.\InvalidParagraphTagPosition.java:18: <p> tag should be placed immediately before the first word, with no space after. [JavadocParagraph]
[ERROR] C:\checkstyle testing\.\InvalidParagraphTagPosition.java:18: <p> tag should be preceded with an empty line. [JavadocParagraph]
Audit done.
Checkstyle ends with 5 errors.
We get errors only for <p>
which are not closed, we don't get any violations for <p>
which are closed properly. We expect the same errors as we got for <p>
Describe what you expect in detail.
Fix the check's implementation to check for both types of tags: <p>
& <p></p>