Fix javadoc warnings across modules (#11747)

AlexeyKuznetsov-DD · web-flow · commit 3d4423e72617 · 2026-06-26T13:14:28.000Z
Fix javadoc warnings across modules

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

Use JUnit example in ThreadUtils javadoc

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

Drop needless javadoc on Closure overload

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

Co-authored-by: alexey.kuznetsov &lt;alexey.kuznetsov@datadoghq.com&gt;
diff --git a/communication/src/main/java/datadog/communication/serialization/GenerationalUtf8Cache.java b/communication/src/main/java/datadog/communication/serialization/GenerationalUtf8Cache.java
@@ -136,7 +136,7 @@ public int tenuredCapacity() {
     return this.tenuredEntries.length;
   }
 
-  /** Updates access time used @link {@link #getUtf8(String, String)} to the provided value */
+  /** Updates the access time used by {@link #getUtf8(String)} to the provided value. */
   @SuppressFBWarnings("AT_NONATOMIC_64BIT_PRIMITIVE")
   public void updateAccessTime(long accessTimeMs) {
     this.accessTimeMs = accessTimeMs;
diff --git a/components/context/src/main/java/datadog/context/ContextKey.java b/components/context/src/main/java/datadog/context/ContextKey.java
@@ -3,7 +3,7 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
- * {@link Context} key that maps to a value of type {@link T}.
+ * {@link Context} key that maps to a value of type {@code T}.
  *
  * <p>Keys are compared by identity rather than by name. Each stored context type should either
  * share its key for re-use or implement {@link ImplicitContextKeyed} to keep its key private.
diff --git a/components/environment/src/main/java/datadog/environment/ThreadSupport.java b/components/environment/src/main/java/datadog/environment/ThreadSupport.java
@@ -24,8 +24,8 @@ public final class ThreadSupport {
   private ThreadSupport() {}
 
   /**
-   * Provides the best identifier available for the current {@link Thread}. Uses {@link
-   * Thread#threadId()} on 19+ or {@link Thread#getId()} on older JVMs.
+   * Provides the best identifier available for the current {@link Thread}. Uses {@code
+   * Thread.threadId()} on 19+ or {@link Thread#getId()} on older JVMs.
    *
    * @return The best identifier available for the current {@link Thread}.
    */
@@ -34,8 +34,8 @@ public static long threadId() {
   }
 
   /**
-   * Provides the best identifier available for the given {@link Thread}. Uses {@link
-   * Thread#threadId()} on 19+ or {@link Thread#getId()} on older JVMs.
+   * Provides the best identifier available for the given {@link Thread}. Uses {@code
+   * Thread.threadId()} on 19+ or {@link Thread#getId()} on older JVMs.
    *
    * @return The best identifier available for the given {@link Thread}.
    */
diff --git a/components/json/src/main/java/datadog/json/JsonMapper.java b/components/json/src/main/java/datadog/json/JsonMapper.java
@@ -69,7 +69,7 @@ public static String toJson(Map<String, ?> map) {
   }
 
   /**
-   * Converts a {@link Iterable<String>} to a JSON array.
+   * Converts a {@code Iterable<String>} to a JSON array.
    *
    * @param items The iterable to convert.
    * @return The converted JSON array as Java string.
@@ -132,10 +132,10 @@ public static Map<String, Object> fromJsonToMap(String json) throws IOException
   }
 
   /**
-   * Parses a JSON string array into a {@link List<String>}.
+   * Parses a JSON string array into a {@code List<String>}.
    *
    * @param json The JSON string array to parse.
-   * @return A {@link List<String>} containing the parsed JSON strings.
+   * @return A {@code List<String>} containing the parsed JSON strings.
    * @throws IOException If the JSON is invalid or a reader error occurs.
    */
   public static List<String> fromJsonToList(String json) throws IOException {
diff --git a/dd-trace-api/src/main/java/datadog/appsec/api/blocking/Blocking.java b/dd-trace-api/src/main/java/datadog/appsec/api/blocking/Blocking.java
@@ -61,8 +61,8 @@ public static boolean tryCommitBlockingResponse(
   }
 
   /**
-   * Equivalent to calling {@link #tryCommitBlockingResponse(int, BlockingContentType, Map<String,
-   * String>)} with the last parameter being an empty map.
+   * Equivalent to calling {@link #tryCommitBlockingResponse(int, BlockingContentType, Map)} with
+   * the last parameter being an empty map.
    *
    * @param statusCode the status code of the response
    * @param contentType the content-type of the response.
diff --git a/dd-trace-api/src/main/java/datadog/trace/api/GlobalTracer.java b/dd-trace-api/src/main/java/datadog/trace/api/GlobalTracer.java
@@ -86,7 +86,7 @@ public static Tracer get() {
   }
 
   /**
-   * @deprecated use static methods in {@link EventTrackerV2} directly
+   * @deprecated use static methods in {@link datadog.appsec.api.login.EventTrackerV2} directly
    */
   @Deprecated
   public static EventTracker getEventTracker() {
diff --git a/dd-trace-api/src/main/java/datadog/trace/api/interceptor/MutableSpan.java b/dd-trace-api/src/main/java/datadog/trace/api/interceptor/MutableSpan.java
@@ -29,9 +29,9 @@ public interface MutableSpan {
   Integer getSamplingPriority();
 
   /**
-   * @param newPriority
-   * @return
-   * @deprecated Use {@link io.opentracing.Span#setTag(String, boolean)} instead using either tag
+   * @param newPriority the sampling priority to set
+   * @return this {@link MutableSpan} instance, for chaining
+   * @deprecated Use {@code io.opentracing.Span#setTag(String, boolean)} instead using either tag
    *     names {@link datadog.trace.api.DDTags#MANUAL_KEEP} or {@link
    *     datadog.trace.api.DDTags#MANUAL_DROP}.
    */
diff --git a/dd-trace-api/src/main/java/datadog/trace/api/internal/TraceSegment.java b/dd-trace-api/src/main/java/datadog/trace/api/internal/TraceSegment.java
@@ -132,8 +132,8 @@ default Object getTagCurrent(String key) {
    *
    * @param field field name
    * @param value value of the data
-   * @see datadog.trace.common.writer.ddagent.TraceMapperV0_4.MetaStructWriter
-   * @see datadog.trace.core.CoreSpan#setMetaStruct(String, Object)
+   * @see "datadog.trace.common.writer.ddagent.TraceMapperV0_4.MetaStructWriter"
+   * @see "datadog.trace.core.CoreSpan#setMetaStruct(String, Object)"
    */
   void setMetaStructCurrent(String field, Object value);
 
diff --git a/dd-trace-core/src/main/java/datadog/trace/common/sampling/SpanSamplingRules.java b/dd-trace-core/src/main/java/datadog/trace/common/sampling/SpanSamplingRules.java
@@ -108,10 +108,10 @@ private Rule(
     }
 
     /**
-     * Validate and create a {@link Rule} from its {@link JsonRule} representation.
+     * Validate and create a {@link Rule} from its {@code JsonRule} representation.
      *
-     * @param jsonRule The {@link JsonRule} to validate.
-     * @return A {@link Rule} if the {@link JsonRule} is valid, {@code null} otherwise.
+     * @param jsonRule The {@code JsonRule} to validate.
+     * @return A {@link Rule} if the {@code JsonRule} is valid, {@code null} otherwise.
      */
     public static Rule create(JsonRule jsonRule) {
       String service = SamplingRule.normalizeGlob(jsonRule.service);
diff --git a/dd-trace-core/src/main/java/datadog/trace/common/sampling/TraceSamplingRules.java b/dd-trace-core/src/main/java/datadog/trace/common/sampling/TraceSamplingRules.java
@@ -87,10 +87,10 @@ private Rule(
     }
 
     /**
-     * Validate and create a {@link Rule} from its {@link JsonRule} representation.
+     * Validate and create a {@link Rule} from its {@code JsonRule} representation.
      *
-     * @param jsonRule The {@link JsonRule} to validate.
-     * @return A {@link Rule} if the {@link JsonRule} is valid, {@code null} otherwise.
+     * @param jsonRule The {@code JsonRule} to validate.
+     * @return A {@link Rule} if the {@code JsonRule} is valid, {@code null} otherwise.
      */
     public static Rule create(JsonRule jsonRule) {
       String service = SamplingRule.normalizeGlob(jsonRule.service);
diff --git a/internal-api/src/main/java/datadog/trace/api/Config.java b/internal-api/src/main/java/datadog/trace/api/Config.java
@@ -5657,9 +5657,9 @@ public boolean isRuleEnabled(final String name, boolean defaultEnabled) {
   }
 
   /**
-   * @param integrationNames
-   * @param defaultEnabled
-   * @return
+   * @param integrationNames the integration names to check
+   * @param defaultEnabled the value to return when no integration name is configured
+   * @return {@code true} if the JMX fetch integration is enabled
    * @deprecated This method should only be used internally. Use the instance getter instead {@link
    *     #isJmxFetchIntegrationEnabled(Iterable, boolean)}.
    */
@@ -5826,9 +5826,9 @@ public <T extends Enum<T>> T getEnumValue(
   }
 
   /**
-   * @param integrationNames
-   * @param defaultEnabled
-   * @return
+   * @param integrationNames the integration names to check
+   * @param defaultEnabled the value to return when no integration name is configured
+   * @return {@code true} if the trace analytics integration is enabled
    * @deprecated This method should only be used internally. Use the instance getter instead {@link
    *     #isTraceAnalyticsIntegrationEnabled(SortedSet, boolean)}.
    */
diff --git a/internal-api/src/main/java/datadog/trace/api/TagMap.java b/internal-api/src/main/java/datadog/trace/api/TagMap.java
@@ -198,8 +198,8 @@ static Ledger ledger(int size) {
    * Similar to {@link Map#putAll(Map)} but optimized to quickly copy from one TagMap to another
    *
    * <p>For optimized TagMaps, this method takes advantage of the consistent TagMap layout to
-   * quickly handle each bucket. And similar to {@link TagMap#(Entry)} this method shares Entry
-   * objects from the source TagMap
+   * quickly handle each bucket. And similar to {@link TagMap#getAndSet(Entry)} this method shares
+   * Entry objects from the source TagMap
    */
   void putAll(TagMap that);
 
@@ -989,7 +989,7 @@ public boolean isDefinitelyEmpty() {
      * Provides the estimated size of the map created by the ledger Doesn't account for overwritten
      * entries or entry removal
      *
-     * @return
+     * @return the estimated size of the map created by the ledger
      */
     public int estimateSize() {
       return this.nextPos;
diff --git a/internal-api/src/main/java/datadog/trace/api/naming/NamingSchema.java b/internal-api/src/main/java/datadog/trace/api/naming/NamingSchema.java
@@ -51,14 +51,14 @@ public interface NamingSchema {
   /**
    * Policy for peer service tags calculation
    *
-   * @return
+   * @return the peer service naming policy
    */
   ForPeerService peerService();
 
   /**
    * If true, the schema allows having service names != DD_SERVICE
    *
-   * @return
+   * @return {@code true} if the schema allows service names different from {@code DD_SERVICE}
    */
   boolean allowInferredServices();
 
@@ -222,7 +222,7 @@ interface ForPeerService {
     /**
      * Whenever the schema supports peer service calculation
      *
-     * @return
+     * @return {@code true} if the schema supports peer service calculation
      */
     boolean supports();
 
diff --git a/internal-api/src/main/java/datadog/trace/api/remoteconfig/ServiceNameCollector.java b/internal-api/src/main/java/datadog/trace/api/remoteconfig/ServiceNameCollector.java
@@ -57,7 +57,7 @@ public void addService(final String serviceName) {
    * Get the list of unique services deduplicated by case. There is no locking on the addService map
    * so, the method is not thread safe.
    *
-   * @return
+   * @return the list of unique services, or {@code null} if none have been collected
    */
   @Nullable
   public List<String> getServices() {
diff --git a/internal-api/src/main/java/datadog/trace/api/sampling/SamplingMechanism.java b/internal-api/src/main/java/datadog/trace/api/sampling/SamplingMechanism.java
@@ -74,9 +74,9 @@ public static boolean validateWithSamplingPriority(int mechanism, int priority)
   /**
    * Returns true if sampling priority lock can be avoided for the given mechanism and priority
    *
-   * @param mechanism
-   * @param priority
-   * @return
+   * @param priority the sampling priority
+   * @param mechanism the sampling mechanism
+   * @return {@code true} if the sampling priority lock can be avoided, {@code false} otherwise
    */
   public static boolean canAvoidSamplingPriorityLock(int priority, int mechanism) {
     return (!Config.get().isApmTracingEnabled() && mechanism == SamplingMechanism.APPSEC)
diff --git a/internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/URIDataAdapter.java b/internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/URIDataAdapter.java
@@ -37,7 +37,7 @@ public interface URIDataAdapter {
   /**
    * The URI is a valid one or not (looks malformed)
    *
-   * @return
+   * @return {@code true} if the URI is valid, {@code false} if it looks malformed
    */
   boolean isValid();
 }
diff --git a/internal-api/src/main/java/datadog/trace/util/Hashtable.java b/internal-api/src/main/java/datadog/trace/util/Hashtable.java
@@ -618,8 +618,7 @@ public TEntry next() {
 
   /**
    * Mutating iterator over entries in a single bucket whose {@code keyHash} matches a specific
-   * search hash. Supports {@link #remove()} and {@link #replace(Entry)} to splice the chain in
-   * place.
+   * search hash. Supports {@link #remove()} and {@link #replace} to splice the chain in place.
    *
    * <p>Carries previous-node pointers for the current entry and the next-match entry so that {@code
    * remove} and {@code replace} can fix up the chain in O(1) without re-walking from the bucket
diff --git a/utils/junit-utils/src/main/java/datadog/trace/junit/utils/config/WithConfig.java b/utils/junit-utils/src/main/java/datadog/trace/junit/utils/config/WithConfig.java
@@ -18,16 +18,16 @@
  *
  * <p>Examples:
  *
- * <pre>{@code
- * @WithConfig(key = "service", value = "my_service")
- * @WithConfig(key = "trace.resolver.enabled", value = "false")
+ * <pre>
+ * &#64;WithConfig(key = "service", value = "my_service")
+ * &#64;WithConfig(key = "trace.resolver.enabled", value = "false")
  * class MyTest extends DDJavaSpecification {
  *
- *   @Test
- *   @WithConfig(key = "AGENT_HOST", value = "localhost", env = true)
+ *   &#64;Test
+ *   &#64;WithConfig(key = "AGENT_HOST", value = "localhost", env = true)
  *   void testWithEnv() { ... }
  * }
- * }</pre>
+ * </pre>
  */
 @Retention(RUNTIME)
 @Target({TYPE, METHOD})
diff --git a/utils/test-utils/src/main/java/datadog/trace/test/util/ThreadUtils.java b/utils/test-utils/src/main/java/datadog/trace/test/util/ThreadUtils.java
@@ -9,35 +9,32 @@
 
 public class ThreadUtils {
 
+  /** A {@link Runnable} whose {@link #run()} may throw a checked exception. */
+  @FunctionalInterface
+  public interface ThrowingRunnable {
+    void run() throws Throwable;
+  }
+
   /**
-   * Utility to easily run a Closure in parallel, i.e. in spock like this:
+   * Utility to easily run a piece of code in parallel, e.g. in a JUnit test like this:
    *
    * <pre>{@code
-   * def "some test"() {
-   *   expect:
-   *   runConcurrently(10, 100, {
-   *     def something = ...
-   *     def other = ...
-   *     assert something == other
-   *   })
-   * }
+   * runConcurrently(
+   *     10,
+   *     100,
+   *     () -> {
+   *       Object something = computeSomething();
+   *       Object other = computeOther();
+   *       assertEquals(something, other);
+   *     });
    * }</pre>
    *
-   * Writing a spock extension was investigated, but it is not possible to run an Invocation
-   * multiple times concurrently since a lot of the spock internal state and mock scoping is not
-   * thread safe.
-   *
    * @param concurrency the number of concurrent invocations
    * @param totalInvocations the total number of invocations
-   * @param closure the closure to run
-   * @return true if everything went well
+   * @param runnable the code to run
+   * @return {@code true} if everything went well
    * @throws Throwable if anything went wrong
    */
-  @FunctionalInterface
-  public interface ThrowingRunnable {
-    void run() throws Throwable;
-  }
-
   public static boolean runConcurrently(
       final int concurrency, final int totalInvocations, final ThrowingRunnable runnable)
       throws Throwable {

Original file line number	Diff line number	Diff line change
`@@ -136,7 +136,7 @@ public int tenuredCapacity() {`
`136`	`136`	`return this.tenuredEntries.length;`
`137`	`137`	`}`
`138`	`138`
`139`		`- /** Updates access time used @link {@link #getUtf8(String, String)} to the provided value */`
	`139`	`+ /** Updates the access time used by {@link #getUtf8(String)} to the provided value. */`
`140`	`140`	`@SuppressFBWarnings("AT_NONATOMIC_64BIT_PRIMITIVE")`
`141`	`141`	`public void updateAccessTime(long accessTimeMs) {`
`142`	`142`	`this.accessTimeMs = accessTimeMs;`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`import java.util.concurrent.atomic.AtomicInteger;`
`4`	`4`
`5`	`5`	`/**`
`6`		`- * {@link Context} key that maps to a value of type {@link T}.`
	`6`	`+ * {@link Context} key that maps to a value of type {@code T}.`
`7`	`7`	`*`
`8`	`8`	`* <p>Keys are compared by identity rather than by name. Each stored context type should either`
`9`	`9`	`* share its key for re-use or implement {@link ImplicitContextKeyed} to keep its key private.`
Original file line number	Diff line number	Diff line change
`@@ -24,8 +24,8 @@ public final class ThreadSupport {`
`24`	`24`	`private ThreadSupport() {}`
`25`	`25`
`26`	`26`	`/**`
`27`		`- * Provides the best identifier available for the current {@link Thread}. Uses {@link`
`28`		`- * Thread#threadId()} on 19+ or {@link Thread#getId()} on older JVMs.`
	`27`	`+ * Provides the best identifier available for the current {@link Thread}. Uses {@code`
	`28`	`+ * Thread.threadId()} on 19+ or {@link Thread#getId()} on older JVMs.`
`29`	`29`	`*`
`30`	`30`	`* @return The best identifier available for the current {@link Thread}.`
`31`	`31`	`*/`
`@@ -34,8 +34,8 @@ public static long threadId() {`
`34`	`34`	`}`
`35`	`35`
`36`	`36`	`/**`
`37`		`- * Provides the best identifier available for the given {@link Thread}. Uses {@link`
`38`		`- * Thread#threadId()} on 19+ or {@link Thread#getId()} on older JVMs.`
	`37`	`+ * Provides the best identifier available for the given {@link Thread}. Uses {@code`
	`38`	`+ * Thread.threadId()} on 19+ or {@link Thread#getId()} on older JVMs.`
`39`	`39`	`*`
`40`	`40`	`* @return The best identifier available for the given {@link Thread}.`
`41`	`41`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -69,7 +69,7 @@ public static String toJson(Map<String, ?> map) {`
`69`	`69`	`}`
`70`	`70`
`71`	`71`	`/**`
`72`		`- * Converts a {@link Iterable<String>} to a JSON array.`
	`72`	`+ * Converts a {@code Iterable<String>} to a JSON array.`
`73`	`73`	`*`
`74`	`74`	`* @param items The iterable to convert.`
`75`	`75`	`* @return The converted JSON array as Java string.`
`@@ -132,10 +132,10 @@ public static Map<String, Object> fromJsonToMap(String json) throws IOException`
`132`	`132`	`}`
`133`	`133`
`134`	`134`	`/**`
`135`		`- * Parses a JSON string array into a {@link List<String>}.`
	`135`	`+ * Parses a JSON string array into a {@code List<String>}.`
`136`	`136`	`*`
`137`	`137`	`* @param json The JSON string array to parse.`
`138`		`- * @return A {@link List<String>} containing the parsed JSON strings.`
	`138`	`+ * @return A {@code List<String>} containing the parsed JSON strings.`
`139`	`139`	`* @throws IOException If the JSON is invalid or a reader error occurs.`
`140`	`140`	`*/`
`141`	`141`	`public static List<String> fromJsonToList(String json) throws IOException {`
Original file line number	Diff line number	Diff line change
`@@ -61,8 +61,8 @@ public static boolean tryCommitBlockingResponse(`
`61`	`61`	`}`
`62`	`62`
`63`	`63`	`/**`
`64`		`- * Equivalent to calling {@link #tryCommitBlockingResponse(int, BlockingContentType, Map<String,`
`65`		`- * String>)} with the last parameter being an empty map.`
	`64`	`+ * Equivalent to calling {@link #tryCommitBlockingResponse(int, BlockingContentType, Map)} with`
	`65`	`+ * the last parameter being an empty map.`
`66`	`66`	`*`
`67`	`67`	`* @param statusCode the status code of the response`
`68`	`68`	`* @param contentType the content-type of the response.`
Original file line number	Diff line number	Diff line change
`@@ -86,7 +86,7 @@ public static Tracer get() {`
`86`	`86`	`}`
`87`	`87`
`88`	`88`	`/**`
`89`		`- * @deprecated use static methods in {@link EventTrackerV2} directly`
	`89`	`+ * @deprecated use static methods in {@link datadog.appsec.api.login.EventTrackerV2} directly`
`90`	`90`	`*/`
`91`	`91`	`@Deprecated`
`92`	`92`	`public static EventTracker getEventTracker() {`
Original file line number	Diff line number	Diff line change
`@@ -108,10 +108,10 @@ private Rule(`
`108`	`108`	`}`
`109`	`109`
`110`	`110`	`/**`
`111`		`- * Validate and create a {@link Rule} from its {@link JsonRule} representation.`
	`111`	`+ * Validate and create a {@link Rule} from its {@code JsonRule} representation.`
`112`	`112`	`*`
`113`		`- * @param jsonRule The {@link JsonRule} to validate.`
`114`		`- * @return A {@link Rule} if the {@link JsonRule} is valid, {@code null} otherwise.`
	`113`	`+ * @param jsonRule The {@code JsonRule} to validate.`
	`114`	`+ * @return A {@link Rule} if the {@code JsonRule} is valid, {@code null} otherwise.`
`115`	`115`	`*/`
`116`	`116`	`public static Rule create(JsonRule jsonRule) {`
`117`	`117`	`String service = SamplingRule.normalizeGlob(jsonRule.service);`
Original file line number	Diff line number	Diff line change
`@@ -87,10 +87,10 @@ private Rule(`
`87`	`87`	`}`
`88`	`88`
`89`	`89`	`/**`
`90`		`- * Validate and create a {@link Rule} from its {@link JsonRule} representation.`
	`90`	`+ * Validate and create a {@link Rule} from its {@code JsonRule} representation.`
`91`	`91`	`*`
`92`		`- * @param jsonRule The {@link JsonRule} to validate.`
`93`		`- * @return A {@link Rule} if the {@link JsonRule} is valid, {@code null} otherwise.`
	`92`	`+ * @param jsonRule The {@code JsonRule} to validate.`
	`93`	`+ * @return A {@link Rule} if the {@code JsonRule} is valid, {@code null} otherwise.`
`94`	`94`	`*/`
`95`	`95`	`public static Rule create(JsonRule jsonRule) {`
`96`	`96`	`String service = SamplingRule.normalizeGlob(jsonRule.service);`