From 66b3b3df55b23dc3c172fb59ccdd528f8b8b18c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Ml=C3=A1dek?= <david.mladek.cz@gmail.com>
Date: Sun, 11 Feb 2024 12:12:03 +0100
Subject: [PATCH] Document usage of concrete state in `FromRequest` macro
 (#2550) (#2581)

---
 axum-macros/src/lib.rs | 49 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/axum-macros/src/lib.rs b/axum-macros/src/lib.rs
index 36f9b50c..f35e7dae 100644
--- a/axum-macros/src/lib.rs
+++ b/axum-macros/src/lib.rs
@@ -233,6 +233,55 @@ use from_request::Trait::{FromRequest, FromRequestParts};
 /// }
 /// ```
 ///
+/// ## Concrete state
+///
+/// If the extraction can be done only for a concrete state, that type can be specified with
+/// `#[from_request(state(YourState))]`:
+///
+/// ```
+/// use axum::extract::{FromRequest, FromRequestParts};
+///
+/// #[derive(Clone)]
+/// struct CustomState;
+///
+/// struct MyInnerType;
+///
+/// #[axum::async_trait]
+/// impl FromRequestParts<CustomState> for MyInnerType {
+///     // ...
+///     # type Rejection = ();
+///
+///     # async fn from_request_parts(
+///         # _parts: &mut axum::http::request::Parts,
+///         # _state: &CustomState
+///     # ) -> Result<Self, Self::Rejection> {
+///     #    todo!()
+///     # }
+/// }
+///
+/// #[derive(FromRequest)]
+/// #[from_request(state(CustomState))]
+/// struct MyExtractor {
+///     custom: MyInnerType,
+///     body: String,
+/// }
+/// ```
+///
+/// This is not needed for a `State<T>` as the type is inferred in that case.
+///
+/// ```
+/// use axum::extract::{FromRequest, FromRequestParts, State};
+///
+/// #[derive(Clone)]
+/// struct CustomState;
+///
+/// #[derive(FromRequest)]
+/// struct MyExtractor {
+///     custom: State<CustomState>,
+///     body: String,
+/// }
+/// ```
+///
 /// # The whole type at once
 ///
 /// By using `#[from_request(via(...))]` on the container you can extract the whole type at once,