Skip to content

Commit 02cf30c

Browse files
vsemozhetbyttargos
vsemozhetbyt
authored and
targos
committed
doc: remove redundant 'Example:' and similar notes
Some nits were also fixed in passing. PR-URL: #22537 Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent 1665583 commit 02cf30c

27 files changed

Lines changed: 53 additions & 260 deletions

‎doc/api/assert.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -667,7 +667,7 @@ changes:
667667
Throws `value` if `value` is not `undefined` or `null`. This is useful when
668668
testing the `error` argument in callbacks. The stack trace contains all frames
669669
from the error passed to `ifError()` including the potential new frames for
670-
`ifError()` itself. See below for an example.
670+
`ifError()` itself.
671671

672672
```js
673673
const assert = require('assert').strict;

‎doc/api/async_hooks.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -534,8 +534,6 @@ expensive nature of the [promise introspection API][PromiseHooks] provided by
534534
V8. This means that programs using promises or `async`/`await` will not get
535535
correct execution and trigger ids for promise callback contexts by default.
536536

537-
Here's an example:
538-
539537
```js
540538
const ah = require('async_hooks');
541539
Promise.resolve(1729).then(() => {
@@ -551,7 +549,7 @@ the `triggerAsyncId` value is `0`, which means that we are missing context about
551549
the resource that caused (triggered) the `then()` callback to be executed.
552550

553551
Installing async hooks via `async_hooks.createHook` enables promise execution
554-
tracking. Example:
552+
tracking:
555553

556554
```js
557555
const ah = require('async_hooks');

‎doc/api/child_process.md‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -633,8 +633,6 @@ pipes between the parent and child. The value is one of the following:
633633
words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the
634634
default is `'ignore'`.
635635

636-
Example:
637-
638636
```js
639637
const { spawn } = require('child_process');
640638

@@ -1042,8 +1040,7 @@ See kill(2) for reference.
10421040

10431041
Also note: on Linux, child processes of child processes will not be terminated
10441042
when attempting to kill their parent. This is likely to happen when running a
1045-
new process in a shell or with use of the `shell` option of `ChildProcess`, such
1046-
as in this example:
1043+
new process in a shell or with use of the `shell` option of `ChildProcess`:
10471044

10481045
```js
10491046
'use strict';
@@ -1087,8 +1084,6 @@ added: v0.1.90
10871084

10881085
Returns the process identifier (PID) of the child process.
10891086

1090-
Example:
1091-
10921087
```js
10931088
const { spawn } = require('child_process');
10941089
const grep = spawn('grep', ['ssh']);

‎doc/api/cluster.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -762,8 +762,6 @@ Note that:
762762
* The defaults above apply to the first call only, the defaults for later
763763
calls is the current value at the time of `cluster.setupMaster()` is called.
764764

765-
Example:
766-
767765
```js
768766
const cluster = require('cluster');
769767
cluster.setupMaster({

‎doc/api/crypto.md‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1700,8 +1700,6 @@ added: v0.9.3
17001700
* Returns: {string[]} An array with the names of the supported cipher
17011701
algorithms.
17021702

1703-
Example:
1704-
17051703
```js
17061704
const ciphers = crypto.getCiphers();
17071705
console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
@@ -1713,8 +1711,6 @@ added: v2.3.0
17131711
-->
17141712
* Returns: {string[]} An array with the names of the supported elliptic curves.
17151713

1716-
Example:
1717-
17181714
```js
17191715
const curves = crypto.getCurves();
17201716
console.log(curves); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]
@@ -1733,7 +1729,7 @@ supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in
17331729
`'modp16'`, `'modp17'`, `'modp18'` (defined in [RFC 3526][]). The
17341730
returned object mimics the interface of objects created by
17351731
[`crypto.createDiffieHellman()`][], but will not allow changing
1736-
the keys (with [`diffieHellman.setPublicKey()`][] for example). The
1732+
the keys (with [`diffieHellman.setPublicKey()`][], for example). The
17371733
advantage of using this method is that the parties do not have to
17381734
generate nor exchange a group modulus beforehand, saving both processor
17391735
and communication time.
@@ -1769,8 +1765,6 @@ added: v0.9.3
17691765
* Returns: {string[]} An array of the names of the supported hash algorithms,
17701766
such as `'RSA-SHA256'`.
17711767

1772-
Example:
1773-
17741768
```js
17751769
const hashes = crypto.getHashes();
17761770
console.log(hashes); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]
@@ -1819,8 +1813,6 @@ but will take a longer amount of time to complete.
18191813
The `salt` should be as unique as possible. It is recommended that a salt is
18201814
random and at least 16 bytes long. See [NIST SP 800-132][] for details.
18211815

1822-
Example:
1823-
18241816
```js
18251817
const crypto = require('crypto');
18261818
crypto.pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
@@ -1884,8 +1876,6 @@ but will take a longer amount of time to complete.
18841876
The `salt` should be as unique as possible. It is recommended that a salt is
18851877
random and at least 16 bytes long. See [NIST SP 800-132][] for details.
18861878

1887-
Example:
1888-
18891879
```js
18901880
const crypto = require('crypto');
18911881
const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');

‎doc/api/dgram.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -546,17 +546,16 @@ chained.
546546
### Change to asynchronous `socket.bind()` behavior
547547

548548
As of Node.js v0.10, [`dgram.Socket#bind()`][] changed to an asynchronous
549-
execution model. Legacy code that assumes synchronous behavior, as in the
550-
following example:
549+
execution model. Legacy code would use synchronous behavior:
551550

552551
```js
553552
const s = dgram.createSocket('udp4');
554553
s.bind(1234);
555554
s.addMembership('224.0.0.114');
556555
```
557556

558-
Must be changed to pass a callback function to the [`dgram.Socket#bind()`][]
559-
function:
557+
Such legacy code would need to be changed to pass a callback function to the
558+
[`dgram.Socket#bind()`][] function:
560559

561560
```js
562561
const s = dgram.createSocket('udp4');

‎doc/api/domain.md‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -311,8 +311,6 @@ The returned function will be a wrapper around the supplied callback
311311
function. When the returned function is called, any errors that are
312312
thrown will be routed to the domain's `'error'` event.
313313

314-
#### Example
315-
316314
```js
317315
const d = domain.create();
318316

@@ -370,8 +368,6 @@ objects sent as the first argument to the function.
370368
In this way, the common `if (err) return callback(err);` pattern can be replaced
371369
with a single error handler in a single place.
372370

373-
#### Example
374-
375371
```js
376372
const d = domain.create();
377373

@@ -415,8 +411,6 @@ the function.
415411

416412
This is the most basic way to use a domain.
417413

418-
Example:
419-
420414
```js
421415
const domain = require('domain');
422416
const fs = require('fs');

‎doc/api/errors.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1253,8 +1253,7 @@ type for one of its returned object properties on execution.
12531253
### ERR_INVALID_RETURN_VALUE
12541254

12551255
Thrown in case a function option does not return an expected value
1256-
type on execution.
1257-
For example when a function is expected to return a promise.
1256+
type on execution, such as when a function is expected to return a promise.
12581257

12591258
<a id="ERR_INVALID_SYNC_FORK_INPUT"></a>
12601259
### ERR_INVALID_SYNC_FORK_INPUT
@@ -1268,8 +1267,6 @@ for more information.
12681267

12691268
A Node.js API function was called with an incompatible `this` value.
12701269

1271-
Example:
1272-
12731270
```js
12741271
const urlSearchParams = new URLSearchParams('foo=bar&baz=new');
12751272

@@ -1595,7 +1592,6 @@ emitted.
15951592
Prevents an abort if a string decoder was set on the Socket or if the decoder
15961593
is in `objectMode`.
15971594

1598-
Example
15991595
```js
16001596
const Socket = require('net').Socket;
16011597
const instance = new Socket();

‎doc/api/fs.md‎

Lines changed: 11 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1044,16 +1044,14 @@ changes:
10441044
Asynchronously append data to a file, creating the file if it does not yet
10451045
exist. `data` can be a string or a [`Buffer`][].
10461046

1047-
Example:
1048-
10491047
```js
10501048
fs.appendFile('message.txt', 'data to append', (err) => {
10511049
if (err) throw err;
10521050
console.log('The "data to append" was appended to file!');
10531051
});
10541052
```
10551053

1056-
If `options` is a string, then it specifies the encoding. Example:
1054+
If `options` is a string, then it specifies the encoding:
10571055

10581056
```js
10591057
fs.appendFile('message.txt', 'data to append', 'utf8', callback);
@@ -1097,8 +1095,6 @@ changes:
10971095
Synchronously append data to a file, creating the file if it does not yet
10981096
exist. `data` can be a string or a [`Buffer`][].
10991097

1100-
Example:
1101-
11021098
```js
11031099
try {
11041100
fs.appendFileSync('message.txt', 'data to append');
@@ -1108,7 +1104,7 @@ try {
11081104
}
11091105
```
11101106

1111-
If `options` is a string, then it specifies the encoding. Example:
1107+
If `options` is a string, then it specifies the encoding:
11121108

11131109
```js
11141110
fs.appendFileSync('message.txt', 'data to append', 'utf8');
@@ -1344,8 +1340,6 @@ fallback copy mechanism is used.
13441340
create a copy-on-write reflink. If the platform does not support copy-on-write,
13451341
then the operation will fail.
13461342

1347-
Example:
1348-
13491343
```js
13501344
const fs = require('fs');
13511345

@@ -1356,8 +1350,7 @@ fs.copyFile('source.txt', 'destination.txt', (err) => {
13561350
});
13571351
```
13581352

1359-
If the third argument is a number, then it specifies `flags`, as shown in the
1360-
following example.
1353+
If the third argument is a number, then it specifies `flags`:
13611354

13621355
```js
13631356
const fs = require('fs');
@@ -1395,8 +1388,6 @@ fallback copy mechanism is used.
13951388
create a copy-on-write reflink. If the platform does not support copy-on-write,
13961389
then the operation will fail.
13971390

1398-
Example:
1399-
14001391
```js
14011392
const fs = require('fs');
14021393

@@ -1405,8 +1396,7 @@ fs.copyFileSync('source.txt', 'destination.txt');
14051396
console.log('source.txt was copied to destination.txt');
14061397
```
14071398

1408-
If the third argument is a number, then it specifies `flags`, as shown in the
1409-
following example.
1399+
If the third argument is a number, then it specifies `flags`:
14101400

14111401
```js
14121402
const fs = require('fs');
@@ -1563,7 +1553,7 @@ deprecated: v1.0.0
15631553
* `exists` {boolean}
15641554

15651555
Test whether or not the given path exists by checking with the file system.
1566-
Then call the `callback` argument with either true or false. Example:
1556+
Then call the `callback` argument with either true or false:
15671557

15681558
```js
15691559
fs.exists('/etc/passwd', (exists) => {
@@ -1896,7 +1886,7 @@ fs.ftruncate(fd, 4, (err) => {
18961886
```
18971887

18981888
If the file previously was shorter than `len` bytes, it is extended, and the
1899-
extended part is filled with null bytes (`'\0'`). For example,
1889+
extended part is filled with null bytes (`'\0'`):
19001890

19011891
```js
19021892
console.log(fs.readFileSync('temp.txt', 'utf8'));
@@ -2500,7 +2490,7 @@ changes:
25002490
* `err` {Error}
25012491
* `data` {string|Buffer}
25022492

2503-
Asynchronously reads the entire contents of a file. Example:
2493+
Asynchronously reads the entire contents of a file.
25042494

25052495
```js
25062496
fs.readFile('/etc/passwd', (err, data) => {
@@ -2514,7 +2504,7 @@ contents of the file.
25142504

25152505
If no encoding is specified, then the raw buffer is returned.
25162506

2517-
If `options` is a string, then it specifies the encoding. Example:
2507+
If `options` is a string, then it specifies the encoding:
25182508

25192509
```js
25202510
fs.readFile('/etc/passwd', 'utf8', callback);
@@ -3514,8 +3504,6 @@ Asynchronously writes data to a file, replacing the file if it already exists.
35143504

35153505
The `encoding` option is ignored if `data` is a buffer.
35163506

3517-
Example:
3518-
35193507
```js
35203508
const data = new Uint8Array(Buffer.from('Hello Node.js'));
35213509
fs.writeFile('message.txt', data, (err) => {
@@ -3524,7 +3512,7 @@ fs.writeFile('message.txt', data, (err) => {
35243512
});
35253513
```
35263514

3527-
If `options` is a string, then it specifies the encoding. Example:
3515+
If `options` is a string, then it specifies the encoding:
35283516

35293517
```js
35303518
fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
@@ -3835,7 +3823,7 @@ doTruncate().catch(console.error);
38353823
```
38363824

38373825
If the file previously was shorter than `len` bytes, it is extended, and the
3838-
extended part is filled with null bytes (`'\0'`). For example,
3826+
extended part is filled with null bytes (`'\0'`):
38393827

38403828
```js
38413829
const fs = require('fs');
@@ -4045,8 +4033,6 @@ fallback copy mechanism is used.
40454033
create a copy-on-write reflink. If the platform does not support copy-on-write,
40464034
then the operation will fail.
40474035

4048-
Example:
4049-
40504036
```js
40514037
const fsPromises = require('fs').promises;
40524038

@@ -4056,8 +4042,7 @@ fsPromises.copyFile('source.txt', 'destination.txt')
40564042
.catch(() => console.log('The file could not be copied'));
40574043
```
40584044

4059-
If the third argument is a number, then it specifies `flags`, as shown in the
4060-
following example.
4045+
If the third argument is a number, then it specifies `flags`:
40614046

40624047
```js
40634048
const fs = require('fs');

0 commit comments

Comments
 (0)