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

its/ruling/src/test/resources/eclipse-jetty-similar-to-main/java-S9355.json

@@ -0,0 +1,23 @@
+{
+"org.eclipse.jetty:jetty-project:jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java": [
+56,
+75,
+105,
+118
+],
+"org.eclipse.jetty:jetty-project:jetty-server/src/main/java/org/eclipse/jetty/server/Request.java": [
+1115,
+1994,
+2002
+],
+"org.eclipse.jetty:jetty-project:jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java": [
+596,
+609,
+626,
+1174,
+1527
+],
+"org.eclipse.jetty:jetty-project:jetty-server/src/main/java/org/eclipse/jetty/server/handler/ScopedHandler.java": [
+204
+]
+}

its/ruling/src/test/resources/eclipse-jetty/java-S9355.json

@@ -0,0 +1,30 @@
+{
+"org.eclipse.jetty:jetty-project:jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java": [
+56,
+75,
+105,
+118
+],
+"org.eclipse.jetty:jetty-project:jetty-server/src/main/java/org/eclipse/jetty/server/Request.java": [
+1115,
+1994,
+2002
+],
+"org.eclipse.jetty:jetty-project:jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java": [
+596,
+609,
+626,
+1174,
+1527
+],
+"org.eclipse.jetty:jetty-project:jetty-server/src/main/java/org/eclipse/jetty/server/handler/ScopedHandler.java": [
+204
+],
+"org.eclipse.jetty:jetty-project:jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java": [
+420
+],
+"org.eclipse.jetty:jetty-project:jetty-util/src/main/java/org/eclipse/jetty/util/ssl/X509.java": [
+41,
+46
+]
+}

its/ruling/src/test/resources/guava/java-S9355.json

@@ -0,0 +1,15 @@
+{
+"com.google.guava:guava:src/com/google/common/collect/ImmutableEnumSet.java": [
+46
+],
+"com.google.guava:guava:src/com/google/common/collect/LinkedListMultimap.java": [
+105
+],
+"com.google.guava:guava:src/com/google/common/net/PercentEscaper.java": [
+136,
+153
+],
+"com.google.guava:guava:src/com/google/common/util/concurrent/AbstractIdleService.java": [
+39
+]
+}

java-checks-test-sources/default/src/main/java/checks/AlmostJavadocCheckSample.java

@@ -0,0 +1,156 @@
+package checks;
+
+class AlmostJavadocCheckSample {
+
+  String name;
+
+  // Noncompliant@+1 [[quickfixes=qf1]]
+  /*
+   * Computes the factorial of a positive integer.
+   * @param n the number to compute factorial for
+   * @return the factorial of n
+   */
+  // fix@qf1 {{Convert to Javadoc comment}}
+  // edit@qf1 [[sc=4;ec=4]] {{*}}
+  public long factorial(int n) {
+    return (n <= 1) ? 1L : n * factorial(n - 1);
+  }
+
+  /**
+   * Computes the factorial of a positive integer.
+   * @param n the number to compute factorial for
+   * @return the factorial of n
+   */
+  public long documentedFactorial(int n) {
+    return (n <= 1) ? 1L : n * documentedFactorial(n - 1);
+  }
+
+  // Noncompliant@+1 [[quickfixes=qf2]]
+  /* Returns the display name as <code>String</code>. */
+  // fix@qf2 {{Convert to Javadoc comment}}
+  // edit@qf2 [[sc=4;ec=4]] {{*}}
+  public String displayName() {
+    return name;
+  }
+
+  /** Returns the display name as <code>String</code>. */
+  public String documentedDisplayName() {
+    return name;
+  }
+
+  interface Repository {
+    // Noncompliant@+1 [[quickfixes=qf3]]
+    // Loads the entity. {@link Entity} */
+    // fix@qf3 {{Convert to Javadoc comment}}
+    // edit@qf3 [[sc=5;ec=7]] {{/**}}
+    Entity load(String id);
+
+    /** Loads the entity. {@link Entity} */
+    Entity documentedLoad(String id);
+
+    // Noncompliant@+1
+    // Loads with trailing space. {@link Entity} */ 
+    Entity loadWithTrailingSpace(String id);
+  }
+
+  // Noncompliant@+1
+  /* {@link AlmostJavadocCheckSample} */
+  static class Nested {}
+
+  /** {@link AlmostJavadocCheckSample} */
+  static class DocumentedNested {}
+
+  // Noncompliant@+1
+  /* @since 1.0 */
+  int version;
+
+  /** @since 1.0 */
+  int documentedVersion;
+
+  enum Kind {
+    // Noncompliant@+1
+    /* Foo <em>bar</em>. */
+    FOO,
+    /** Foo <em>bar</em>. */
+    BAR
+  }
+
+  /* Regular commentary without tags. */
+  void undocumentedOnPurpose() {
+  }
+
+  // Regular line comment with {@link tags} is not almost-Javadoc
+  void lineCommentWithoutTerminator() {
+  }
+
+  /* returns 0 on success */
+  int noTagBecauseReturnIsAWord() {
+    return 0;
+  }
+
+  /* support@param.org is an email, not a Javadoc tag */
+  void emailLooksLikeTag() {
+  }
+
+  /* @Override is a Java annotation mentioned in a comment */
+  void annotationMention() {
+  }
+
+  /* List<String> uses generics, not HTML */
+  void genericsAreNotHtml() {
+    voidWithLocalComment();
+  }
+
+  void voidWithLocalComment() {
+    /* @param local is not attached to a documentable declaration */
+    int local = 1;
+  }
+
+  /** Valid Javadoc. */
+  /* Extra note with {@link tags}. */
+  void alreadyHasJavadoc() {
+  }
+
+  /// Markdown documentation with {@link tags}.
+  /* Extra note with @param. */
+  void alreadyHasMarkdown() {
+  }
+
+  @Override
+  public String toString() {
+    return name;
+  }
+
+  record Point(int x, int y) {
+    // Noncompliant@+1
+    /* @param x the x coordinate */
+    Point {
+    }
+  }
+
+  // Noncompliant@+1
+  /* @since 1.0 */
+  int a, b, c;
+
+  int trailingField; // trailing note: see @param x */
+  void methodAfterTrailingComment(int x) {
+  }
+
+  void localClassIsNotDocumentable() {
+    /* @param q */
+    class Local {
+      /* @return r */
+      int r;
+    }
+  }
+
+  static class Entity {
+  }
+}
+
+// Noncompliant@+1 [[quickfixes=qf4]]
+// /** Extra documentation. {@link AlmostJavadocCheckSample.Entity} */
+// fix@qf4 {{Convert to Javadoc comment}}
+// edit@qf4 [[sc=1;ec=3]] {{}}
+class AlmostJavadocCheckSampleSecondType {
+}

java-checks-test-sources/default/src/main/java/checks/AlmostJavadocCheck_compactSource.java

@@ -0,0 +1,20 @@
+void main() {
+  System.out.println("compact source");
+}
+
+// Noncompliant@+1
+/* @since 1.0 */
+int version;
+
+/** @since 1.0 */
+int documentedVersion;
+
+// Noncompliant@+1
+/* @param n unused */
+int a, b, c;
+
+// Noncompliant@+1
+/* Returns <code>ok</code>. */
+String status() {
+  return "ok";
+}