From 26123d3057d87da9aa893d86da9cb30a9b35bb0d Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Fri, 30 May 2025 09:52:30 -0400
Subject: [PATCH] Improve documentation for http client timeout

---
 src/client/mod.rs   | 33 ++++++++++++++++++++++++++++-----
 src/client/retry.rs |  2 +-
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/src/client/mod.rs b/src/client/mod.rs
index a71814b9..5a11b7ad 100644
--- a/src/client/mod.rs
+++ b/src/client/mod.rs
@@ -498,12 +498,21 @@ impl ClientOptions {
         self
     }
 
-    /// Set a request timeout
+    /// Set timeout for the overall request
     ///
-    /// The timeout is applied from when the request starts connecting until the
-    /// response body has finished
+    /// The timeout starts from when the request starts connecting until the
+    /// response body has finished. If the request does not complete within the
+    /// timeout, the client returns a timeout error.
+    ///
+    /// Timeout errors are retried, subject to the [`RetryConfig`]
     ///
     /// Default is 30 seconds
+    ///
+    /// # See Also
+    /// * [`Self::with_timeout_disabled`] to disable the timeout
+    /// * [`Self::with_connect_timeout`] to set a timeout for the connect phase
+    ///
+    /// [`RetryConfig`]: crate::RetryConfig
     pub fn with_timeout(mut self, timeout: Duration) -> Self {
         self.timeout = Some(ConfigValue::Parsed(timeout));
         self
@@ -511,7 +520,8 @@ impl ClientOptions {
 
     /// Disables the request timeout
     ///
-    /// See [`Self::with_timeout`]
+    /// # See Also
+    /// * [`Self::with_timeout`]
     pub fn with_timeout_disabled(mut self) -> Self {
         self.timeout = None;
         self
@@ -519,7 +529,19 @@ impl ClientOptions {
 
     /// Set a timeout for only the connect phase of a Client
     ///
+    /// This is the time allowed for the client to establish a connection
+    /// and if the connection is not established within this time,
+    /// the client returns a timeout error.
+    ///
+    /// Timeout errors are retried, subject to the [`RetryConfig`]
+    ///
     /// Default is 5 seconds
+    ///
+    /// # See Also
+    /// * [`Self::with_timeout`] to set a timeout for the overall request
+    /// * [`Self::with_connect_timeout_disabled`] to disable the connect timeout
+    ///
+    /// [`RetryConfig`]: crate::RetryConfig
     pub fn with_connect_timeout(mut self, timeout: Duration) -> Self {
         self.connect_timeout = Some(ConfigValue::Parsed(timeout));
         self
@@ -527,7 +549,8 @@ impl ClientOptions {
 
     /// Disables the connection timeout
     ///
-    /// See [`Self::with_connect_timeout`]
+    /// # See Also
+    /// * [`Self::with_connect_timeout`]
     pub fn with_connect_timeout_disabled(mut self) -> Self {
         self.connect_timeout = None;
         self
diff --git a/src/client/retry.rs b/src/client/retry.rs
index fb098137..cf020b39 100644
--- a/src/client/retry.rs
+++ b/src/client/retry.rs
@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! A shared HTTP client implementation incorporating retries
+//! [`RetryConfig`] connection retry policy
 
 use crate::client::backoff::{Backoff, BackoffConfig};
 use crate::client::builder::HttpRequestBuilder;