doc: explain HTTP writeHead()'s fast path behavior

calling writeHead() into a Response object that has no headers already
set causes getHeader() to return undefined, even if the header was set
in the writeHead() function call. Explain this behavior as an
optimiation as opposed to a bug.

Fixes: #10354
PR-URL: #21289

Reviewed-By: Anatoli Papirovski <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Timothy Gu <[email protected]>
Reviewed-By: Vse Mozhet Byt <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>

doc/api/http.md

@@ -1271,6 +1271,13 @@ const server = http.createServer((req, res) => {
 });
 ```
 
+If [`response.writeHead()`][] method is called and this method has not been
+called, it will directly write the supplied header values onto the network
+channel without caching internally, and the [`response.getHeader()`][] on the
+header will not yield the expected result. If progressive population of headers
+is desired with potential future retrieval and modification, use
+[`response.setHeader()`][] instead of [`response.writeHead()`][].
+
 ### response.setTimeout(msecs[, callback])
 <!-- YAML
 added: v0.9.12
@@ -1438,6 +1445,13 @@ 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.
 
+If this method is called and [`response.setHeader()`][] has not been called,
+it will directly write the supplied header values onto the network channel
+without caching internally, and the [`response.getHeader()`][] on the header
+will not yield the expected result. If progressive population of headers is
+desired with potential future retrieval and modification, use
+[`response.setHeader()`][] instead.
+
 ```js
 // returns content-type = text/plain
 const server = http.createServer((req, res) => {