SONARJAVA-6782: Implement S9355: use Javadoc syntax for almost-Javadoc comments by nathsou · Pull Request #5960 · SonarSource/sonar-java

nathsou · 2026-08-19T09:54:49Z

Summary

Implement S9355 in SonarJava as a native AlmostJavadocCheck.
Flag /* comments and // ... */ comments that contain Javadoc or HTML tags immediately before a documentable declaration.
Add a quick fix that converts the comment to /**.
Generate rule metadata from the S9355 RSPEC branch.

Links

Jira: https://sonarsource.atlassian.net/browse/SONARJAVA-6782
RSPEC PR: https://github.com/SonarSource/rspec/pull/7916

AI disclosure

LLM model used for implementation: cursor-grok-4.6-high

Flag comments that contain Javadoc or HTML tags but are not started with /**, so they do not document the following declaration.

hashicorp-vault-sonar-prod · 2026-08-19T09:55:05Z

SONARJAVA-6782

github-actions · 2026-08-19T10:08:12Z

❌ Ruling needs updating. A fix PR has been created: #5962

Please review and merge it into your branch.

Deduplicate multi-declarator fields, ignore trailing comments and local classes, and mark the implemented quick fix as covered.

github-actions · 2026-08-19T10:22:51Z

❌ Ruling needs updating. A fix PR has been created: #5962

Please review and merge it into your branch.

Sanity Test crashed because QuickFixHelper.previousVariable does not support IMPLICIT_CLASS parents on compact source files. Walk class members locally instead, skip the unnamed class itself, and cover the case with a compact-source sample.

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

github-actions · 2026-08-19T10:25:12Z

Ruling Diff Summary

Detected changes in 3 rule files: 0 issues removed, 34 issues added.

S9355 (java) on eclipse-jetty - 0 issues removed, 16 issues added - new ruling file

Added jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java (line 56)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java (line 75)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java (line 105)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/Request.java (line 1115)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/Request.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/Request.java (line 1994)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/Request.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/Request.java (line 2002)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/Request.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java (line 596)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java (line 609)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java (line 626)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/handler/ScopedHandler.java (line 204)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/handler/ScopedHandler.java)

Added jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java (line 420)

(source file not found at this revision: jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java)

Added jetty-util/src/main/java/org/eclipse/jetty/util/ssl/X509.java (line 41)

(source file not found at this revision: jetty-util/src/main/java/org/eclipse/jetty/util/ssl/X509.java)

Added jetty-util/src/main/java/org/eclipse/jetty/util/ssl/X509.java (line 46)

(source file not found at this revision: jetty-util/src/main/java/org/eclipse/jetty/util/ssl/X509.java)

S9355 (java) on eclipse-jetty-similar-to-main - 0 issues removed, 13 issues added - new ruling file

Added jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java (line 56)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java (line 75)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java (line 105)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/Request.java (line 1115)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/Request.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/Request.java (line 1994)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/Request.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/Request.java (line 2002)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/Request.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java (line 596)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java (line 609)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java (line 626)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java)

Added jetty-server/src/main/java/org/eclipse/jetty/server/handler/ScopedHandler.java (line 204)

(source file not found at this revision: jetty-server/src/main/java/org/eclipse/jetty/server/handler/ScopedHandler.java)

S9355 (java) on guava - 0 issues removed, 5 issues added - new ruling file

Added src/com/google/common/collect/ImmutableEnumSet.java (line 46)

        41 |       default:
        42 |         return new ImmutableEnumSet(set);
        43 |     }
        44 |   }
        45 | 
>>>     46 |   /*
        47 |    * Notes on EnumSet and <E extends Enum<E>>:
        48 |    *
        49 |    * This class isn't an arbitrary ForwardingImmutableSet because we need to
        50 |    * know that calling {@code clone()} during deserialization will return an
        51 |    * object that no one else has a reference to, allowing us to guarantee

Added src/com/google/common/collect/LinkedListMultimap.java (line 105)

       100 |  * @since 2.0
       101 |  */
       102 | @GwtCompatible(serializable = true, emulated = true)
       103 | public class LinkedListMultimap<K, V> extends AbstractMultimap<K, V>
       104 |     implements ListMultimap<K, V>, Serializable {
>>>    105 |   /*
       106 |    * Order is maintained using a linked list containing all key-value pairs. In
       107 |    * addition, a series of disjoint linked lists of "siblings", each containing
       108 |    * the values for a specific key, is used to implement {@link
       109 |    * ValueForKeyIterator} in constant time.
       110 |    */

Added src/com/google/common/net/PercentEscaper.java (line 136)

       131 |       octets[c] = true;
       132 |     }
       133 |     return octets;
       134 |   }
       135 | 
>>>    136 |   /*
       137 |    * Overridden for performance. For unescaped strings this improved the
       138 |    * performance of the uri escaper from ~760ns to ~400ns as measured by
       139 |    * {@link CharEscapersBenchmark}.
       140 |    */
       141 |   @Override

Added src/com/google/common/net/PercentEscaper.java (line 153)

       148 |       }
       149 |     }
       150 |     return index;
       151 |   }
       152 | 
>>>    153 |   /*
       154 |    * Overridden for performance. For unescaped strings this improved the
       155 |    * performance of the uri escaper from ~400ns to ~170ns as measured by
       156 |    * {@link CharEscapersBenchmark}.
       157 |    */
       158 |   @Override

Added src/com/google/common/util/concurrent/AbstractIdleService.java (line 39)

        34 |  * @since 1.0
        35 |  */
        36 | @Beta
        37 | public abstract class AbstractIdleService implements Service {
        38 | 
>>>     39 |   /* Thread names will look like {@code "MyService STARTING"}. */
        40 |   private final Supplier<String> threadNameSupplier = new Supplier<String>() {
        41 |     @Override public String get() {
        42 |       return serviceName() + " " + state();
        43 |     }
        44 |   };

Exercise the // /** quick fix and a second top-level type so compilation-unit siblings and the last convert-to-Javadoc branch are covered by tests.

The first auto-generated ruling update covered eclipse-jetty and guava only. The similar-to-main project reports the same HttpChannel/Request/ContextHandler issues and needs its own expected dump.

The combined HTML/Javadoc regex exceeded the allowed complexity of 20. Match closing HTML tags and @tags separately against a known tag set.

S2920 is not implemented in the Java analyzer, so the generated {rule:java:S2920} link did not resolve for users.

sonarqube-next · 2026-08-19T14:47:00Z

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
0 Dependency risks
94.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube

gitar-bot · 2026-08-19T15:05:23Z

Code Review ✅ Approved

Implements the new S9355 rule to detect and convert almost-Javadoc comments using standard Javadoc syntax. No issues found.

Implementation Status ✅ 1 / 1 issues implemented

✅ SONARJAVA-6782 — 1 / 1 objectives

The PR implements rule S9355 to detect almost-Javadoc comments before documentable declarations.

✅ 1 complete

✅ Implement rule S9355 to detect comments that look like Javadoc or contain HTML tags but do not start with /**, positioned immediately before documentable declarations

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

`Auto-apply`	`Compact`
`gitar auto-apply:on`	`gitar display:verbose`

_{Was this helpful? React with 👍 / 👎 | Gitar}

Implement S9355

091bdc8

Flag comments that contain Javadoc or HTML tags but are not started with /**, so they do not document the following declaration.

nathsou self-assigned this Aug 19, 2026

github-actions Bot mentioned this pull request Aug 19, 2026

Update ruling results for PR #5960 #5962

Merged

Fix review findings for S9355

d717a1e

Deduplicate multi-declarator fields, ignore trailing comments and local classes, and mark the implemented quick fix as covered.

nathsou and others added 2 commits August 19, 2026 12:23

fix-ci: handle implicit-class fields in S9355

ad0313a

Sanity Test crashed because QuickFixHelper.previousVariable does not support IMPLICIT_CLASS parents on compact source files. Walk class members locally instead, skip the unnamed class itself, and cover the case with a compact-source sample.

Update ruling results for PR #5960 (#5962)

6d9a717

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

nathsou added 3 commits August 19, 2026 12:25

fix-ci: cover remaining S9355 comment forms

0d498db

Exercise the // /** quick fix and a second top-level type so compilation-unit siblings and the last convert-to-Javadoc branch are covered by tests.

fix-ci: add S9355 ruling expected file for eclipse-jetty-similar-to-main

01fbfc9

The first auto-generated ruling update covered eclipse-jetty and guava only. The similar-to-main project reports the same HttpChannel/Request/ContextHandler issues and needs its own expected dump.

fix-ci: split S9355 tag matching to satisfy S5843

4ab5e1b

The combined HTML/Javadoc regex exceeded the allowed complexity of 20. Match closing HTML tags and @tags separately against a known tag set.

nathsou requested a review from romainbrenguier August 19, 2026 11:20

romainbrenguier approved these changes Aug 19, 2026

View reviewed changes

Comment thread sonar-java-plugin/src/main/resources/org/sonar/l10n/java/rules/java/S9355.html Outdated

Regenerate S9355 description without S2920 reference

4b1b980

S2920 is not implemented in the Java analyzer, so the generated {rule:java:S2920} link did not resolve for users.

nathsou merged commit 01507dd into master Aug 19, 2026
18 checks passed

nathsou deleted the new-rule/S9355 branch August 19, 2026 15:04

Navigation Menu

Uh oh!

SONARJAVA-6782: Implement S9355: use Javadoc syntax for almost-Javadoc comments - #5960

SONARJAVA-6782: Implement S9355: use Javadoc syntax for almost-Javadoc comments#5960
nathsou merged 8 commits into
masterfrom
new-rule/S9355

nathsou commented Aug 19, 2026

Uh oh!

hashicorp-vault-sonar-prod Bot commented Aug 19, 2026 •

edited by atlassian Bot

Loading

Uh oh!

github-actions Bot commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

sonarqube-next Bot commented Aug 19, 2026

Uh oh!

Uh oh!

gitar-bot Bot commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

nathsou commented Aug 19, 2026

Summary

Links

AI disclosure

Uh oh!

hashicorp-vault-sonar-prod Bot commented Aug 19, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Ruling Diff Summary

Uh oh!

Uh oh!

sonarqube-next Bot commented Aug 19, 2026

Quality Gate passed

Uh oh!

Uh oh!

gitar-bot Bot commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hashicorp-vault-sonar-prod Bot commented Aug 19, 2026 •

edited by atlassian Bot

Loading

github-actions Bot commented Aug 19, 2026 •

edited

Loading