docs(client): add link and cleanup example for hyper::client::conn (#2533)

src/client/conn.rs

@@ -13,17 +13,16 @@
 //! ```no_run
 //! # #[cfg(all(feature = "client", feature = "http1", feature = "runtime"))]
 //! # mod rt {
+//! use tower::ServiceExt;
 //! use http::{Request, StatusCode};
-//! use hyper::{client::conn::Builder, Body};
+//! use hyper::{client::conn, Body};
 //! use tokio::net::TcpStream;
 //!
 //! #[tokio::main]
 //! async fn main() -> Result<(), Box<dyn std::error::Error>> {
 //!     let target_stream = TcpStream::connect("example.com:80").await?;
 //!
-//!     let (mut request_sender, connection) = Builder::new()
+//!     let (mut request_sender, connection) = conn::handshake(target_stream).await?;
-//!         .handshake::<TcpStream, Body>(target_stream)
-//!         .await?;
 //!
 //!     // spawn a task to poll the connection and drive the HTTP state
 //!     tokio::spawn(async move {
@@ -37,7 +36,16 @@
 //!         .header("Host", "example.com")
 //!         .method("GET")
 //!         .body(Body::from(""))?;
+//!     let response = request_sender.send_request(request).await?;
+//!     assert!(response.status() == StatusCode::OK);
 //!
+//!     // To send via the same connection again, it may not work as it may not be ready,
+//!     // so we have to wait until the request_sender becomes ready.
+//!     request_sender.ready().await?;
+//!     let request = Request::builder()
+//!         .header("Host", "example.com")
+//!         .method("GET")
+//!         .body(Body::from(""))?;
 //!     let response = request_sender.send_request(request).await?;
 //!     assert!(response.status() == StatusCode::OK);
 //!     Ok(())
@@ -109,6 +117,7 @@ pin_project! {
 /// Returns a handshake future over some IO.
 ///
 /// This is a shortcut for `Builder::new().handshake(io)`.
+/// See [`client::conn`](crate::client::conn) for more.
 pub async fn handshake<T>(
     io: T,
 ) -> crate::Result<(SendRequest<crate::Body>, Connection<T, crate::Body>)>
@@ -803,6 +812,10 @@ impl Builder {
     }
 
     /// Constructs a connection with the configured options and IO.
+    /// See [`client::conn`](crate::client::conn) for more.
+    ///
+    /// Note, if [`Connection`] is not `await`-ed, [`SendRequest`] will
+    /// do nothing.
     pub fn handshake<T, B>(
         &self,
         io: T,