Improve 'Route' documentation.

lib/src/router/route.rs

@@ -12,7 +12,7 @@ use http::uri::URI;
 pub struct Route {
     /// The method this route matches against.
     pub method: Method,
-    /// A function that should be called when the route matches.
+    /// The function that should be called when the route matches.
     pub handler: Handler,
     /// The base mount point of this `Route`.
     pub base: URI<'static>,
@@ -21,7 +21,7 @@ pub struct Route {
     pub uri: URI<'static>,
     /// The rank of this route. Lower ranks have higher priorities.
     pub rank: isize,
-    /// The media type this route matches against.
+    /// The media type this route matches against, if any.
     pub format: Option<MediaType>,
 }
 
@@ -38,10 +38,43 @@ fn default_rank(uri: &URI) -> isize {
 }
 
 impl Route {
-    /// Creates a new route with the method, path, and handler.
+    /// Creates a new route with the given method, path, and handler with a base
+    /// of `/`.
     ///
-    /// The rank of the route will be `0` if the path contains no dynamic
-    /// segments, and `1` if it does.
+    /// # Ranking
+    ///
+    /// The route rank's is set so that routes with static paths are ranked
+    /// higher than route's with dynamic paths, and routes with query strings
+    /// are ranked higher than ranks without query strings. This default ranking
+    /// is summarized by the table below:
+    ///
+    /// | static path | query | rank |
+    /// |-------------|-------|------|
+    /// | yes         | yes   | -4   |
+    /// | yes         | no    | -3   |
+    /// | no          | yes   | -2   |
+    /// | no          | no    | -1   |
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use rocket::{Request, Route, Data};
+    /// use rocket::handler::Outcome;
+    /// use rocket::http::Method;
+    ///
+    /// fn handler<'r>(request: &'r Request, _data: Data) -> Outcome<'r> {
+    ///     Outcome::from(request, "Hello, world!")
+    /// }
+    ///
+    /// // this is a rank -3 route matching requests to `GET /`
+    /// let index = Route::new(Method::Get, "/", handler);
+    ///
+    /// // this is a rank -4 route matching requests to `GET /?<name>`
+    /// let index_name = Route::new(Method::Get, "/?<name>", handler);
+    ///
+    /// // this is a rank -1 route matching requests to `GET /<name>`
+    /// let name = Route::new(Method::Get, "/<name>", handler);
+    /// ```
     pub fn new<S>(m: Method, path: S, handler: Handler) -> Route
         where S: AsRef<str>
     {
@@ -56,7 +89,23 @@ impl Route {
         }
     }
 
-    /// Creates a new route with the given rank, method, path, and handler.
+    /// Creates a new route with the given rank, method, path, and handler with
+    /// a base of `/`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use rocket::{Request, Route, Data};
+    /// use rocket::handler::Outcome;
+    /// use rocket::http::Method;
+    ///
+    /// fn handler<'r>(request: &'r Request, _data: Data) -> Outcome<'r> {
+    ///     Outcome::from(request, "Hello, world!")
+    /// }
+    ///
+    /// // this is a rank 1 route matching requests to `GET /`
+    /// let index = Route::ranked(1, Method::Get, "/", handler);
+    /// ```
     pub fn ranked<S>(rank: isize, m: Method, uri: S, handler: Handler) -> Route
         where S: AsRef<str>
     {
@@ -70,7 +119,23 @@ impl Route {
         }
     }
 
-    /// Retrieves the base mount point of this route.
+    /// Retrieves the path of the base mount point of this route as an `&str`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use rocket::{Request, Route, Data};
+    /// use rocket::handler::Outcome;
+    /// use rocket::http::Method;
+    ///
+    /// fn handler<'r>(request: &'r Request, _data: Data) -> Outcome<'r> {
+    ///     Outcome::from(request, "Hello, world!")
+    /// }
+    ///
+    /// let mut index = Route::ranked(1, Method::Get, "/", handler);
+    /// assert_eq!(index.base(), "/");
+    /// assert_eq!(index.base.path(), "/");
+    /// ```
     #[inline]
     pub fn base(&self) -> &str {
         self.base.path()
@@ -78,12 +143,50 @@ impl Route {
 
     /// Sets the base mount point of the route. Does not update the rank or any
     /// other parameters.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use rocket::{Request, Route, Data};
+    /// use rocket::handler::Outcome;
+    /// use rocket::http::Method;
+    ///
+    /// fn handler<'r>(request: &'r Request, _data: Data) -> Outcome<'r> {
+    ///     Outcome::from(request, "Hello, world!")
+    /// }
+    ///
+    /// let mut index = Route::ranked(1, Method::Get, "/", handler);
+    /// assert_eq!(index.base(), "/");
+    /// assert_eq!(index.base.path(), "/");
+    ///
+    /// index.set_base("/hi");
+    /// assert_eq!(index.base(), "/hi");
+    /// assert_eq!(index.base.path(), "/hi");
+    /// ```
     pub fn set_base<S>(&mut self, path: S) where S: AsRef<str> {
         self.base = URI::from(path.as_ref().to_string());
     }
 
     /// Sets the path of the route. Does not update the rank or any other
     /// parameters.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use rocket::{Request, Route, Data};
+    /// use rocket::handler::Outcome;
+    /// use rocket::http::Method;
+    ///
+    /// fn handler<'r>(request: &'r Request, _data: Data) -> Outcome<'r> {
+    ///     Outcome::from(request, "Hello, world!")
+    /// }
+    ///
+    /// let mut index = Route::ranked(1, Method::Get, "/", handler);
+    /// assert_eq!(index.uri.path(), "/");
+    ///
+    /// index.set_uri("/hello");
+    /// assert_eq!(index.uri.path(), "/hello");
+    /// ```
     pub fn set_uri<S>(&mut self, uri: S) where S: AsRef<str> {
         self.uri = URI::from(uri.as_ref().to_string());
     }