doc: Add URL argument with http/https request

PR-URL: https://github.com/nodejs/node/pull/13405
Fixes: https://github.com/nodejs/node/issues/13383
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

1 files changed, 29 insertions, 6 deletions

diff --git a/doc/api/https.md b/doc/api/https.md
index 0f42366a70..f4000335a0 100644
--- a/doc/api/https.md
+++ b/doc/api/https.md
@@ -115,15 +115,20 @@ See [`http.listen()`][] for details.
 ## https.get(options[, callback])
 <!-- YAML
 added: v0.3.6
+changes:
+  - version: v7.5.0
+    pr-url: https://github.com/nodejs/node/pull/10638
+    description: The `options` parameter can be a WHATWG `URL` object.
 -->
-- `options` {Object | string} Accepts the same `options` as
+- `options` {Object | string | URL} Accepts the same `options` as
   [`https.request()`][], with the `method` always set to `GET`.
 - `callback` {Function}
 
 Like [`http.get()`][] but for HTTPS.
 
-`options` can be an object or a string. If `options` is a string, it is
-automatically parsed with [`url.parse()`][].
+`options` can be an object, a string, or a [`URL`][] object. If `options` is a
+string, it is automatically parsed with [`url.parse()`][]. If it is a [`URL`][]
+object, it will be automatically converted to an ordinary `options` object.
 
 Example:
 
@@ -153,8 +158,12 @@ Global instance of [`https.Agent`][] for all HTTPS client requests.
 ## https.request(options[, callback])
 <!-- YAML
 added: v0.3.6
+changes:
+  - version: v7.5.0
+    pr-url: https://github.com/nodejs/node/pull/10638
+    description: The `options` parameter can be a WHATWG `URL` object.
 -->
-- `options` {Object | string} Accepts all `options` from [`http.request()`][],
+- `options` {Object | string | URL} Accepts all `options` from [`http.request()`][],
   with some differences in default values:
   - `protocol` Defaults to `https:`
   - `port` Defaults to `443`.
@@ -168,8 +177,9 @@ The following additional `options` from [`tls.connect()`][] are also accepted wh
   custom [`Agent`][]:
   `pfx`, `key`, `passphrase`, `cert`, `ca`, `ciphers`, `rejectUnauthorized`, `secureProtocol`, `servername`
 
-`options` can be an object or a string. If `options` is a string, it is
-automatically parsed with [`url.parse()`][].
+`options` can be an object, a string, or a [`URL`][] object. If `options` is a
+string, it is automatically parsed with [`url.parse()`][]. If it is a [`URL`][]
+object, it will be automatically converted to an ordinary `options` object.
 
 Example:
 
@@ -235,7 +245,20 @@ const req = https.request(options, (res) => {
 });
 ```
 
+Example using a [`URL`][] as `options`:
+
+```js
+const { URL } = require('url');
+
+const options = new URL('https://abc:xyz@example.com');
+
+const req = https.request(options, (res) => {
+  // ...
+});
+```
+
 [`Agent`]: #https_class_https_agent
+[`URL`]: url.html#url_the_whatwg_url_api
 [`http.Agent`]: http.html#http_class_http_agent
 [`http.Server#keepAliveTimeout`]: http.html#http_server_keepalivetimeout
 [`http.Server#setTimeout()`]: http.html#http_server_settimeout_msecs_callback