Document OffLockDisposalCallback behaviour (#766)

Add class-level Javadoc explaining deferred graceful disposal semantics.

Author: arturobernalg

httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/OffLockDisposalCallback.java

@@ -34,6 +34,17 @@
 import org.apache.hc.core5.io.ModalCloseable;
 import org.apache.hc.core5.pool.DisposalCallback;
 
+/**
+ * {@link DisposalCallback} that defers graceful connection disposal so it can
+ * be executed outside core pool synchronization.
+ * <p>
+ * Calls with {@link CloseMode#IMMEDIATE} are delegated directly to the
+ * underlying callback on the caller thread. All other modes are queued and
+ * later disposed with {@link CloseMode#GRACEFUL} when {@link #drain()} is
+ * invoked by {@link PoolingHttpClientConnectionManager}.
+ *
+ * @since 5.6
+ */
 @Internal
 final class OffLockDisposalCallback<T extends ModalCloseable> implements DisposalCallback<T> {
 

httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/PoolingHttpClientConnectionManagerBuilder.java

@@ -46,6 +46,7 @@
 import org.apache.hc.core5.http.config.RegistryBuilder;
 import org.apache.hc.core5.http.io.HttpConnectionFactory;
 import org.apache.hc.core5.http.io.SocketConfig;
+import org.apache.hc.core5.io.CloseMode;
 import org.apache.hc.core5.pool.PoolConcurrencyPolicy;
 import org.apache.hc.core5.pool.PoolReusePolicy;
 import org.apache.hc.core5.util.TimeValue;
@@ -308,7 +309,17 @@ public final PoolingHttpClientConnectionManagerBuilder useSystemProperties() {
     }
 
     /**
-     * Enable/disable off-lock disposal.
+     * Enable or disable off-lock connection disposal for blocking I/O pools.
+     * <p>
+     * When enabled, graceful connection closes are deferred and performed
+     * outside the core pool synchronization in
+     * {@link PoolingHttpClientConnectionManager}. This reduces the time spent
+     * holding internal locks at the cost of slightly more complex disposal
+     * logic. Immediate closes  {@link CloseMode#IMMEDIATE} are still executed
+     * on the caller thread.
+     *
+     * @param enabled {@code true} to enable off-lock disposal, {@code false} to disable
+     * @return this builder
      * @since 5.6
      */
     @Experimental
@@ -317,6 +328,7 @@ public final PoolingHttpClientConnectionManagerBuilder setOffLockDisposalEnabled
         return this;
     }
 
+
     @Internal
     protected HttpClientConnectionOperator createConnectionOperator(
             final SchemePortResolver schemePortResolver,