Improve HTTP library javadocs

instrumentation/apache-httpclient/apache-httpclient-5.2/library/src/main/java/io/opentelemetry/instrumentation/apachehttpclient/v5_2/ApacheHttpClientTelemetry.java

@@ -16,10 +16,7 @@
 /** 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();
   }
@@ -42,13 +39,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.
    */
@@ -57,7 +54,7 @@ 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 HttpClientBuilder.create()
         .addExecInterceptorAfter(
@@ -67,7 +64,7 @@ public HttpClientBuilder createHttpClientBuilder() {
   }
 
   /**
-   * 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-5.2/library/src/main/java/io/opentelemetry/instrumentation/apachehttpclient/v5_2/ApacheHttpClientTelemetryBuilder.java

@@ -16,7 +16,7 @@
 import java.util.function.UnaryOperator;
 import org.apache.hc.core5.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-5.2";
@@ -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());
   }