Document the Failure and Flash responses.

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

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

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<R> {
     name: String,
     message: String,
@@ -14,6 +43,19 @@ pub struct Flash<R> {
 }
 
 impl<R: Responder> Flash<R> {
+    /// 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<N: AsRef<str>, M: AsRef<str>>(res: R, name: N, msg: M) -> Flash<R> {
         Flash {
             name: name.as_ref().to_string(),
@@ -22,14 +64,53 @@ impl<R: Responder> Flash<R> {
         }
     }
 
-    pub fn warning<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
+    /// Constructs a "success" `Flash` message with the given `responder` and
-        Flash::new(responder, "warning", msg)
+    /// `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<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
         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<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
+        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<S: AsRef<str>>(responder: R, msg: S) -> Flash<R> {
         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<()>
+// This is Type-Aliased in Request.
-// or create a Flash under request that does this.
 impl<'r> FromRequest<'r> for Flash<()> {
     type Error = ();
 

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;