Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: several minor documentation improvements #23359

Closed
wants to merge 4 commits into from
Closed

doc: several minor documentation improvements #23359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
80e267a
doc: wrap links in <>
ChALkeR Sep 2, 2018
7ac0f2a
doc: fix pr-url in repl.md
ChALkeR Sep 2, 2018
3f4dc54
doc: use reserved domains for examples in url.md
ChALkeR Sep 2, 2018
a2af3a4
doc: fix url example to match behavior
ChALkeR Oct 10, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions doc/api/deprecations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -334,7 +334,7 @@ changes:
Type: End-of-Life

Calling an asynchronous function without a callback throws a `TypeError`
in Node.js 10.0.0 onwards. (See https://github.com/nodejs/node/pull/12562.)
in Node.js 10.0.0 onwards. (See <https://github.com/nodejs/node/pull/12562>.)

<a id="DEP0014"></a>
### DEP0014: fs.read legacy String interface
Expand Down Expand Up @@ -1717,7 +1717,7 @@ changes:
Type: End-of-Life

The AsyncHooks Sensitive API was never documented and had various minor issues.
(See https://github.com/nodejs/node/issues/15572.) Use the `AsyncResource`
(See <https://github.com/nodejs/node/issues/15572>.) Use the `AsyncResource`
API instead.

<a id="DEP0086"></a>
Expand All @@ -1737,8 +1737,8 @@ changes:
Type: End-of-Life

`runInAsyncIdScope` doesn't emit the `'before'` or `'after'` event and can thus
cause a lot of issues. See https://github.com/nodejs/node/issues/14328 for more
details.
cause a lot of issues. See <https://github.com/nodejs/node/issues/14328> for
more details.

<a id="DEP0089"></a>
### DEP0089: require('assert')
Expand Down Expand Up @@ -1897,7 +1897,7 @@ to unrecoverable errors.

Use [`asyncResource.runInAsyncScope()`][] API instead which provides a much
safer, and more convenient, alternative. See
https://github.com/nodejs/node/pull/18513 for more details.
<https://github.com/nodejs/node/pull/18513> for more details.

<a id="DEP0099"></a>
### DEP0099: async context-unaware node::MakeCallback C++ APIs
Expand Down
6 changes: 3 additions & 3 deletions doc/api/repl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -453,7 +453,7 @@ Returns `true` if `keyword` is a valid keyword, otherwise `false`.
added: v0.1.91
changes:
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/v10.0.0
pr-url: https://github.com/nodejs/node/pull/19187
description: The `REPL_MAGIC_MODE` `replMode` was removed.
- version: v5.8.0
pr-url: https://github.com/nodejs/node/pull/5388
Expand Down Expand Up @@ -619,10 +619,10 @@ possible to connect to a long-running Node.js process without restarting it.

For an example of running a "full-featured" (`terminal`) REPL over
a `net.Server` and `net.Socket` instance, see:
[https://gist.github.com/TooTallNate/2209310](https://gist.github.com/TooTallNate/2209310).
<https://gist.github.com/TooTallNate/2209310>.

For an example of running a REPL instance over [curl(1)][], see:
[https://gist.github.com/TooTallNate/2053342](https://gist.github.com/TooTallNate/2053342).
<https://gist.github.com/TooTallNate/2053342>.

[`'uncaughtException'`]: process.html#process_event_uncaughtexception
[`--experimental-repl-await`]: cli.html#cli_experimental_repl_await
Expand Down
4 changes: 2 additions & 2 deletions doc/api/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -566,7 +566,7 @@ field which always contains the value `'TLSv1/SSLv3'`.
For example: `{ name: 'AES256-SHA', version: 'TLSv1/SSLv3' }`.

See `SSL_CIPHER_get_name()` in
https://www.openssl.org/docs/man1.1.0/ssl/SSL_CIPHER_get_name.html for more
<https://www.openssl.org/docs/man1.1.0/ssl/SSL_CIPHER_get_name.html> for more
information.

### tlsSocket.getEphemeralKeyInfo()
Expand Down Expand Up @@ -683,7 +683,7 @@ Example responses include:
* `TLSv1.2`
* `unknown`

See https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_version.html for more
See <https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_version.html> for more
information.

### tlsSocket.getSession()
Expand Down
96 changes: 48 additions & 48 deletions doc/api/url.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,47 +26,47 @@ backwards compatibility with existing applications. New application code
should use the WHATWG API.

A comparison between the WHATWG and Legacy APIs is provided below. Above the URL
`'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash'`, properties of
an object returned by the legacy `url.parse()` are shown. Below it are
`'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'`, properties
of an object returned by the legacy `url.parse()` are shown. Below it are
properties of a WHATWG `URL` object.

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 │ │
" https: // user : pass @ sub.host.com : 8080 /p/a/t/h ? query=string #hash "
│ │ │ │ │ hostname │ port │ │ │ │
│ │ │ │ ├──────────────┴──────┤ │ │ │
│ protocol │ │ username │ password │ host │ │ │ │
├──────────┴──┼──────────┴──────────┼─────────────────────┤ │ │ │
│ origin │ │ origin │ pathname │ search │ hash │
├─────────────┴─────────────────────┴─────────────────────┴──────────┴────────────────┴───────┤
│ href │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│ href │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │ │ auth │ host │ path │ hash │
│ │ │ ├─────────────────┬──────┼──────────┬────────────────┤ │
│ │ │ │ hostname │ port │ pathname │ search │ │
│ │ │ │ │ │ ├─┬──────────────┤ │
│ │ │ │ │ │ │ │ query │ │
" https: // user : pass @ sub.example.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)
```

Parsing the URL string using the WHATWG API:

```js
const myURL =
new URL('https://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash');
new URL('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
```

Parsing the URL string using the Legacy API:

```js
const url = require('url');
const myURL =
url.parse('https://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash');
url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
```

## The WHATWG URL API
Expand Down Expand Up @@ -120,8 +120,8 @@ Unicode characters appearing within the hostname of `input` will be
automatically converted to ASCII using the [Punycode][] algorithm.

```js
const myURL = new URL('https://你好你好');
// https://xn--6qqa088eba/
const myURL = new URL('https://測試');
// https://xn--g6w251d/
```

This feature is only available if the `node` executable was compiled with
Expand All @@ -132,23 +132,23 @@ and a `base` is provided, it is advised to validate that the `origin` of
the `URL` object is what is expected.

```js
let myURL = new URL('http://anotherExample.org/', 'https://example.org/');
// http://anotherexample.org/
let myURL = new URL('http://Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https://anotherExample.org/', 'https://example.org/');
// https://anotherexample.org/
myURL = new URL('https://Example.com/', 'https://example.org/');
// https://example.com/

myURL = new URL('foo://anotherExample.org/', 'https://example.org/');
// foo://anotherExample.org/
myURL = new URL('foo://Example.com/', 'https://example.org/');
// foo://Example.com/

myURL = new URL('http:anotherExample.org/', 'https://example.org/');
// http://anotherexample.org/
myURL = new URL('http:Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https:anotherExample.org/', 'https://example.org/');
// https://example.org/anotherExample.org/
myURL = new URL('https:Example.com/', 'https://example.org/');
// https://example.org/Example.com/

myURL = new URL('foo:anotherExample.org/', 'https://example.org/');
// foo:anotherExample.org/
myURL = new URL('foo:Example.com/', 'https://example.org/');
// foo:Example.com/
```

#### url.hash
Expand Down Expand Up @@ -249,12 +249,12 @@ console.log(myURL.origin);
```

```js
const idnURL = new URL('https://你好你好');
const idnURL = new URL('https://測試');
console.log(idnURL.origin);
// Prints https://xn--6qqa088eba
// Prints https://xn--g6w251d

console.log(idnURL.hostname);
// Prints xn--6qqa088eba
// Prints xn--g6w251d
```

#### url.password
Expand Down Expand Up @@ -929,16 +929,16 @@ any way. The `url.format(URL[, options])` method allows for basic customization
of the output.

```js
const myURL = new URL('https://a:b@你好你好?abc#foo');
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(myURL.href);
// Prints https://a:b@xn--6qqa088eba/?abc#foo
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString());
// Prints https://a:b@xn--6qqa088eba/?abc#foo
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
// Prints 'https://你好你好/?abc'
// Prints 'https://測試/?abc'
```

### url.pathToFileURL(path)
Expand Down Expand Up @@ -999,21 +999,21 @@ For example: `'#hash'`.
The `host` property is the full lower-cased host portion of the URL, including
the `port` if specified.

For example: `'sub.host.com:8080'`.
For example: `'sub.example.com:8080'`.

#### urlObject.hostname

The `hostname` property is the lower-cased host name portion of the `host`
component *without* the `port` included.

For example: `'sub.host.com'`.
For example: `'sub.example.com'`.

#### urlObject.href

The `href` property is the full URL string that was parsed with both the
`protocol` and `host` components converted to lower-case.

For example: `'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash'`.
For example: `'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'`.

#### urlObject.path

Expand Down Expand Up @@ -1282,11 +1282,11 @@ using the [Punycode][] algorithm. Note, however, that a hostname *may* contain
*both* Punycode encoded and percent-encoded characters:

```js
const myURL = new URL('https://%CF%80.com/foo');
const myURL = new URL('https://%CF%80.example.com/foo');
console.log(myURL.href);
// Prints https://xn--1xa.com/foo
// Prints https://xn--1xa.example.com/foo
console.log(myURL.origin);
// Prints https://π.com
// Prints https://xn--1xa.example.com
```

[`Error`]: errors.html#errors_class_error
Expand Down