open-telemetry
/
opentelemetry-java-instrumentation
mirror of https://github.com/open-telemetry/opentelemetry-java-instrumentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Support alternate internal javadoc comment for "experimental" classes (#12866)

This commit is contained in:
Trask Stalnaker 2024-12-09 14:09:51 -08:00 committed by GitHub
parent d26c1f6d51
commit 96eccaf008
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 16 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
custom-checks/src/main/java/io/opentelemetry/javaagent/customchecks/OtelInternalJavadoc.java
View File

@ -23,8 +23,10 @@ import javax.lang.model.element.Modifier;
@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);

6
custom-checks/src/test/resources/io/opentelemetry/javaagent/customchecks/internal/InternalJavadocPositiveCases.java
View File

@ -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 {}
}