Skip to content

JavadocParagraph does not work when paragraphs have their corresponding closing tag #15685

@Zopsss

Description

@Zopsss

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:

@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>

Metadata

Metadata

Assignees

Labels

approvedbugfalse negativeissues where check should place violations on code, but does not

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions