Improve 'Route' documentation.

This commit is contained in:
Sergio Benitez 2017-06-30 13:17:40 -07:00
parent b0612d7346
commit beb5ca14cf
1 changed files with 110 additions and 7 deletions

View File

@ -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());
}