Improve the documentation for default_service (#2614)

src/app.rs

@@ -236,9 +236,9 @@ where
         self
     }
 
-    /// Default service to be used if no matching resource could be found.
+    /// Default service that is invoked when no matching resource could be found.
     ///
-    /// It is possible to use services like `Resource`, `Route`.
+    /// You must use a [`Route`] as default service:
     ///
     /// ```
     /// use actix_web::{web, App, HttpResponse};
@@ -253,19 +253,6 @@ where
     ///     .default_service(
     ///         web::route().to(|| HttpResponse::NotFound()));
     /// ```
-    ///
-    /// It is also possible to use static files as default service.
-    ///
-    /// ```
-    /// use actix_web::{web, App, HttpResponse};
-    ///
-    /// let app = App::new()
-    ///     .service(
-    ///         web::resource("/index.html").to(|| HttpResponse::Ok()))
-    ///     .default_service(
-    ///         web::to(|| HttpResponse::NotFound())
-    ///     );
-    /// ```
     pub fn default_service<F, U>(mut self, svc: F) -> Self
     where
         F: IntoServiceFactory<U, ServiceRequest>,

src/resource.rs

@@ -313,8 +313,10 @@ where
     }
 
     /// Default service to be used if no matching route could be found.  
-    /// By default *405* response get returned. Resource does not use
+    /// You can pass a [`Route`] as default_service.
-    /// default handler from `App` or `Scope`.
+    ///
+    /// If no default service is specified, a `405 Method Not Allowed` response will be returned to the caller.  
+    /// [`Resource`] does **not** inherit the default handler specified on the parent [`App`](crate::App) or [`Scope`](crate::Scope).
     pub fn default_service<F, U>(mut self, f: F) -> Self
     where
         F: IntoServiceFactory<U, ServiceRequest>,

src/scope.rs

@@ -264,7 +264,8 @@ where
 
     /// Default service to be used if no matching route could be found.
     ///
-    /// If default resource is not registered, app's default resource is being used.
+    /// If a default service is not registered, it will fall back to the default service of
+    /// the parent [`App`](crate::App) (see [`App::default_service`](crate::App::default_service).
     pub fn default_service<F, U>(mut self, f: F) -> Self
     where
         F: IntoServiceFactory<U, ServiceRequest>,