Improve State and Router docs

axum/src/docs/routing/nest.md

@@ -1,4 +1,4 @@
-Nest a [`Service`] at some path.
+Nest a [`Router`] at some path.
 
 This allows you to break your application into smaller pieces and compose
 them together.
@@ -64,7 +64,7 @@ let app = Router::new().nest("/:version/api", users_api);
 # };
 ```
 
-# Differences to wildcard routes
+# Differences from wildcard routes
 
 Nested routes are similar to wildcard routes. The difference is that
 wildcard routes still see the whole URI whereas nested routes will have

axum/src/extract/state.rs

@@ -8,7 +8,7 @@ use std::{
 
 /// Extractor for state.
 ///
-/// See ["Accessing state in middleware"][state-from-middleware] for how to  
+/// See ["Accessing state in middleware"][state-from-middleware] for how to
 /// access state in middleware.
 ///
 /// [state-from-middleware]: crate::middleware#accessing-state-in-middleware
@@ -46,6 +46,14 @@ use std::{
 /// # let _: axum::routing::RouterService = app;
 /// ```
 ///
+/// [`Router`]s that are combined with [`Router::nest`] or [`Router::merge`]
+/// generally require the same type of state. See [`Router::nest`] for how to
+/// combine routers with different types of state.
+/// 
+/// [`Router`]: crate::Router
+/// [`Router::nest`]: crate::Router::nest
+/// [`Router::merge`]: crate::Router::merge
+///
 /// # With `MethodRouter`
 ///
 /// ```

axum/src/lib.rs

@@ -164,11 +164,12 @@
 //!
 //! # Sharing state with handlers
 //!
-//! It is common to share some state between handlers for example to share a
-//! pool of database connections or clients to other services.
+//! It is common to share some state between handlers. For example, a
+//! pool of database connections or clients to other services may need to
+//! be shared.
 //!
 //! The three most common ways of doing that are:
-//! - Using the [`State`] extractor.
+//! - Using the [`State`] extractor
 //! - Using request extensions
 //! - Using closure captures
 //!