From beb5ca14cfd4a3263a8f4b4e60c5628158502afd Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Fri, 30 Jun 2017 13:17:40 -0700 Subject: [PATCH] Improve 'Route' documentation. --- lib/src/router/route.rs | 117 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 110 insertions(+), 7 deletions(-) diff --git a/lib/src/router/route.rs b/lib/src/router/route.rs index fb400594..229ab3d9 100644 --- a/lib/src/router/route.rs +++ b/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, } @@ -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 /?` + /// let index_name = Route::new(Method::Get, "/?", handler); + /// + /// // this is a rank -1 route matching requests to `GET /` + /// let name = Route::new(Method::Get, "/", handler); + /// ``` pub fn new(m: Method, path: S, handler: Handler) -> Route where S: AsRef { @@ -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(rank: isize, m: Method, uri: S, handler: Handler) -> Route where S: AsRef { @@ -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(&mut self, path: S) where S: AsRef { 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(&mut self, uri: S) where S: AsRef { self.uri = URI::from(uri.as_ref().to_string()); }