From 8d5d6a2598887ef74e162f32dd34138b8cd0a75c Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Sun, 26 Feb 2023 13:28:15 +0000
Subject: [PATCH] tweak err handlers docs

---
 actix-web/src/middleware/err_handlers.rs | 76 ++++++++++++++++--------
 1 file changed, 50 insertions(+), 26 deletions(-)

diff --git a/actix-web/src/middleware/err_handlers.rs b/actix-web/src/middleware/err_handlers.rs
index 00fb5cf59..557fa3849 100644
--- a/actix-web/src/middleware/err_handlers.rs
+++ b/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::middleware::{ErrorHandlerResponse, ErrorHandlers};
-/// use actix_web::{dev, web, App, HttpResponse, Result};
+/// use actix_web::{
+///     dev::ServiceResponse,
+///     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,37 +76,52 @@ 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::middleware::{ErrorHandlerResponse, ErrorHandlers};
-/// use actix_web::{dev, web, App, HttpResponse, Result};
-/// fn add_error_body<B>(res: dev::ServiceResponse<B>) -> Result<ErrorHandlerResponse<B>> {
-///    // Get the error message and status code
-///    let error_message = "An error occurred";
-///    // Destructures ServiceResponse 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();
-///    // Create a new ServiceResponse with the modified response
-///    let res = dev::ServiceResponse::new(req, res).map_into_right_body();
-///    Ok(ErrorHandlerResponse::Response(res))
-///}
+/// use actix_web::{
+///     dev::ServiceResponse,
+///     http::{header, StatusCode},
+///     middleware::{ErrorHandlerResponse, ErrorHandlers},
+///     web, App, HttpResponse, Result,
+/// };
+///
+/// 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();
+///
+///     // set body of response to modified body
+///     let res = res.set_body("An error occurred.");
+///
+///     // 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))
+/// }
 ///
 /// let app = App::new()
 ///     .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::middleware::{ErrorHandlerResponse, ErrorHandlers};
-/// # use actix_web::{dev, web, App, HttpResponse, Result};
+/// # use actix_web::{
+/// #     dev::ServiceResponse,
+/// #     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};