Apply javadoc updates to other modules (open-telemetry#15857)

Author: trask

instrumentation/apache-httpclient/apache-httpclient-4.3/library/src/main/java/io/opentelemetry/instrumentation/apachehttpclient/v4_3/ApacheHttpClientTelemetry.java

@@ -15,18 +15,12 @@
 /** Entrypoint for instrumenting Apache HTTP Client. */
 public final class ApacheHttpClientTelemetry {
 
-  /**
-   * Returns a new {@link ApacheHttpClientTelemetry} configured with the given {@link
-   * OpenTelemetry}.
-   */
+  /** Returns a new instance configured with the given {@link OpenTelemetry} instance. */
   public static ApacheHttpClientTelemetry create(OpenTelemetry openTelemetry) {
     return builder(openTelemetry).build();
   }
 
-  /**
-   * Returns a new {@link ApacheHttpClientTelemetryBuilder} configured with the given {@link
-   * OpenTelemetry}.
-   */
+  /** Returns a builder configured with the given {@link OpenTelemetry} instance. */
   public static ApacheHttpClientTelemetryBuilder builder(OpenTelemetry openTelemetry) {
     return new ApacheHttpClientTelemetryBuilder(openTelemetry);
   }
@@ -41,13 +35,13 @@ public static ApacheHttpClientTelemetryBuilder builder(OpenTelemetry openTelemet
     this.propagators = propagators;
   }
 
-  /** Returns a new {@link CloseableHttpClient} with tracing configured. */
+  /** Returns an instrumented HTTP client. */
   public CloseableHttpClient createHttpClient() {
     return createHttpClientBuilder().build();
   }
 
   /**
-   * Returns a new {@link CloseableHttpClient} with tracing configured.
+   * Returns an instrumented HTTP client.
    *
    * @deprecated Use {@link #createHttpClient()} instead.
    */
@@ -56,13 +50,13 @@ public CloseableHttpClient newHttpClient() {
     return createHttpClient();
   }
 
-  /** Returns a new {@link HttpClientBuilder} to create a client with tracing configured. */
+  /** Returns a builder for creating an instrumented HTTP client. */
   public HttpClientBuilder createHttpClientBuilder() {
     return new TracingHttpClientBuilder(instrumenter, propagators);
   }
 
   /**
-   * Returns a new {@link HttpClientBuilder} to create a client with tracing configured.
+   * Returns a builder for creating an instrumented HTTP client.
    *
    * @deprecated Use {@link #createHttpClientBuilder()} instead.
    */

instrumentation/apache-httpclient/apache-httpclient-4.3/library/src/main/java/io/opentelemetry/instrumentation/apachehttpclient/v4_3/ApacheHttpClientTelemetryBuilder.java

@@ -16,7 +16,7 @@
 import java.util.function.UnaryOperator;
 import org.apache.http.HttpResponse;
 
-/** A builder for {@link ApacheHttpClientTelemetry}. */
+/** Builder for {@link ApacheHttpClientTelemetry}. */
 public final class ApacheHttpClientTelemetryBuilder {
 
   private static final String INSTRUMENTATION_NAME = "io.opentelemetry.apache-httpclient-4.3";
@@ -36,8 +36,8 @@ public final class ApacheHttpClientTelemetryBuilder {
   }
 
   /**
-   * Adds an additional {@link AttributesExtractor} to invoke to set attributes to instrumented
-   * items. The {@link AttributesExtractor} will be executed after all default extractors.
+   * Adds an {@link AttributesExtractor} to extract attributes from requests and responses. Executed
+   * after all default extractors.
    */
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder addAttributesExtractor(
@@ -47,9 +47,9 @@ public ApacheHttpClientTelemetryBuilder addAttributesExtractor(
   }
 
   /**
-   * Configures the HTTP request headers that will be captured as span attributes.
+   * Configures HTTP request headers to capture as span attributes.
    *
-   * @param requestHeaders A list of HTTP header names.
+   * @param requestHeaders HTTP header names to capture.
    */
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder setCapturedRequestHeaders(
@@ -59,9 +59,9 @@ public ApacheHttpClientTelemetryBuilder setCapturedRequestHeaders(
   }
 
   /**
-   * Configures the HTTP response headers that will be captured as span attributes.
+   * Configures HTTP response headers to capture as span attributes.
    *
-   * @param responseHeaders A list of HTTP header names.
+   * @param responseHeaders HTTP header names to capture.
    */
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder setCapturedResponseHeaders(
@@ -71,16 +71,15 @@ public ApacheHttpClientTelemetryBuilder setCapturedResponseHeaders(
   }
 
   /**
-   * Configures the instrumentation to recognize an alternative set of HTTP request methods.
+   * Configures recognized HTTP request methods.
    *
-   * <p>By default, this instrumentation defines "known" methods as the ones listed in <a
-   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and the PATCH
-   * method defined in <a href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>.
+   * <p>By default, recognizes methods from <a
+   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and PATCH from <a
+   * href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>.
    *
-   * <p>Note: calling this method <b>overrides</b> the default known method sets completely; it does
-   * not supplement it.
+   * <p><b>Note:</b> This <b>overrides</b> defaults completely; it does not supplement them.
    *
-   * @param knownMethods A set of recognized HTTP request methods.
+   * @param knownMethods HTTP request methods to recognize.
    * @see HttpClientAttributesExtractorBuilder#setKnownMethods(Collection)
    */
   @CanIgnoreReturnValue
@@ -89,21 +88,15 @@ public ApacheHttpClientTelemetryBuilder setKnownMethods(Collection<String> known
     return this;
   }
 
-  /**
-   * Sets a customizer that receives the default {@link SpanNameExtractor} and returns a customized
-   * one.
-   */
+  /** Customizes the {@link SpanNameExtractor} by transforming the default instance. */
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder setSpanNameExtractorCustomizer(
       UnaryOperator<SpanNameExtractor<ApacheHttpClientRequest>> spanNameExtractorCustomizer) {
     builder.setSpanNameExtractorCustomizer(spanNameExtractorCustomizer);
     return this;
   }
 
-  /**
-   * Returns a new {@link ApacheHttpClientTelemetry} configured with this {@link
-   * ApacheHttpClientTelemetryBuilder}.
-   */
+  /** Returns a new instance with the configured settings. */
   public ApacheHttpClientTelemetry build() {
     return new ApacheHttpClientTelemetry(builder.build(), openTelemetry.getPropagators());
   }

instrumentation/armeria/armeria-1.3/library/src/main/java/io/opentelemetry/instrumentation/armeria/v1_3/ArmeriaClientTelemetry.java

@@ -15,13 +15,12 @@
 /** Entrypoint for instrumenting Armeria clients. */
 public final class ArmeriaClientTelemetry {
 
-  /**
-   * Returns a new {@link ArmeriaClientTelemetry} configured with the given {@link OpenTelemetry}.
-   */
+  /** Returns a new instance configured with the given {@link OpenTelemetry} instance. */
   public static ArmeriaClientTelemetry create(OpenTelemetry openTelemetry) {
     return builder(openTelemetry).build();
   }
 
+  /** Returns a builder configured with the given {@link OpenTelemetry} instance. */
   public static ArmeriaClientTelemetryBuilder builder(OpenTelemetry openTelemetry) {
     return new ArmeriaClientTelemetryBuilder(openTelemetry);
   }
@@ -32,10 +31,7 @@ public static ArmeriaClientTelemetryBuilder builder(OpenTelemetry openTelemetry)
     this.instrumenter = instrumenter;
   }
 
-  /**
-   * Returns a new {@link HttpClient} decorator for use with methods like {@link
-   * com.linecorp.armeria.client.ClientBuilder#decorator(Function)}.
-   */
+  /** Returns a decorator for instrumenting Armeria clients. */
   public Function<? super HttpClient, ? extends HttpClient> newDecorator() {
     return client -> new OpenTelemetryClient(client, instrumenter);
   }

instrumentation/armeria/armeria-1.3/library/src/main/java/io/opentelemetry/instrumentation/armeria/v1_3/ArmeriaClientTelemetryBuilder.java

@@ -36,10 +36,7 @@ public final class ArmeriaClientTelemetryBuilder {
     builder = ArmeriaInstrumenterBuilderFactory.getClientBuilder(openTelemetry);
   }
 
-  /**
-   * Sets a customizer that receives the default {@link SpanStatusExtractor} and returns a
-   * customized one.
-   */
+  /** Customizes the {@link SpanStatusExtractor} by transforming the default instance. */
   @CanIgnoreReturnValue
   public ArmeriaClientTelemetryBuilder setSpanStatusExtractorCustomizer(
       UnaryOperator<SpanStatusExtractor<ClientRequestContext, RequestLog>>
@@ -49,8 +46,8 @@ public ArmeriaClientTelemetryBuilder setSpanStatusExtractorCustomizer(
   }
 
   /**
-   * Adds an extra {@link AttributesExtractor} to invoke to set attributes to instrumented items.
-   * The {@link AttributesExtractor} will be executed after all default extractors.
+   * Adds an {@link AttributesExtractor} to extract attributes from requests and responses. Executed
+   * after all default extractors.
    */
   @CanIgnoreReturnValue
   public ArmeriaClientTelemetryBuilder addAttributesExtractor(
@@ -60,9 +57,9 @@ public ArmeriaClientTelemetryBuilder addAttributesExtractor(
   }
 
   /**
-   * Configures the HTTP client request headers that will be captured as span attributes.
+   * Configures HTTP request headers to capture as span attributes.
    *
-   * @param requestHeaders A list of HTTP header names.
+   * @param requestHeaders HTTP header names to capture.
    */
   @CanIgnoreReturnValue
   public ArmeriaClientTelemetryBuilder setCapturedRequestHeaders(
@@ -72,9 +69,9 @@ public ArmeriaClientTelemetryBuilder setCapturedRequestHeaders(
   }
 
   /**
-   * Configures the HTTP client response headers that will be captured as span attributes.
+   * Configures HTTP response headers to capture as span attributes.
    *
-   * @param responseHeaders A list of HTTP header names.
+   * @param responseHeaders HTTP header names to capture.
    */
   @CanIgnoreReturnValue
   public ArmeriaClientTelemetryBuilder setCapturedResponseHeaders(
@@ -84,16 +81,15 @@ public ArmeriaClientTelemetryBuilder setCapturedResponseHeaders(
   }
 
   /**
-   * Configures the instrumentation to recognize an alternative set of HTTP request methods.
+   * Configures recognized HTTP request methods.
    *
-   * <p>By default, this instrumentation defines "known" methods as the ones listed in <a
-   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and the PATCH
-   * method defined in <a href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>.
+   * <p>By default, recognizes methods from <a
+   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and PATCH from <a
+   * href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>.
    *
-   * <p>Note: calling this method <b>overrides</b> the default known method sets completely; it does
-   * not supplement it.
+   * <p><b>Note:</b> This <b>overrides</b> defaults completely; it does not supplement them.
    *
-   * @param knownMethods A set of recognized HTTP request methods.
+   * @param knownMethods HTTP request methods to recognize.
    * @see HttpClientAttributesExtractorBuilder#setKnownMethods(Collection)
    */
   @CanIgnoreReturnValue
@@ -102,17 +98,15 @@ public ArmeriaClientTelemetryBuilder setKnownMethods(Collection<String> knownMet
     return this;
   }
 
-  /**
-   * Sets a customizer that receives the default {@link SpanNameExtractor} and returns a customized
-   * one.
-   */
+  /** Customizes the {@link SpanNameExtractor} by transforming the default instance. */
   @CanIgnoreReturnValue
   public ArmeriaClientTelemetryBuilder setSpanNameExtractorCustomizer(
       UnaryOperator<SpanNameExtractor<ClientRequestContext>> spanNameExtractorCustomizer) {
     builder.setSpanNameExtractorCustomizer(spanNameExtractorCustomizer);
     return this;
   }
 
+  /** Returns a new instance with the configured settings. */
   public ArmeriaClientTelemetry build() {
     return new ArmeriaClientTelemetry(builder.build());
   }

instrumentation/armeria/armeria-1.3/library/src/main/java/io/opentelemetry/instrumentation/armeria/v1_3/ArmeriaServerTelemetry.java

@@ -15,13 +15,12 @@
 /** Entrypoint for instrumenting Armeria services. */
 public final class ArmeriaServerTelemetry {
 
-  /**
-   * Returns a new {@link ArmeriaServerTelemetry} configured with the given {@link OpenTelemetry}.
-   */
+  /** Returns a new instance configured with the given {@link OpenTelemetry} instance. */
   public static ArmeriaServerTelemetry create(OpenTelemetry openTelemetry) {
     return builder(openTelemetry).build();
   }
 
+  /** Returns a builder configured with the given {@link OpenTelemetry} instance. */
   public static ArmeriaServerTelemetryBuilder builder(OpenTelemetry openTelemetry) {
     return new ArmeriaServerTelemetryBuilder(openTelemetry);
   }
@@ -32,10 +31,7 @@ public static ArmeriaServerTelemetryBuilder builder(OpenTelemetry openTelemetry)
     this.instrumenter = instrumenter;
   }
 
-  /**
-   * Returns a new {@link HttpService} decorator for use with methods like {@link
-   * HttpService#decorate(Function)}.
-   */
+  /** Returns a decorator for instrumenting Armeria services. */
   public Function<? super HttpService, ? extends HttpService> newDecorator() {
     return service -> new OpenTelemetryService(service, instrumenter);
   }

instrumentation/armeria/armeria-1.3/library/src/main/java/io/opentelemetry/instrumentation/armeria/v1_3/ArmeriaServerTelemetryBuilder.java

@@ -34,10 +34,7 @@ public final class ArmeriaServerTelemetryBuilder {
     builder = ArmeriaInstrumenterBuilderFactory.getServerBuilder(openTelemetry);
   }
 
-  /**
-   * Sets a customizer that receives the default {@link SpanStatusExtractor} and returns a
-   * customized one.
-   */
+  /** Customizes the {@link SpanStatusExtractor} by transforming the default instance. */
   @CanIgnoreReturnValue
   public ArmeriaServerTelemetryBuilder setSpanStatusExtractorCustomizer(
       UnaryOperator<SpanStatusExtractor<ServiceRequestContext, RequestLog>>
@@ -47,8 +44,8 @@ public ArmeriaServerTelemetryBuilder setSpanStatusExtractorCustomizer(
   }
 
   /**
-   * Adds an extra {@link AttributesExtractor} to invoke to set attributes to instrumented items.
-   * The {@link AttributesExtractor} will be executed after all default extractors.
+   * Adds an {@link AttributesExtractor} to extract attributes from requests and responses. Executed
+   * after all default extractors.
    */
   @CanIgnoreReturnValue
   public ArmeriaServerTelemetryBuilder addAttributesExtractor(
@@ -58,9 +55,9 @@ public ArmeriaServerTelemetryBuilder addAttributesExtractor(
   }
 
   /**
-   * Configures the HTTP server request headers that will be captured as span attributes.
+   * Configures HTTP request headers to capture as span attributes.
    *
-   * @param requestHeaders A list of HTTP header names.
+   * @param requestHeaders HTTP header names to capture.
    */
   @CanIgnoreReturnValue
   public ArmeriaServerTelemetryBuilder setCapturedRequestHeaders(
@@ -70,9 +67,9 @@ public ArmeriaServerTelemetryBuilder setCapturedRequestHeaders(
   }
 
   /**
-   * Configures the HTTP server response headers that will be captured as span attributes.
+   * Configures HTTP response headers to capture as span attributes.
    *
-   * @param responseHeaders A list of HTTP header names.
+   * @param responseHeaders HTTP header names to capture.
    */
   @CanIgnoreReturnValue
   public ArmeriaServerTelemetryBuilder setCapturedResponseHeaders(
@@ -82,16 +79,15 @@ public ArmeriaServerTelemetryBuilder setCapturedResponseHeaders(
   }
 
   /**
-   * Configures the instrumentation to recognize an alternative set of HTTP request methods.
+   * Configures recognized HTTP request methods.
    *
-   * <p>By default, this instrumentation defines "known" methods as the ones listed in <a
-   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and the PATCH
-   * method defined in <a href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>.
+   * <p>By default, recognizes methods from <a
+   * href="https://www.rfc-editor.org/rfc/rfc9110.html#name-methods">RFC9110</a> and PATCH from <a
+   * href="https://www.rfc-editor.org/rfc/rfc5789.html">RFC5789</a>.
    *
-   * <p>Note: calling this method <b>overrides</b> the default known method sets completely; it does
-   * not supplement it.
+   * <p><b>Note:</b> This <b>overrides</b> defaults completely; it does not supplement them.
    *
-   * @param knownMethods A set of recognized HTTP request methods.
+   * @param knownMethods HTTP request methods to recognize.
    * @see HttpServerAttributesExtractorBuilder#setKnownMethods(Collection)
    */
   @CanIgnoreReturnValue
@@ -100,17 +96,15 @@ public ArmeriaServerTelemetryBuilder setKnownMethods(Collection<String> knownMet
     return this;
   }
 
-  /**
-   * Sets a customizer that receives the default {@link SpanNameExtractor} and returns a customized
-   * one.
-   */
+  /** Customizes the {@link SpanNameExtractor} by transforming the default instance. */
   @CanIgnoreReturnValue
   public ArmeriaServerTelemetryBuilder setSpanNameExtractorCustomizer(
       UnaryOperator<SpanNameExtractor<ServiceRequestContext>> spanNameExtractorCustomizer) {
     builder.setSpanNameExtractorCustomizer(spanNameExtractorCustomizer);
     return this;
   }
 
+  /** Returns a new instance with the configured settings. */
   public ArmeriaServerTelemetry build() {
     return new ArmeriaServerTelemetry(builder.build());
   }