(arrow-rs-object-store) branch main updated: Improve documentation for http client timeout (#390)

[alamb]

This is an automated email from the ASF dual-hosted git repository.

alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs-object-store.git


The following commit(s) were added to refs/heads/main by this push:
     new 94c25d2  Improve documentation for http client timeout (#390)
94c25d2 is described below

commit 94c25d2dea15d2a7154bb166ae58cbf9452ebcd9
Author: Andrew Lamb <and...@nerdnetworks.org>
AuthorDate: Mon Aug 4 09:07:21 2025 -0400

    Improve documentation for http client timeout (#390)
---
 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 a71814b..5a11b7a 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 0d10e60..2ec1a7c 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;