From 5919b84ea2e6f4d8c578f4a4be930a0545e669f6 Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Tue, 8 Mar 2022 00:26:29 +0000
Subject: [PATCH] document `ConnectRequest` and `ConnectResponse`

closes #2476
---
 awc/src/connect.rs | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/awc/src/connect.rs b/awc/src/connect.rs
index f93014a67..be1ea0fee 100644
--- a/awc/src/connect.rs
+++ b/awc/src/connect.rs
@@ -30,17 +30,35 @@ pub type BoxConnectorService = Rc<
 
 pub type BoxedSocket = Box<dyn ConnectionIo>;
 
+/// Combined HTTP and WebSocket request type received by connection service.
 pub enum ConnectRequest {
+    /// Standard HTTP request.
+    ///
+    /// Contains the request head, body type, and optional pre-resolved socket address.
     Client(RequestHeadType, AnyBody, Option<net::SocketAddr>),
+
+    /// Tunnel used by WebSocket connection requests.
+    ///
+    /// Contains the request head and optional pre-resolved socket address.
     Tunnel(RequestHead, Option<net::SocketAddr>),
 }
 
+/// Combined HTTP response & WebSocket tunnel type returned from connection service.
 pub enum ConnectResponse {
+    /// Standard HTTP response.
     Client(ClientResponse),
+
+    /// Tunnel used for WebSocket communication.
+    ///
+    /// Contains response head and framed HTTP/1.1 codec.
     Tunnel(ResponseHead, Framed<BoxedSocket, ClientCodec>),
 }
 
 impl ConnectResponse {
+    /// Unwraps type into HTTP response.
+    ///
+    /// # Panics
+    /// Panics if enum variant is not `Client`.
     pub fn into_client_response(self) -> ClientResponse {
         match self {
             ConnectResponse::Client(res) => res,
@@ -50,6 +68,10 @@ impl ConnectResponse {
         }
     }
 
+    /// Unwraps type into WebSocket tunnel response.
+    ///
+    /// # Panics
+    /// Panics if enum variant is not `Tunnel`.
     pub fn into_tunnel_response(self) -> (ResponseHead, Framed<BoxedSocket, ClientCodec>) {
         match self {
             ConnectResponse::Tunnel(head, framed) => (head, framed),
@@ -136,30 +158,37 @@ where
             ConnectRequestProj::Connection { fut, req } => {
                 let connection = ready!(fut.poll(cx))?;
                 let req = req.take().unwrap();
+
                 match req {
                     ConnectRequest::Client(head, body, ..) => {
                         // send request
                         let fut = ConnectRequestFuture::Client {
                             fut: connection.send_request(head, body),
                         };
+
                         self.set(fut);
                     }
+
                     ConnectRequest::Tunnel(head, ..) => {
                         // send request
                         let fut = ConnectRequestFuture::Tunnel {
                             fut: connection.open_tunnel(RequestHeadType::from(head)),
                         };
+
                         self.set(fut);
                     }
                 }
+
                 self.poll(cx)
             }
+
             ConnectRequestProj::Client { fut } => {
                 let (head, payload) = ready!(fut.as_mut().poll(cx))?;
                 Poll::Ready(Ok(ConnectResponse::Client(ClientResponse::new(
                     head, payload,
                 ))))
             }
+
             ConnectRequestProj::Tunnel { fut } => {
                 let (head, framed) = ready!(fut.as_mut().poll(cx))?;
                 let framed = framed.into_map_io(|io| Box::new(io) as _);