docs: document connection pooling behavior (#2851)

Add connection pooling section to Client struct docs and update
pool_idle_timeout and pool_max_idle_per_host methods.

Author: vinzmyko

src/async_impl/client.rs

@@ -69,12 +69,19 @@ use tower_http::follow_redirect::FollowRedirect;
 /// are set to what is usually the most commonly desired value. To configure a
 /// `Client`, use `Client::builder()`.
 ///
-/// The `Client` holds a connection pool internally, so it is advised that
+/// The `Client` holds a connection pool internally to improve performance
+/// by reusing connections and avoiding setup overhead, so it is advised that
 /// you create one and **reuse** it.
 ///
 /// You do **not** have to wrap the `Client` in an [`Rc`] or [`Arc`] to **reuse** it,
 /// because it already uses an [`Arc`] internally.
 ///
+/// # Connection Pooling
+///
+/// The connection pool can be configured using [`ClientBuilder`] methods
+/// with the `pool_` prefix, such as [`ClientBuilder::pool_idle_timeout`]
+/// and [`ClientBuilder::pool_max_idle_per_host`].
+///
 /// [`Rc`]: std::rc::Rc
 #[derive(Clone)]
 pub struct Client {
@@ -1406,6 +1413,8 @@ impl ClientBuilder {
     }
 
     /// Sets the maximum idle connection per host allowed in the pool.
+    ///
+    /// Default is `usize::MAX` (no limit).
     pub fn pool_max_idle_per_host(mut self, max: usize) -> ClientBuilder {
         self.config.pool_max_idle_per_host = max;
         self