updated wrap and wrap fn descriptions, still requiring viable examples

src/app.rs

@@ -112,9 +112,12 @@ where
         self
     }
 
-    /// Registers heavyweight Application-level middleware, in the form of a
-    /// re-usable middleware type, that runs during inbound and/or outbound 
-    /// processing in the request lifecycle (request -> response).
+    /// 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;
@@ -171,9 +174,12 @@ where
         }
     }
 
-    /// Registers lightweight Application-level middleware, in the form of a
-    /// closure, that runs during inbound and/or outbound processing in the 
-    /// request lifecycle (request -> response).
+    /// 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;
@@ -421,9 +427,13 @@ where
         self
     }
 
-    /// Registers heavyweight Route-level middleware, in the form of a
-    /// re-usable middleware type, that runs during inbound and/or outbound 
-    /// processing in the request lifecycle (request -> response).
+    /// 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,
@@ -463,9 +473,13 @@ where
         }
     }
 
-    /// Registers lightweight Route-level middleware, in the form of a
-    /// closure, that runs during inbound and/or outbound processing in the 
-    /// request lifecycle (request -> response).
+    /// 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,14 @@ 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*.  Note that
+    /// Scope-level middleware is only used for inbound requests, not outbound
+    /// responses.
     ///
-    /// 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 +241,11 @@ 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*.  
+    /// Note that Scope-level middleware is only used for inbound requests, 
+    /// not outbound responses.
     ///
     /// ```rust
     /// use actix_service::Service;