From 919e5fa78a2c7dc6867eee79407f8769f5ce767c Mon Sep 17 00:00:00 2001
From: Ravishankar Nagendran <Ravi.mbatechie@gmail.com>
Date: Fri, 15 Nov 2024 17:31:39 -0700
Subject: [PATCH] Add javadoc boilerplate internal comment v2 for experimental
 classes

---
 .../gradle/customchecks/OtelInternalJavadoc.java | 16 ++++++++++++----
 .../internal/InternalJavadocPositiveCases.java   |  6 +++---
 .../sdk/logs/internal/LoggerConfig.java          |  5 +++--
 .../logs/internal/SdkEventLoggerProvider.java    |  5 +++--
 .../sdk/metrics/internal/MeterConfig.java        |  5 +++--
 .../metrics/internal/SdkMeterProviderUtil.java   |  5 +++--
 .../trace/internal/SdkTracerProviderUtil.java    |  5 +++--
 .../sdk/trace/internal/TracerConfig.java         |  5 +++--
 8 files changed, 33 insertions(+), 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
index 3ac6b964dac..962ab0d25be 100644
--- 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/custom-checks/src/test/resources/io/opentelemetry/gradle/customchecks/internal/InternalJavadocPositiveCases.java b/custom-checks/src/test/resources/io/opentelemetry/gradle/customchecks/internal/InternalJavadocPositiveCases.java
index dc36e5ef636..f7a3042e4d6 100644
--- a/custom-checks/src/test/resources/io/opentelemetry/gradle/customchecks/internal/InternalJavadocPositiveCases.java
+++ b/custom-checks/src/test/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
index 8fb0f7dac2e..00ffdc86b41 100644
--- 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
index 7a2972056a3..d198675f552 100644
--- 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
index ededd6acdad..35981025071 100644
--- 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
index c559fc4c76f..1b203d9d9a2 100644
--- 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
index 7d00f230dea..76111258a67 100644
--- 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
index 535760cbfd4..4fa8c702b1c 100644
--- 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,