Improve docs regarding state and extensions (#2991)

Co-authored-by: David Mládek <david.mladek.cz@gmail.com>

Author: Lachstec

axum/src/docs/routing/with_state.md

@@ -1,4 +1,5 @@
-Provide the state for the router.
+Provide the state for the router. State passed to this method is global and will be used
+for all requests this router receives. That means it is not suitable for holding state derived from a request, such as authorization data extracted in a middleware. Use [`Extension`] instead for such data.
 
 ```rust
 use axum::{Router, routing::get, extract::State};
@@ -94,13 +95,6 @@ axum::serve(listener, routes).await.unwrap();
 # };
 ```
 
-# State is global within the router
-
-The state passed to this method will be used for all requests this router
-receives. That means it is not suitable for holding state derived from a
-request, such as authorization data extracted in a middleware. Use [`Extension`]
-instead for such data.
-
 # What `S` in `Router<S>` means
 
 `Router<S>` means a router that is _missing_ a state of type `S` to be able to

axum/src/extract/state.rs

@@ -10,7 +10,11 @@ use std::{
 /// See ["Accessing state in middleware"][state-from-middleware] for how to
 /// access state in middleware.
 ///
+/// State is global and used in every request a router with state receives.
+/// For accessing data derived from requests, such as authorization data, see [`Extension`].
+///
 /// [state-from-middleware]: crate::middleware#accessing-state-in-middleware
+/// [`Extension`]: crate::Extension
 ///
 /// # With `Router`
 ///