diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java
index b372d461aa..478ee86a1c 100644
--- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java
+++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java
@@ -149,7 +149,15 @@ public Builder setSocketTimeout(final int soTimeout, final TimeUnit timeUnit) {
         }
 
         /**
-         * Determines the default socket timeout value for I/O operations.
+         * Determines the default socket timeout value for I/O operations on
+         * connections created by this configuration.
+         * A timeout value of zero is interpreted as an infinite timeout.
+         * <p>
+         * This value acts as a baseline configured by the I/O layer. It can be
+         * overridden by settings applied at the connection layer, and in turn may be
+         * overridden by parameters applied at the protocol layer for the duration of
+         * a message execution.
+         * </p>
          * <p>
          * Default: {@code null} (undefined)
          * </p>
diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java
index f13d940fe3..4dbf1cc8e6 100644
--- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java
+++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java
@@ -549,6 +549,13 @@ public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeU
          * configured appropriately.
          * </p>
          * <p>
+         * This parameter may override a socket timeout configured at the connection
+         * or I/O layers for the duration of a message execution. It is not a hard
+         * deadline; its effective duration can be exceeded, for example, by automatic
+         * request re-execution policies. Ensure such policies are configured
+         * appropriately.
+         * </p>
+         * <p>
          * Default: {@code null}
          * </p>
          *