tweak err handlers docs

actix-web/src/middleware/err_handlers.rs

@@ -50,18 +50,24 @@ type DefaultHandler<B> = Option<Rc<ErrorHandler<B>>>;
 /// will pass by unchanged by this middleware.
 ///
 /// # Examples
-/// ## Handler Response
+///
-/// Header
+/// Adding a header:
+///
 /// ```
-/// use actix_web::http::{header, StatusCode};
+/// use actix_web::{
-/// use actix_web::middleware::{ErrorHandlerResponse, ErrorHandlers};
+///     dev::ServiceResponse,
-/// use actix_web::{dev, web, App, HttpResponse, Result};
+///     http::{header, StatusCode},
+///     middleware::{ErrorHandlerResponse, ErrorHandlers},
+///     web, App, HttpResponse, Result,
+/// };
 ///
 /// fn add_error_header<B>(mut res: dev::ServiceResponse<B>) -> Result<ErrorHandlerResponse<B>> {
 ///     res.response_mut().headers_mut().insert(
 ///         header::CONTENT_TYPE,
 ///         header::HeaderValue::from_static("Error"),
 ///     );
+///
+///     // body is unchanged, map to "left" slot
 ///     Ok(ErrorHandlerResponse::Response(res.map_into_left_body()))
 /// }
 ///
@@ -70,20 +76,28 @@ type DefaultHandler<B> = Option<Rc<ErrorHandler<B>>>;
 ///     .service(web::resource("/").route(web::get().to(HttpResponse::InternalServerError)));
 /// ```
 ///
-/// Body Content
+/// Modifying response body:
+///
 /// ```
-/// use actix_web::http::{header, StatusCode};
+/// use actix_web::{
-/// use actix_web::middleware::{ErrorHandlerResponse, ErrorHandlers};
+///     dev::ServiceResponse,
-/// use actix_web::{dev, web, App, HttpResponse, Result};
+///     http::{header, StatusCode},
-/// fn add_error_body<B>(res: dev::ServiceResponse<B>) -> Result<ErrorHandlerResponse<B>> {
+///     middleware::{ErrorHandlerResponse, ErrorHandlers},
-///    // Get the error message and status code
+///     web, App, HttpResponse, Result,
-///    let error_message = "An error occurred";
+/// };
-///    // Destructures ServiceResponse into request and response components
+///
+/// fn add_error_body<B>(res: ServiceResponse<B>) -> Result<ErrorHandlerResponse<B>> {
+///     // split service response into request and response components
 ///     let (req, res) = res.into_parts();
-///    // Create a new response with the modified body
+///
-///    let res = res.set_body(error_message).map_into_boxed_body();
+///     // set body of response to modified body
-///    // Create a new ServiceResponse with the modified response
+///     let res = res.set_body("An error occurred.");
-///    let res = dev::ServiceResponse::new(req, res).map_into_right_body();
+///
+///     // modified bodies need to be boxed and placed in the "right" slot
+///     let res = ServiceResponse::new(req, res)
+///         .map_into_boxed_body()
+///         .map_into_right_body();
+///
 ///     Ok(ErrorHandlerResponse::Response(res))
 /// }
 ///
@@ -91,16 +105,23 @@ type DefaultHandler<B> = Option<Rc<ErrorHandler<B>>>;
 ///     .wrap(ErrorHandlers::new().handler(StatusCode::INTERNAL_SERVER_ERROR, add_error_body))
 ///     .service(web::resource("/").route(web::get().to(HttpResponse::InternalServerError)));
 /// ```
-/// ## Registering default handler
+///
+/// Registering default handler:
+///
 /// ```
-/// # use actix_web::http::{header, StatusCode};
+/// # use actix_web::{
-/// # use actix_web::middleware::{ErrorHandlerResponse, ErrorHandlers};
+/// #     dev::ServiceResponse,
-/// # use actix_web::{dev, web, App, HttpResponse, Result};
+/// #     http::{header, StatusCode},
+/// #     middleware::{ErrorHandlerResponse, ErrorHandlers},
+/// #     web, App, HttpResponse, Result,
+/// # };
 /// fn add_error_header<B>(mut res: dev::ServiceResponse<B>) -> Result<ErrorHandlerResponse<B>> {
 ///     res.response_mut().headers_mut().insert(
 ///         header::CONTENT_TYPE,
 ///         header::HeaderValue::from_static("Error"),
 ///     );
+///
+///     // body is unchanged, map to "left" slot
 ///     Ok(ErrorHandlerResponse::Response(res.map_into_left_body()))
 /// }
 ///
@@ -109,6 +130,8 @@ type DefaultHandler<B> = Option<Rc<ErrorHandler<B>>>;
 ///         header::CONTENT_TYPE,
 ///         header::HeaderValue::from_static("Bad Request Error"),
 ///     );
+///
+///     // body is unchanged, map to "left" slot
 ///     Ok(ErrorHandlerResponse::Response(res.map_into_left_body()))
 /// }
 ///
@@ -122,9 +145,10 @@ type DefaultHandler<B> = Option<Rc<ErrorHandler<B>>>;
 ///     )
 ///     .service(web::resource("/").route(web::get().to(HttpResponse::InternalServerError)));
 /// ```
-/// Alternatively, you can set default handlers for only client or only server errors:
 ///
-/// ```rust
+/// You can set default handlers for all client (4xx) or all server (5xx) errors:
+///
+/// ```
 /// # use actix_web::http::{header, StatusCode};
 /// # use actix_web::middleware::{ErrorHandlerResponse, ErrorHandlers};
 /// # use actix_web::{dev, web, App, HttpResponse, Result};