Fix nest docs inconsistency (#230)

src/lib.rs

@@ -9,7 +9,7 @@
 //!     - [Precedence](#precedence)
 //!     - [Matching multiple methods](#matching-multiple-methods)
 //!     - [Routing to any `Service`](#routing-to-any-service)
-//!     - [Nesting Routes](#nesting-routes)
+//!     - [Nesting routes](#nesting-routes)
 //! - [Extractors](#extractors)
 //! - [Building responses](#building-responses)
 //! - [Applying middleware](#applying-middleware)
@@ -255,7 +255,7 @@
 //! Routing to arbitrary services in this way has complications for backpressure
 //! ([`Service::poll_ready`]). See the [`service`] module for more details.
 //!
-//! ## Nesting Routes
+//! ## Nesting routes
 //!
 //! Routes can be nested by calling [`Router::nest`](routing::Router::nest):
 //!

src/routing/mod.rs

@@ -143,8 +143,8 @@ impl<S> Router<S> {
     /// use http::Uri;
     ///
     /// async fn users_get(uri: Uri) {
-    ///     // `users_get` will still see the whole URI.
-    ///     assert_eq!(uri.path(), "/api/users");
+    ///     // `uri` will be `/users` since `nest` strips the matching prefix.
+    ///     // use `OriginalUri` to always get the full URI.
     /// }
     ///
     /// async fn users_post() {}
@@ -153,12 +153,19 @@ impl<S> Router<S> {
     ///
     /// let users_api = Router::new().route("/users", get(users_get).post(users_post));
     ///
-    /// let app = Router::new().nest("/api", users_api).route("/careers", get(careers));
+    /// let app = Router::new()
+    ///     .nest("/api", users_api)
+    ///     .route("/careers", get(careers));
     /// # async {
     /// # axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap();
     /// # };
     /// ```
     ///
+    /// Note that nested routes will not see the orignal request URI but instead
+    /// have the matched prefix stripped. This is necessary for services like static
+    /// file serving to work. Use [`OriginalUri`] if you need the original request
+    /// URI.
+    ///
     /// Take care when using `nest` together with dynamic routes as nesting also
     /// captures from the outer routes:
     ///
@@ -207,6 +214,8 @@ impl<S> Router<S> {
     /// If necessary you can use [`Router::boxed`] to box a group of routes
     /// making the type easier to name. This is sometimes useful when working with
     /// `nest`.
+    ///
+    /// [`OriginalUri`]: crate::extract::OriginalUri
     pub fn nest<T>(self, description: &str, svc: T) -> Router<Nested<T, S>> {
         self.map(|fallback| Nested {
             pattern: PathPattern::new(description),