From 33cd51aabf930ed18444c7304da519b1c4cf278d Mon Sep 17 00:00:00 2001
From: dowwie <dkcdkg@gmail.com>
Date: Thu, 4 Apr 2019 11:40:28 -0400
Subject: [PATCH] added docs for trait Service, trait Transform

---
 actix-service/src/lib.rs       |  3 +++
 actix-service/src/transform.rs | 15 ++++++++++++---
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/actix-service/src/lib.rs b/actix-service/src/lib.rs
index 3b1e6e38..6e0aea4b 100644
--- a/actix-service/src/lib.rs
+++ b/actix-service/src/lib.rs
@@ -53,6 +53,9 @@ pub use self::then::{Then, ThenNewService};
 pub use self::transform::{apply_transform, IntoTransform, Transform};
 
 /// An asynchronous function from `Request` to a `Response`.
+/// The entire request/response lifecycle can be represented as a pipeline of
+/// Services.  The linkage between Services is represented in terms of ownership,
+/// where the preceeding Service owns that which follows it.
 pub trait Service {
     /// Requests handled by the service.
     type Request;
diff --git a/actix-service/src/transform.rs b/actix-service/src/transform.rs
index b511b67a..03b84b5b 100644
--- a/actix-service/src/transform.rs
+++ b/actix-service/src/transform.rs
@@ -6,9 +6,16 @@ use futures::{Async, Future, IntoFuture, Poll};
 use crate::transform_err::{TransformFromErr, TransformMapInitErr};
 use crate::{IntoNewService, NewService, Service};
 
-/// `Transform` service factory.
+/// The `Transform` trait defines the interface of a Service factory.  `Transform`
+/// is often implemented for middleware, defining how to manufacture a
+/// middleware Service.  A Service that is manufactured by the factory takes 
+/// the Service that follows it during execution as a parameter, assuming
+/// ownership of the next Service.  A Service can be a variety of types, such
+/// as (but not limited to) another middleware Service, an extractor Service,
+/// other helper Services, or the request handler endpoint Service.
+///
+/// A Service is created by the factory during server initialization.
 ///
-/// Transform factory creates service that wraps other services.
 /// `Config` is a service factory configuration type.
 pub trait Transform<S> {
     /// Requests handled by the service.
@@ -33,7 +40,9 @@ pub trait Transform<S> {
     /// The future response value.
     type Future: Future<Item = Self::Transform, Error = Self::InitError>;
 
-    /// Create and return a new service value asynchronously.
+    /// Creates and returns a new Service component, asynchronously.  `new_transform`
+    /// is called only once during the lifetime of a server -- as the server
+    /// initializes.
     fn new_transform(&self, service: S) -> Self::Future;
 
     /// Map this service's factory error to a different error,