Skip to content

Commit 50316e2

Browse files
vsemozhetbytMylesBorins
authored andcommitted
doc,tools: formalize, unify, codify default values
Backport-PR-URL: #22388 PR-URL: #19737 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
1 parent a023193 commit 50316e2

30 files changed

+331
-357
lines changed

doc/STYLE_GUIDE.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,9 @@
6262
* Use a capital letter after the "Note:" label.
6363
* Preferably, make the note a new paragraph for better visual distinction.
6464
* Function arguments or object properties should use the following format:
65-
* <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`</code>
66-
* E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`</code>
67-
* The `type` should refer to a Node.js type or a [JavaScript type][]
65+
* <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`.</code>
66+
* E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code>
67+
* The `type` should refer to a Node.js type or a [JavaScript type][].
6868
* Function returns should use the following format:
6969
* <code>* Returns: {type|type2} Optional description.</code>
7070
* E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code>

doc/api/assert.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -280,7 +280,7 @@ added: v0.1.21
280280
* `actual` {any}
281281
* `expected` {any}
282282
* `message` {any}
283-
* `operator` {string} **Default:** '!='
283+
* `operator` {string} **Default:** `'!='`
284284
* `stackStartFunction` {Function} **Default:** `assert.fail`
285285

286286
Throws an `AssertionError`. If `message` is falsy, the error message is set as

doc/api/async_hooks.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -642,12 +642,11 @@ asyncResource.emitAfter();
642642
* `type` {string} The type of async event.
643643
* `options` {Object}
644644
* `triggerAsyncId` {number} The ID of the execution context that created this
645-
async event. **Default:** `executionAsyncId()`
645+
async event. **Default:** `executionAsyncId()`.
646646
* `requireManualDestroy` {boolean} Disables automatic `emitDestroy` when the
647647
object is garbage collected. This usually does not need to be set (even if
648648
`emitDestroy` is called manually), unless the resource's asyncId is retrieved
649-
and the sensitive API's `emitDestroy` is called with it.
650-
**Default:** `false`
649+
and the sensitive API's `emitDestroy` is called with it. **Default:** `false`.
651650

652651
Example usage:
653652

doc/api/buffer.md

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -359,9 +359,9 @@ changes:
359359
360360
* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`],
361361
[`SharedArrayBuffer`] or the `.buffer` property of a [`TypedArray`].
362-
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`
362+
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
363363
* `length` {integer} Number of bytes to expose.
364-
**Default:** `arrayBuffer.length - byteOffset`
364+
**Default:** `arrayBuffer.length - byteOffset`.
365365

366366
This creates a view of the [`ArrayBuffer`] or [`SharedArrayBuffer`] without
367367
copying the underlying memory. For example, when passed a reference to the
@@ -481,7 +481,7 @@ changes:
481481
> Use [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] instead.
482482
483483
* `string` {string} String to encode.
484-
* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`
484+
* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`.
485485

486486
Creates a new `Buffer` containing the given JavaScript string `string`. If
487487
provided, the `encoding` parameter identifies the character encoding of `string`.
@@ -515,9 +515,9 @@ changes:
515515

516516
* `size` {integer} The desired length of the new `Buffer`.
517517
* `fill` {string|Buffer|integer} A value to pre-fill the new `Buffer` with.
518-
**Default:** `0`
518+
**Default:** `0`.
519519
* `encoding` {string} If `fill` is a string, this is its encoding.
520-
**Default:** `'utf8'`
520+
**Default:** `'utf8'`.
521521

522522
Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the
523523
`Buffer` will be *zero-filled*.
@@ -683,7 +683,7 @@ changes:
683683
* `string` {string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer} A
684684
value to calculate the length of.
685685
* `encoding` {string} If `string` is a string, this is its encoding.
686-
**Default:** `'utf8'`
686+
**Default:** `'utf8'`.
687687
* Returns: {integer} The number of bytes contained within `string`.
688688

689689
Returns the actual byte length of a string. This is not the same as
@@ -810,9 +810,9 @@ added: v5.10.0
810810

811811
* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`],
812812
[`SharedArrayBuffer`], or the `.buffer` property of a [`TypedArray`].
813-
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`
813+
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
814814
* `length` {integer} Number of bytes to expose.
815-
**Default:** `arrayBuffer.length - byteOffset`
815+
**Default:** `arrayBuffer.length - byteOffset`.
816816

817817
This creates a view of the [`ArrayBuffer`] without copying the underlying
818818
memory. For example, when passed a reference to the `.buffer` property of a
@@ -889,7 +889,7 @@ added: v5.10.0
889889
-->
890890

891891
* `string` {string} A string to encode.
892-
* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`
892+
* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`.
893893

894894
Creates a new `Buffer` containing the given JavaScript string `string`. If
895895
provided, the `encoding` parameter identifies the character encoding of `string`.
@@ -1037,13 +1037,13 @@ changes:
10371037

10381038
* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to compare to.
10391039
* `targetStart` {integer} The offset within `target` at which to begin
1040-
comparison. **Default:** `0`
1040+
comparison. **Default:** `0`.
10411041
* `targetEnd` {integer} The offset with `target` at which to end comparison
1042-
(not inclusive). **Default:** `target.length`
1042+
(not inclusive). **Default:** `target.length`.
10431043
* `sourceStart` {integer} The offset within `buf` at which to begin comparison.
1044-
**Default:** `0`
1044+
**Default:** `0`.
10451045
* `sourceEnd` {integer} The offset within `buf` at which to end comparison
1046-
(not inclusive). **Default:** [`buf.length`]
1046+
(not inclusive). **Default:** [`buf.length`].
10471047
* Returns: {integer}
10481048

10491049
Compares `buf` with `target` and returns a number indicating whether `buf`
@@ -1111,11 +1111,11 @@ added: v0.1.90
11111111

11121112
* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to copy into.
11131113
* `targetStart` {integer} The offset within `target` at which to begin
1114-
copying to. **Default:** `0`
1114+
copying to. **Default:** `0`.
11151115
* `sourceStart` {integer} The offset within `buf` at which to begin copying from.
1116-
**Default:** `0`
1116+
**Default:** `0`.
11171117
* `sourceEnd` {integer} The offset within `buf` at which to stop copying (not
1118-
inclusive). **Default:** [`buf.length`]
1118+
inclusive). **Default:** [`buf.length`].
11191119
* Returns: {integer} The number of bytes copied.
11201120

11211121
Copies data from a region of `buf` to a region in `target` even if the `target`
@@ -1222,10 +1222,10 @@ changes:
12221222
-->
12231223

12241224
* `value` {string|Buffer|integer} The value to fill `buf` with.
1225-
* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`
1226-
* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`]
1225+
* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`.
1226+
* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`].
12271227
* `encoding` {string} If `value` is a string, this is its encoding.
1228-
**Default:** `'utf8'`
1228+
**Default:** `'utf8'`.
12291229
* Returns: {Buffer} A reference to `buf`.
12301230

12311231
Fills `buf` with the specified `value`. If the `offset` and `end` are not given,
@@ -1276,9 +1276,9 @@ added: v5.3.0
12761276
-->
12771277

12781278
* `value` {string|Buffer|integer} What to search for.
1279-
* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`
1279+
* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`.
12801280
* `encoding` {string} If `value` is a string, this is its encoding.
1281-
**Default:** `'utf8'`
1281+
**Default:** `'utf8'`.
12821282
* Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise.
12831283

12841284
Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`].
@@ -1918,9 +1918,9 @@ changes:
19181918
calculations with them.
19191919
-->
19201920

1921-
* `start` {integer} Where the new `Buffer` will start. **Default:** `0`
1921+
* `start` {integer} Where the new `Buffer` will start. **Default:** `0`.
19221922
* `end` {integer} Where the new `Buffer` will end (not inclusive).
1923-
**Default:** [`buf.length`]
1923+
**Default:** [`buf.length`].
19241924
* Returns: {Buffer}
19251925

19261926
Returns a new `Buffer` that references the same memory as the original, but
@@ -2099,10 +2099,10 @@ console.log(copy);
20992099
added: v0.1.90
21002100
-->
21012101

2102-
* `encoding` {string} The character encoding to decode to. **Default:** `'utf8'`
2103-
* `start` {integer} The byte offset to start decoding at. **Default:** `0`
2102+
* `encoding` {string} The character encoding to decode to. **Default:** `'utf8'`.
2103+
* `start` {integer} The byte offset to start decoding at. **Default:** `0`.
21042104
* `end` {integer} The byte offset to stop decoding at (not inclusive).
2105-
**Default:** [`buf.length`]
2105+
**Default:** [`buf.length`].
21062106
* Returns: {string}
21072107

21082108
Decodes `buf` to a string according to the specified character encoding in
@@ -2183,9 +2183,9 @@ added: v0.1.90
21832183
-->
21842184

21852185
* `string` {string} String to be written to `buf`.
2186-
* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0`
2187-
* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset`
2188-
* `encoding` {string} The character encoding of `string`. **Default:** `'utf8'`
2186+
* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0`.
2187+
* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset`.
2188+
* `encoding` {string} The character encoding of `string`. **Default:** `'utf8'`.
21892189
* Returns: {integer} Number of bytes written.
21902190

21912191
Writes `string` to `buf` at `offset` according to the character encoding in `encoding`.
@@ -2520,7 +2520,7 @@ added: v0.5.5
25202520
* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - byteLength`.
25212521
* `byteLength` {integer} Number of bytes to write. Must satisfy: `0 < byteLength <= 6`.
25222522
* `noAssert` {boolean} Skip `value`, `offset`, and `byteLength` validation?
2523-
**Default:** `false`
2523+
**Default:** `false`.
25242524
* Returns: {integer} `offset` plus the number of bytes written.
25252525

25262526
Writes `byteLength` bytes of `value` to `buf` at the specified `offset`.

0 commit comments

Comments
 (0)