docs(headers): clarify TransferEncoding xor ContentLength

Update the docs for `Content-Length` and `Transfer-Encoding` to mention
that they are mutually exclusive, and that setting one will unset the
other, in accordance with RFC7230.

Also expand the docs for `Request::set_body` to say that chunked
encoding is used by default, and mention how to disable this feature.

src/header/common/content_length.rs

@@ -14,6 +14,13 @@ use header::{Header, Raw, parsing};
 /// body, the Content-Length indicates the size of the selected
 /// representation.
 ///
+/// Note that setting this header will *remove* any previously set
+/// `Transfer-Encoding` header, in accordance with
+/// [RFC7230](http://tools.ietf.org/html/rfc7230#section-3.3.2):
+///
+/// > A sender MUST NOT send a Content-Length header field in any message
+/// that > contains a Transfer-Encoding header field.
+///
 /// # ABNF
 /// ```plain
 /// Content-Length = 1*DIGIT

src/header/common/transfer_encoding.rs

@@ -8,6 +8,13 @@ header! {
     /// corresponding to the sequence of transfer codings that have been (or
     /// will be) applied to the payload body in order to form the message
     /// body.
+    ///
+    /// Note that setting this header will *remove* any previously set
+    /// `Content-Length` header, in accordance with
+    /// [RFC7230](http://tools.ietf.org/html/rfc7230#section-3.3.2):
+    ///
+    /// > A sender MUST NOT send a Content-Length header field in any message
+    /// > that contains a Transfer-Encoding header field.
     /// 
     /// # ABNF
     /// ```plain

src/http/request.rs

@@ -91,6 +91,10 @@ impl<B> Request<B> {
     pub fn set_version(&mut self, version: HttpVersion) { self.version = version; }
 
     /// Set the body of the request.
+    ///
+    /// By default, the body will be sent using `Transfer-Encoding: chunked`. To
+    /// override this behavior, manually set a [`ContentLength`] header with the
+    /// length of `body`.
     #[inline]
     pub fn set_body<T: Into<B>>(&mut self, body: T) { self.body = Some(body.into()); }