From c2d3bdccdbb87a9dd41eb352521286d3546aacd3 Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Wed, 2 Nov 2016 18:48:43 +0100 Subject: [PATCH] Document the Failure and Flash responses. --- lib/src/request/mod.rs | 3 ++ lib/src/response/failure.rs | 2 + lib/src/response/flash.rs | 94 ++++++++++++++++++++++++++++++++++--- lib/src/response/mod.rs | 6 +++ 4 files changed, 99 insertions(+), 6 deletions(-) diff --git a/lib/src/request/mod.rs b/lib/src/request/mod.rs index 56c2bb33..05cab1ae 100644 --- a/lib/src/request/mod.rs +++ b/lib/src/request/mod.rs @@ -9,3 +9,6 @@ pub use self::request::Request; pub use self::from_request::{FromRequest, Outcome}; pub use self::param::{FromParam, FromSegments}; pub use self::form::{Form, FromForm, FromFormValue, FormItems}; + +/// Type alias to retrieve flash messages from a request. +pub type FlashMessage = ::response::Flash<()>; diff --git a/lib/src/response/failure.rs b/lib/src/response/failure.rs index 12aadf21..28386484 100644 --- a/lib/src/response/failure.rs +++ b/lib/src/response/failure.rs @@ -2,6 +2,8 @@ use outcome::Outcome; use response::{self, Responder}; use http::hyper::{FreshHyperResponse, StatusCode}; +/// A failing response; simply forwards to the catcher for the given +/// `StatusCode`. #[derive(Debug)] pub struct Failure(pub StatusCode); diff --git a/lib/src/response/flash.rs b/lib/src/response/flash.rs index 31b702cb..72783645 100644 --- a/lib/src/response/flash.rs +++ b/lib/src/response/flash.rs @@ -7,6 +7,35 @@ use http::hyper::{HyperSetCookie, HyperCookiePair, FreshHyperResponse}; const FLASH_COOKIE_NAME: &'static str = "_flash"; +/// Sets a "flash" cookies that will be removed the next time it is accessed. +/// The anologous type on the request side is +/// [FlashMessage](/rocket/request/type.FlashMessage.html). +/// +/// This type makes it easy to send messages across requests. It is typically +/// used for "status" messages after redirects. For instance, if a user attempts +/// to visit a page he/she does not have access to, you may want to redirect the +/// user to a safe place and show a message indicating what happened on the +/// redirected page. The message should only persist for a single request. This +/// can be accomplished with this type. +/// +/// # Usage +/// +/// Each `Flash` message consists of a `name` and some `msg` contents. A generic +/// constructor ([new](#method.new)) can be used to construct a message with any +/// name, while the [warning](#method.warning), [success](#method.success), and +/// [error](#method.error) constructors create messages with the corresponding +/// names. +/// +/// Messages can be retrieved on the request side via the +/// [FlashMessage](/rocket/request/type.FlashMessage.html) type and the +/// [name](#method.name) and [msg](#method.msg) methods. +/// +/// # Responder +/// +/// The `Responder` implementation for `Flash` sets the message cookie and then +/// uses the passed in responder `res` to complete the response. In other words, +/// it simply sets a cookie and delagates the rest of the response handling to +/// the wrapped responder. pub struct Flash { name: String, message: String, @@ -14,6 +43,19 @@ pub struct Flash { } impl Flash { + /// Constructs a new `Flash` message with the given `name`, `msg`, and + /// underlying `responder`. + /// + /// # Examples + /// + /// Construct a "suggestion" message with contents "Try this out!" that + /// redirects to "/". + /// + /// ```rust + /// use rocket::response::{Redirect, Flash}; + /// + /// let msg = Flash::new(Redirect::to("/"), "suggestion", "Try this out!"); + /// ``` pub fn new, M: AsRef>(res: R, name: N, msg: M) -> Flash { Flash { name: name.as_ref().to_string(), @@ -22,14 +64,53 @@ impl Flash { } } - pub fn warning>(responder: R, msg: S) -> Flash { - Flash::new(responder, "warning", msg) - } - + /// Constructs a "success" `Flash` message with the given `responder` and + /// `msg`. + /// + /// # Examples + /// + /// Construct a "success" message with contents "It worked!" that redirects + /// to "/". + /// + /// ```rust + /// use rocket::response::{Redirect, Flash}; + /// + /// let msg = Flash::success(Redirect::to("/"), "It worked!"); + /// ``` pub fn success>(responder: R, msg: S) -> Flash { Flash::new(responder, "success", msg) } + /// Constructs a "warning" `Flash` message with the given `responder` and + /// `msg`. + /// + /// # Examples + /// + /// Construct a "warning" message with contents "Watch out!" that redirects + /// to "/". + /// + /// ```rust + /// use rocket::response::{Redirect, Flash}; + /// + /// let msg = Flash::warning(Redirect::to("/"), "Watch out!"); + /// ``` + pub fn warning>(responder: R, msg: S) -> Flash { + Flash::new(responder, "warning", msg) + } + + /// Constructs an "error" `Flash` message with the given `responder` and + /// `msg`. + /// + /// # Examples + /// + /// Construct an "error" message with contents "Whoops!" that redirects + /// to "/". + /// + /// ```rust + /// use rocket::response::{Redirect, Flash}; + /// + /// let msg = Flash::error(Redirect::to("/"), "Whoops!"); + /// ``` pub fn error>(responder: R, msg: S) -> Flash { Flash::new(responder, "error", msg) } @@ -60,17 +141,18 @@ impl Flash<()> { } } + /// Returns the `name` of this message. pub fn name(&self) -> &str { self.name.as_str() } + /// Returns the `msg` contents of this message. pub fn msg(&self) -> &str { self.message.as_str() } } -// TODO: Using Flash<()> is ugly. Either create a type FlashMessage = Flash<()> -// or create a Flash under request that does this. +// This is Type-Aliased in Request. impl<'r> FromRequest<'r> for Flash<()> { type Error = (); diff --git a/lib/src/response/mod.rs b/lib/src/response/mod.rs index ecdd6b34..b2a0d1a8 100644 --- a/lib/src/response/mod.rs +++ b/lib/src/response/mod.rs @@ -1,3 +1,9 @@ +//! Types and traits to build and send responses. +//! +//! The return type of a Rocket handler can be any type that implements the +//! [Responder](trait.Responder.html) trait. This module contains several useful +//! types that implement this trait. + mod responder; mod redirect; mod with_status;