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

Zopsss · 2024-09-21T17:35:10Z

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  which doesn't have corresponding .

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 (  ). If yes then move further.

This case is only valid for  tags which does not have their corresponding , so when we encounter a proper pair of paragraph tag (), 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  which are not closed, we don't get any violations for  which are closed properly. We expect the same errors as we got for 

Describe what you expect in detail.

Fix the check's implementation to check for both types of tags:  & 

The text was updated successfully, but these errors were encountered:

…g when they have their corresponding closing tag

Zopsss · 2024-09-21T21:10:05Z

I've sent PR for this issue, when I tried to run build command locally, I got so many errors for different files like checks, filters, etc for  tag. Most of them were for:

<p> tag should be placed immediately before the first word, with no space after.

I want your help with this one, not sure how to fix it.

…g when they have their corresponding closing tag

…y have their corresponding closing tag

…g when they have their corresponding closing tag

Zopsss mentioned this issue Sep 21, 2024

JavadocParagraph: violate preceding P tag before block-level HTML tags #15503

Closed

Zopsss moved this to For Approval in Refine Google Style Guide Sep 21, 2024

Zopsss added this to Refine Google Style Guide Sep 21, 2024

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Sep 21, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

c88060a

…g when they have their corresponding closing tag

Zopsss mentioned this issue Sep 21, 2024

Issue #15685: fixed JavadocParagraph to detect paragraph tag when they have their corresponding closing tag #15686

Merged

romani added approved bug labels Sep 22, 2024

romani moved this from For Approval to Todo in Refine Google Style Guide Sep 22, 2024

romani assigned Zopsss Sep 22, 2024

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Sep 24, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

c23ec48

…g when they have their corresponding closing tag

romani added the false negative issues where check should place violations on code, but does not label Sep 24, 2024

This was referenced Sep 26, 2024

Issue #15690: fix allowNewlineParagraph at JavadocParagraphCheck #15711

Merged

supplemental: added violation messages in JavadocParagraph's input files #15712

Merged

Issue #15503: Added support for violation of p tag if it precedes a block tag #15710

Merged

Zopsss closed this as completed by moving to Done in Refine Google Style Guide Sep 27, 2024

github-project-automation bot moved this from In Progress to Done in Refine Google Style Guide Sep 27, 2024

Zopsss reopened this Sep 27, 2024

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Sep 27, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

eff31fd

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Sep 27, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

fd5db92

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 2, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

a358f05

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 2, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

643b58d

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 3, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

c80a41c

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 3, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

88c23c4

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 4, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

1042402

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 4, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

de2acad

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 4, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

619265d

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 5, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

0ceb142

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 5, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

5e28ccc

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 5, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

092c63d

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 6, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

efd6b31

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 6, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

215e43d

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 6, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

973b2bf

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 6, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

0d9c5f8

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 7, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

c13b1d4

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 7, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

34a018e

…g when they have their corresponding closing tag

Zopsss mentioned this issue Oct 7, 2024

fixed paragraphs in javadoc comments pgjdbc/pgjdbc#3397

Merged

2 tasks

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 8, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

9beee5b

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 8, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

bcde89a

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 8, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

d4edd09

…g when they have their corresponding closing tag

romani pushed a commit to Zopsss/checkstyle that referenced this issue Oct 10, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

dae7d5e

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 10, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

e4bb4f4

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 10, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

c0d510e

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 10, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

cb7cac3

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 10, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

dedae08

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 10, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

5a6b51e

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 10, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

116c234

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 10, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

bc5dfcf

…g when they have their corresponding closing tag

Zopsss added a commit to Zopsss/checkstyle that referenced this issue Oct 11, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

ca20d44

…g when they have their corresponding closing tag

romani pushed a commit that referenced this issue Oct 11, 2024

Issue #15685: fixed JavadocParagraph to detect paragraph tag when the…

5b21ee5

…y have their corresponding closing tag

romani closed this as completed in #15686 Oct 11, 2024

github-project-automation bot moved this from In Progress to Done in Refine Google Style Guide Oct 11, 2024

github-actions bot added this to the 10.18.3 milestone Oct 11, 2024

MohanadKh03 pushed a commit to MohanadKh03/checkstyle that referenced this issue Oct 18, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

d3d1178

…g when they have their corresponding closing tag

MohanadKh03 pushed a commit to MohanadKh03/checkstyle that referenced this issue Oct 18, 2024

Issue checkstyle#15685: fixed JavadocParagraph to detect paragraph ta…

e05fb16

…g when they have their corresponding closing tag

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

Zopsss commented Sep 21, 2024 •

edited

Loading

Zopsss commented Sep 21, 2024

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

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

Comments

Zopsss commented Sep 21, 2024 • edited Loading

Zopsss commented Sep 21, 2024

Zopsss commented Sep 21, 2024 •

edited

Loading