From 41ac9e7873036e6903ab82ed2715735b938851a5 Mon Sep 17 00:00:00 2001
From: Jon Gjengset <jon@thesquareplanet.com>
Date: Wed, 21 Jun 2017 15:29:08 -0400
Subject: [PATCH] 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    | 7 +++++++
 src/header/common/transfer_encoding.rs | 7 +++++++
 src/http/request.rs                    | 4 ++++
 3 files changed, 18 insertions(+)

diff --git a/src/header/common/content_length.rs b/src/header/common/content_length.rs
index 382c7c09..68ba8104 100644
--- a/src/header/common/content_length.rs
+++ b/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
diff --git a/src/header/common/transfer_encoding.rs b/src/header/common/transfer_encoding.rs
index a5a93b3e..7f0dd70a 100644
--- a/src/header/common/transfer_encoding.rs
+++ b/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
diff --git a/src/http/request.rs b/src/http/request.rs
index d92f1556..223a8d6b 100644
--- a/src/http/request.rs
+++ b/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()); }