doc: clarify http.Agent constructor options

PR-URL: #26412 Fixes: #26357 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Masashi Hirano <shisama07@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

Author: lpinca

doc/api/http.md

@@ -116,13 +116,19 @@ added: v0.3.4
  Can have the following fields:
  * `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`.
+ having to reestablish a TCP connection. Not to be confused with the
+ `keep-alive` value of the `Connection` header. The `Connection: keep-alive`
+ header is always sent when using an agent except when the `Connection`
+ header is explicitly specified or when the `keepAlive` and `maxSockets`
+ options are respectively set to `false` and `Infinity`, in which case
+ `Connection: close` will be used. **Default:** `false`.
  * `keepAliveMsecs` {number} When using the `keepAlive` option, specifies
  the [initial delay](net.html#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`.
+ host. Each request will use a new socket until the maximum is reached.
+ **Default:** `Infinity`.
  * `maxFreeSockets` {number} Maximum number of sockets to leave open
  in a free state. Only relevant if `keepAlive` is set to `true`.
  **Default:** `256`.