Merge pull request #750 from Dowwie/master

added docs for wrap and wrap_fn

src/app.rs

@@ -112,7 +112,29 @@ where
         self
     }
 
-    /// Register a middleware.
+    /// Registers middleware, in the form of a middleware component (type), 
+    /// that runs during inbound and/or outbound processing in the request 
+    /// lifecycle (request -> response), modifying request/response as 
+    /// necessary, across all requests managed by the *Application*.
+    ///
+    /// Use middleware when you need to read or modify *every* request or response in some way.
+    ///
+    /// ```rust
+    /// use actix_service::Service;
+    /// # use futures::Future;
+    /// use actix_web::{middleware, web, App};
+    /// use actix_web::http::{header::CONTENT_TYPE, HeaderValue};
+    ///
+    /// fn index() -> &'static str {
+    ///     "Welcome!"
+    /// }
+    ///
+    /// fn main() {
+    ///     let app = App::new()
+    ///         .wrap(middleware::Logger::default())
+    ///         .route("/index.html", web::get().to(index));
+    /// }
+    /// ```
     pub fn wrap<M, B, F>(
         self,
         mw: F,
@@ -152,7 +174,12 @@ where
         }
     }
 
-    /// Register a middleware function.
+    /// Registers middleware, in the form of a closure, that runs during inbound
+    /// and/or outbound processing in the request lifecycle (request -> response),
+    /// modifying request/response as necessary, across all requests managed by
+    /// the *Application*.
+    ///
+    /// Use middleware when you need to read or modify *every* request or response in some way.
     ///
     /// ```rust
     /// use actix_service::Service;
@@ -400,7 +427,13 @@ where
         self
     }
 
-    /// Register a middleware.
+    /// Registers middleware, in the form of a middleware component (type), 
+    /// that runs during inbound and/or outbound processing in the request 
+    /// lifecycle (request -> response), modifying request/response as 
+    /// necessary, across all requests managed by the *Route*.
+    ///
+    /// Use middleware when you need to read or modify *every* request or response in some way.
+    ///
     pub fn wrap<M, B1, F>(
         self,
         mw: F,
@@ -440,7 +473,13 @@ where
         }
     }
 
-    /// Register a middleware function.
+    /// Registers middleware, in the form of a closure, that runs during inbound
+    /// and/or outbound processing in the request lifecycle (request -> response),
+    /// modifying request/response as necessary, across all requests managed by
+    /// the *Route*.
+    ///
+    /// Use middleware when you need to read or modify *every* request or response in some way.
+    ///
     pub fn wrap_fn<B1, F, R>(
         self,
         mw: F,

src/scope.rs

@@ -200,11 +200,15 @@ where
         self
     }
 
-    /// Register a scope level middleware.
+    /// Registers middleware, in the form of a middleware component (type), 
+    /// that runs during inbound processing in the request 
+    /// lifecycle (request -> response), modifying request as 
+    /// necessary, across all requests managed by the *Scope*.  Scope-level
+    /// middleware is more limited in what it can modify, relative to Route or
+    /// Application level middleware, in that Scope-level middleware can not modify 
+    /// ServiceResponse.
     ///
-    /// This is similar to `App's` middlewares, but middleware get invoked on scope level.
-    /// Scope level middlewares are not allowed to change response
-    /// type (i.e modify response's body).
+    /// Use middleware when you need to read or modify *every* request in some way.
     pub fn wrap<M, F>(
         self,
         mw: F,
@@ -238,10 +242,12 @@ where
         }
     }
 
-    /// Register a scope level middleware function.
-    ///
-    /// This function accepts instance of `ServiceRequest` type and
-    /// mutable reference to the next middleware in chain.
+    /// Registers middleware, in the form of a closure, that runs during inbound
+    /// processing in the request lifecycle (request -> response), modifying 
+    /// request as necessary, across all requests managed by the *Scope*.  
+    /// Scope-level middleware is more limited in what it can modify, relative
+    /// to Route or Application level middleware, in that Scope-level middleware
+    /// can not modify ServiceResponse.
     ///
     /// ```rust
     /// use actix_service::Service;