doc: Options passed needlessly to https request object and agent prop

[netanel-haber]

📗 API Reference Docs Problem

• Version: v14.12.0

Location

Affected URL(s):

• https://nodejs.org/api/https.html#https_https_request_options_callback

Description

In the following example provided for the https.request method, the request config object is passed both to the top level https request object, and to the agent property of said object.
This seems to either be a typo, or unclear. I would expect to see the following:

• "key" and "cert" should be provided to the agent object only, and should not appear at the top level of the options object.
• The properties that comprise the URL object ("hostname", "port", "path" and "method") should not be provided to the agent object.

I think this would avoid confusion.

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
};
options.agent = new https.Agent(options);

const req = https.request(options, (res) => {
  // ...
});

[dev-script]

Hi @netanel-haber , I would like to work on this issue.

[netanel-haber]

The question is, if it's really an issue at all or just my misunderstanding/a general styling decision that was made for the docs.

[lpinca]

@netanel-haber I think this was done for simplicity to avoid creating two options objects. Feel free to open a PR if you think that using two options objects clarifies the example. I personally don't mind.

[netanel-haber]

Thanks for the reply - Where can I find the format for posting prs to this repo?

[lpinca]

See https://github.com/nodejs/node/blob/master/doc/guides/contributing/pull-requests.md