From cb10c51c417e1b5de0e8ee5214eee0833b955f1c Mon Sep 17 00:00:00 2001
From: Altair-Bueno <67512202+Altair-Bueno@users.noreply.github.com>
Date: Mon, 15 Aug 2022 19:56:24 +0200
Subject: [PATCH] docs(axum-extra): Added doc to `WithRejection`

---
 axum-extra/src/extract/with_rejection.rs | 52 ++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/axum-extra/src/extract/with_rejection.rs b/axum-extra/src/extract/with_rejection.rs
index 0f40fa00..834f8102 100644
--- a/axum-extra/src/extract/with_rejection.rs
+++ b/axum-extra/src/extract/with_rejection.rs
@@ -4,10 +4,62 @@ use axum::response::IntoResponse;
 use std::marker::PhantomData;
 use std::ops::{Deref, DerefMut};
 
+/// Extractor for customizing extractor rejections
+/// 
+/// `WithRejection` wraps another extractor and gives you the result. If the 
+/// extraction fails, the `Rejection` is transformed into `R` and returned as a 
+/// response
+/// 
+/// `E` is expected to implement [`FromRequest`]
+/// 
+/// `R` is expected to implement [`IntoResponse`] and [`From<E::Rejection>`]
+/// 
+/// 
+/// # Example
+///
+/// ```rust
+/// use axum::extract::rejection::JsonRejection;
+/// use axum::response::{Response, IntoResponse};
+/// use axum::Json;
+/// use axum_extra::extract::WithRejection;
+/// use serde::Deserialize;
+///
+/// struct MyRejection { /* ... */ }
+///
+/// impl From<JsonRejection> for MyRejection {
+///     fn from(_:JsonRejection) -> MyRejection {
+///         // ...
+///         # todo!()
+///     }
+/// }
+///
+/// impl IntoResponse for MyRejection {
+///     fn into_response(self) -> Response {
+///         // ...
+///         # todo!()
+///     }
+/// }
+/// #[derive(Debug, Deserialize)]
+/// struct Person { /* ... */ }
+///
+/// async fn handler(
+///     // If the `Json` extractor ever fails, `MyRejection` will be sent to the
+///     // client using the `IntoResponse` impl
+///     WithRejection(Json(Person), _): WithRejection<Json<Person>, MyRejection>
+/// ) { /* ... */ }
+/// ```
+/// 
+/// For a full example see the [customize-extractor-error] example
+/// 
+/// [customize-extractor-error]: https://github.com/tokio-rs/axum/blob/main/examples/customize-extractor-error/src/main.rs
+/// [`FromRequest`]: axum::extract::FromRequest
+/// [`IntoResponse`]: axum::response::IntoResponse
+/// [`From<E::Rejection>`]: std::convert::From
 #[derive(Debug, Clone, Copy, Default)]
 pub struct WithRejection<E, R>(pub E, pub PhantomData<R>);
 
 impl<E, R> WithRejection<E, R> {
+    /// Returns the wrapped extractor
     fn into_inner(self) -> E {
         self.0
     }