javadoc fixes

Author: ok2c

httpclient5-observation/src/main/java/org/apache/hc/client5/http/observation/HttpClientObservationSupport.java

@@ -57,7 +57,7 @@
  *       connection pool gauges.</li>
  * </ul>
  *
- * <h3>Optional dependencies</h3>
+ * <p><strong>Optional dependencies</strong></p>
  * <p>
  * Micrometer and OpenTelemetry are <em>optional</em> dependencies. Use the
  * overloads that accept explicit registries (recommended) or the convenience
@@ -66,7 +66,7 @@
  * will be required.
  * </p>
  *
- * <h3>Typical usage (classic client)</h3>
+ * <p><strong>Typical usage (classic client)</strong></p>
  * <pre>{@code
  * ObservationRegistry obs = ObservationRegistry.create();
  * MeterRegistry meters = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
@@ -80,7 +80,7 @@
  * CloseableHttpClient client = b.build();
  * }</pre>
  *
- * <h3>What gets installed</h3>
+ * <p><strong>What gets installed</strong></p>
  * <ul>
  *   <li>An <em>observation</em> interceptor (if {@code obsReg} is non-null)
  *       that surrounds each execution with a start/stop span.</li>

httpclient5-observation/src/main/java/org/apache/hc/client5/http/observation/binder/ConnPoolMeters.java

@@ -46,7 +46,7 @@
  * </ul>
  * The {@code prefix} and any common tags come from {@link MetricConfig}.
  *
- * <h3>Usage</h3>
+ * <p><strong>Usage</strong></p>
  * <pre>{@code
  * MeterRegistry meters = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
  * MetricConfig mc = MetricConfig.builder().prefix("http_client").build();

httpclient5-observation/src/main/java/org/apache/hc/client5/http/observation/binder/ConnPoolMetersAsync.java

@@ -46,7 +46,7 @@
  * </ul>
  * The {@code prefix} and any common tags come from {@link MetricConfig}.
  *
- * <h3>Usage</h3>
+ * <p><strong>Usage</strong></p>
  * <pre>{@code
  * MeterRegistry meters = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
  * MetricConfig mc = MetricConfig.builder().prefix("http_client").build();

httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/DeflatingBrotliEntityProducer.java

@@ -50,11 +50,11 @@
  * has been fully drained.
  * </p>
  *
- * <h4>Content metadata</h4>
+ * <p><strong>Content metadata</strong></p>
  * Returns {@code Content-Encoding: br}, {@code Content-Length: -1} and {@code chunked=true}.
  * Repeatability matches the upstream producer.
  *
- * <h4>Implementation notes</h4>
+ * <p><strong>Implementation notes</strong></p>
  * Uses Brotli4j’s {@code EncoderJNI.Wrapper}. JNI-owned output buffers are written directly
  * when possible; if the channel applies back-pressure, the unwritten tail is copied into
  * small pooled direct {@link java.nio.ByteBuffer}s to reduce allocation churn. Native
@@ -64,15 +64,6 @@
  * called once at startup; this class also invokes it in a static initializer as a safeguard.
  * </p>
  *
- * <h4>Usage</h4>
- * <pre>{@code
- * AsyncEntityProducer plain = new StringAsyncEntityProducer("hello", ContentType.TEXT_PLAIN);
- * AsyncEntityProducer br = new DeflatingBrotliEntityProducer(plain); // defaults q=5, lgwin=22
- * client.execute(new BasicRequestProducer(post, br),
- *                new BasicResponseConsumer<>(new StringAsyncEntityConsumer()),
- *                null);
- * }</pre>
- *
  * @see org.apache.hc.core5.http.nio.AsyncEntityProducer
  * @see org.apache.hc.core5.http.nio.DataStreamChannel
  * @see com.aayushatharva.brotli4j.encoder.EncoderJNI

httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/DeflatingZstdEntityProducer.java

@@ -59,24 +59,9 @@
  *   <li>{@link #isChunked()} returns {@code true} (requests are typically sent chunked).</li>
  * </ul>
  *
- * <h3>Usage</h3>
- * <pre>{@code
- * AsyncEntityProducer plain = new StringAsyncEntityProducer("payload", ContentType.TEXT_PLAIN);
- * AsyncEntityProducer zstd  = new DeflatingZstdEntityProducer(plain);
- *
- * SimpleHttpRequest req = SimpleRequestBuilder.post("http://localhost/echo")
- *     .setHeader(HttpHeaders.CONTENT_ENCODING, "zstd") // inform the server
- *     .build();
- *
- * client.execute(
- *     new BasicRequestProducer(req, zstd),
- *     new BasicResponseConsumer<>(new StringAsyncEntityConsumer()),
- *     null);
- * }</pre>
- *
- * <h3>Behavior</h3>
+ * <p><strong>Behavior</strong></p>
  * <ul>
- *   <li><b>Streaming & back-pressure:</b> compressed output is staged in direct
+ *   <li><b>Streaming &amp; back-pressure:</b> compressed output is staged in direct
  *       {@link java.nio.ByteBuffer}s and written only when the channel accepts bytes.
  *       When {@code DataStreamChannel.write(...)} returns {@code 0}, the producer pauses and
  *       requests another output turn.</li>
@@ -88,16 +73,16 @@
  *   <li><b>Resources:</b> invoke {@link #releaseResources()} to free native compressor resources.</li>
  * </ul>
  *
- * <h3>Constructors</h3>
+ * <p><strong>Constructors</strong></p>
  * <ul>
  *   <li>{@code DeflatingZstdEntityProducer(delegate)} – uses a default compression level.</li>
  *   <li>{@code DeflatingZstdEntityProducer(delegate, level)} – explicitly sets the zstd level.</li>
  * </ul>
  *
- * <h3>Thread-safety</h3>
+ * <p><strong>Thread-safety</strong></p>
  * <p>Not thread-safe; one instance per message exchange.</p>
  *
- * <h3>Runtime dependency</h3>
+ * <p><strong>Runtime dependency</strong></p>
  * <p>Requires {@code com.github.luben:zstd-jni} on the classpath.</p>
  *
  * @see org.apache.hc.client5.http.async.methods.InflatingZstdDataConsumer

httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/InflatingBrotliDataConsumer.java

@@ -48,7 +48,7 @@
  * downstream consumer (which may retain them).
  * </p>
  *
- * <h4>Implementation notes</h4>
+ * <p><strong>Implementation notes</strong></p>
  * Uses Brotli4j’s {@code DecoderJNI.Wrapper}. Native resources are released in
  * {@link #releaseResources()}. Throws an {@link java.io.IOException} if the stream is
  * truncated or corrupted.
@@ -57,13 +57,6 @@
  * called once at startup; this class also invokes it in a static initializer as a safeguard.
  * </p>
  *
- * <h4>Usage</h4>
- * <pre>{@code
- * AsyncDataConsumer textConsumer = new StringAsyncEntityConsumer();
- * AsyncDataConsumer brInflating  = new InflatingBrotliDataConsumer(textConsumer);
- * client.execute(producer, new BasicResponseConsumer<>(brInflating), null);
- * }</pre>
- *
  * @see org.apache.hc.core5.http.nio.AsyncDataConsumer
  * @see org.apache.hc.core5.http.nio.CapacityChannel
  * @see com.aayushatharva.brotli4j.decoder.DecoderJNI

httpclient5/src/main/java/org/apache/hc/client5/http/async/methods/InflatingZstdDataConsumer.java

@@ -47,7 +47,7 @@
  * normally do not instantiate it directly—enable content compression (default) and let
  * {@code ContentCompressionAsyncExec} wire it automatically.</p>
  *
- * <h3>Behavior</h3>
+ * <p><strong>Behavior</strong></p>
  * <ul>
  *   <li>Streams decompression as data arrives; does not require the full message in memory.</li>
  *   <li>Updates the downstream with plain bytes; the client removes the original
@@ -56,20 +56,6 @@
  *   <li>{@link #releaseResources()} must be called to free native resources.</li>
  * </ul>
  *
- * <h3>Typical wiring (automatic)</h3>
- * <pre>{@code
- * // Enabled by default; when the response has Content-Encoding: zstd
- * // the execution chain wraps the application consumer:
- * client = HttpAsyncClients.createDefault();
- * }</pre>
- *
- * <h3>Direct use (advanced)</h3>
- * <pre>{@code
- * AsyncDataConsumer app = ...; // where you want plain bytes
- * AsyncDataConsumer zstd = new InflatingZstdDataConsumer(app);
- * // feed zstd.consume(ByteBuffer) with compressed bytes
- * }</pre>
- *
  * @since 5.6
  */
 

httpclient5/src/main/java/org/apache/hc/client5/http/entity/GZIPInputStreamFactory.java

@@ -37,9 +37,9 @@
 /**
  * {@link InputStreamFactory} for handling GZIPContent Coded responses.
  * @deprecated – the public extension point has moved to
- *             {@link org.apache.hc.client5.http.entity.compress.Decoder}.
+ *             {@link org.apache.hc.client5.http.entity.compress.DecompressingEntity}.
  *             For built-in gzip support use
- *             {@code ContentCodecRegistry.decoder(ContentCoding.GZIP)} or
+ *             {@link org.apache.hc.client5.http.entity.compress.ContentCodecRegistry} or
  *             wrap a stream directly with
  * @since 5.0
  */

httpclient5/src/main/java/org/apache/hc/client5/http/protocol/RequestValidateTrace.java

@@ -43,34 +43,7 @@
 import org.apache.hc.core5.util.Args;
 
 /**
- * <h1>RequestTraceInterceptor</h1>
- *
- * <p>This class serves as an interceptor for HTTP TRACE requests, ensuring they adhere to specific security and protocol guidelines.</p>
- *
- * <p><strong>Responsibilities:</strong></p>
- * <ul>
- *   <li>Validates TRACE requests by checking for sensitive headers such as {@code Authorization} and {@code Cookie}.</li>
- *   <li>Ensures that TRACE requests do not contain a request body, throwing a {@link ProtocolException} if a body is present.</li>
- * </ul>
- *
- * <p><strong>Thread Safety:</strong> This class is stateless and therefore thread-safe, as indicated by its {@code ThreadingBehavior.STATELESS} annotation.</p>
- *
- * <p><strong>Interceptor Behavior:</strong></p>
- * <ul>
- *   <li>If the HTTP method is TRACE, the interceptor throws a {@link ProtocolException} if any {@code Authorization} or {@code Cookie} headers are present to prevent sensitive data leakage.</li>
- *   <li>If a TRACE request contains a body, a {@link ProtocolException} is thrown.</li>
- * </ul>
- *
- * @version 5.4
- * @see HttpRequestInterceptor
- * @see HttpException
- * @see IOException
- * @see ProtocolException
- * @see Method#TRACE
- * @see HttpHeaders#AUTHORIZATION
- * @see HttpHeaders#COOKIE
- *//**
- * <h1>RequestTraceInterceptor</h1>
+ * <strong>RequestTraceInterceptor</strong>
  *
  * <p>This class serves as an interceptor for HTTP TRACE requests, ensuring they adhere to specific security and protocol guidelines.</p>
  *

httpclient5/src/test/java/org/apache/hc/client5/http/examples/AsyncClientServerZstdExample.java

@@ -79,14 +79,14 @@
  * deterministic zstd payloads for demonstration and tests; the client side does not depend
  * on it and relies solely on HttpComponents.</p>
  *
- * <h3>What this demonstrates</h3>
+ * <p><strong>What this demonstrates</strong></p>
  * <ul>
  *   <li>How to validate transparent zstd decoding without hitting external endpoints.</li>
  *   <li>That the async client strips {@code Content-Encoding} on success.</li>
  *   <li>No special client wiring is required beyond enabling content compression (on by default).</li>
  * </ul>
  *
- * <h3>Expected output</h3>
+ * <p><strong>Expected output</strong></p>
  * <pre>{@code
  * status=200
  * content-encoding=(stripped by client)