Refine request module API docs.

lib/src/request/data/from_data.rs

@@ -32,7 +32,7 @@ impl<S, E> DataOutcome<S, E> {
 
 /// Trait used to derive an object from incoming request data.
 ///
-/// Type that implement this trait can be used as target for the `data =
+/// Types that implement this trait can be used as a target for the `data =
 /// "<param>"` route parmater, as illustrated below:
 ///
 /// ```rust,ignore
@@ -45,20 +45,23 @@ impl<S, E> DataOutcome<S, E> {
 /// # Outcomes
 ///
 /// The returned [Outcome](/rocket/outcome/index.html) of a `from_data` call
-/// determines what will happen with the incoming request.
+/// determines how the incoming request will be processed.
 ///
-/// * **Success**
+/// * **Success**(S)
 ///
 ///   If the `Outcome` is `Success`, then the `Success` value will be used as
-///   the value for the data parameter.
+///   the value for the data parameter.  As long as all other parsed types
+///   succeed, the request will be handled by the requesting handler.
 ///
-/// * **Failure**
+/// * **Failure**(StatusCode, E)
 ///
 ///   If the `Outcome` is `Failure`, the request will fail with the given status
-///   code. Note that users can request types of `Result<S, E>` and `Option<S>`
+///   code and error. The designated error
-///   to catch `Failure`s.
+///   [Catcher](/rocket/struct.Catcher.html) will be used to respond to the
+///   request. Note that users can request types of `Result<S, E>` and
+///   `Option<S>` to catch `Failure`s and retrieve the error value.
 ///
-/// * **Failure**
+/// * **Forward**(Data)
 ///
 ///   If the `Outcome` is `Forward`, the request will be forwarded to the next
 ///   matching request. This requires that no data has been read from the `Data`

lib/src/request/form/from_form_value.rs

@@ -51,8 +51,8 @@ pub trait FromFormValue<'v>: Sized {
     fn from_form_value(form_value: &'v str) -> Result<Self, Self::Error>;
 
     /// Returns a default value to be used when the form field does not exist.
-    /// If this returns None, then the field is required. Otherwise, this should
+    /// If this returns `None`, then the field is required. Otherwise, this
-    /// return Some(default_value).
+    /// should return `Some(default_value)`.
     fn default() -> Option<Self> {
         None
     }

lib/src/request/form/mod.rs

@@ -40,8 +40,8 @@ use request::{Request, FromData, Data, DataOutcome};
 ///
 /// This type can be used with any type that implements the `FromForm` trait.
 /// The trait can be automatically derived; see the
-/// [FromForm](trait.FromForm.html) documentation for more information about
+/// [FromForm](trait.FromForm.html) documentation for more information on
-/// implementing the trait.
+/// deriving or implementing the trait.
 ///
 /// Because `Form` implement `FromData`, it can be used directly as a target of
 /// the `data = "<param>"` route parameter. For instance, if some structure of

lib/src/request/param.rs

@@ -19,11 +19,9 @@ use http::uri::Segments;
 /// handler for the dynamic `"/<id>"` path:
 ///
 /// ```rust
-/// #![feature(plugin)]
+/// # #![feature(plugin)]
-/// #![plugin(rocket_codegen)]
+/// # #![plugin(rocket_codegen)]
-///
+/// # extern crate rocket;
-/// extern crate rocket;
-///
 /// #[get("/<id>")]
 /// fn hello(id: usize) -> String {
 /// # /*
@@ -40,6 +38,8 @@ use http::uri::Segments;
 /// routes, this example will result in a 404 error for requests with invalid
 /// `id` values.
 ///
+/// # Catching Errors
+///
 /// # `str` vs. `String`
 ///
 /// Paths are URL encoded. As a result, the `str` `FromParam` implementation