doc: improve http.request and https.request opts

This adds a few previously undocumented option to both functions.

PR-URL: #1551
Fixes: #1082
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>

Author: silverwind

doc/api/http.markdown

@@ -460,10 +460,14 @@ Options:
 
 - `host`: A domain name or IP address of the server to issue the request to.
   Defaults to `'localhost'`.
-- `hostname`: To support `url.parse()` `hostname` is preferred over `host`
+- `hostname`: Alias for `host`. To support `url.parse()` `hostname` is
+  preferred over `host`.
+- `family`: IP address family to use when resolving `host` and `hostname`.
+  Valid values are `4` or `6`. When unspecified, both IP v4 and v6 will be
+  used.
 - `port`: Port of remote server. Defaults to 80.
 - `localAddress`: Local interface to bind for network connections.
-- `socketPath`: Unix Domain Socket (use one of host:port or socketPath)
+- `socketPath`: Unix Domain Socket (use one of host:port or socketPath).
 - `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
 - `path`: Request path. Defaults to `'/'`. Should include query string if any.
   E.G. `'/index.html?page=12'`. An exception is thrown when the request path
@@ -474,7 +478,7 @@ Options:
   Authorization header.
 - `agent`: Controls [Agent][] behavior. When an Agent is used request will
   default to `Connection: keep-alive`. Possible values:
- - `undefined` (default): use [global Agent][] for this host and port.
+ - `undefined` (default): use [globalAgent][] for this host and port.
  - `Agent` object: explicitly use the passed in `Agent`.
  - `false`: opts out of connection pooling with an Agent, defaults request to
    `Connection: close`.
@@ -1069,7 +1073,7 @@ authentication details.
 [EventEmitter]: events.html#events_class_events_eventemitter
 [Readable Stream]: stream.html#stream_class_stream_readable
 [Writable Stream]: stream.html#stream_class_stream_writable
-[global Agent]: #http_http_globalagent
+[globalAgent]: #http_http_globalagent
 [http.ClientRequest]: #http_class_http_clientrequest
 [http.IncomingMessage]: #http_http_incomingmessage
 [http.ServerResponse]: #http_class_http_serverresponse

doc/api/https.markdown

@@ -103,11 +103,19 @@ The options argument has the following options
 
 - `host`: A domain name or IP address of the server to issue the request to.
   Defaults to `'localhost'`.
-- `hostname`: To support `url.parse()` `hostname` is preferred over `host`
+- `hostname`: Alias for `host`. To support `url.parse()` `hostname` is
+  preferred over `host`.
+- `family`: IP address family to use when resolving `host` and `hostname`.
+  Valid values are `4` or `6`. When unspecified, both IP v4 and v6 will be
+  used.
 - `port`: Port of remote server. Defaults to 443.
+- `localAddress`: Local interface to bind for network connections.
+- `socketPath`: Unix Domain Socket (use one of host:port or socketPath).
 - `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
 - `path`: Request path. Defaults to `'/'`. Should include query string if any.
-  E.G. `'/index.html?page=12'`
+  E.G. `'/index.html?page=12'`. An exception is thrown when the request path
+  contains illegal characters. Currently, only spaces are rejected but that
+  may change in the future.
 - `headers`: An object containing request headers.
 - `auth`: Basic authentication i.e. `'user:password'` to compute an
   Authorization header.