Add javadoc boilerplate internal comment v2 for experimental classes

open-telemetry · Nov 16, 2024 · 919e5fa · 919e5fa
1 parent ca98fc5
commit 919e5fa
Show file tree

Hide file tree

Showing 8 changed files with 33 additions and 19 deletions.
diff --git a/custom-checks/src/main/java/io/opentelemetry/gradle/customchecks/OtelInternalJavadoc.java b/custom-checks/src/main/java/io/opentelemetry/gradle/customchecks/OtelInternalJavadoc.java
@@ -21,8 +21,9 @@
 
 @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
+            + OtelInternalJavadoc.EXPECTED_INTERNAL_COMMENT_V2
             + "\"",
     severity = WARNING)
 public class OtelInternalJavadoc extends BugChecker implements BugChecker.ClassTreeMatcher {
@@ -31,17 +32,24 @@ public class OtelInternalJavadoc extends BugChecker implements BugChecker.ClassT
 
   private static final Pattern INTERNAL_PACKAGE_PATTERN = Pattern.compile("\\binternal\\b");
 
-  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.contains(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/...resources/io/opentelemetry/gradle/customchecks/internal/InternalJavadocPositiveCases.java b/...resources/io/opentelemetry/gradle/customchecks/internal/InternalJavadocPositiveCases.java
@@ -5,13 +5,13 @@
 
 package io.opentelemetry.gradle.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 {}
 }
diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/internal/LoggerConfig.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/internal/LoggerConfig.java
@@ -17,8 +17,9 @@
 /**
  * A collection of configuration options which define the behavior of a {@link Logger}.
  *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
+ * <p>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.
  *
  * @see SdkLoggerProviderUtil#setLoggerConfigurator(SdkLoggerProviderBuilder, ScopeConfigurator)
  * @see SdkLoggerProviderUtil#addLoggerConfiguratorCondition(SdkLoggerProviderBuilder, Predicate,

diff --git a/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/internal/SdkEventLoggerProvider.java b/sdk/logs/src/main/java/io/opentelemetry/sdk/logs/internal/SdkEventLoggerProvider.java
@@ -22,8 +22,9 @@
  * <p>Delegates all calls to the configured {@link LoggerProvider}, and its {@link LoggerBuilder}s,
  * {@link Logger}s.
  *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
+ * <p>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.
  */
 public final class SdkEventLoggerProvider implements EventLoggerProvider {
 

diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/MeterConfig.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/MeterConfig.java
@@ -17,8 +17,9 @@
 /**
  * A collection of configuration options which define the behavior of a {@link Meter}.
  *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
+ * <p>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.
  *
  * @see SdkMeterProviderUtil#setMeterConfigurator(SdkMeterProviderBuilder, ScopeConfigurator)
  * @see SdkMeterProviderUtil#addMeterConfiguratorCondition(SdkMeterProviderBuilder, Predicate,

diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/SdkMeterProviderUtil.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/SdkMeterProviderUtil.java
@@ -21,8 +21,9 @@
  * A collection of methods that allow use of experimental features prior to availability in public
  * APIs.
  *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
+ * <p>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.
  */
 public final class SdkMeterProviderUtil {
 

diff --git a/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/internal/SdkTracerProviderUtil.java b/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/internal/SdkTracerProviderUtil.java
@@ -16,8 +16,9 @@
  * A collection of methods that allow use of experimental features prior to availability in public
  * APIs.
  *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
+ * <p>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.
  */
 public final class SdkTracerProviderUtil {
 

diff --git a/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/internal/TracerConfig.java b/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/internal/TracerConfig.java
@@ -17,8 +17,9 @@
 /**
  * A collection of configuration options which define the behavior of a {@link Tracer}.
  *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
+ * <p>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.
  *
  * @see SdkTracerProviderUtil#setTracerConfigurator(SdkTracerProviderBuilder, ScopeConfigurator)
  * @see SdkTracerProviderUtil#addTracerConfiguratorCondition(SdkTracerProviderBuilder, Predicate,