Improve 'Redirect' and 'rocket_codegen' documentation.

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

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) => (

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()