Documentation and minor fixes

- Add with_type to catcher
- Documents CatcherType, RouteType, and the associated methods in
LocalResponse.

Author: the10thWiz

core/lib/src/catcher/catcher.rs

@@ -9,12 +9,10 @@ use crate::catcher::{Handler, BoxFuture};
 
 use yansi::Paint;
 
-// We could also choose to require a Debug impl?
-/// A generic trait for route types. This should be automatically implemented on the structs
-/// generated by the codegen for each route.
+/// A generic trait for catcher types. This should be automatically implemented on the structs
+/// generated by the codegen for each catcher, and manually implemented on custom cater types.
 ///
-/// It may also be desirable to add an option for other routes to define a RouteType. This
-/// would likely just be a case of adding an alternate constructor to the Route type.
+/// Use the `Catcher::with_type::<T>()` method to set the catcher type.
 pub trait CatcherType: Any + Send + Sync + 'static { }
 
 /// An error catching route.
@@ -165,6 +163,8 @@ impl Catcher {
     ///
     /// Panics if `code` is not in the HTTP status code error range `[400,
     /// 600)`.
+    ///
+    /// If applicable, `with_type` should also be called to set the route type for testing
     #[inline(always)]
     pub fn new<S, H>(code: S, handler: H) -> Catcher
         where S: Into<Option<u16>>, H: Handler
@@ -183,6 +183,13 @@ impl Catcher {
         }
     }
 
+    /// Marks this catcher with the specified type. For a custom catcher type, i.e. something that can
+    /// be passed to `.register()`, it should be that type to make identification easier.
+    pub fn with_type<T: CatcherType>(mut self) -> Self {
+        self.catcher_type = Some(TypeId::of::<T>());
+        self
+    }
+
     /// Maps the `base` of this catcher using `mapper`, returning a new
     /// `Catcher` with the returned base.
     ///

core/lib/src/local/response.rs

@@ -180,7 +180,8 @@ macro_rules! pub_response_impl {
         self._into_msgpack() $(.$suffix)?
     }
 
-    /// Checks if a route was routed by a specific route type
+    /// Checks if a route was routed by a specific route type. This only returns true if the route
+    /// actually generated a response, and a catcher was not run.
     ///
     /// # Example
     ///
@@ -194,6 +195,12 @@ macro_rules! pub_response_impl {
     /// assert!(response.routed_by::<index>())
     /// # });
     /// ```
+    ///
+    /// # Other Route types
+    ///
+    /// [`FileServer`](crate::fs::FileServer) implementes `RouteType`, so a route that should
+    /// return a static file can be checked against it. Libraries which provide a Route type should
+    /// implement `RouteType`, see [`RouteType`](crate::route::RouteType) for more information.
     pub fn routed_by<T: crate::route::RouteType>(&self) -> bool {
         if let Some(route_type) = self._request().route().map(|r| r.route_type).flatten() {
             route_type == std::any::TypeId::of::<T>()
@@ -208,14 +215,18 @@ macro_rules! pub_response_impl {
     ///
     /// ```rust
     /// # use rocket::get;
-    /// #[get("/")]
-    /// fn index() -> &'static str { "Hello World" }
+    /// #[catch(404)]
+    /// fn default_404() -> &'static str { "Hello World" }
     #[doc = $doc_prelude]
     /// # Client::_test(|_, _, response| {
     /// let response: LocalResponse = response;
-    /// assert!(response.routed_by::<index>())
+    /// assert!(response.caught_by::<default_404>())
     /// # });
     /// ```
+    ///
+    /// # Rocket's default catcher
+    ///
+    /// The default catcher has a `CatcherType` of [`DefaultCatcher`](crate::catcher::DefaultCatcher)
     pub fn caught_by<T: crate::catcher::CatcherType>(&self) -> bool {
         if let Some(catcher_type) = self._request().catcher().map(|r| r.catcher_type).flatten() {
             catcher_type == std::any::TypeId::of::<T>()
@@ -224,6 +235,22 @@ macro_rules! pub_response_impl {
         }
     }
 
+    /// Checks if a route was caught by a catcher
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use rocket::get;
+    #[doc = $doc_prelude]
+    /// # Client::_test(|_, _, response| {
+    /// let response: LocalResponse = response;
+    /// assert!(response.was_caught())
+    /// # });
+    /// ```
+    pub fn was_caught(&self) -> bool {
+        self._request().catcher().is_some()
+    }
+
     #[cfg(test)]
     #[allow(dead_code)]
     fn _ensure_impls_exist() {

core/lib/src/route/route.rs

@@ -9,12 +9,10 @@ use crate::http::{uri, MediaType, Method};
 use crate::route::{BoxFuture, Handler, RouteUri};
 use crate::sentinel::Sentry;
 
-// We could also choose to require a Debug impl?
 /// A generic trait for route types. This should be automatically implemented on the structs
-/// generated by the codegen for each route.
+/// generated by the codegen for each route, and manually implemented on custom route types.
 ///
-/// It may also be desirable to add an option for other routes to define a RouteType. This
-/// would likely just be a case of adding an alternate constructor to the Route type.
+/// Use the `Route::with_type::<T>()` method to set the route type.
 pub trait RouteType: Any + Send + Sync + 'static { }
 
 /// A request handling route.
@@ -225,6 +223,8 @@ impl Route {
     /// assert_eq!(index.method, Method::Get);
     /// assert_eq!(index.uri, "/");
     /// ```
+    ///
+    /// If applicable, `with_type` should also be called to set the route type for testing
     #[track_caller]
     pub fn new<H: Handler>(method: Method, uri: &str, handler: H) -> Route {
         Route::ranked(None, method, uri, handler)
@@ -255,6 +255,8 @@ impl Route {
     /// assert_eq!(foo.method, Method::Post);
     /// assert_eq!(foo.uri, "/foo?bar");
     /// ```
+    ///
+    /// If applicable, `with_type` should also be called to set the route type for testing
     #[track_caller]
     pub fn ranked<H, R>(rank: R, method: Method, uri: &str, handler: H) -> Route
     where
@@ -275,7 +277,8 @@ impl Route {
         }
     }
 
-    /// Marks this route with the specified type
+    /// Marks this route with the specified type. For a custom route type, i.e. something that can
+    /// be passed to `.mount()`, it should be that type to make identification easier.
     pub fn with_type<T: RouteType>(mut self) -> Self {
         self.route_type = Some(TypeId::of::<T>());
         self