http(s) agent docs for createConnection don't reflect reality

[tkennedy1-godaddy]

Affected URL(s)

https://nodejs.org/docs/latest/api/http.html#agentcreateconnectionoptions-callback

Description of the problem

In http agents, the createConnection function is a direct passthrough to net.connect, which the function signature does not take, nor call a callback.

In https agents, the createConnection function has a wildly different signature, but the https docs say "it's the same as the http" agent. But again, there is no callback for this function and none is called.

[lpinca]

Quoting the documentation

By default, this function is the same as net.createConnection(). However, 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

The callback is for custom implementations to allow asynchronous creation of the socket. See

node/lib/_http_agent.js

Line 324 in f552c86

const newSocket = this.createConnection(options, oncreate);

.