Rocket

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README

commit c1b39a016b1729b9b6dbe335c095d05574f1ab79
parent a77876f64065eb88e62dc65193b8b1fa0dd02c55
Author: Sergio Benitez <sb@sergio.bz>
Date:   Sun, 28 Oct 2018 04:07:46 -0700

Improve 'Redirect' and 'rocket_codegen' documentation.

Diffstat:
Mcore/codegen/src/lib.rs | 21+++++++++++++++++++++
Mcore/codegen/tests/uri_display.rs | 2+-
Mcore/lib/src/response/redirect.rs | 57+++++++++++++++++++++++++++++++++++++++++++++++++--------
3 files changed, 71 insertions(+), 9 deletions(-)

diff --git a/core/codegen/src/lib.rs b/core/codegen/src/lib.rs @@ -15,6 +15,27 @@ //! here is purely technical. The code generation facilities are documented //! thoroughly in the [Rocket programming guide](https://rocket.rs/v0.4/guide). //! +//! # Usage +//! +//! You **_should not_** directly depend on this library. To use the macros, +//! attributes, and derives in this crate, it suffices to depend on `rocket` in +//! `Cargo.toml`: +//! +//! ```toml +//! [dependencies] +//! rocket = "0.4.0-dev" +//! ``` +//! +//! And to import macros via `#[macro_use]` in the crate root: +//! +//! ```rust +//! #![feature(proc_macro_hygiene, decl_macro)] +//! +//! #[macro_use] extern crate rocket; +//! # #[get("/")] fn hello() { } +//! # fn main() { rocket::ignite().mount("/", routes![hello]); } +//! ``` +//! //! # Debugging Codegen //! //! When the `ROCKET_CODEGEN_DEBUG` environment variable is set, this crate diff --git a/core/codegen/tests/uri_display.rs b/core/codegen/tests/uri_display.rs @@ -3,7 +3,7 @@ #[macro_use] extern crate rocket; use rocket::http::RawStr; -use rocket::http::uri::{UriDisplay, Formatter}; +use rocket::http::uri::UriDisplay; macro_rules! assert_uri_display { ($v:expr, $s:expr) => ( diff --git a/core/lib/src/response/redirect.rs b/core/lib/src/response/redirect.rs @@ -8,6 +8,41 @@ use http::Status; /// An empty redirect response to a given URL. /// /// This type simplifies returning a redirect response to the client. +/// +/// # Usage +/// +/// All constructors accept a generic type of `T: TryInto<Uri<'static>>`. Among +/// the candidate types are: +/// +/// * `String` +/// * `&'static str` +/// * [`Origin`](::http::uri::Origin) +/// * [`Authority`](::http::uri::Authority) +/// * [`Absolute`](::http::uri::Absolute) +/// * [`Uri`](::http::uri::Uri) +/// +/// Any non-`'static` strings must first be allocated using `.to_string()` or +/// similar before being passed to a `Redirect` constructor. When redirecting to +/// a route, _always_ use [`uri!`] to construct a valid [`Origin`]: +/// +/// ```rust +/// # #![feature(proc_macro_hygiene, decl_macro)] +/// # #[macro_use] extern crate rocket; +/// use rocket::response::Redirect; +/// +/// #[get("/hello/<name>/<age>")] +/// fn hello(name: String, age: u8) -> String { +/// format!("Hello, {} year old named {}!", age, name) +/// } +/// +/// #[get("/hi/<name>/<age>")] +/// fn hi(name: String, age: u8) -> Redirect { +/// Redirect::to(uri!(hello: name, age)) +/// } +/// ``` +/// +/// [`Origin`]: ::http::uri::Origin +/// [`uri!`]: ../../rocket_codegen/macro.uri.html #[derive(Debug)] pub struct Redirect(Status, Option<Uri<'static>>); @@ -22,8 +57,9 @@ impl Redirect { /// ```rust /// use rocket::response::Redirect; /// - /// # #[allow(unused_variables)] + /// # let query = "foo"; /// let redirect = Redirect::to("/other_url"); + /// let redirect = Redirect::to(format!("https://google.com/{}", query)); /// ``` pub fn to<U: TryInto<Uri<'static>>>(uri: U) -> Redirect { Redirect(Status::SeeOther, uri.try_into().ok()) @@ -40,8 +76,9 @@ impl Redirect { /// ```rust /// use rocket::response::Redirect; /// - /// # #[allow(unused_variables)] + /// # let query = "foo"; /// let redirect = Redirect::temporary("/other_url"); + /// let redirect = Redirect::temporary(format!("https://google.com/{}", query)); /// ``` pub fn temporary<U: TryInto<Uri<'static>>>(uri: U) -> Redirect { Redirect(Status::TemporaryRedirect, uri.try_into().ok()) @@ -59,8 +96,9 @@ impl Redirect { /// ```rust /// use rocket::response::Redirect; /// - /// # #[allow(unused_variables)] + /// # let query = "foo"; /// let redirect = Redirect::permanent("/other_url"); + /// let redirect = Redirect::permanent(format!("https://google.com/{}", query)); /// ``` pub fn permanent<U: TryInto<Uri<'static>>>(uri: U) -> Redirect { Redirect(Status::PermanentRedirect, uri.try_into().ok()) @@ -78,8 +116,9 @@ impl Redirect { /// ```rust /// use rocket::response::Redirect; /// - /// # #[allow(unused_variables)] + /// # let query = "foo"; /// let redirect = Redirect::found("/other_url"); + /// let redirect = Redirect::found(format!("https://google.com/{}", query)); /// ``` pub fn found<U: TryInto<Uri<'static>>>(uri: U) -> Redirect { Redirect(Status::Found, uri.try_into().ok()) @@ -95,8 +134,9 @@ impl Redirect { /// ```rust /// use rocket::response::Redirect; /// - /// # #[allow(unused_variables)] + /// # let query = "foo"; /// let redirect = Redirect::moved("/other_url"); + /// let redirect = Redirect::moved(format!("https://google.com/{}", query)); /// ``` pub fn moved<U: TryInto<Uri<'static>>>(uri: U) -> Redirect { Redirect(Status::MovedPermanently, uri.try_into().ok()) @@ -104,9 +144,10 @@ impl Redirect { } /// Constructs a response with the appropriate status code and the given URL in -/// the `Location` header field. The body of the response is empty. This -/// responder does not fail. -impl Responder<'static> for Redirect { +/// the `Location` header field. The body of the response is empty. If the URI +/// value used to create the `Responder` is an invalid URI, an error of +/// `Status::InternalServerError` is returned. +impl<'a> Responder<'a> for Redirect { fn respond_to(self, _: &Request) -> Result<Response<'static>, Status> { if let Some(uri) = self.1 { Response::build()