doc/url: various improvements to WHATWG API

Also remove executable bit from doc/api/url.md's mode.

PR-URL: https://github.com/nodejs/node/pull/11330
Fixes: 4757ddcce10af04 "doc: add basic documentation for WHATWG URL API"
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

1 files changed, 195 insertions, 40 deletions

diff --git a/doc/api/url.md b/doc/api/url.md
index d81c31d126..470357e089 100755..100644
--- a/doc/api/url.md
+++ b/doc/api/url.md
@@ -311,6 +311,35 @@ console.log(myURL.pathname); // /foo
 *Note*: Using the `delete` keyword (e.g. `delete myURL.protocol`,
 `delete myURL.pathname`, etc) has no effect but will still return `true`.
 
+A comparison between this API and `url.parse()` is given below. Above the URL
+`'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`, properties of an
+object returned by `url.parse()` are shown. Below it are properties of a WHATWG
+`URL` object.
+
+*Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not
+`username` or `password`.
+
+```txt
+┌─────────────────────────────────────────────────────────────────────────────────────────┐
+│                                          href                                           │
+├──────────┬──┬─────────────────────┬─────────────────┬───────────────────────────┬───────┤
+│ protocol │  │        auth         │      host       │           path            │ hash  │
+│          │  │                     ├──────────┬──────┼──────────┬────────────────┤       │
+│          │  │                     │ hostname │ port │ pathname │     search     │       │
+│          │  │                     │          │      │          ├─┬──────────────┤       │
+│          │  │                     │          │      │          │ │    query     │       │
+"  http:    //    user   :   pass   @ host.com : 8080   /p/a/t/h  ?  query=string   #hash "
+│          │  │          │          │ hostname │ port │          │                │       │
+│          │  │          │          ├──────────┴──────┤          │                │       │
+│ protocol │  │ username │ password │      host       │          │                │       │
+├──────────┴──┼──────────┴──────────┼─────────────────┤          │                │       │
+│   origin    │                     │     origin      │ pathname │     search     │ hash  │
+├─────────────┴─────────────────────┴─────────────────┴──────────┴────────────────┴───────┤
+│                                          href                                           │
+└─────────────────────────────────────────────────────────────────────────────────────────┘
+(all spaces in the "" line should be ignored -- they are purely for formatting)
+```
+
 ### Class: URL
 #### Constructor: new URL(input[, base])
 
@@ -340,13 +369,15 @@ automatically converted to ASCII using the [Punycode][] algorithm.
 
 ```js
 const myURL = new URL('https://你好你好');
-  // https://xn--6qqa088eba
+  // https://xn--6qqa088eba/
 ```
 
 Additional [examples of parsed URLs][] may be found in the WHATWG URL Standard.
 
 #### url.hash
 
+* {String}
+
 Gets and sets the fragment portion of the URL.
 
 ```js
@@ -360,12 +391,14 @@ console.log(myURL.href);
 ```
 
 Invalid URL characters included in the value assigned to the `hash` property
-are [percent-encoded](#whatwg-percent-encoding). Note that the selection of
-which characters to percent-encode may vary somewhat from what the
-[`url.parse()`][] and [`url.format()`][] methods would produce.
+are [percent-encoded][]. Note that the selection of which characters to
+percent-encode may vary somewhat from what the [`url.parse()`][] and
+[`url.format()`][] methods would produce.
 
 #### url.host
 
+* {String}
+
 Gets and sets the host portion of the URL.
 
 ```js
@@ -382,6 +415,8 @@ Invalid host values assigned to the `host` property are ignored.
 
 #### url.hostname
 
+* {String}
+
 Gets and sets the hostname portion of the URL. The key difference between
 `url.host` and `url.hostname` is that `url.hostname` does *not* include the
 port.
@@ -400,6 +435,8 @@ Invalid hostname values assigned to the `hostname` property are ignored.
 
 #### url.href
 
+* {String}
+
 Gets and sets the serialized URL.
 
 ```js
@@ -411,15 +448,20 @@ myURL.href = 'https://example.com/bar'
   // Prints https://example.com/bar
 ```
 
-Setting the value of the `href` property to a new value is equivalent to
-creating a new `URL` object using `new URL(value)`. Each of the `URL` object's
-properties will be modified.
+Getting the value of the `href` property is equivalent to calling
+[`url.toString()`][].
+
+Setting the value of this property to a new value is equivalent to creating a
+new `URL` object using [`new URL(value)`][`new URL()`]. Each of the `URL`
+object's properties will be modified.
 
 If the value assigned to the `href` property is not a valid URL, a `TypeError`
 will be thrown.
 
 #### url.origin
 
+* {String}
+
 Gets the read-only serialization of the URL's origin. Unicode characters that
 may be contained within the hostname will be encoded as-is without [Punycode][]
 encoding.
@@ -441,6 +483,8 @@ console.log(idnURL.hostname);
 
 #### url.password
 
+* {String}
+
 Gets and sets the password portion of the URL.
 
 ```js
@@ -454,12 +498,14 @@ console.log(myURL.href);
 ```
 
 Invalid URL characters included in the value assigned to the `password` property
-are [percent-encoded](#whatwg-percent-encoding). Note that the selection of
-which characters to percent-encode may vary somewhat from what the
-[`url.parse()`][] and [`url.format()`][] methods would produce.
+are [percent-encoded][]. Note that the selection of which characters to
+percent-encode may vary somewhat from what the [`url.parse()`][] and
+[`url.format()`][] methods would produce.
 
 #### url.pathname
 
+* {String}
+
 Gets and sets the path portion of the URL.
 
 ```js
@@ -473,23 +519,54 @@ console.log(myURL.href);
 ```
 
 Invalid URL characters included in the value assigned to the `pathname`
-property are [percent-encoded](#whatwg-percent-encoding). Note that the
-selection of which characters to percent-encode may vary somewhat from what the
-[`url.parse()`][] and [`url.format()`][] methods would produce.
+property are [percent-encoded][]. Note that the selection of which characters
+to percent-encode may vary somewhat from what the [`url.parse()`][] and
+[`url.format()`][] methods would produce.
 
 #### url.port
 
-Gets and sets the port portion of the URL. When getting the port, the value
-is returned as a String.
+* {String}
+
+Gets and sets the port portion of the URL.
 
 ```js
 const myURL = new URL('https://example.org:8888');
 console.log(myURL.port);
   // Prints 8888
 
+// Default ports are automatically transformed to the empty string
+// (HTTPS protocol's default port is 443)
+myURL.port = '443';
+console.log(myURL.port);
+  // Prints the empty string
+console.log(myURL.href);
+  // Prints https://example.org/
+
 myURL.port = 1234;
+console.log(myURL.port);
+  // Prints 1234
 console.log(myURL.href);
-  // Prints https://example.org:1234
+  // Prints https://example.org:1234/
+
+// Completely invalid port strings are ignored
+myURL.port = 'abcd';
+console.log(myURL.port);
+  // Prints 1234
+
+// Leading numbers are treated as a port number
+myURL.port = '5678abcd';
+console.log(myURL.port);
+  // Prints 5678
+
+// Non-integers are truncated
+myURL.port = 1234.5678;
+console.log(myURL.port);
+  // Prints 1234
+
+// Out-of-range numbers are ignored
+myURL.port = 1e10;
+console.log(myURL.port);
+  // Prints 1234
 ```
 
 The port value may be set as either a number or as a String containing a number
@@ -497,10 +574,14 @@ in the range `0` to `65535` (inclusive). Setting the value to the default port
 of the `URL` objects given `protocol` will result in the `port` value becoming
 the empty string (`''`).
 
-Invalid URL port values assigned to the `port` property are ignored.
+If an invalid string is assigned to the `port` property, but it begins with a
+number, the leading number is assigned to `port`. Otherwise, or if the number
+lies outside the range denoted above, it is ignored.
 
 #### url.protocol
 
+* {String}
+
 Gets and sets the protocol portion of the URL.
 
 ```js
@@ -517,6 +598,8 @@ Invalid URL protocol values assigned to the `protocol` property are ignored.
 
 #### url.search
 
+* {String}
+
 Gets and sets the serialized query portion of the URL.
 
 ```js
@@ -530,17 +613,23 @@ console.log(myURL.href);
 ```
 
 Any invalid URL characters appearing in the value assigned the `search`
-property will be [percent-encoded](#whatwg-percent-encoding). Note that the
-selection of which characters to percent-encode may vary somewhat from what the
-[`url.parse()`][] and [`url.format()`][] methods would produce.
+property will be [percent-encoded][]. Note that the selection of which
+characters to percent-encode may vary somewhat from what the [`url.parse()`][]
+and [`url.format()`][] methods would produce.
 
 #### url.searchParams
 
-Gets a [`URLSearchParams`](#url_class_urlsearchparams) object representing the
-query parameters of the URL.
+* {URLSearchParams}
+
+Gets the [`URLSearchParams`][] object representing the query parameters of the
+URL. This property is read-only; to replace the entirety of query parameters of
+the URL, use the [`url.search`][] setter. See [`URLSearchParams`][]
+documentation for details.
 
 #### url.username
 
+* {String}
+
 Gets and sets the username portion of the URL.
 
 ```js
@@ -554,21 +643,32 @@ console.log(myURL.href);
 ```
 
 Any invalid URL characters appearing in the value assigned the `username`
-property will be [percent-encoded](#whatwg-percent-encoding). Note that the
-selection of which characters to percent-encode may vary somewhat from what the
-[`url.parse()`][] and [`url.format()`][] methods would produce.
+property will be [percent-encoded][]. Note that the selection of which
+characters to percent-encode may vary somewhat from what the [`url.parse()`][]
+and [`url.format()`][] methods would produce.
 
 #### url.toString()
 
+* Returns: {String}
+
 The `toString()` method on the `URL` object returns the serialized URL. The
-value returned is equivalent to that of `url.href`.
+value returned is equivalent to that of [`url.href`][].
+
+Because of the need for standard compliance, this method does not allow users
+to customize the serialization process of the URL. For more flexibility,
+[`require('url').format()`][] method might be of interest.
 
 ### Class: URLSearchParams
 
-The `URLSearchParams` object provides read and write access to the query of a
+The `URLSearchParams` API provides read and write access to the query of a
 `URL`. The `URLSearchParams` class can also be used standalone with one of the
 four following constructors.
 
+The WHATWG `URLSearchParams` interface and the [`querystring`][] module have
+similar purpose, but the purpose of the [`querystring`][] module is more
+general, as it allows the customization of delimiter characters (`&` and `=`).
+On the other hand, this API is designed purely for URL query strings.
+
 ```js
 const { URL, URLSearchParams } = require('url');
 
@@ -725,36 +825,41 @@ Returns an ES6 Iterator over each of the name-value pairs in the query.
 Each item of the iterator is a JavaScript Array. The first item of the Array
 is the `name`, the second item of the Array is the `value`.
 
-Alias for `urlSearchParams\[\@\@iterator\]()`.
+Alias for [`urlSearchParams[@@iterator]()`][`urlSearchParams@@iterator()`].
 
-#### urlSearchParams.forEach(fn)
+#### urlSearchParams.forEach(fn[, thisArg])
 
 * `fn` {Function} Function invoked for each name-value pair in the query.
+* `thisArg` {Object} Object to be used as `this` value for when `fn` is called
 
 Iterates over each name-value pair in the query and invokes the given function.
 
 ```js
 const URL = require('url').URL;
 const myURL = new URL('https://example.org/?a=b&c=d');
-myURL.searchParams.forEach((value, name) => {
-  console.log(name, value);
+myURL.searchParams.forEach((value, name, searchParams) => {
+  console.log(name, value, myURL.searchParams === searchParams);
 });
+  // Prints:
+  // a b true
+  // c d true
 ```
 
 #### urlSearchParams.get(name)
 
 * `name` {String}
-* Returns: {String} or `null` if there is no name-value pair with the given
-  `name`.
+* Returns: {String | Null}
 
-Returns the value of the first name-value pair whose name is `name`.
+Returns the value of the first name-value pair whose name is `name`. If there
+are no such pairs, `null` is returned.
 
 #### urlSearchParams.getAll(name)
 
 * `name` {String}
 * Returns: {Array}
 
-Returns the values of all name-value pairs whose name is `name`.
+Returns the values of all name-value pairs whose name is `name`. If there are
+no such pairs, an empty array is returned.
 
 #### urlSearchParams.has(name)
 
@@ -769,13 +874,42 @@ Returns `true` if there is at least one name-value pair whose name is `name`.
 
 Returns an ES6 Iterator over the names of each name-value pair.
 
+```js
+const { URLSearchParams } = require('url');
+const params = new URLSearchParams('foo=bar&foo=baz');
+for (const name of params.keys()) {
+  console.log(name);
+}
+  // Prints:
+  // foo
+  // foo
+```
+
 #### urlSearchParams.set(name, value)
 
 * `name` {String}
 * `value` {String}
 
-Remove any existing name-value pairs whose name is `name` and append a new
-name-value pair.
+Sets the value in the `URLSearchParams` object associated with `name` to
+`value`. If there are any pre-existing name-value pairs whose names are `name`,
+set the first such pair's value to `value` and remove all others. If not,
+append the name-value pair to the query string.
+
+```js
+const { URLSearchParams } = require('url');
+
+const params = new URLSearchParams();
+params.append('foo', 'bar');
+params.append('foo', 'baz');
+params.append('abc', 'def');
+console.log(params.toString());
+  // Prints foo=bar&foo=baz&abc=def
+
+params.set('foo', 'def');
+params.set('xyz', 'opq');
+console.log(params.toString());
+  // Prints foo=def&abc=def&xyz=opq
+```
 
 #### urlSearchParams.sort()
 
@@ -796,7 +930,8 @@ console.log(params.toString());
 
 * Returns: {String}
 
-Returns the search parameters serialized as a URL-encoded string.
+Returns the search parameters serialized as a string, with characters
+percent-encoded where necessary.
 
 #### urlSearchParams.values()
 
@@ -804,7 +939,7 @@ Returns the search parameters serialized as a URL-encoded string.
 
 Returns an ES6 Iterator over the values of each name-value pair.
 
-#### urlSearchParams\[\@\@iterator\]()
+#### urlSearchParams\[@@iterator\]()
 
 * Returns: {Iterator}
 
@@ -812,7 +947,18 @@ Returns an ES6 Iterator over each of the name-value pairs in the query string.
 Each item of the iterator is a JavaScript Array. The first item of the Array
 is the `name`, the second item of the Array is the `value`.
 
-Alias for `urlSearchParams.entries()`.
+Alias for [`urlSearchParams.entries()`][].
+
+```js
+const { URLSearchParams } = require('url');
+const params = new URLSearchParams('foo=bar&xyz=baz');
+for (const [name, value] of params) {
+  console.log(name, value);
+}
+  // Prints:
+  // foo bar
+  // xyz baz
+```
 
 ### require('url').domainToAscii(domain)
 
@@ -883,8 +1029,17 @@ console.log(myURL.origin);
 [examples of parsed URLs]: https://url.spec.whatwg.org/#example-url-parsing
 [`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost
 [`url.format()`]: #url_url_format_urlobject
+[`require('url').format()`]: #url_url_format_url_options
+[`url.toString()`]: #url_url_tostring
 [Punycode]: https://tools.ietf.org/html/rfc5891#section-4.4
 [`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
 [`array.toString()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString
 [WHATWG URL]: #url_the_whatwg_url_api
+[`new URL()`]: #url_constructor_new_url_input_base
+[`url.href`]: #url_url_href
+[`url.search`]: #url_url_search
+[percent-encoded]: #whatwg-percent-encoding
+[`URLSearchParams`]: #url_class_urlsearchparams
+[`urlSearchParams.entries()`]: #url_urlsearchparams_entries
+[`urlSearchParams@@iterator()`]: #url_urlsearchparams_iterator
 [stable sorting algorithm]: https://en.wikipedia.org/wiki/Sorting_algorithm#Stability