doc: improve http.setHeader and getHeader typeinfo

http.setHeader() coerces input values.
http.getHeader() returns the type as passed to setHeader().

PR-URL: nodejs#19902
Fixes: nodejs#13825
Reviewed-By: Chen Gang <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: James M Snell <[email protected]>

doc/api/http.md

@@ -551,13 +551,24 @@ added: v1.6.0
 -->
 
 * `name` {string}
-* Returns: {string}
+* Returns: {any}
 
 Reads out a header on the request. Note that the name is case insensitive.
+The type of the return value depends on the arguments provided to
+[`request.setHeader()`][].
 
 Example:
 ```js
+request.setHeader('content-type', 'text/html');
+request.setHeader('Content-Length', Buffer.byteLength(body));
+request.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
 const contentType = request.getHeader('Content-Type');
+// contentType is 'text/html'
+const contentLength = request.getHeader('Content-Length');
+// contentLength is of type number
+const setCookie = request.getHeader('set-cookie');
+// setCookie is of type string[]
+
 ```
 
 ### request.removeHeader(name)
@@ -580,11 +591,14 @@ added: v1.6.0
 -->
 
 * `name` {string}
-* `value` {string}
+* `value` {any}
 
 Sets a single header value for headers object. If this header already exists in
 the to-be-sent headers, its value will be replaced. Use an array of strings
-here to send multiple headers with the same name.
+here to send multiple headers with the same name. Non-string values will be
+stored without modification. Therefore, [`request.getHeader()`][] may return
+non-string values. However, the non-string values will be converted to strings
+for network transmission.
 
 Example:
 ```js
@@ -1044,15 +1058,24 @@ added: v0.4.0
 -->
 
 * `name` {string}
-* Returns: {string}
+* Returns: {any}
 
 Reads out a header that's already been queued but not sent to the client.
-Note that the name is case insensitive.
+Note that the name is case insensitive. The type of the return value depends
+on the arguments provided to [`response.setHeader()`][].
 
 Example:
 
 ```js
+response.setHeader('Content-Type', 'text/html');
+response.setHeader('Content-Length', Buffer.byteLength(body));
+response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
 const contentType = response.getHeader('content-type');
+// contentType is 'text/html'
+const contentLength = response.getHeader('Content-Length');
+// contentLength is of type number
+const setCookie = response.getHeader('set-cookie');
+// setCookie is of type string[]
 ```
 
 ### response.getHeaderNames()
@@ -1163,11 +1186,14 @@ added: v0.4.0
 -->
 
 * `name` {string}
-* `value` {string | string[]}
+* `value` {any}
 
 Sets a single header value for implicit headers. If this header already exists
 in the to-be-sent headers, its value will be replaced. Use an array of strings
-here to send multiple headers with the same name.
+here to send multiple headers with the same name. Non-string values will be
+stored without modification. Therefore, [`response.getHeader()`][] may return
+non-string values. However, the non-string values will be converted to strings
+for network transmission.
 
 Example:
 
@@ -1965,11 +1991,14 @@ not abort the request or do anything besides add a `'timeout'` event.
 [`net.createConnection()`]: net.html#net_net_createconnection_options_connectlistener
 [`removeHeader(name)`]: #http_request_removeheader_name
 [`request.end()`]: #http_request_end_data_encoding_callback
+[`request.getHeader()`]: #http_request_getheader_name
+[`request.setHeader()`]: #http_request_setheader_name_value
 [`request.setTimeout()`]: #http_request_settimeout_timeout_callback
 [`request.socket`]: #http_request_socket
 [`request.socket.getPeerCertificate()`]: tls.html#tls_tlssocket_getpeercertificate_detailed
 [`request.write(data, encoding)`]: #http_request_write_chunk_encoding_callback
 [`response.end()`]: #http_response_end_data_encoding_callback
+[`response.getHeader()`]: #http_response_getheader_name
 [`response.setHeader()`]: #http_response_setheader_name_value
 [`response.socket`]: #http_response_socket
 [`response.write()`]: #http_response_write_chunk_encoding_callback