Document Body. Derive Clone/Copy/PartialEq appropriately in response module.

lib/src/response/content.rs

@@ -3,10 +3,10 @@
 //! # Usage
 //!
 //! Each type wraps a given responder. The `Responder` implementation of each
-//! type simply sets the Content-Type and delegates the remainder of the
+//! type replaces the Content-Type of the wrapped responder and delegates the
-//! response to the wrapped responder. This is useful for setting the
+//! remainder of the response to the wrapped responder. This allows for setting
-//! Content-Type of a type that doesn't set it itself or for overriding one that
+//! the Content-Type of a type that doesn't set it itself or for overriding one
-//! does.
+//! that does.
 //!
 //! # Example
 //!
@@ -24,24 +24,24 @@
 use response::{Response, Responder};
 use http::{Status, ContentType};
 
-/// Set the Content-Type to any arbitrary value.
+/// Sets the Content-Type of a `Responder` to a chosen value.
 ///
 /// Delagates the remainder of the response to the wrapped responder.
 ///
 /// # Example
 ///
-/// Set the Content-Type of a string to be PDF.
+/// Set the Content-Type of a string to PDF.
 ///
 /// ```rust
 /// use rocket::response::content::Content;
 /// use rocket::http::ContentType;
 ///
-/// let response = Content(ContentType::from_extension("pdf"), "Hi.");
+/// let response = Content(ContentType::PDF, "Hi.");
 /// ```
-#[derive(Debug)]
+#[derive(Debug, Clone, PartialEq)]
 pub struct Content<R>(pub ContentType, pub R);
 
-/// Sets the Content-Type of the response to the wrapped `ContentType` then
+/// Overrides the Content-Type of the response to the wrapped `ContentType` then
 /// delegates the remainder of the response to the wrapped responder.
 impl<'r, R: Responder<'r>> Responder<'r> for Content<R> {
     #[inline(always)]
@@ -56,14 +56,14 @@ impl<'r, R: Responder<'r>> Responder<'r> for Content<R> {
 macro_rules! ctrs {
     ($($name:ident: $name_str:expr, $ct_str:expr),+) => {
         $(
-            #[doc="Set the `Content-Type` of the response to <b>"]
+            #[doc="Override the `Content-Type` of the response to <b>"]
             #[doc=$name_str]
             #[doc="</b>, or <i>"]
             #[doc=$ct_str]
             #[doc="</i>."]
             ///
             /// Delagates the remainder of the response to the wrapped responder.
-            #[derive(Debug)]
+            #[derive(Debug, Clone, PartialEq)]
             pub struct $name<R>(pub R);
 
             /// Sets the Content-Type of the response then delegates the

lib/src/response/mod.rs

@@ -1,17 +1,23 @@
 //! Types and traits to build and send responses.
 //!
 //! The return type of a Rocket handler can be any type that implements the
-//! [Responder](trait.Responder.html) trait. This module contains several such
+//! [Responder](trait.Responder.html) trait. Among other things, this module
-//! types.
+//! contains several such types.
 //!
 //! # Composing
 //!
 //! Many of the built-in `Responder` types _chain_ responses: they take in
-//! another `Responder` and simply add, remove, or change information in the
+//! another `Responder` and add, remove, or change information in the response.
-//! response. In other words, many `Responder` types are built to compose well.
+//! In other words, many `Responder` types are built to compose well. As a
-//! As a result, you'll often have types of the form `A<B<C>>` consisting of
+//! result, you'll often have types of the form `A<B<C>>` consisting of three
-//! three `Responder`s `A`, `B`, and `C`. This is normal and encouraged as the
+//! `Responder`s `A`, `B`, and `C`. This is normal and encouraged as the type
-//! type names typically illustrate the intended response.
+//! names typically illustrate the intended response.
+//!
+//! # Contrib
+//!
+//! The [contrib crate](/rocket_contrib) contains several useful `Responder`s
+//! including [Template](/rocket_contrib/struct.Template.html) and
+//! [JSON](/rocket_contrib/struct.JSON.html).
 
 mod responder;
 mod redirect;
@@ -30,7 +36,7 @@ pub use self::redirect::Redirect;
 pub use self::flash::Flash;
 pub use self::named_file::NamedFile;
 pub use self::stream::Stream;
-pub use self::content::Content;
 pub use self::failure::Failure;
+#[doc(inline)] pub use self::content::Content;
 
 pub type Result<'r> = ::std::result::Result<self::Response<'r>, ::http::Status>;

lib/src/response/response.rs

@@ -5,14 +5,20 @@ use http::{Header, HeaderMap};
 use response::Responder;
 use http::Status;
 
+/// The default size, in bytes, of a chunk for streamed responses.
 pub const DEFAULT_CHUNK_SIZE: u64 = 4096;
 
+#[derive(PartialEq, Clone, Hash)]
+/// The body of a response: can be sized or streamed/chunked.
 pub enum Body<T> {
+    /// A fixed-size body.
     Sized(T, u64),
+    /// A streamed/chunked body, akin to `Transfer-Encoding: chunked`.
     Chunked(T, u64)
 }
 
 impl<T> Body<T> {
+    /// Returns a mutable borrow to the inner type.
     pub fn as_mut(&mut self) -> Body<&mut T> {
         match *self {
             Body::Sized(ref mut b, n) => Body::Sized(b, n),
@@ -20,6 +26,9 @@ impl<T> Body<T> {
         }
     }
 
+    /// Consumes `self`. Passes the inner type as a parameter to `f` and
+    /// constructs a new body with the size of `self` and the return value of
+    /// the call to `f`.
     pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Body<U> {
         match self {
             Body::Sized(b, n) => Body::Sized(f(b), n),
@@ -29,6 +38,8 @@ impl<T> Body<T> {
 }
 
 impl<T: io::Read> Body<T> {
+    /// Attepts to read `self` into a `String` and returns it. If reading or
+    /// conversion fails, returns `None`.
     pub fn into_string(self) -> Option<String> {
         let (mut body, mut string) = match self {
             Body::Sized(b, size) => (b, String::with_capacity(size as usize)),
@@ -162,7 +173,7 @@ impl<'r> ResponseBuilder<'r> {
 // `join`? Maybe one does one thing, the other does another? IE: `merge`
 // replaces, `join` adds. One more thing that could be done: we could make it
 // some that _some_ headers default to replacing, and other to joining.
-/// Return type of a thing.
+/// An HTTP response.
 #[derive(Default)]
 pub struct Response<'r> {
     status: Option<Status>,

lib/src/response/status.rs

@@ -1,8 +1,8 @@
 //! Contains types that set the status code and correspoding headers of a
 //! response.
 //!
-//! These types are designed to make it easier to respond with a given status
+//! These types are designed to make it easier to respond correctly with a given
-//! code. Each type takes in the minimum number of parameters required to
+//! status code. Each type takes in the minimum number of parameters required to
 //! construct a proper response with that status code. Some types take in
 //! responders; when they do, the responder finalizes the response by writing
 //! out additional headers and, importantly, the body of the response.
@@ -28,6 +28,7 @@ use http::Status;
 /// let content = "{ 'resource': 'Hello, world!' }";
 /// let response = status::Created(url, Some(content));
 /// ```
+#[derive(Debug, Clone, PartialEq)]
 pub struct Created<R>(pub String, pub Option<R>);
 
 /// Sets the status code of the response to 201 Created. Sets the `Location`
@@ -90,6 +91,7 @@ impl<'r, R: Responder<'r> + Hash> Responder<'r> for Created<R> {
 ///
 /// let response = status::Accepted(Some("processing"));
 /// ```
+#[derive(Debug, Clone, PartialEq)]
 pub struct Accepted<R>(pub Option<R>);
 
 /// Sets the status code of the response to 202 Accepted. If the responder is
@@ -115,6 +117,7 @@ impl<'r, R: Responder<'r>> Responder<'r> for Accepted<R> {
 /// let response = status::NoContent;
 /// ```
 // TODO: This would benefit from Header support.
+#[derive(Debug, Clone, PartialEq)]
 pub struct NoContent;
 
 /// Sets the status code of the response to 204 No Content. The body of the
@@ -135,6 +138,7 @@ impl<'r> Responder<'r> for NoContent {
 ///
 /// let response = status::Reset;
 /// ```
+#[derive(Debug, Copy, Clone, PartialEq)]
 pub struct Reset;
 
 /// Sets the status code of the response to 205 Reset Content. The body of the
@@ -155,6 +159,7 @@ impl<'r> Responder<'r> for Reset {
 ///
 /// let response = status::Custom(Status::ImATeapot, "Hi!");
 /// ```
+#[derive(Debug, Clone, PartialEq)]
 pub struct Custom<R>(pub Status, pub R);
 
 /// Sets the status code of the response and then delegates the remainder of the