-
-
Notifications
You must be signed in to change notification settings - Fork 4k
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>