False positive warning java:S125 for {@return foo} and code examples in Markdown Javadoc

SonarQube for IDE IntelliJ Platform
1

Environment:

  • Operating system: Windows 11
  • SonarQube for IntelliJ plugin version: 11.6.0.83783
  • IntelliJ version: 2025.2.5
  • Programming language you’re coding in: Java
  • Is connected mode used: SonarQube Server Enterprise Edition v2025.1.3 (110580)

Description of the problem / question 1:

There is no equivalent to the {@return foo} syntax in the new Markdown Javadoc comments introduced with Java 23/25. Instead, JEP 467 states:

JavaDoc tags, both inline tags such as {@inheritDoc} and block tags such as @param and @return, may be used in Markdown documentation comments

But unfortunately, SonarQube for IDE creates a false warning java:S125 This block of commented-out lines of code should be removed.

    /**
     * {@return foo}
     */

is fine but

/// {@return foo}

isn’t.

Description of the problem / question 2:

Same issue occurs with code examples in Markdown JavaDoc:

    /**
     * Use like this:
     * 
     * <pre>
     * Instant fooTime = bar.getDisconnectTime();
     * </pre>
     */

works fine but

    /// Use like this:
    /// ```
    /// Instant fooTime = bar.getDisconnectTime();
    /// ```

again results in wrong SonarQube for IDE warning java:S125 This block of commented-out lines of code should be removed.

It looks to me as if markdown Javadoc comments are classified as regular block comments, which they shouldn’t.

False "unused import" warning if class is only used in Markdown Javadoc
5

Hi,

We’ve done some work in 2025.4 to support these types of comments, but if you’re connected to 2025.1 you’re not going to see that.

 
Ann

6

Hello Ann, thanks for the super quick answer! I will ask our tool owner whether we can do an update then. Thanks for working on it, looking forward to the new version then!

I can confirm that the warnings disappear when disconnecting from our (slightly) outdated SonarQube server. And that SonarQube IDE even gives new helpful hints regarding Markdown Javadoc, great! (“java:S7474 Markdown, HTML and Javadoc tags should be consistent”) :+1:

1 Like