From fdcc250dbf74d317842f2f0931181379c41a6351 Mon Sep 17 00:00:00 2001
From: Alejandro Oviedo <alejandro.oviedo.g@gmail.com>
Date: Fri, 5 Feb 2016 10:48:41 -0300
Subject: [PATCH] doc: merging behavior of writeHead vs setHeader

---
 doc/api/http.markdown | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/doc/api/http.markdown b/doc/api/http.markdown
index fc55777acf6ada..257a676a5b5b47 100644
--- a/doc/api/http.markdown
+++ b/doc/api/http.markdown
@@ -724,6 +724,20 @@ response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
 Attempting to set a header field name that contains invalid characters will
 result in a [`TypeError`][] being thrown.
 
+When headers have been set with [`response.setHeader()`][], they will be merged with
+any headers passed to [`response.writeHead()`][], with the headers passed to
+[`response.writeHead()`][] given precedence.
+
+```js
+// returns content-type = text/plain
+const server = http.createServer((req,res) => {
+  res.setHeader('Content-Type', 'text/html');
+  res.setHeader('X-Foo', 'bar');
+  res.writeHead(200, {'Content-Type': 'text/plain'});
+  res.end('ok');
+});
+```
+
 ### response.setTimeout(msecs, callback)
 
 * `msecs` {Number}
@@ -825,6 +839,20 @@ be called before [`response.end()`][] is called.
 If you call [`response.write()`][] or [`response.end()`][] before calling this, the
 implicit/mutable headers will be calculated and call this function for you.
 
+When headers have been set with [`response.setHeader()`][], they will be merged with
+any headers passed to [`response.writeHead()`][], with the headers passed to
+[`response.writeHead()`][] given precedence.
+
+```js
+// returns content-type = text/plain
+const server = http.createServer((req,res) => {
+  res.setHeader('Content-Type', 'text/html');
+  res.setHeader('X-Foo', 'bar');
+  res.writeHead(200, {'Content-Type': 'text/plain'});
+  res.end('ok');
+});
+```
+
 Note that Content-Length is given in bytes not characters. The above example
 works because the string `'hello world'` contains only single byte characters.
 If the body contains higher coded characters then `Buffer.byteLength()`
@@ -1180,6 +1208,7 @@ There are a few special headers that should be noted.
 [`net.Socket`]: net.html#net_class_net_socket
 [`request.socket.getPeerCertificate()`]: tls.html#tls_tlssocket_getpeercertificate_detailed
 [`response.end()`]: #http_response_end_data_encoding_callback
+[`response.setHeader()`]: #http_response_setheader_name_value
 [`response.write()`]: #http_response_write_chunk_encoding_callback
 [`response.write(data, encoding)`]: #http_response_write_chunk_encoding_callback
 [`response.writeContinue()`]: #http_response_writecontinue