Add javadoc

Author: arturobernalg

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/nio/support/H2OverH2TunnelExchangeHandler.java

@@ -60,7 +60,10 @@
 import org.apache.hc.core5.util.Timeout;
 
 /**
- * Exchange handler that establishes CONNECT and then exposes the tunnel stream as a ProtocolIOSession.
+ * Exchange handler that establishes an HTTP/2 CONNECT tunnel and exposes
+ * the resulting data stream as a {@link ProtocolIOSession}.
+ *
+ * @since 5.5
  */
 final class H2OverH2TunnelExchangeHandler implements AsyncClientExchangeHandler {
 

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/nio/support/H2OverH2TunnelSupport.java

@@ -26,6 +26,8 @@
  */
 package org.apache.hc.core5.http2.nio.support;
 
+import org.apache.hc.core5.annotation.Contract;
+import org.apache.hc.core5.annotation.ThreadingBehavior;
 import org.apache.hc.core5.concurrent.FutureCallback;
 import org.apache.hc.core5.http.HttpRequestInterceptor;
 import org.apache.hc.core5.http.nio.command.RequestExecutionCommand;
@@ -41,20 +43,20 @@
 import org.apache.hc.core5.util.Timeout;
 
 /**
- * Helper for establishing HTTP/2 tunnels through HTTP/2 proxies using the CONNECT method.
- *
+ * Helper for establishing HTTP/2 CONNECT tunnels through HTTP/2 proxies.
  * <p>
- * Multiplexing-safe: tunnel close/reset affects only the CONNECT stream (via StreamControl),
- * never the underlying physical HTTP/2 connection.
+ * Multiplexing-safe: tunnel close affects only the CONNECT stream,
+ * not the underlying physical HTTP/2 connection.
  * </p>
- *
  * <p>
- * Note: This helper does not implement proxy authentication challenge handling (407 retries).
- * That belongs in client implementations that maintain authentication state.
+ * This helper does not handle proxy authentication (407 retries).
+ * That responsibility belongs to client implementations that maintain
+ * authentication state.
  * </p>
  *
  * @since 5.5
  */
+@Contract(threading = ThreadingBehavior.STATELESS)
 public final class H2OverH2TunnelSupport {
 
     private H2OverH2TunnelSupport() {

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/nio/support/H2TunnelProtocolIOSession.java

@@ -57,7 +57,13 @@
 import org.apache.hc.core5.util.Timeout;
 
 /**
- * ProtocolIOSession backed by a single HTTP/2 CONNECT stream.
+ * {@link ProtocolIOSession} backed by a single HTTP/2 CONNECT stream.
+ * <p>
+ * Supports optional TLS upgrade via {@link #startTls} for establishing
+ * secure tunnels to the target endpoint.
+ * </p>
+ *
+ * @since 5.5
  */
 final class H2TunnelProtocolIOSession implements ProtocolIOSession {
 

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/nio/support/H2TunnelRawIOSession.java

@@ -47,8 +47,14 @@
 import org.apache.hc.core5.util.Timeout;
 
 /**
- * Raw tunnel IOSession implementation: bounded buffering + capacity updates + stream-scoped close/cancel.
+ * Raw tunnel {@link IOSession} implementation with bounded buffering,
+ * capacity flow control and stream-scoped close semantics.
  * <p>
+ * Closing this session cancels only the CONNECT stream,
+ * not the underlying physical HTTP/2 connection.
+ * </p>
+ *
+ * @since 5.5
  */
 final class H2TunnelRawIOSession implements IOSession {