From eb6451c4fe2862e666f308e5aa6d1fb5a4ff82ee Mon Sep 17 00:00:00 2001
From: David Pedersen <david.pdrsn@gmail.com>
Date: Fri, 26 Aug 2022 09:42:32 +0200
Subject: [PATCH] Clarify `Clone` requirements even if using
 `Router::with_state_arc` (#1329)

---
 axum/src/routing/mod.rs | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/axum/src/routing/mod.rs b/axum/src/routing/mod.rs
index 3f75a9686f..d33918e19d 100644
--- a/axum/src/routing/mod.rs
+++ b/axum/src/routing/mod.rs
@@ -136,10 +136,33 @@ where
 
     /// Create a new `Router` with the given [`Arc`]'ed state.
     ///
-    /// See [`State`](crate::extract::State) for more details about accessing state.
+    /// See [`State`] for more details about accessing state.
     ///
     /// Unless you add additional routes this will respond with `404 Not Found` to
     /// all requests.
+    ///
+    /// Note that the state type you extract with [`State`] must implement [`FromRef<S>`]. If
+    /// you're extracting `S` itself that requires `S` to implement `Clone`. That is still the
+    /// case, even if you're using this method:
+    ///
+    /// ```
+    /// use axum::{Router, routing::get, extract::State};
+    /// use std::sync::Arc;
+    ///
+    /// // `AppState` must implement `Clone` to be extracted...
+    /// #[derive(Clone)]
+    /// struct AppState {}
+    ///
+    /// // ...even though we're wrapping it an an `Arc`
+    /// let state = Arc::new(AppState {});
+    ///
+    /// let app: Router<AppState> = Router::with_state_arc(state).route("/", get(handler));
+    ///
+    /// async fn handler(state: State<AppState>) {}
+    /// ```
+    ///
+    /// [`FromRef<S>`]: crate::extract::FromRef
+    /// [`State`]: crate::extract::State
     pub fn with_state_arc(state: Arc<S>) -> Self {
         Self {
             state,