From 51e9e1500b18a5ce55f90085f1397ef8f6c3d1cf Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Wed, 6 Jan 2021 18:52:06 +0000
Subject: [PATCH] add docs to recent additions

---
 actix-http/src/h1/dispatcher.rs | 16 ++++++++--------
 actix-http/src/h1/service.rs    | 14 +++++++-------
 actix-http/src/h2/dispatcher.rs |  6 +++---
 actix-http/src/h2/service.rs    |  8 ++++----
 actix-http/src/lib.rs           |  9 ++++++---
 actix-http/src/service.rs       | 18 +++++++++---------
 6 files changed, 37 insertions(+), 34 deletions(-)

diff --git a/actix-http/src/h1/dispatcher.rs b/actix-http/src/h1/dispatcher.rs
index 60552d10..a914880c 100644
--- a/actix-http/src/h1/dispatcher.rs
+++ b/actix-http/src/h1/dispatcher.rs
@@ -91,7 +91,7 @@ where
     U: Service<(Request, Framed<T, Codec>), Response = ()>,
     U::Error: fmt::Display,
 {
-    services: Rc<RefCell<HttpFlow<S, X, U>>>,
+    flow: Rc<RefCell<HttpFlow<S, X, U>>>,
     on_connect_data: OnConnectData,
     flags: Flags,
     peer_addr: Option<net::SocketAddr>,
@@ -230,7 +230,7 @@ where
                 io: Some(io),
                 codec,
                 read_buf,
-                services,
+                flow: services,
                 on_connect_data,
                 flags,
                 peer_addr,
@@ -384,7 +384,7 @@ where
                     Poll::Ready(Ok(req)) => {
                         self.as_mut().send_continue();
                         this = self.as_mut().project();
-                        let fut = this.services.borrow_mut().service.call(req);
+                        let fut = this.flow.borrow_mut().service.call(req);
                         this.state.set(State::ServiceCall(fut));
                         continue;
                     }
@@ -474,12 +474,12 @@ where
         if req.head().expect() {
             // set dispatcher state so the future is pinned.
             let mut this = self.as_mut().project();
-            let task = this.services.borrow_mut().expect.call(req);
+            let task = this.flow.borrow_mut().expect.call(req);
             this.state.set(State::ExpectCall(task));
         } else {
             // the same as above.
             let mut this = self.as_mut().project();
-            let task = this.services.borrow_mut().service.call(req);
+            let task = this.flow.borrow_mut().service.call(req);
             this.state.set(State::ServiceCall(task));
         };
 
@@ -492,7 +492,7 @@ where
                         Poll::Ready(Ok(req)) => {
                             self.as_mut().send_continue();
                             let mut this = self.as_mut().project();
-                            let task = this.services.borrow_mut().service.call(req);
+                            let task = this.flow.borrow_mut().service.call(req);
                             this.state.set(State::ServiceCall(task));
                             continue;
                         }
@@ -564,7 +564,7 @@ where
                             this.on_connect_data.merge_into(&mut req);
 
                             if pl == MessageType::Stream
-                                && this.services.borrow().upgrade.is_some()
+                                && this.flow.borrow().upgrade.is_some()
                             {
                                 this.messages.push_back(DispatcherMessage::Upgrade(req));
                                 break;
@@ -830,7 +830,7 @@ where
                             parts.write_buf = mem::take(inner_p.write_buf);
                             let framed = Framed::from_parts(parts);
                             let upgrade = inner_p
-                                .services
+                                .flow
                                 .borrow_mut()
                                 .upgrade
                                 .take()
diff --git a/actix-http/src/h1/service.rs b/actix-http/src/h1/service.rs
index 19272c13..067c8b64 100644
--- a/actix-http/src/h1/service.rs
+++ b/actix-http/src/h1/service.rs
@@ -367,7 +367,7 @@ where
     X: Service<Request>,
     U: Service<(Request, Framed<T, Codec>)>,
 {
-    services: Rc<RefCell<HttpFlow<S, X, U>>>,
+    flow: Rc<RefCell<HttpFlow<S, X, U>>>,
     on_connect_ext: Option<Rc<ConnectCallback<T>>>,
     cfg: ServiceConfig,
     _phantom: PhantomData<B>,
@@ -392,7 +392,7 @@ where
         on_connect_ext: Option<Rc<ConnectCallback<T>>>,
     ) -> H1ServiceHandler<T, S, B, X, U> {
         H1ServiceHandler {
-            services: HttpFlow::new(service, expect, upgrade),
+            flow: HttpFlow::new(service, expect, upgrade),
             cfg,
             on_connect_ext,
             _phantom: PhantomData,
@@ -418,8 +418,8 @@ where
     type Future = Dispatcher<T, S, B, X, U>;
 
     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
-        let mut services = self.services.borrow_mut();
-        let ready = services
+        let mut flow = self.flow.borrow_mut();
+        let ready = flow
             .expect
             .poll_ready(cx)
             .map_err(|e| {
@@ -429,7 +429,7 @@ where
             })?
             .is_ready();
 
-        let ready = services
+        let ready = flow
             .service
             .poll_ready(cx)
             .map_err(|e| {
@@ -440,7 +440,7 @@ where
             .is_ready()
             && ready;
 
-        let ready = if let Some(ref mut upg) = services.upgrade {
+        let ready = if let Some(ref mut upg) = flow.upgrade {
             upg.poll_ready(cx)
                 .map_err(|e| {
                     let e = e.into();
@@ -467,7 +467,7 @@ where
         Dispatcher::new(
             io,
             self.cfg.clone(),
-            self.services.clone(),
+            self.flow.clone(),
             on_connect_data,
             addr,
         )
diff --git a/actix-http/src/h2/dispatcher.rs b/actix-http/src/h2/dispatcher.rs
index 62103586..959c34f1 100644
--- a/actix-http/src/h2/dispatcher.rs
+++ b/actix-http/src/h2/dispatcher.rs
@@ -37,7 +37,7 @@ where
     S: Service<Request>,
     B: MessageBody,
 {
-    services: Rc<RefCell<HttpFlow<S, X, U>>>,
+    flow: Rc<RefCell<HttpFlow<S, X, U>>>,
     connection: Connection<T, Bytes>,
     on_connect_data: OnConnectData,
     config: ServiceConfig,
@@ -80,7 +80,7 @@ where
         };
 
         Dispatcher {
-            services,
+            flow: services,
             config,
             peer_addr,
             connection,
@@ -138,7 +138,7 @@ where
 
                     let svc = ServiceResponse::<S::Future, S::Response, S::Error, B> {
                         state: ServiceResponseState::ServiceCall(
-                            this.services.borrow_mut().service.call(req),
+                            this.flow.borrow_mut().service.call(req),
                             Some(res),
                         ),
                         config: this.config.clone(),
diff --git a/actix-http/src/h2/service.rs b/actix-http/src/h2/service.rs
index f94aae79..95ff3de2 100644
--- a/actix-http/src/h2/service.rs
+++ b/actix-http/src/h2/service.rs
@@ -249,7 +249,7 @@ pub struct H2ServiceHandler<T, S, B>
 where
     S: Service<Request>,
 {
-    services: Rc<RefCell<HttpFlow<S, (), ()>>>,
+    flow: Rc<RefCell<HttpFlow<S, (), ()>>>,
     cfg: ServiceConfig,
     on_connect_ext: Option<Rc<ConnectCallback<T>>>,
     _phantom: PhantomData<B>,
@@ -269,7 +269,7 @@ where
         service: S,
     ) -> H2ServiceHandler<T, S, B> {
         H2ServiceHandler {
-            services: HttpFlow::new(service, (), None),
+            flow: HttpFlow::new(service, (), None),
             cfg,
             on_connect_ext,
             _phantom: PhantomData,
@@ -291,7 +291,7 @@ where
     type Future = H2ServiceHandlerResponse<T, S, B>;
 
     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
-        self.services
+        self.flow
             .borrow_mut()
             .service
             .poll_ready(cx)
@@ -308,7 +308,7 @@ where
 
         H2ServiceHandlerResponse {
             state: State::Handshake(
-                Some(self.services.clone()),
+                Some(self.flow.clone()),
                 Some(self.cfg.clone()),
                 addr,
                 on_connect_data,
diff --git a/actix-http/src/lib.rs b/actix-http/src/lib.rs
index 0c58df2e..3879bae8 100644
--- a/actix-http/src/lib.rs
+++ b/actix-http/src/lib.rs
@@ -72,7 +72,7 @@ pub mod http {
     pub use crate::message::ConnectionType;
 }
 
-/// Http protocol
+/// HTTP protocol
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 pub enum Protocol {
     Http1,
@@ -82,6 +82,9 @@ pub enum Protocol {
 type ConnectCallback<IO> = dyn Fn(&IO, &mut Extensions);
 
 /// Container for data that extract with ConnectCallback.
+///
+/// # Implementation Details
+/// Uses Option to reduce necessary allocations when merging with request extensions.
 pub(crate) struct OnConnectData(Option<Extensions>);
 
 impl Default for OnConnectData {
@@ -91,7 +94,7 @@ impl Default for OnConnectData {
 }
 
 impl OnConnectData {
-    // construct self from io.
+    /// Construct by calling the on-connect callback with the underlying transport I/O.
     pub(crate) fn from_io<T>(
         io: &T,
         on_connect_ext: Option<&ConnectCallback<T>>,
@@ -105,7 +108,7 @@ impl OnConnectData {
         Self(ext)
     }
 
-    // merge self to given request's head extension.
+    /// Merge self into given request's extensions.
     #[inline]
     pub(crate) fn merge_into(&mut self, req: &mut Request) {
         if let Some(ref mut ext) = self.0 {
diff --git a/actix-http/src/service.rs b/actix-http/src/service.rs
index eb16a6e7..e137ab6f 100644
--- a/actix-http/src/service.rs
+++ b/actix-http/src/service.rs
@@ -441,13 +441,13 @@ where
     X: Service<Request>,
     U: Service<(Request, Framed<T, h1::Codec>)>,
 {
-    services: Rc<RefCell<HttpFlow<S, X, U>>>,
+    flow: Rc<RefCell<HttpFlow<S, X, U>>>,
     cfg: ServiceConfig,
     on_connect_ext: Option<Rc<ConnectCallback<T>>>,
     _phantom: PhantomData<B>,
 }
 
-// a collection of service for http.
+/// A collection of services that describe an HTTP request flow.
 pub(super) struct HttpFlow<S, X, U> {
     pub(super) service: S,
     pub(super) expect: X,
@@ -486,7 +486,7 @@ where
         HttpServiceHandler {
             cfg,
             on_connect_ext,
-            services: HttpFlow::new(service, expect, upgrade),
+            flow: HttpFlow::new(service, expect, upgrade),
             _phantom: PhantomData,
         }
     }
@@ -511,8 +511,8 @@ where
     type Future = HttpServiceHandlerResponse<T, S, B, X, U>;
 
     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
-        let mut services = self.services.borrow_mut();
-        let ready = services
+        let mut flow = self.flow.borrow_mut();
+        let ready = flow
             .expect
             .poll_ready(cx)
             .map_err(|e| {
@@ -522,7 +522,7 @@ where
             })?
             .is_ready();
 
-        let ready = services
+        let ready = flow
             .service
             .poll_ready(cx)
             .map_err(|e| {
@@ -533,7 +533,7 @@ where
             .is_ready()
             && ready;
 
-        let ready = if let Some(ref mut upg) = services.upgrade {
+        let ready = if let Some(ref mut upg) = flow.upgrade {
             upg.poll_ready(cx)
                 .map_err(|e| {
                     let e = e.into();
@@ -565,7 +565,7 @@ where
                 state: State::H2Handshake(Some((
                     server::handshake(io),
                     self.cfg.clone(),
-                    self.services.clone(),
+                    self.flow.clone(),
                     on_connect_data,
                     peer_addr,
                 ))),
@@ -575,7 +575,7 @@ where
                 state: State::H1(h1::Dispatcher::new(
                     io,
                     self.cfg.clone(),
-                    self.services.clone(),
+                    self.flow.clone(),
                     on_connect_data,
                     peer_addr,
                 )),