From 11b6158276c0a45ec15b4ba779ed1437841a9495 Mon Sep 17 00:00:00 2001
From: Sergio Benitez <sb@sergio.bz>
Date: Mon, 24 Oct 2016 10:09:50 +0200
Subject: [PATCH] Refine request module API docs.

---
 lib/src/request/data/from_data.rs       | 19 +++++++++++--------
 lib/src/request/form/from_form_value.rs |  4 ++--
 lib/src/request/form/mod.rs             |  4 ++--
 lib/src/request/param.rs                | 10 +++++-----
 4 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/lib/src/request/data/from_data.rs b/lib/src/request/data/from_data.rs
index a7d2eb01..32166fa1 100644
--- a/lib/src/request/data/from_data.rs
+++ b/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>`
-///   to catch `Failure`s.
+///   code and error. The designated error
+///   [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`
diff --git a/lib/src/request/form/from_form_value.rs b/lib/src/request/form/from_form_value.rs
index fe6cbfc2..de1b8bde 100644
--- a/lib/src/request/form/from_form_value.rs
+++ b/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
-    /// return Some(default_value).
+    /// If this returns `None`, then the field is required. Otherwise, this
+    /// should return `Some(default_value)`.
     fn default() -> Option<Self> {
         None
     }
diff --git a/lib/src/request/form/mod.rs b/lib/src/request/form/mod.rs
index 60620e60..a3adfe96 100644
--- a/lib/src/request/form/mod.rs
+++ b/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
-/// implementing the trait.
+/// [FromForm](trait.FromForm.html) documentation for more information on
+/// 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
diff --git a/lib/src/request/param.rs b/lib/src/request/param.rs
index 6dae4b8c..3d4ba4e7 100644
--- a/lib/src/request/param.rs
+++ b/lib/src/request/param.rs
@@ -19,11 +19,9 @@ use http::uri::Segments;
 /// handler for the dynamic `"/<id>"` path:
 ///
 /// ```rust
-/// #![feature(plugin)]
-/// #![plugin(rocket_codegen)]
-///
-/// extern crate rocket;
-///
+/// # #![feature(plugin)]
+/// # #![plugin(rocket_codegen)]
+/// # 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