Support alternate internal javadoc comment for "experimental" classes (…

…#12866)
open-telemetry · Dec 9, 2024 · 96eccaf · 96eccaf
1 parent d26c1f6
commit 96eccaf
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 7 deletions.
diff --git a/custom-checks/src/main/java/io/opentelemetry/javaagent/customchecks/OtelInternalJavadoc.java b/custom-checks/src/main/java/io/opentelemetry/javaagent/customchecks/OtelInternalJavadoc.java
@@ -23,8 +23,10 @@
 @AutoService(BugChecker.class)
 @BugPattern(
     summary =
-        "This public internal class doesn't end with the javadoc disclaimer: \""
-            + OtelInternalJavadoc.EXPECTED_INTERNAL_COMMENT
+        "This public internal class doesn't end with any of the applicable javadoc disclaimers: \""
+            + OtelInternalJavadoc.EXPECTED_INTERNAL_COMMENT_V1
+            + "\", or \""
+            + OtelInternalJavadoc.EXPECTED_INTERNAL_COMMENT_V2
             + "\"",
     severity = WARNING)
 public class OtelInternalJavadoc extends BugChecker implements BugChecker.ClassTreeMatcher {
@@ -36,17 +38,24 @@ public class OtelInternalJavadoc extends BugChecker implements BugChecker.ClassT
   private static final Pattern EXCLUDE_PACKAGE_PATTERN =
       Pattern.compile("^io\\.opentelemetry\\.javaagent\\.instrumentation\\.internal\\.");
 
-  static final String EXPECTED_INTERNAL_COMMENT =
+  static final String EXPECTED_INTERNAL_COMMENT_V1 =
       "This class is internal and is hence not for public use."
           + " Its APIs are unstable and can change at any time.";
 
+  static final String EXPECTED_INTERNAL_COMMENT_V2 =
+      "This class is internal and experimental. Its APIs are unstable and can change at any time."
+          + " Its APIs (or a version of them) may be promoted to the public stable API in the"
+          + " future, but no guarantees are made.";
+
   @Override
   public Description matchClass(ClassTree tree, VisitorState state) {
     if (!isPublic(tree) || !isInternal(state) || tree.getSimpleName().toString().endsWith("Test")) {
       return Description.NO_MATCH;
     }
     String javadoc = getJavadoc(state);
-    if (javadoc != null && javadoc.endsWith(EXPECTED_INTERNAL_COMMENT)) {
+    if (javadoc != null
+        && (javadoc.contains(EXPECTED_INTERNAL_COMMENT_V1)
+            || javadoc.contains(EXPECTED_INTERNAL_COMMENT_V2))) {
       return Description.NO_MATCH;
     }
     return describeMatch(tree);

diff --git a/...ources/io/opentelemetry/javaagent/customchecks/internal/InternalJavadocPositiveCases.java b/...ources/io/opentelemetry/javaagent/customchecks/internal/InternalJavadocPositiveCases.java
@@ -5,13 +5,13 @@
 
 package io.opentelemetry.javaagent.customchecks.internal;
 
-// BUG: Diagnostic contains: doesn't end with the javadoc disclaimer
+// BUG: Diagnostic contains: doesn't end with any of the applicable javadoc disclaimers
 public class InternalJavadocPositiveCases {
 
-  // BUG: Diagnostic contains: doesn't end with the javadoc disclaimer
+  // BUG: Diagnostic contains: doesn't end with any of the applicable javadoc disclaimers
   public static class One {}
 
   /** Doesn't have the disclaimer. */
-  // BUG: Diagnostic contains: doesn't end with the javadoc disclaimer
+  // BUG: Diagnostic contains: doesn't end with any of the applicable javadoc disclaimers
   public static class Two {}
 }