Extend FormFormValue docs with details and built-in impls.

Closes #129.

lib/src/request/form/from_form_value.rs

@@ -7,10 +7,101 @@ use http::uri::URI;
 /// Trait to create instance of some type from a form value; expected from field
 /// types in structs deriving `FromForm`.
 ///
-/// # Examples
+/// When deriving the `FromForm` trait, Rocket uses the `FromFormValue`
+/// implementation of each field's type to validate the form input. To
+/// illustrate, consider the following structure:
 ///
-/// This trait is generally implemented when verifying form inputs. For example,
-/// if you'd like to verify that some user is over some age in a form, then you
+/// ```rust,ignore
+/// #[derive(FromForm)]
+/// struct Person {
+///     name: String,
+///     age: u16
+/// }
+/// ```
+///
+/// The `FromForm` implementation generated by Rocket will call
+/// `String::from_form_value` for the `name` field, and `u16::from_form_value`
+/// for the `age` field. The `Person` structure can only be created from a form
+/// if both calls return successfully.
+///
+/// ## Catching Validation Errors
+///
+/// Sometimes you want to be informed of validation errors. When this is
+/// desired, types of `Option<T>` or `Result<T, T::Error>` can be used. These
+/// types implement `FromFormValue` themselves. Their implementations always
+/// return successfully, so their validation never fails. They can be used to
+/// determine if the `from_form_value` call failed and to retrieve the error
+/// value from the failed call.
+///
+/// For instance, if we wanted to know if a user entered an invalid `age` in the
+/// form corresponding to the `Person` structure above, we could use the
+/// following structure:
+///
+/// ```rust
+/// struct Person<'r> {
+///     name: String,
+///     age: Result<u16, &'r str>
+/// }
+/// ```
+///
+/// The `Err` value in this case is `&str` since `u16::from_form_value` returns
+/// a `Result<u16, &str>`.
+///
+/// # Provided Implementations
+///
+/// Rocket implements `FromFormValue` for many standard library types. Their
+/// behavior is documented here.
+///
+///   * **f32, f64, isize, i8, i16, i32, i64, usize, u8, u16, u32, u64**
+///
+///   **IpAddr, Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6, SocketAddr**
+///
+///     A value is validated successfully if the `from_str` method for the given
+///     type returns successfully. Otherwise, the raw form value is returned as
+///     the `Err` value.
+///
+///   * **bool**
+///
+///     A value is validated successfully as `true` if the the form value is
+///     `"true"` or `"on"`, and as a `false` value if the form value is
+///     `"false"`, or `"off"`. Otherwise, the raw form value is returned in the
+///     `Err` value.
+///
+///   * **str**
+///
+///     _This implementation always returns successfully._
+///
+///     The raw, undecoded string is returned directly without modification.
+///
+///   * **String**
+///
+///     URL decodes the form value. If the decode is successful, the decoded
+///     string is returned. Otherwise, an `Err` with the original form value is
+///     returned.
+///
+///   * **Option&lt;T>** _where_ **T: FromFormValue**
+///
+///     _This implementation always returns successfully._
+///
+///     The form value is validated by `T`'s `FromFormValue` implementation. If
+///     the validation succeeds, a `Some(validated_value)` is returned.
+///     Otherwise, a `None` is returned.
+///
+///   * **Result&lt;T, T::Error>** _where_ **T: FromFormValue**
+///
+///     _This implementation always returns successfully._
+///
+///     The from value is validated by `T`'s `FromFormvalue` implementation. The
+///     returned `Result` value is returned.
+///
+/// # Example
+///
+/// This trait is generally implemented to parse and validate form values. While
+/// Rocket provides parsing and validation for many of the standard library
+/// types such as `u16` and `String`, you can implement `FromFormValue` for a
+/// custom type to get custom validation.
+///
+/// Imagine you'd like to verify that some user is over some age in a form. You
 /// might define a new type and implement `FromFormValue` as follows:
 ///
 /// ```rust
@@ -31,15 +122,18 @@ use http::uri::URI;
 /// }
 /// ```
 ///
-/// This type can then be used in a `FromForm` struct as follows:
+/// The type can then be used in a `FromForm` struct as follows:
 ///
 /// ```rust,ignore
 /// #[derive(FromForm)]
-/// struct User {
-///     age: AdultAge,
-///     ...
+/// struct Person {
+///     name: String,
+///     age: AdultAge
 /// }
 /// ```
+///
+/// A form using the `Person` structure as its target will only parse and
+/// validate if the `age` field contains a `usize` greater than `21`.
 pub trait FromFormValue<'v>: Sized {
     /// The associated error which can be returned from parsing. It is a good
     /// idea to have the return type be or contain an `&'v str` so that the

lib/src/request/form/mod.rs

@@ -9,11 +9,12 @@
 //! ```
 //!
 //! Form parameter types must implement the [FromForm](trait.FromForm.html)
-//! trait, which is automaForwarp derivable. Automatically deriving `FromForm`
-//! for a structure requires that all of its fields implement
-//! [FromFormValue](trait.FormFormValue.html). See the
-//! [codegen](/rocket_codegen/) documentation or the [forms guide](/guide/forms)
-//! for more information on forms and on deriving `FromForm`.
+//! trait, which is auto-derivable. Automatically deriving `FromForm` for a
+//! structure requires that all of its fields implement
+//! [FromFormValue](trait.FormFormValue.html), which parses and validates form
+//! fields. See the [codegen](/rocket_codegen/) documentation or the [forms
+//! guide](/guide/forms) for more information on forms and on deriving
+//! `FromForm`.
 
 mod form_items;
 mod from_form;

lib/src/request/param.rs

@@ -43,7 +43,7 @@ use http::uri::{URI, Segments, SegmentError};
 /// Sometimes, a forward is not desired, and instead, we simply want to know
 /// that the dynamic path segment could not be parsed into some desired type
 /// `T`. In these cases, types of `Option<T>` or `Result<T, T::Error>` can be
-/// used. These types implement `FromParam` themeselves. Their implementations
+/// used. These types implement `FromParam` themselves. Their implementations
 /// always return successfully, so they never forward. They can be used to
 /// determine if the `FromParam` call failed and to retrieve the error value
 /// from the failed `from_param` call.