Repository: checkstyle/checkstyle
Pull request #16586: Issue #43: Javadoc should be detected above block comment
Author: login: mahfouz72
Created: 2025-03-17T02:32:23Z | Merged: 2025-03-22T14:20:41Z

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


Linked issue #43: JavadocMethod: Javadoc Not Detected Above Multiline Comments
Check: http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod

When programming in Java with JML annotations (http://www.jmlspecs.org/), the typical convention is to place the JML annotations - which are, for the purposes of any non-JML-aware tools, specially formatted Java comments - directly above the method they are annotating. 

A Javadoc comment also needs to be placed above the method it is documenting. Most Javadoc processing tools (including "javadoc" itself with the standard doclet) have no problem ignoring non-Javadoc comments that occur between the Javadoc comment for a method and the method declaration. However, Checkstyle will fail to detect the Javadoc comment for a method if there is a multi-line (but not a single-line) comment between the Javadoc comment and the method declaration. For example, Checkstyle correctly detects the Javadoc in this case:

```
/**
 * A Javadoc comment.
 */
//@ A JML Annotation
public void foo() {}
```

but not in this case:

```
/**
 * A Javadoc comment.
 */
/*@ A JML Annotation */
public void foo() {} 
```

It would be very helpful for Checkstyle to be able to detect such Javadoc comments. 

Examples of JML JavaDoc: https://sourceforge.net/apps/trac/jmlspecs/browser/TeachingMaterials/trunk/CAV2007Tutorial/examples/Actor.java?rev=2675 (https://sourceforge.net/apps/trac/jmlspecs/wiki/TeachingMaterials)
## 


This change impacts the following checks:
UnusedImports
JavadocMethod
JavadocStyle
JavadocType
JavadocVariable
MissingJavadocMethod
MissingJavadocType
WriteTag
Linked issue comments: user: login: romani
created_at: 2013-10-31T04:02:02Z
body: unfortunately Javadoc is handled by RegExp in Checkstyle for now, there is no simple way to six that in code in reliable way.

author_association: MEMBER
user: login: dmzimmerman
created_at: 2013-10-31T04:39:07Z
body: Hmm. So there's no way to change the regexp so that it also matches comments after the Javadoc comment? That's unfortunate. 

author_association: NONE
user: login: dmzimmerman
created_at: 2013-10-31T04:50:02Z
body: It seems that Javadoc comments are found by calling getJavadocBefore() in com.puppycrawl.tools.checkstyle.api.FileContents, and that in turn explicitly skips over single line comments but not multi-line comments. Making it skip over multi-line comments as well would probably not be too difficult (I could take a stab at it but I'm pretty unfamiliar with the codebase).

author_association: NONE
user: login: dmzimmerman
created_at: 2013-10-31T04:57:46Z
body: In fact, it seems that there is a map in FileContents from line numbers to C comments; finding all the the C comments that are not possible Javadoc comments and that occur above the line number of the top of the method would probably work, with the possible exception of the degenerate case where the code looks like this:

```
/**
 * A Javadoc comment.
 */ /* A C comment
     * 
     */
```

I suspect such degenerate cases are exceptionally uncommon.

author_association: NONE
user: login: romani
created_at: 2013-10-31T22:38:02Z
body: Checkstyle is very simple and very modular , to fix a problem you need to debug only one file - check that have problem. So if you so care about this problem - please be welcome with patch.

FYI: do parsing by RegExp is never a good approach, one day we will update grammar to parser JavaDoc more properly - so after that happen, it will be a reasonable to spend maintainers time on it.
We already have numerous issues with JavaDoc support: https://sourceforge.net/p/checkstyle/bugs/?source=navbar .

author_association: MEMBER
user: login: dmzimmerman
created_at: 2013-11-02T02:19:38Z
body: Yes, Checkstyle is modular... but this particular check is _not_, since it explicitly relies, as I said, on that FileContents class to properly find the Javadoc comment before a particular point and it's the _finding_ of the Javadoc that's a problem. I'll take a look at the FileContents class and see if I can convince it to do something more intelligent.

author_association: NONE
user: login: dmzimmerman
created_at: 2013-11-02T03:08:04Z
body: I believe that this diff on com.puppycrawl.tools.checkstyle.api.FileContents should fix it: instead of checking only for a line being blank or a single-line comment before moving to the previous line, it checks that the line isn't blank, doesn't intersect any comment (using existing intersection check functionality), and isn't the end of a Javadoc comment before moving to the previous line.

```
index 6014aac..77a3a74 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/FileContents.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/FileContents.java
@@ -213,8 +213,12 @@ public final class FileContents implements CommentListener
         // Lines start at 1 to the callers perspective, so need to take off 2
         int lineNo = aLineNo - 2;

-        // skip blank lines
-        while ((lineNo > 0) && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
+        // skip blank lines and comments
+        // we skip comments by checking to see if any part of the
+        // current line intersects one.
+        while ((lineNo > 0) && mJavadocComments.get(lineNo) == null && 
+               (lineIsBlank(lineNo) || 
+                hasIntersectionWithComment(lineNo, 0, lineNo, Integer.MAX_VALUE))) {
             lineNo--;
         }
```

author_association: NONE
user: login: romani
created_at: 2013-11-02T05:55:16Z
body: The more I look at JML JavaDoc, the more I think that Checkstyle should not be changed in favour of your project, sorry.
Even following code is bug in Checkstyle as it is wrong usage of comments in Java and bad practice to my mind.

```
/**
 * A Javadoc comment.
 */
// any comment
public void foo() {}
```

I would recommend you to make fork from us, and build JML-Checkstyle on your own with patch that you provided or even more make your own custom Checks see that project as example (https://github.com/sevntu-checkstyle/sevntu.checkstyle). 
I will try to make other maintainers to review your request to have second opinion.

author_association: MEMBER
user: login: dmzimmerman
created_at: 2013-11-02T06:17:21Z
body: "It is wrong usage of comments in Java and bad practice to my mind" is an odd judgement call to make on your part, especially since Checkstyle currently _explicitly supports_ the syntax you just wrote in your comment, while disallowing other forms of comments between Javadoc and a method declaration. Plus, there really is no such thing as "wrong usage of comments in Java"; comments are allowed anywhere and I'm not aware of any well-respected coding standards that say otherwise.

The placement of comments between Javadoc and a method declaration is understood perfectly by both the official Javadoc tool's standard doclet and by Eclipse's Javadoc parser. Whether non-Javadoc comments should be placed either above or below the Javadoc comments seems to me to be a personal preference issue, along the lines of whether braces should be placed at the ends of lines or on new lines, and as such - like the brace placement issue - is probably not a judgement that Checkstyle should be making for all its users. 

Put another way: it seems to me that either Checkstyle should allow _no_ comments between a Javadoc comment and a method declaration, or it should allow _any_ comments between a Javadoc comment and a method declaration; it should not do something in between solely because of lazy coding.

author_association: NONE
user: login: romani
created_at: 2013-11-03T03:24:56Z
body: > comments are allowed anywhere and I'm not aware of any well-respected coding standards that say otherwise.

Whole Checkstyle is about to forbid user to do that is allowed :), Nobody develop with 100% following of Sun guidelines, everyone invent style/rules that fit their team, and Checkstyle help to keep an eye on these rules.
Please give me real use case of such style, out of JML.

> like the brace placement issue - is probably not a judgement that Checkstyle should be making for all its users. 

Right, so that is why Check should have options, to let use check exactly as user want.

> Put another way: .....

You are in right direction, so Check have to have an option to allow comments between or not, by default it will be not allowed. But before implementing that feature please prove that is required not only by JML :), I need examples and evidences.

author_association: MEMBER
user: login: dmzimmerman
created_at: 2013-11-03T07:35:41Z
body: You say "Please give me real use case of such style, out of JML" as though JML is some fly-by-night project that I just made up rather than a decade-old de facto standard for formal specification of Java programs, used both by actual developers and in educational contexts, which is understood by many Java specification, testing and verification tools and has inspired multiple other formal specification languages (including the commercial Frama-C for C programs). 

Still, as an example of how the current implementation is broken, even outside the presence of JML, consider these two examples where a developer wants to explain why he used a particular Java annotation:

```
/**
 * A Javadoc comment.
 */
@SuppressWarnings("unchecked")
/* generic type warnings are suppressed for this method 
   because of reason xyz */
public void method() {}
```

```
/**
 * A Javadoc comment.
 */
/* generic type warnings are suppressed for this method 
   because of reason xyz */
@SuppressWarnings("unchecked")
public void method() {}
```

You'd expect those to have the same result in Checkstyle, right? But they don't. The first one, surprisingly enough, checks fine. The second one causes Checkstyle to complain about missing Javadoc. Of course if the comments were single-line comments, neither would cause Checkstyle to complain; but does it really make any sense at all to force developers to choose between single-line and multi-line comments based on how broken Checkstyle's Javadoc recognition is?

Perhaps you would prefer for the comment to appear above the Javadoc, like this:

```
/* generic type warnings are suppressed for this method 
   because of reason xyz */
/**
 * A Javadoc comment.
 */
@SuppressWarnings("unchecked")
public void method() {}
```

I think that looks ridiculous, and that it makes far more sense to place a comment about an annotation adjacent to that annotation - not inside the method, and not above the Javadoc; moreover, there's no legitimate reason for that comment to be restricted to be of the single-line variety.

Essentially, what you have here is a situation where a method has legal Javadoc, the Javadoc tool says the method has legal Javadoc, every other current Javadoc parser says the method has legal Javadoc, and Checkstyle is _the only tool_ that complains. Morever, when Checkstyle complains, it doesn't say "the method has Javadoc in a location we don't like", but rather, "the method is missing Javadoc." Checkstyle is _lying to me_ when it checks my code and says this. It shouldn't matter to Checkstyle whether I'm writing JML comments above my methods or whether I'm writing short stories above them; what should matter to Checkstyle is whether Javadoc for the method exists, since that is what it is claiming to check. To boil it down to its essence: this check as currently implemented is fundamentally broken because it disagrees with both the authoritative tools and the Javadoc specification about when a Javadoc comment for a method exists.

All that aside, though; I would be thrilled with the method Javadoc check having an option to allow or disallow comments in between, if it were possible, and I wouldn't even care if you chose the wrong default (hint: the correct default is the one that agrees with standard Javadoc parsers). I'd gladly implement it myself, and if you didn't want to include it in Checkstyle I'd distribute it both to my students and with the JML tools. However, the way Javadoc identification is currently implemented, it seems like it's not actually possible to do that simply by changing the check; the method Javadoc check relies on Checkstyle's FileContents API to tell it where Javadoc comments are, and the way Checkstyle searches for Javadoc comments above a particular line is undeniably broken. If that search were fixed (this is what the patch I wrote attempts to do), it would be relatively straightforward to also implement logic in the Javadoc check that says "ok, now that you've found the Javadoc for this method, was there any other comment in between?". 

author_association: NONE
user: login: isopov
created_at: 2013-11-03T09:48:57Z
body: I think we should support this case since it is supported by other javadocs tools.

author_association: CONTRIBUTOR
user: login: isopov
created_at: 2013-11-03T12:00:53Z
body: > > Please give me real use case of such style

```
public class Test{
    /**
    * Foo Method foobar foobar foobar foobar foobar foobar foobar foobar foobar foobar foobar foobar foobar foobar foobar
    */
    //CHECKSTYLE:OFF
    public void FooBar(){
    //CHECKSTYLE:ON
        System.out.println("Hello World!");
    }
}
```

author_association: CONTRIBUTOR
user: login: romani
created_at: 2013-11-03T16:46:12Z
body: > as though JML is some fly-by-night project

I did not mean anything bad, I appreciate your work and your interest in Checkstyle and your time you spend in this issue. ....... .

>  because it disagrees with both the authoritative tools and the Javadoc specification about when a Javadoc

this just a bug, that you experience the most.

> an option to allow or disallow comments in between

I take my idea back, as it would reasonable to do only after introduction of Comments to ANTLR grammar. Lets proceed with minor fixes.
For future reference : http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

> I'd gladly implement it myself,

Ok, thanks for your persistence, I marked issue as "Approved", please provide pull request, but do not forget about UTs.

author_association: MEMBER
user: login: romani
created_at: 2014-11-24T05:04:59Z
body: @dmzimmerman , we implemented full support on comments and javadoc parsing in Checkstyle.
To support your comments notation you can do it yourself, comments Nodes are now inlined to java AST. You can see example of work : 
https://github.com/checkstyle/checkstyle/blob/master/src/main/java/com/puppycrawl/tools/checkstyle/checks/TodoCommentCheck.java
https://github.com/checkstyle/checkstyle/blob/master/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocParagraphCheck.java

I highly recommend you to create grammar for your comments and parse it as we do Javadoc. 
As you be ready we could update https://github.com/checkstyle/checkstyle/blob/master/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.java#L161 to call custom Comment parser.

author_association: MEMBER
user: login: romani
created_at: 2014-11-25T01:06:20Z
body: http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod should be updated to use comments from AST tree, rather than from FileContent.java file. Check need to be reimplemented to use new API for JavaDocs.

author_association: MEMBER
user: login: MEZk
created_at: 2017-04-18T20:51:05Z
body: @romani 
Can I try to reimplement the Check?
author_association: CONTRIBUTOR
user: login: rnveach
created_at: 2017-04-18T22:12:40Z
body: @MEZk I think this will be covered by GSoC if the project is picked, https://github.com/checkstyle/checkstyle/wiki/Checkstyle-GSoC-2017-Project-Ideas#project-name-coverage-of-documentation-comments-style-guide-and-performance-optimization-of-javadoc-parser
author_association: CONTRIBUTOR
user: login: romani
created_at: 2017-04-22T19:12:35Z
body: @MEZk , reimplementation is part of GSoC project. 
I am not sure if issue be fixed after reimplementation, this issue and reimplementation are two different issues.
author_association: MEMBER
user: login: rnveach
created_at: 2019-12-31T01:02:22Z
body: Example of issue:

````
$ cat TestClass.java
public class TestClass {
/**
 * A Javadoc comment.
 */
//@ A JML Annotation
public int foo() { return 0; } 

/**
 * A Javadoc comment.
 */
/*@ A JML Annotation */
public int foo2() { return 0; } 
}

$ cat TestConfig.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
          "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
          "https://checkstyle.org/dtds/configuration_1_3.dtd">

<module name="Checker">
    <property name="charset" value="UTF-8"/>

    <module name="TreeWalker">
<module name="JavadocMethod" />
    </module>
</module>

$ java -jar checkstyle-8.27-all.jar -c TestConfig.xml TestClass.java
Starting audit...
[ERROR] TestClass.java:6: Expected @return tag. [JavadocMethod]
Audit done.
Checkstyle ends with 1 errors.
````

Both methods should be handled the same but only 1 produces a violation.

As discussed above, issue is with `FileContents.getJavadocBefore` and this is used by 8 checks, so each one is affected by this bug. We have checks use this which are not AbstractJavadocCheck and probably will never be converted to it s it wouldn't make sense. Example: MissingJavadocMethodCheck .

So this issue needs to be fixed regardless of type of check it is. I believe we have other checks that use their own implementation of finding the javadoc.
author_association: CONTRIBUTOR
user: login: rnveach
created_at: 2019-12-31T02:51:52Z
body: It seems `FileContents.getJavadocBefore` allows checks a way to bypass checkstyle restrictions by not needing to declare `isCommentNodesRequired`. `JavadocMethodCheck` does not declare it is comments aware via said method, but it is clearly examining javadocs which are comments.
author_association: CONTRIBUTOR
user: login: m1shaq
created_at: 2020-04-22T07:42:27Z
body: Hi, I have switched to version 8.30 and all of a sudden, the checkstyle has stopped noticing me of no javadoc comments before any method or before the constructor. Here is my JavadocMethod module

```
<module name="JavadocMethod">
        <property name="allowMissingParamTags" value="true"/>
        <property name="allowMissingReturnTag" value="true"/>
</module>
```

I don't know what else I should provide, since it's my first post here, so sorry for any obvious goofs.

author_association: NONE
user: login: romani
created_at: 2025-03-22T14:22:06Z
body: @dmzimmerman  , I hope you are doing well.
Sorry, that it took us 11 years to fix this issue :) .

@mahfouz72 did it.
author_association: MEMBER
user: login: dmzimmerman
created_at: 2025-03-22T14:57:17Z
body: > @dmzimmerman  , I hope you are doing well.
> Sorry, that it took us 11 years to fix this issue :) .
> 
> @mahfouz72 did it.

Excellent! Thanks so much, even though it took a while. 😀 
author_association: NONE
user: login: mahfouz72
created_at: 2025-03-22T15:18:56Z
body: Glad to help! Thanks for your patience over the past decade! 😀
author_association: MEMBER

Diff:
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java b/src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java
index 498c798c9ad1..771bfdbba2b4 100644
--- a/src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java
+++ b/src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java
@@ -216,14 +216,35 @@ public TextBlock getJavadocBefore(int lineNoBefore) {
         // Lines start at 1 to the callers perspective, so need to take off 2
         int lineNo = lineNoBefore - 2;
 
-        // skip blank lines
-        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
+        // skip blank lines and comments
+        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo)
+                            || lineInsideBlockComment(lineNo + 1))) {
             lineNo--;
         }
 
         return javadocComments.get(lineNo);
     }
 
+    /**
+     * Checks if the specified line number is inside a block comment.
+     * This method scans through all block comments (excluding Javadoc comments)
+     * and determines whether the given line number falls within any of them
+     *
+     * @param lineNo the line number to check
+     * @return {@code true} if the line is inside a block comment (excluding Javadoc comments)
+     *          , {@code false} otherwise
+     */
+    private boolean lineInsideBlockComment(int lineNo) {
+        final Collection<List<TextBlock>> values = clangComments.values();
+        return values.stream()
+            .flatMap(List::stream)
+            .filter(comment -> !javadocComments.containsValue(comment))
+            .anyMatch(comment -> {
+                return lineNo >= comment.getStartLineNo()
+                                        && lineNo <= comment.getEndLineNo();
+            });
+    }
+
     /**
      * Checks if the specified line is blank.
      *
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java
index 87de39fdb3da..47676768769a 100644
--- a/src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java
@@ -202,11 +202,11 @@ public void testReportBlockCommentJavadoc() {
                 .that(fileContents.getJavadocBefore(4).toString())
                 .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
         assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(5))
-                .isNull();
+                .that(fileContents.getJavadocBefore(5).toString())
+                .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
         assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(6))
-                .isNull();
+                .that(fileContents.getJavadocBefore(6).toString())
+                .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
     }
 
     @Test
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/imports/UnusedImportsCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/imports/UnusedImportsCheckTest.java
index a4d76e748180..6aa78e9a1c5d 100644
--- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/imports/UnusedImportsCheckTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/imports/UnusedImportsCheckTest.java
@@ -381,4 +381,13 @@ public void testStaticMethodRefImportsInDocsOnly() throws Exception {
                 getPath("InputUnusedImportsFromStaticMethodRefInDocsOnly.java"), expected);
     }
 
+    @Test
+    public void testUnusedImportsJavadocAboveComments() throws Exception {
+        final String[] expected = {
+            "11:8: " + getCheckMessage(MSG_KEY, "java.util.List"),
+        };
+        verifyWithInlineConfigParser(
+                getPath("InputUnusedImportsJavadocAboveComments.java"), expected);
+    }
+
 }
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java
index 17e66a7b3de4..acfe9446384d 100644
--- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java
@@ -593,4 +593,19 @@ public void testJavadocMethodRecords3() throws Exception {
         verifyWithInlineConfigParser(
                 getNonCompilablePath("InputJavadocMethodRecords3.java"), expected);
     }
+
+    @Test
+    public void testJavadocMethodAboveComments() throws Exception {
+        final String[] expected = {
+            "16:29: " + getCheckMessage(MSG_EXPECTED_TAG, "@throws", "Exception"),
+            "25:30: " + getCheckMessage(MSG_EXPECTED_TAG, "@throws", "Exception"),
+            "52:30: " + getCheckMessage(MSG_EXPECTED_TAG, "@throws", "Exception"),
+            "63:32: " + getCheckMessage(MSG_EXPECTED_TAG, "@throws", "Exception"),
+            "74:33: " + getCheckMessage(MSG_EXPECTED_TAG, "@throws", "Exception"),
+            "84:33: " + getCheckMessage(MSG_EXPECTED_TAG, "@throws", "Exception"),
+            "94:33: " + getCheckMessage(MSG_EXPECTED_TAG, "@throws", "Exception"),
+        };
+        verifyWithInlineConfigParser(
+                getPath("InputJavadocMethodAboveComments.java"), expected);
+    }
 }
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java
index b47274449419..09504f83f114 100644
--- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java
@@ -822,4 +822,15 @@ public void testJavadocStyleCheck4() throws Exception {
                 getPath("InputJavadocStyleCheck5.java"),
                 expected);
     }
+
+    @Test
+    public void testJavadocStyleAboveComments() throws Exception {
+        final String[] expected = {
+            "13: " + getCheckMessage(MSG_NO_PERIOD),
+        };
+
+        verifyWithInlineConfigParser(
+                getPath("InputJavadocStyleAboveComments.java"),
+                expected);
+    }
 }
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheckTest.java
index 449a9438e821..0ca4d52c4f75 100644
--- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheckTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheckTest.java
@@ -470,4 +470,13 @@ public void testJavadocType2() throws Exception {
         verifyWithInlineConfigParser(
                 getPath("InputJavadocType4.java"), expected);
     }
+
+    @Test
+    public void testJavadocTypeAboveComments() throws Exception {
+        final String[] expected = {
+            "15:1: " + getCheckMessage(MSG_MISSING_TAG, "@author"),
+        };
+        verifyWithInlineConfigParser(
+                getPath("InputJavadocTypeAboveComments.java"), expected);
+    }
 }
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheckTest.java
index ad6ca0d9cfc7..99798a1f82c8 100644
--- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheckTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheckTest.java
@@ -26,6 +26,7 @@
 
 import com.puppycrawl.tools.checkstyle.AbstractModuleTestSupport;
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
+import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
 
 public class JavadocVariableCheckTest
     extends AbstractModuleTestSupport {
@@ -372,4 +373,12 @@ public void testMethodInnerClass() throws Exception {
             getPath("InputJavadocVariableMethodInnerClass.java"),
             expected);
     }
+
+    @Test
+    public void testJavadocVariableAboveComment() throws Exception {
+        final String[] expected = CommonUtil.EMPTY_STRING_ARRAY;
+        verifyWithInlineConfigParser(
+            getPath("InputJavadocVariableAboveComment.java"),
+            expected);
+    }
 }
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocMethodCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocMethodCheckTest.java
index 6de920104df9..ca36ab82f45b 100644
--- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocMethodCheckTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocMethodCheckTest.java
@@ -528,4 +528,14 @@ public void missingJavadoc() throws Exception {
         verifyWithInlineConfigParser(
                 getNonCompilablePath("InputMissingJavadocMethodBasic.java"), expected);
     }
+
+    @Test
+    public void testMissingJavadocMethodAboveComments() throws Exception {
+        final String[] expected = {
+            "18:5: " + getCheckMessage(MSG_JAVADOC_MISSING),
+        };
+        verifyWithInlineConfigParser(
+                getPath("InputMissingJavadocMethodAboveComments.java"),
+                expected);
+    }
 }
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheckTest.java
index cb1ddd594881..4725edbc74b3 100644
--- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheckTest.java
+++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheckTest.java
@@ -436,4 +436,14 @@ public void testQualifiedAnnotationWithParameters() throws Exception {
             expected);
     }
 
+    @Test
+    public void testMissingJavadocTypeAboveComments() throws Exception {
+        final String[] expected = {
+            "13:1: " + getCheckMessage(MSG_JAVADOC_MISSING),
+        };
+        verifyWithInlineConfigParser(
+            getPath("InputMissingJavadocTypeAboveComments.java"),
+            expected);
+    }
+
 }
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/imports/unusedimports/InputUnusedImportsJavadocAboveComments.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/imports/unusedimports/InputUnusedImportsJavadocAboveComments.java
new file mode 100644
index 000000000000..96f796a345e3
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/imports/unusedimports/InputUnusedImportsJavadocAboveComments.java
@@ -0,0 +1,20 @@
+/*
+UnusedImports
+processJavadoc = (default)true
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.imports.unusedimports;
+
+import java.util.Map;
+import java.util.List; // violation 'Unused import - java.util.List.'
+
+/**
+ * Use {@link Map.Entry} in this javadoc.
+ */
+/*
+    Input for UnusedImports
+*/
+public class InputUnusedImportsJavadocAboveComments {
+}
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
new file mode 100644
index 000000000000..59f8f08f3744
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
@@ -0,0 +1,102 @@
+/*
+JavadocMethod
+validateThrows = true
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    //@ A JML Annotation
+    public int foo() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    /*@ A JML Annotation */
+    public int foo2() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A dangling Javadoc comment.
+     * @throws Exception exception
+     * @return 0
+     */
+    /**
+     * A Javadoc comment.
+     * @throws Exception exception
+     * @return 0
+     */
+    public int foo3() throws Exception {
+        return 0;
+    }
+
+    /**
+     * A dangling Javadoc comment.
+     * @throws Exception exception
+     * @return 0
+     */
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    public int foo4() throws Exception {  // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    @SuppressWarnings("unchecked")
+    /* generic type warnings are suppressed for this method
+    because of reason xyz */
+    public int method() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    /* generic type warnings are suppressed for this method
+    because of reason xyz */
+    @SuppressWarnings("unchecked")
+    public int method2() throws Exception {  // violation,'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    // generic type warnings are suppressed for this method because of reason xyz
+    @SuppressWarnings("unchecked")
+    public int method3() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    @SuppressWarnings("unchecked")
+    // generic type warnings are suppressed for this method because of reason xyz */
+    public int method4() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /*@ A JML Annotation */
+    public int foo5() {
+        return 0;
+    }
+}
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocstyle/InputJavadocStyleAboveComments.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocstyle/InputJavadocStyleAboveComments.java
new file mode 100644
index 000000000000..9f280d6a755f
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocstyle/InputJavadocStyleAboveComments.java
@@ -0,0 +1,18 @@
+/*
+JavadocStyle
+endOfSentenceFormat = (default)([.?!][ \t\n\r\f<])|([.?!]$)
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocstyle;
+
+public class InputJavadocStyleAboveComments {
+
+     // violation below, 'First sentence should end with a period'
+     /**             Set of all class field names        */
+     /*
+        field
+     */
+    public String field;
+}
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadoctype/InputJavadocTypeAboveComments.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadoctype/InputJavadocTypeAboveComments.java
new file mode 100644
index 000000000000..ecb693aeaecc
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadoctype/InputJavadocTypeAboveComments.java
@@ -0,0 +1,28 @@
+/*
+JavadocType
+authorFormat = Mohamed Mahfouz
+
+
+*/
+
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadoctype;
+
+/** Test class for variable naming in for each clause. */
+/*
+   Input class for JavadocType
+*/
+public class InputJavadocTypeAboveComments {
+    // violation above, 'Type Javadoc comment is missing @author tag'
+}
+
+/**
+ * Test class for variable naming in for each clause.*
+ * @author Mohamed Mahfouz
+ */
+/*
+   Input class for JavadocType
+*/
+class MyClass {
+
+}
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocvariable/InputJavadocVariableAboveComment.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocvariable/InputJavadocVariableAboveComment.java
new file mode 100644
index 000000000000..e5f461125e9c
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocvariable/InputJavadocVariableAboveComment.java
@@ -0,0 +1,16 @@
+/*
+JavadocVariable
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocvariable;
+
+public class InputJavadocVariableAboveComment {
+    /**
+     * A public variable
+     */
+    /*
+       test comment
+     */
+    public int variablePublic;
+}
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/missingjavadocmethod/InputMissingJavadocMethodAboveComments.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/missingjavadocmethod/InputMissingJavadocMethodAboveComments.java
new file mode 100644
index 000000000000..cda877f73a1e
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/missingjavadocmethod/InputMissingJavadocMethodAboveComments.java
@@ -0,0 +1,28 @@
+/*
+MissingJavadocMethod
+minLineCount = (default)-1
+allowedAnnotations = (default)Override
+scope = private
+excludeScope = (default)null
+allowMissingPropertyJavadoc = (default)false
+ignoreMethodNamesRegex = (default)null
+tokens = (default)METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF , COMPACT_CTOR_DEF
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.missingjavadocmethod;
+
+public class InputMissingJavadocMethodAboveComments {
+
+    public InputMissingJavadocMethodAboveComments() { }// violation
+
+    /**
+     *
+     */
+    /*
+     */
+    public InputMissingJavadocMethodAboveComments(String p1) {
+
+    }
+}
diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/missingjavadoctype/InputMissingJavadocTypeAboveComments.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/missingjavadoctype/InputMissingJavadocTypeAboveComments.java
new file mode 100644
index 000000000000..dd59d9736574
--- /dev/null
+++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/missingjavadoctype/InputMissingJavadocTypeAboveComments.java
@@ -0,0 +1,22 @@
+/*
+MissingJavadocType
+scope = (default)public
+excludeScope = (default)null
+skipAnnotations = (default)Generated
+tokens = (default)INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF, RECORD_DEF
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.missingjavadoctype;
+
+public class InputMissingJavadocTypeAboveComments { // violation, 'Missing a Javadoc comment.'
+}
+
+/**
+ *
+ */
+/* */
+class InputMissingJavadocTypeAboveComments2 {
+}
+


Reviews:
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-17T14:52:08Z
user: login: nrmancuso
body: Good stuff :)
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T02:37:28Z
user: login: rnveach
body: https://github.com/checkstyle/checkstyle/issues/43#issuecomment-569840264
> 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.
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T02:52:32Z
user: login: rnveach
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T02:56:06Z
user: login: rnveach
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T02:58:03Z
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-20T16:01:26Z
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-20T16:34:00Z
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-20T16:34:04Z
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-20T16:34:24Z
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-20T16:37:04Z
user: login: rnveach
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T00:07:19Z
user: login: rnveach
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T00:13:31Z
user: login: rnveach
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T00:17:47Z
user: login: romani
body: item:
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-21T12:50:03Z
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-21T14:38:05Z
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-21T14:38:10Z
user: login: romani
body: Last 
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-21T17:23:33Z
user: login: mahfouz72
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-21T20:54:16Z
user: login: romani
body: Thanks a lot !!!
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-21T21:55:32Z

Review comments:
diff_hunk: @@ -202,11 +202,8 @@ public void testReportBlockCommentJavadoc() {
                 .that(fileContents.getJavadocBefore(4).toString())
                 .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
         assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(5))
-                .isNull();
-        assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(6))
-                .isNull();
+                .that(fileContents.getJavadocBefore(5).toString())
+                .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
path: src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java
user: login: mahfouz72
body: `/** A */` is the valid Javadoc before line 5 so null is not correct here

![image](https://github.com/user-attachments/assets/19045c17-5307-4e9b-9808-59e7af63e07f)

created_at: 2025-03-17T14:52:08Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,91 @@
+/*
+JavadocMethod
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     */
+    //@ A JML Annotation
+    public int foo() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /*@ A JML Annotation */
+    public int foo2() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /**
+     * A Javadoc comment.
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: rnveach
body: One of these is not a javadoc comment. Can we change the wording of one so it is clear from people reading the input.
Same for the others in the file.
created_at: 2025-03-20T02:46:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,91 @@
+/*
+JavadocMethod
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     */
+    //@ A JML Annotation
+    public int foo() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /*@ A JML Annotation */
+    public int foo2() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * 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.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    /* generic type warnings are suppressed for this method
+    because of reason xyz */
+    public int method() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /* generic type warnings are suppressed for this method
+    because of reason xyz */
+    @SuppressWarnings("unchecked")  // violation, '@return tag should be present.*.'
+    public int method2() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    // generic type warnings are suppressed for this method because of reason xyz
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    public int method3() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    // generic type warnings are suppressed for this method because of reason xyz */
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: rnveach
body: I am not seeing something similar, but the comment is a block comment. Please add an example.
created_at: 2025-03-20T02:48:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -216,14 +216,35 @@ public TextBlock getJavadocBefore(int lineNoBefore) {
         // Lines start at 1 to the callers perspective, so need to take off 2
         int lineNo = lineNoBefore - 2;
 
-        // skip blank lines
-        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
+        // skip blank lines and comments
+        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo)
+                            || lineInsideBlockComment(lineNo + 1))) {
path: src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java
user: login: rnveach
body: 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?
created_at: 2025-03-20T02:50:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -202,11 +202,8 @@ public void testReportBlockCommentJavadoc() {
                 .that(fileContents.getJavadocBefore(4).toString())
                 .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
         assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(5))
-                .isNull();
-        assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(6))
-                .isNull();
+                .that(fileContents.getJavadocBefore(5).toString())
+                .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
path: src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java
user: login: rnveach
body: I am not fully following this comment. Your comment and code says "A", but then the screenshot has "B" and technically the javadoc in the screenshot is "This is Javadoc".
created_at: 2025-03-20T02:56:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -202,11 +202,8 @@ public void testReportBlockCommentJavadoc() {
                 .that(fileContents.getJavadocBefore(4).toString())
                 .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
         assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(5))
-                .isNull();
-        assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(6))
-                .isNull();
path: src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java
user: login: rnveach
body: Also why did we remove 6? It looks like it was for `5, 0, 5, 6`.
created_at: 2025-03-20T02:57:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -202,11 +202,8 @@ public void testReportBlockCommentJavadoc() {
                 .that(fileContents.getJavadocBefore(4).toString())
                 .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
         assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(5))
-                .isNull();
-        assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(6))
-                .isNull();
+                .that(fileContents.getJavadocBefore(5).toString())
+                .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
path: src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java
user: login: mahfouz72
body:  ```Java
       final FileContents fileContents = new FileContents(new FileText(new File("filename"),
                Arrays.asList("/** A */", "", "//", "/**/", "/* B */")));
```

In the test, the order of comments indicates that the Javadoc before line 6 is `/** A */`. but the test was incorrect in stating that there was no Javadoc before (because we were not skipping the block comments). After correcting this, I updated the test accordingly.

As proof, I attached a screenshot from IDEA using the same comment order as in the test, which shows that IDEA correctly renders the Javadoc for the method.

To make things identical just replace `/** This is Javadoc */` by `/** A */` in the screenshot.
created_at: 2025-03-20T16:01:26Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,91 @@
+/*
+JavadocMethod
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     */
+    //@ A JML Annotation
+    public int foo() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /*@ A JML Annotation */
+    public int foo2() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /**
+     * A Javadoc comment.
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: mahfouz72
body: Done
created_at: 2025-03-20T16:34:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,91 @@
+/*
+JavadocMethod
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     */
+    //@ A JML Annotation
+    public int foo() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /*@ A JML Annotation */
+    public int foo2() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * 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.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    /* generic type warnings are suppressed for this method
+    because of reason xyz */
+    public int method() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /* generic type warnings are suppressed for this method
+    because of reason xyz */
+    @SuppressWarnings("unchecked")  // violation, '@return tag should be present.*.'
+    public int method2() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    // generic type warnings are suppressed for this method because of reason xyz
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    public int method3() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    // generic type warnings are suppressed for this method because of reason xyz */
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: mahfouz72
body: There is.

https://github.com/checkstyle/checkstyle/blob/dc6d7f1e1a996cf6c70e80958a4ec97dac9803fd/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java#L49-L55

Are you looking for something else?
created_at: 2025-03-20T16:34:04Z
author_association: MEMBER
diff_hunk: @@ -202,11 +202,8 @@ public void testReportBlockCommentJavadoc() {
                 .that(fileContents.getJavadocBefore(4).toString())
                 .isEqualTo(new Comment(new String[] {"/** A */"}, 0, 1, 7).toString());
         assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(5))
-                .isNull();
-        assertWithMessage("Invalid comment")
-                .that(fileContents.getJavadocBefore(6))
-                .isNull();
path: src/test/java/com/puppycrawl/tools/checkstyle/api/FileContentsTest.java
user: login: mahfouz72
body: It was 1 4 5 6. Looks like I removed 6 by mistake I don't remember. Restored
4, 5, 6 have the same expected output
created_at: 2025-03-20T16:34:24Z
author_association: MEMBER
diff_hunk: @@ -216,14 +216,35 @@ public TextBlock getJavadocBefore(int lineNoBefore) {
         // Lines start at 1 to the callers perspective, so need to take off 2
         int lineNo = lineNoBefore - 2;
 
-        // skip blank lines
-        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
+        // skip blank lines and comments
+        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo)
+                            || lineInsideBlockComment(lineNo + 1))) {
path: src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java
user: login: mahfouz72
body: 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.

![1](https://github.com/user-attachments/assets/5a55b6e7-3e25-483f-8e67-85e383589dac)
![2](https://github.com/user-attachments/assets/16505e0b-1cb0-45a9-a4aa-dd6d13dafbc4)

created_at: 2025-03-20T16:37:03Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,91 @@
+/*
+JavadocMethod
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     */
+    //@ A JML Annotation
+    public int foo() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /*@ A JML Annotation */
+    public int foo2() { // violation, '@return tag should be present and have description.'
+        return 0;
+    }
+
+    /**
+     * 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.'
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    /* generic type warnings are suppressed for this method
+    because of reason xyz */
+    public int method() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    /* generic type warnings are suppressed for this method
+    because of reason xyz */
+    @SuppressWarnings("unchecked")  // violation, '@return tag should be present.*.'
+    public int method2() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    // generic type warnings are suppressed for this method because of reason xyz
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    public int method3() {
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     */
+    @SuppressWarnings("unchecked") // violation, '@return tag should be present.*.'
+    // generic type warnings are suppressed for this method because of reason xyz */
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: rnveach
body: No, I just missed this. Sorry.
created_at: 2025-03-21T00:07:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -216,14 +216,35 @@ public TextBlock getJavadocBefore(int lineNoBefore) {
         // Lines start at 1 to the callers perspective, so need to take off 2
         int lineNo = lineNoBefore - 2;
 
-        // skip blank lines
-        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
+        // skip blank lines and comments
+        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo)
+                            || lineInsideBlockComment(lineNo + 1))) {
path: src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java
user: login: rnveach
body: > 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.
created_at: 2025-03-21T00:13:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -216,14 +216,35 @@ public TextBlock getJavadocBefore(int lineNoBefore) {
         // Lines start at 1 to the callers perspective, so need to take off 2
         int lineNo = lineNoBefore - 2;
 
-        // skip blank lines
-        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
+        // skip blank lines and comments
+        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo)
+                            || lineInsideBlockComment(lineNo + 1))) {
             lineNo--;
         }
 
         return javadocComments.get(lineNo);
     }
 
+    /**
+     * Checks if the specified line number is inside a block comment.
+     * This method scans through all block comments (excluding Javadoc comments)
+     * and determines whether the given line number falls within any of them
+     *
+     * @param lineNo the line number to check
+     * @return {@code true} if the line is inside a block comment (excluding Javadoc comments)
+     *          , {@code false} otherwise
+     */
+    public boolean lineInsideBlockComment(int lineNo) {
path: src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java
user: login: romani
body: please make it private.

We should not grow our API contract to users.
created_at: 2025-03-21T12:41:43Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,91 @@
+/*
+JavadocMethod
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     */
+    //@ A JML Annotation
+    public int foo() { // violation, '@return tag should be present and have description.'
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: romani
body: 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.
created_at: 2025-03-21T12:48:53Z
author_association: MEMBER
diff_hunk: @@ -216,14 +216,35 @@ public TextBlock getJavadocBefore(int lineNoBefore) {
         // Lines start at 1 to the callers perspective, so need to take off 2
         int lineNo = lineNoBefore - 2;
 
-        // skip blank lines
-        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo))) {
+        // skip blank lines and comments
+        while (lineNo > 0 && (lineIsBlank(lineNo) || lineIsComment(lineNo)
+                            || lineInsideBlockComment(lineNo + 1))) {
             lineNo--;
         }
 
         return javadocComments.get(lineNo);
     }
 
+    /**
+     * Checks if the specified line number is inside a block comment.
+     * This method scans through all block comments (excluding Javadoc comments)
+     * and determines whether the given line number falls within any of them
+     *
+     * @param lineNo the line number to check
+     * @return {@code true} if the line is inside a block comment (excluding Javadoc comments)
+     *          , {@code false} otherwise
+     */
+    public boolean lineInsideBlockComment(int lineNo) {
path: src/main/java/com/puppycrawl/tools/checkstyle/api/FileContents.java
user: login: mahfouz72
body: done
created_at: 2025-03-21T14:38:05Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,91 @@
+/*
+JavadocMethod
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     */
+    //@ A JML Annotation
+    public int foo() { // violation, '@return tag should be present and have description.'
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: mahfouz72
body: done
created_at: 2025-03-21T14:38:10Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,97 @@
+/*
+JavadocMethod
+validateThrows = true
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    //@ A JML Annotation
+    public int foo() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    /*@ A JML Annotation */
+    public int foo2() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A dangling Javadoc comment.
+     */
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    public int foo3() {
+        return 0;
+    }
+
+    /**
+     * A dangling Javadoc comment.
+     * @return 0
+     */
+    /**
+     * A Javadoc comment.
+     */
+    public int foo4() { // violation, '@return tag should be present and have description.'
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: romani
body: Please put exception to all javadoc, to make it clear by return what comment is Javadoc.

Please do for all
created_at: 2025-03-21T17:23:20Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,97 @@
+/*
+JavadocMethod
+validateThrows = true
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAboveComments {
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    //@ A JML Annotation
+    public int foo() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    /*@ A JML Annotation */
+    public int foo2() throws Exception { // violation, 'Expected @throws tag for 'Exception''
+        return 0;
+    }
+
+    /**
+     * A dangling Javadoc comment.
+     */
+    /**
+     * A Javadoc comment.
+     * @return 0
+     */
+    public int foo3() {
+        return 0;
+    }
+
+    /**
+     * A dangling Javadoc comment.
+     * @return 0
+     */
+    /**
+     * A Javadoc comment.
+     */
+    public int foo4() { // violation, '@return tag should be present and have description.'
path: src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java
user: login: mahfouz72
body: done
created_at: 2025-03-21T20:54:16Z
author_association: MEMBER

PR comments:
user: login: mahfouz72
created_at: 2025-03-17T02:36:19Z
body: Github, generate report


author_association: MEMBER
user: login: mahfouz72
created_at: 2025-03-17T14:54:34Z
body: Github, generate report
author_association: MEMBER
user: login: github-actions[bot]
created_at: 2025-03-17T15:56:13Z
body: https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/bde9397_2025155543/reports/diff/index.html
author_association: CONTRIBUTOR
user: login: nrmancuso
created_at: 2025-03-19T10:47:26Z
body: @mahfouz72 if we have two “Javadocs” above a method, how does this work out? 
author_association: CONTRIBUTOR
user: login: mahfouz72
created_at: 2025-03-19T13:01:49Z
body: @nrmancuso The closer to the method is the Javadoc to check.

https://github.com/checkstyle/checkstyle/blob/dc6d7f1e1a996cf6c70e80958a4ec97dac9803fd/src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAboveComments.java#L27-L45
author_association: MEMBER
user: login: nrmancuso
created_at: 2025-03-20T02:39:08Z
body: @rnveach please take a look
author_association: CONTRIBUTOR
user: login: rnveach
created_at: 2025-03-20T02:43:09Z
body: You certainly found an old issue to look at.
author_association: CONTRIBUTOR
user: login: nrmancuso
created_at: 2025-03-20T02:46:28Z
body: > 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.
author_association: CONTRIBUTOR
user: login: mahfouz72
created_at: 2025-03-20T15:50:28Z
body: > 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 :)
author_association: MEMBER
user: login: mahfouz72
created_at: 2025-03-20T22:42:12Z
body: > 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

author_association: MEMBER
user: login: romani
created_at: 2025-03-21T12:53:58Z
body: > 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.
author_association: MEMBER
user: login: mahfouz72
created_at: 2025-03-21T14:30:22Z
body: The report is already there for all Javadoc checks

https://github.com/checkstyle/checkstyle/pull/16586#issuecomment-2730044420
author_association: MEMBER