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