Document the content module, complete response documentation.

lib/src/http/content_type.rs

@@ -19,7 +19,8 @@ pub struct ContentType(pub TopLevel, pub SubLevel, pub Option<Vec<Param>>);
 
 macro_rules! ctrs {
     ($($(#[$attr:meta])* | $name:ident: $top:ident/$sub:ident),+) => {
-        $($(#[$attr])*
+        $
+            ($(#[$attr])*
             #[inline(always)]
             pub fn $name() -> ContentType {
                 ContentType::of(TopLevel::$top, SubLevel::$sub)
@@ -29,7 +30,8 @@ macro_rules! ctrs {
 
 macro_rules! checkers {
     ($($(#[$attr:meta])* | $name:ident: $top:ident/$sub:ident),+) => {
-        $($(#[$attr])*
+        $(
+            $(#[$attr])*
             #[inline(always)]
             pub fn $name(&self) -> bool {
                 self.0 == TopLevel::$top && self.1 == SubLevel::$sub
@@ -131,7 +133,10 @@ impl ContentType {
         | xml: Text/Xml,
 
         /// Returns a `ContentType` representing HTML, i.e, `text/html`.
-        | html: Text/Html
+        | html: Text/Html,
+
+        /// Returns a `ContentType` representing plain text, i.e, `text/plain`.
+        | plain: Text/Plain
     }
 
     /// Returns true if this content type is not one of the standard content

lib/src/response/content.rs

@@ -1,11 +1,50 @@
+//! Contains types that set the Content-Type of a response.
+//!
+//! # Usage
+//!
+//! Each type wraps a given responder. The `Responder` implementation of each
+//! type simply sets the Content-Type and delegates the remainder of the
+//! response to the wrapped responder. This is useful for setting the
+//! Content-Type of a type that doesn't set it itself or for overriding one that
+//! does.
+//!
+//! # Example
+//!
+//! The following snippet creates an `HTML` content response for a string.
+//! Normally, raw strings set their response Content-Type to `text/plain`. By
+//! using the `HTML` content response, the Content-Type will be set to
+//! `text/html` instead.
+//!
+//! ```rust
+//! use rocket::response::content;
+//!
+//! let response = content::HTML("<h1>Hello, world!</h1>");
+//! ```
+
 use response::{Responder, Outcome};
 use http::hyper::{header, FreshHyperResponse};
 use http::mime::{Mime, TopLevel, SubLevel};
 use http::ContentType;
 
+/// Set the Content-Type to any arbitrary value.
+///
+/// Delagates the remainder of the response to the wrapped responder.
+///
+/// # Example
+///
+/// Set the Content-Type of a string to be PDF.
+///
+/// ```rust
+/// use rocket::response::content::Content;
+/// use rocket::http::ContentType;
+///
+/// let response = Content(ContentType::from_extension("pdf"), "Hi.");
+/// ```
 #[derive(Debug)]
 pub struct Content<T: Responder>(pub ContentType, pub T);
 
+/// Sets the Content-Type of the response to the wrapped `ContentType` then
+/// delegates the remainder of the response to the wrapped responder.
 impl<T: Responder> Responder for Content<T> {
     fn respond<'b>(&mut self, mut res: FreshHyperResponse<'b>) -> Outcome<'b> {
         res.headers_mut().set(header::ContentType(self.0.clone().into()));
@@ -13,23 +52,46 @@ impl<T: Responder> Responder for Content<T> {
     }
 }
 
-macro_rules! impl_data_type_responder {
-    ($name:ident: $top:ident/$sub:ident) => (
-    #[derive(Debug)]
-    pub struct $name<T: Responder>(pub T);
+macro_rules! ctrs {
+    ($($(#[$attr:meta])* | $name:ident: $top:ident/$sub:ident),+) => {
+        $(
+            $(#[$attr])*
+            ///
+            /// Delagates the remainder of the response to the wrapped responder.
+            #[derive(Debug)]
+            pub struct $name<T: Responder>(pub T);
 
-    impl<T: Responder> Responder for $name<T> {
-        fn respond<'b>(&mut self, mut res: FreshHyperResponse<'b>) -> Outcome<'b> {
-            let mime = Mime(TopLevel::$top, SubLevel::$sub, vec![]);
-            res.headers_mut().set(header::ContentType(mime));
-            self.0.respond(res)
-        }
-    })
+            /// Sets the Content-Type of the response then delegates the
+            /// remainder of the response to the wrapped responder.
+            impl<T: Responder> Responder for $name<T> {
+                #[inline(always)]
+                fn respond<'b>(&mut self, mut res: FreshHyperResponse<'b>) -> Outcome<'b> {
+                    let mime = Mime(TopLevel::$top, SubLevel::$sub, vec![]);
+                    res.headers_mut().set(header::ContentType(mime));
+                    self.0.respond(res)
+                }
+            })+
+    }
+}
+
+ctrs! {
+    /// Sets the Content-Type of the response to JSON (`application/json`).
+    | JSON: Application/Json,
+
+    /// Sets the Content-Type of the response to XML (`text/xml`).
+    | XML: Text/Xml,
+
+    /// Sets the Content-Type of the response to HTML (`text/html`).
+    | HTML: Text/Html,
+
+    /// Sets the Content-Type of the response to plain text (`text/plain`).
+    | Plain: Text/Plain,
+
+    /// Sets the Content-Type of the response to CSS (`text/css`).
+    | CSS: Text/Css,
+
+    /// Sets the Content-Type of the response to JavaScript
+    /// (`application/javascript`).
+    | JavaScript: Application/Javascript
 }
 
-impl_data_type_responder!(JSON: Application/Json);
-impl_data_type_responder!(XML: Application/Xml);
-impl_data_type_responder!(HTML: Text/Html);
-impl_data_type_responder!(Plain: Text/Plain);
-impl_data_type_responder!(CSS: Text/Css);
-impl_data_type_responder!(JavaScript: Application/Javascript);