From 988236f272060a8bb0fc7a1377af08940dee18e0 Mon Sep 17 00:00:00 2001
From: Sergio Benitez <sb@sergio.bz>
Date: Thu, 2 Feb 2017 18:00:18 -0800
Subject: [PATCH] Add documentation for State request guard.

---
 lib/src/request/state.rs | 47 +++++++++++++++++++++++++++++++++++++++-
 lib/src/rocket.rs        |  2 +-
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/lib/src/request/state.rs b/lib/src/request/state.rs
index d6f2150b..28d373ae 100644
--- a/lib/src/request/state.rs
+++ b/lib/src/request/state.rs
@@ -4,7 +4,52 @@ use request::{self, FromRequest, Request};
 use outcome::Outcome;
 use http::Status;
 
-// TODO: Doc.
+/// Request guard to retrieve managed state.
+///
+/// This type can be used as a request guard to retrieve the state Rocket is
+/// managing for some type `T`. This allows for the sharing of state across any
+/// number of handlers. A value for the given type must previously have been
+/// registered to be managed by Rocket via the
+/// [manage](/rocket/struct.Rocket.html#method.manage) method. The type being
+/// managed must be thread safe and sendable across thread boundaries. In otehr
+/// words, it must implement `Send + Sync + 'static`.
+///
+/// # Example
+///
+/// Imagine you have some configuration struct of the type `MyConfig` that you'd
+/// like to initialize at start-up and later access it in several handlers. The
+/// following example does just this:
+///
+/// ```rust
+/// # #![feature(plugin)]
+/// # #![plugin(rocket_codegen)]
+/// # extern crate rocket;
+/// use rocket::State;
+///
+/// // In a real application, this would likely be more complex.
+/// struct MyConfig(String);
+///
+/// #[get("/")]
+/// fn index(state: State<MyConfig>) -> String {
+///     format!("The config value is: {}", state.0)
+/// }
+///
+/// #[get("/raw")]
+/// fn raw_config_value<'r>(state: State<'r, MyConfig>) -> &'r str {
+///     // use `inner()` to get a lifetime longer than `deref` gives us
+///     state.inner().0.as_str()
+/// }
+///
+/// fn main() {
+///     let config = MyConfig("user input".to_string());
+/// # if false { // We don't actually want to launch the server in an example.
+///     rocket::ignite()
+///         .mount("/", routes![index, raw_config_value])
+///         .manage(config)
+///         .launch()
+/// # }
+/// }
+/// ```
 #[derive(Debug, PartialEq, Eq)]
 pub struct State<'r, T: Send + Sync + 'static>(&'r T);
 
diff --git a/lib/src/rocket.rs b/lib/src/rocket.rs
index 200693be..456e0e14 100644
--- a/lib/src/rocket.rs
+++ b/lib/src/rocket.rs
@@ -513,7 +513,7 @@ impl Rocket {
     ///     rocket::ignite()
     ///         .mount("/", routes![index])
     ///         .manage(MyValue(10))
-    /// #       .launch()
+    ///         .launch()
     /// # }
     /// }
     /// ```