doc: update http.md for consistency and clarity

The HTTP Keep-Alive text was inconsistent. These changes follow the
following rules

* When referring to flag used in code, it should always be written using
  backticks and in camel case. E.g. `keepAlive`.
* When referring to the mechanism Keep-Alive functionality as described
  in the HTTP 1.1 RFC, it is written as 'HTTP Keep-Alive', without the
  use of backticks.
* When referring to the request header, it should always use backticks
  and be written as `Connection: keep-alive`.

This commit also includes some changes to how `http.Agent` is
referenced. When `Agent` is used as a reference to an object or
instance, backticks should always be used.

And lastly, the documentation about `Agent` behavior around HTTP
Keep-Alive has been clarified and improved.

Fixes: nodejs#10567
PR-URL: nodejs#10715

Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

doc/api/http.md

@@ -48,26 +48,32 @@ list like the following:
 added: v0.3.4
 -->
 
-The HTTP Agent is used for pooling sockets used in HTTP client
-requests.
-
-The HTTP Agent also defaults client requests to using
-`Connection: keep-alive`. If no pending HTTP requests are waiting on a
-socket to become free the socket is closed. This means that Node.js's
-pool has the benefit of keep-alive when under load but still does not
-require developers to manually close the HTTP clients using
-KeepAlive.
-
-If you opt into using HTTP KeepAlive, you can create an Agent object
-with that flag set to `true`.  (See the [constructor options][].)
-Then, the Agent will keep unused sockets in a pool for later use.  They
-will be explicitly marked so as to not keep the Node.js process running.
-However, it is still a good idea to explicitly [`destroy()`][] KeepAlive
-agents when they are no longer in use, so that the Sockets will be shut
-down.
-
-Sockets are removed from the agent's pool when the socket emits either
-a `'close'` event or a special `'agentRemove'` event. This means that if
+An `Agent` is responsible for managing connection persistence
+and reuse for HTTP clients. It maintains a queue of pending requests
+for a given host and port, reusing a single socket connection for each
+until the queue is empty, at which time the socket is either destroyed
+or put into a pool where it is kept to be used again for requests to the
+same host and port. Whether it is destroyed or pooled depends on the
+`keepAlive` [option](#http_new_agent_options).
+
+Pooled connections have TCP Keep-Alive enabled for them, but servers may
+still close idle connections, in which case they will be removed from the
+pool and a new connection will be made when a new HTTP request is made for
+that host and port. Servers may also refuse to allow multiple requests
+over the same connection, in which case the connection will have to be
+remade for every request and cannot be pooled. The `Agent` will still make
+the requests to that server, but each one will occur over a new connection.
+
+When a connection is closed by the client or the server, it is removed
+from the pool. Any unused sockets in the pool will be unrefed so as not
+to keep the Node.js process running when there are no outstanding requests.
+(see [socket.unref()]).
+
+It is good practice, to [`destroy()`][] an `Agent` instance when it is no
+longer in use, because unused sockets consume OS resources.
+
+Sockets are removed from an agent's pool when the socket emits either
+a `'close'` event or an `'agentRemove'` event. This means that if
 you intend to keep one HTTP request open for a long time and don't
 want it to stay in the pool you can do something along the lines of:
 
@@ -79,7 +85,11 @@ http.get(options, (res) => {
 });
 ```
 
-Alternatively, you could just opt out of pooling entirely using
+You may also use an agent for an individual request. By providing
+`{agent: false}` as an option to the `http.get()` or `http.request()`
+functions, a one-time use `Agent` with default options will be used
+for the client connection.
+
 `agent:false`:
 
 ```js
@@ -100,11 +110,13 @@ added: v0.3.4
 
 * `options` {Object} Set of configurable options to set on the agent.
   Can have the following fields:
-  * `keepAlive` {Boolean} Keep sockets around in a pool to be used by
-    other requests in the future. Default = `false`
-  * `keepAliveMsecs` {Integer} When using HTTP KeepAlive, how often
-    to send TCP KeepAlive packets over sockets being kept alive.
-    Default = `1000`.  Only relevant if `keepAlive` is set to `true`.
+  * `keepAlive` {Boolean} Keep sockets around even when there are no
+    outstanding requests, so they can be used for future requests without
+    having to reestablish a TCP connection. Default = `false`
+  * `keepAliveMsecs` {Integer} When using the `keepAlive` option, specifies
+    the [initial delay](#net_socket_setkeepalive_enable_initialdelay)
+    for TCP Keep-Alive packets. Ignored when the
+    `keepAlive` option is `false` or `undefined`. Default = `1000`.
   * `maxSockets` {Number} Maximum number of sockets to allow per
     host.  Default = `Infinity`.
   * `maxFreeSockets` {Number} Maximum number of sockets to leave open
@@ -114,7 +126,7 @@ added: v0.3.4
 The default [`http.globalAgent`][] that is used by [`http.request()`][] has all
 of these values set to their respective defaults.
 
-To configure any of them, you must create your own [`http.Agent`][] object.
+To configure any of them, you must create your own [`http.Agent`][] instance.
 
 ```js
 const http = require('http');
@@ -136,7 +148,7 @@ added: v0.11.4
 Produces a socket/stream to be used for HTTP requests.
 
 By default, this function is the same as [`net.createConnection()`][]. However,
-custom Agents may override this method in case greater flexibility is desired.
+custom agents may override this method in case greater flexibility is desired.
 
 A socket/stream can be supplied in one of two ways: by returning the
 socket/stream from this function, or by passing the socket/stream to `callback`.
@@ -151,7 +163,7 @@ added: v0.11.4
 Destroy any sockets that are currently in use by the agent.
 
 It is usually not necessary to do this.  However, if you are using an
-agent with KeepAlive enabled, then it is best to explicitly shut down
+agent with `keepAlive` enabled, then it is best to explicitly shut down
 the agent when you know that it will no longer be used.  Otherwise,
 sockets may hang open for quite a long time before the server
 terminates them.
@@ -164,7 +176,7 @@ added: v0.11.4
 * {Object}
 
 An object which contains arrays of sockets currently awaiting use by
-the Agent when HTTP KeepAlive is used.  Do not modify.
+the agent when `keepAlive` is enabled.  Do not modify.
 
 ### agent.getName(options)
 <!-- YAML
@@ -179,8 +191,8 @@ added: v0.11.4
 * Returns: {String}
 
 Get a unique name for a set of request options, to determine whether a
-connection can be reused.  In the http agent, this returns
-`host:port:localAddress`.  In the https agent, the name includes the
+connection can be reused.  For an HTTP agent, this returns
+`host:port:localAddress`.  For an HTTPS agent, the name includes the
 CA, cert, ciphers, and other HTTPS/TLS-specific options that determine
 socket reusability.
 
@@ -191,7 +203,7 @@ added: v0.11.7
 
 * {Number}
 
-By default set to 256.  For Agents supporting HTTP KeepAlive, this
+By default set to 256.  For agents with `keepAlive` enabled, this
 sets the maximum number of sockets that will be left open in the free
 state.
 
@@ -224,7 +236,7 @@ added: v0.3.6
 * {Object}
 
 An object which contains arrays of sockets currently in use by the
-Agent.  Do not modify.
+agent.  Do not modify.
 
 ## Class: http.ClientRequest
 <!-- YAML
@@ -652,7 +664,7 @@ added: v0.1.0
 * `response` {http.ServerResponse}
 
 Emitted each time there is a request. Note that there may be multiple requests
-per connection (in the case of keep-alive connections).
+per connection (in the case of HTTP Keep-Alive connections).
 
 ### Event: 'upgrade'
 <!-- YAML
@@ -1489,7 +1501,7 @@ added: v0.5.9
 
 * {http.Agent}
 
-Global instance of Agent which is used as the default for all HTTP client
+Global instance of `Agent` which is used as the default for all HTTP client
 requests.
 
 ## http.request(options[, callback])
@@ -1519,15 +1531,13 @@ added: v0.3.6
   * `headers` {Object} An object containing request headers.
   * `auth` {String} Basic authentication i.e. `'user:password'` to compute an
     Authorization header.
-  * `agent` {http.Agent|Boolean} Controls [`Agent`][] behavior. When an Agent
-    is used request will default to `Connection: keep-alive`. Possible values:
+  * `agent` {http.Agent|Boolean} Controls [`Agent`][] behavior. Possible values:
    * `undefined` (default): use [`http.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`.
+   * `false`: causes a new `Agent` with default values to be used.
   * `createConnection` {Function} A function that produces a socket/stream to
     use for the request when the `agent` option is not used. This can be used to
-    avoid creating a custom Agent class just to override the default
+    avoid creating a custom `Agent` class just to override the default
     `createConnection` function. See [`agent.createConnection()`][] for more
     details.
   * `timeout` {Integer}: A number specifying the socket timeout in milliseconds.
@@ -1648,3 +1658,4 @@ There are a few special headers that should be noted.
 [constructor options]: #http_new_agent_options
 [Readable Stream]: stream.html#stream_class_stream_readable
 [Writable Stream]: stream.html#stream_class_stream_writable
+[socket.unref()]: net.html#net_socket_unref