Issue #43: Javadoc should be detected above block comment #16586

mahfouz72 · 2025-03-17T02:32:23Z

closes #43

Diff Regression config: https://gist.githubusercontent.com/mohitsatr/f5a524a06294d907c84b9fc5b68661dc/raw/604872961df92db35e66c26218dc74c61bb10097/config.xml

mahfouz72 · 2025-03-17T02:36:19Z

Github, generate report

src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java

mahfouz72 · 2025-03-17T14:54:34Z

Github, generate report

github-actions · 2025-03-17T15:56:13Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/bde9397_2025155543/reports/diff/index.html

nrmancuso · 2025-03-19T10:47:26Z

@mahfouz72 if we have two “Javadocs” above a method, how does this work out?

mahfouz72 · 2025-03-19T13:01:49Z

@nrmancuso The closer to the method is the Javadoc to check.

checkstyle/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java

Lines 27 to 45 in dc6d7f1

    
               /** 
        
                * A Javadoc comment. 
        
                */ 
        
               /** 
        
                * A Javadoc comment. 
        
                * @return 0 
        
                */ 
        
               public int foo3() { 
        
                   return 0; 
        
               } 
        
               /** 
        
                * A Javadoc comment. 
        
                * @return 0 
        
                */ 
        
               /** 
        
                * A Javadoc comment. 
        
                */ 
        
               public int foo4() { // violation, '@return tag should be present and have description.'

nrmancuso

Good stuff :)

nrmancuso · 2025-03-20T02:39:08Z

@rnveach please take a look

rnveach · 2025-03-20T02:43:09Z

You certainly found an old issue to look at.

nrmancuso · 2025-03-20T02:46:28Z

You certainly found an old issue to look at.

I was thinking the same 😂 i don’t think I’ve dealt with anything less than four digits before.

rnveach

#43 (comment)

FileContents.getJavadocBefore and this is used by 8 checks, so each one is affected by this bug

Can you provide us a list so it can be put in the first issue of the post.

...uppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java

rnveach · 2025-03-20T02:50:14Z

src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java

-        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
+        // skip blank lines and comments
+        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo)
+                            || lineInsideBlockComment(lineNo + 1))) {


Not near a computer, but I am curious why this one is the only one which is +1. Would this method call work if lineNo was 0? Is this something we need to be concerned about?

Inside this method, I used the clangComments collection and the lineNos in this collection is shifted by 1 from the file text. That's why I added 1.

I used the clangComments collection and the lineNos in this collection is shifted by 1 from the file text. That's why I added 1.

Is this a bug in our code? I believe some places still have issues with 0 versus 1 in our code.

src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java

mahfouz72 · 2025-03-20T15:50:28Z

You certainly found an old issue to look at.

yeah, I selected the Javadoc issues and sorted them by total comments this was the second one. By doing a quick search now, this is the oldest issue in the repo :)

mahfouz72 · 2025-03-20T22:42:12Z

Can you provide us a list so it can be put in the first issue of the post.

UnusedImports
JavadocMethod
JavadocStyle
JavadocType
JavadocVariable
MissingJavadocMethod
MissingJavadocType
WriteTag

romani

item:

romani · 2025-03-21T12:41:43Z

src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java

+     * @return {@code true} if the line is inside a block comment (excluding Javadoc comments)
+     *          , {@code false} otherwise
+     */
+    public boolean lineInsideBlockComment(int lineNo) {


please make it private.

We should not grow our API contract to users.

romani · 2025-03-21T12:48:53Z

...uppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java

+    /**
+     * A Javadoc comment.
+     */
+    //@ A JML Annotation
+    public int foo() { // violation, '@return tag should be present and have description.'


from user perspective it is not clear what is considered as javadoc comment. may be //@ A JML Annotation ?

/** * A Javadoc comment. * @return result */ //@ A JML Annotation public int foo() throws Exception { // violation, '@throw tag should be present and have description.'

let update to this to give more hints that return is found, so javadoc is second comment from method signature.
same for all others.

romani · 2025-03-21T12:53:58Z

UnusedImports
JavadocMethod
JavadocStyle
JavadocType
JavadocVariable
MissingJavadocMethod
MissingJavadocType

lets add one javadoc above comment to Input of each of this check. as they are affected.

please use https://github.com/checkstyle/checkstyle/blob/master/.github/workflows/README.md#diff-report-by-configuration-at-test-configs-repository to trigger diff report for Example1 for each check.

mahfouz72 · 2025-03-21T14:30:22Z

The report is already there for all Javadoc checks

#16586 (comment)

romani

Last

...uppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java

romani

Thanks a lot !!!

mahfouz72 force-pushed the issue-43 branch from 7b093b4 to bde9397 Compare March 17, 2025 14:45

mahfouz72 commented Mar 17, 2025

View reviewed changes

src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java Outdated Show resolved Hide resolved

nrmancuso self-assigned this Mar 18, 2025

mahfouz72 force-pushed the issue-43 branch from bde9397 to dc6d7f1 Compare March 19, 2025 12:57

nrmancuso approved these changes Mar 20, 2025

View reviewed changes

nrmancuso removed their assignment Mar 20, 2025

nrmancuso assigned rnveach Mar 20, 2025

rnveach reviewed Mar 20, 2025

View reviewed changes

src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java Show resolved Hide resolved

mahfouz72 force-pushed the issue-43 branch from dc6d7f1 to 15516e6 Compare March 20, 2025 16:33

rnveach approved these changes Mar 21, 2025

View reviewed changes

nrmancuso assigned romani and unassigned rnveach Mar 21, 2025

romani requested changes Mar 21, 2025

View reviewed changes

mahfouz72 force-pushed the issue-43 branch 2 times, most recently from 4d241af to 14135e2 Compare March 21, 2025 15:12

romani requested changes Mar 21, 2025

View reviewed changes

...uppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java Outdated Show resolved Hide resolved

Issue checkstyle#43: Javadoc should be detected above block comment

a3706e3

mahfouz72 force-pushed the issue-43 branch from 14135e2 to a3706e3 Compare March 21, 2025 19:51

romani approved these changes Mar 21, 2025

View reviewed changes

romani merged commit a99db09 into checkstyle:master Mar 22, 2025
96 checks passed

mahfouz72 mentioned this pull request Mar 23, 2025

FileContents.getJavadocBefore(): Comments should not be skipped if it is not alone in line #16641

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Issue #43: Javadoc should be detected above block comment #16586

Issue #43: Javadoc should be detected above block comment #16586

mahfouz72 commented Mar 17, 2025 •

edited

Loading

mahfouz72 commented Mar 17, 2025

mahfouz72 commented Mar 17, 2025

github-actions bot commented Mar 17, 2025

nrmancuso commented Mar 19, 2025

mahfouz72 commented Mar 19, 2025

nrmancuso left a comment

nrmancuso commented Mar 20, 2025

rnveach commented Mar 20, 2025

nrmancuso commented Mar 20, 2025

rnveach left a comment

rnveach Mar 20, 2025

mahfouz72 Mar 20, 2025

rnveach Mar 21, 2025

mahfouz72 commented Mar 20, 2025

mahfouz72 commented Mar 20, 2025

romani left a comment

romani Mar 21, 2025

mahfouz72 Mar 21, 2025

romani Mar 21, 2025

mahfouz72 Mar 21, 2025

romani commented Mar 21, 2025 •

edited

Loading

mahfouz72 commented Mar 21, 2025

romani left a comment

romani left a comment

Issue #43: Javadoc should be detected above block comment #16586

Issue #43: Javadoc should be detected above block comment #16586

Conversation

mahfouz72 commented Mar 17, 2025 • edited Loading

mahfouz72 commented Mar 17, 2025

mahfouz72 commented Mar 17, 2025

github-actions bot commented Mar 17, 2025

nrmancuso commented Mar 19, 2025

mahfouz72 commented Mar 19, 2025

nrmancuso left a comment

Choose a reason for hiding this comment

nrmancuso commented Mar 20, 2025

rnveach commented Mar 20, 2025

nrmancuso commented Mar 20, 2025

rnveach left a comment

Choose a reason for hiding this comment

rnveach Mar 20, 2025

Choose a reason for hiding this comment

mahfouz72 Mar 20, 2025

Choose a reason for hiding this comment

rnveach Mar 21, 2025

Choose a reason for hiding this comment

mahfouz72 commented Mar 20, 2025

mahfouz72 commented Mar 20, 2025

romani left a comment

Choose a reason for hiding this comment

romani Mar 21, 2025

Choose a reason for hiding this comment

mahfouz72 Mar 21, 2025

Choose a reason for hiding this comment

romani Mar 21, 2025

Choose a reason for hiding this comment

mahfouz72 Mar 21, 2025

Choose a reason for hiding this comment

romani commented Mar 21, 2025 • edited Loading

mahfouz72 commented Mar 21, 2025

romani left a comment

Choose a reason for hiding this comment

romani left a comment

Choose a reason for hiding this comment

mahfouz72 commented Mar 17, 2025 •

edited

Loading

romani commented Mar 21, 2025 •

edited

Loading