Skip to content

Commit 8ac4348

Browse files
vsemozhetbyttargos
authored andcommitted
doc,tools: formalize, unify, codify default values
Backport-PR-URL: #19793 PR-URL: #19737 Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
1 parent 52dae89 commit 8ac4348

32 files changed

+378
-408
lines changed

doc/STYLE_GUIDE.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,9 @@
5959
* Use a capital letter after the "Note:" label.
6060
* Preferably, make the note a new paragraph for better visual distinction.
6161
* Function arguments or object properties should use the following format:
62-
* <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`</code>
63-
* E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`</code>
64-
* The `type` should refer to a Node.js type or a [JavaScript type][]
62+
* <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`.</code>
63+
* E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code>
64+
* The `type` should refer to a Node.js type or a [JavaScript type][].
6565
* Function returns should use the following format:
6666
* <code>* Returns: {type|type2} Optional description.</code>
6767
* 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
@@ -494,7 +494,7 @@ added: v0.1.21
494494
* `actual` {any}
495495
* `expected` {any}
496496
* `message` {any} **Default:** `'Failed'`
497-
* `operator` {string} **Default:** '!='
497+
* `operator` {string} **Default:** `'!='`
498498
* `stackStartFunction` {Function} **Default:** `assert.fail`
499499

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

doc/api/async_hooks.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,7 @@ instance is destroyed.
206206
* `type` {string} The type of the async resource.
207207
* `triggerAsyncId` {number} The unique ID of the async resource in whose
208208
execution context this async resource was created.
209-
* `resource` {Object} Reference to the resource representing the async
209+
* `resource` {Object} Reference to the resource representing the async
210210
operation, needs to be released during _destroy_.
211211

212212
Called when a class is constructed that has the _possibility_ to emit an
@@ -283,10 +283,10 @@ The `TCPSERVERWRAP` is the server which receives the connections.
283283

284284
The `TCPWRAP` is the new connection from the client. When a new
285285
connection is made the `TCPWrap` instance is immediately constructed. This
286-
happens outside of any JavaScript stack (side note: a `executionAsyncId()` of
286+
happens outside of any JavaScript stack (side note: a `executionAsyncId()` of
287287
`0` means it's being executed from C++, with no JavaScript stack above it).
288288
With only that information, it would be impossible to link resources together in
289-
terms of what caused them to be created, so `triggerAsyncId` is given the task
289+
terms of what caused them to be created, so `triggerAsyncId` is given the task
290290
of propagating what resource is responsible for the new resource's existence.
291291

292292
###### `resource`
@@ -582,7 +582,7 @@ the details of the V8 [PromiseHooks][] API.
582582
## JavaScript Embedder API
583583

584584
Library developers that handle their own asynchronous resources performing tasks
585-
like I/O, connection pooling, or managing callback queues may use the
585+
like I/O, connection pooling, or managing callback queues may use the
586586
`AsyncWrap` JavaScript API so that all the appropriate callbacks are called.
587587

588588
### `class AsyncResource()`
@@ -640,8 +640,7 @@ asyncResource.emitAfter();
640640
* `requireManualDestroy` {boolean} Disables automatic `emitDestroy` when the
641641
object is garbage collected. This usually does not need to be set (even if
642642
`emitDestroy` is called manually), unless the resource's asyncId is retrieved
643-
and the sensitive API's `emitDestroy` is called with it.
644-
**Default:** `false`
643+
and the sensitive API's `emitDestroy` is called with it. **Default:** `false`.
645644

646645
Example usage:
647646

@@ -728,7 +727,7 @@ never be called.
728727

729728
#### `asyncResource.triggerAsyncId()`
730729

731-
* Returns: {number} The same `triggerAsyncId` that is passed to the
730+
* Returns: {number} The same `triggerAsyncId` that is passed to the
732731
`AsyncResource` constructor.
733732

734733
[`after` callback]: #async_hooks_after_asyncid

doc/api/buffer.md

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -345,9 +345,9 @@ changes:
345345
346346
* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`],
347347
[`SharedArrayBuffer`] or the `.buffer` property of a [`TypedArray`].
348-
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`
348+
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
349349
* `length` {integer} Number of bytes to expose.
350-
**Default:** `arrayBuffer.length - byteOffset`
350+
**Default:** `arrayBuffer.length - byteOffset`.
351351

352352
This creates a view of the [`ArrayBuffer`] or [`SharedArrayBuffer`] without
353353
copying the underlying memory. For example, when passed a reference to the
@@ -459,7 +459,7 @@ changes:
459459
> Use [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] instead.
460460
461461
* `string` {string} String to encode.
462-
* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`
462+
* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`.
463463

464464
Creates a new `Buffer` containing `string`. The `encoding` parameter identifies
465465
the character encoding of `string`.
@@ -488,9 +488,9 @@ changes:
488488

489489
* `size` {integer} The desired length of the new `Buffer`.
490490
* `fill` {string|Buffer|integer} A value to pre-fill the new `Buffer` with.
491-
**Default:** `0`
491+
**Default:** `0`.
492492
* `encoding` {string} If `fill` is a string, this is its encoding.
493-
**Default:** `'utf8'`
493+
**Default:** `'utf8'`.
494494

495495
Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the
496496
`Buffer` will be *zero-filled*.
@@ -646,7 +646,7 @@ changes:
646646
* `string` {string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer} A
647647
value to calculate the length of.
648648
* `encoding` {string} If `string` is a string, this is its encoding.
649-
**Default:** `'utf8'`
649+
**Default:** `'utf8'`.
650650
* Returns: {integer} The number of bytes contained within `string`.
651651

652652
Returns the actual byte length of a string. This is not the same as
@@ -766,9 +766,9 @@ added: v5.10.0
766766

767767
* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`],
768768
[`SharedArrayBuffer`], or the `.buffer` property of a [`TypedArray`].
769-
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`
769+
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
770770
* `length` {integer} Number of bytes to expose.
771-
**Default:** `arrayBuffer.length - byteOffset`
771+
**Default:** `arrayBuffer.length - byteOffset`.
772772

773773
This creates a view of the [`ArrayBuffer`] without copying the underlying
774774
memory. For example, when passed a reference to the `.buffer` property of a
@@ -837,7 +837,7 @@ added: v5.10.0
837837
-->
838838

839839
* `string` {string} A string to encode.
840-
* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`
840+
* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`.
841841

842842
Creates a new `Buffer` containing `string`. The `encoding` parameter identifies
843843
the character encoding of `string`.
@@ -976,13 +976,13 @@ changes:
976976

977977
* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to compare to.
978978
* `targetStart` {integer} The offset within `target` at which to begin
979-
comparison. **Default:** `0`
979+
comparison. **Default:** `0`.
980980
* `targetEnd` {integer} The offset with `target` at which to end comparison
981-
(not inclusive). **Default:** `target.length`
981+
(not inclusive). **Default:** `target.length`.
982982
* `sourceStart` {integer} The offset within `buf` at which to begin comparison.
983-
**Default:** `0`
983+
**Default:** `0`.
984984
* `sourceEnd` {integer} The offset within `buf` at which to end comparison
985-
(not inclusive). **Default:** [`buf.length`]
985+
(not inclusive). **Default:** [`buf.length`].
986986
* Returns: {integer}
987987

988988
Compares `buf` with `target` and returns a number indicating whether `buf`
@@ -1039,11 +1039,11 @@ added: v0.1.90
10391039

10401040
* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to copy into.
10411041
* `targetStart` {integer} The offset within `target` at which to begin
1042-
copying to. **Default:** `0`
1042+
copying to. **Default:** `0`.
10431043
* `sourceStart` {integer} The offset within `buf` at which to begin copying from.
1044-
**Default:** `0`
1044+
**Default:** `0`.
10451045
* `sourceEnd` {integer} The offset within `buf` at which to stop copying (not
1046-
inclusive). **Default:** [`buf.length`]
1046+
inclusive). **Default:** [`buf.length`].
10471047
* Returns: {integer} The number of bytes copied.
10481048

10491049
Copies data from a region of `buf` to a region in `target` even if the `target`
@@ -1146,10 +1146,10 @@ changes:
11461146
-->
11471147

11481148
* `value` {string|Buffer|integer} The value to fill `buf` with.
1149-
* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`
1150-
* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`]
1149+
* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`.
1150+
* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`].
11511151
* `encoding` {string} If `value` is a string, this is its encoding.
1152-
**Default:** `'utf8'`
1152+
**Default:** `'utf8'`.
11531153
* Returns: {Buffer} A reference to `buf`.
11541154

11551155
Fills `buf` with the specified `value`. If the `offset` and `end` are not given,
@@ -1197,9 +1197,9 @@ added: v5.3.0
11971197
-->
11981198

11991199
* `value` {string|Buffer|integer} What to search for.
1200-
* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`
1200+
* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`.
12011201
* `encoding` {string} If `value` is a string, this is its encoding.
1202-
**Default:** `'utf8'`
1202+
**Default:** `'utf8'`.
12031203
* Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise.
12041204

12051205
Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`].
@@ -1237,9 +1237,9 @@ changes:
12371237
-->
12381238

12391239
* `value` {string|Buffer|Uint8Array|integer} What to search for.
1240-
* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`
1240+
* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`.
12411241
* `encoding` {string} If `value` is a string, this is its encoding.
1242-
**Default:** `'utf8'`
1242+
**Default:** `'utf8'`.
12431243
* Returns: {integer} The index of the first occurrence of `value` in `buf` or `-1`
12441244
if `buf` does not contain `value`.
12451245

@@ -1339,9 +1339,9 @@ changes:
13391339

13401340
* `value` {string|Buffer|Uint8Array|integer} What to search for.
13411341
* `byteOffset` {integer} Where to begin searching in `buf`.
1342-
**Default:** [`buf.length`]` - 1`
1342+
**Default:** [`buf.length`]` - 1`.
13431343
* `encoding` {string} If `value` is a string, this is its encoding.
1344-
**Default:** `'utf8'`
1344+
**Default:** `'utf8'`.
13451345
* Returns: {integer} The index of the last occurrence of `value` in `buf` or `-1`
13461346
if `buf` does not contain `value`.
13471347

@@ -1761,9 +1761,9 @@ changes:
17611761
calculations with them.
17621762
-->
17631763

1764-
* `start` {integer} Where the new `Buffer` will start. **Default:** `0`
1764+
* `start` {integer} Where the new `Buffer` will start. **Default:** `0`.
17651765
* `end` {integer} Where the new `Buffer` will end (not inclusive).
1766-
**Default:** [`buf.length`]
1766+
**Default:** [`buf.length`].
17671767
* Returns: {Buffer}
17681768

17691769
Returns a new `Buffer` that references the same memory as the original, but
@@ -1932,10 +1932,10 @@ console.log(copy);
19321932
added: v0.1.90
19331933
-->
19341934

1935-
* `encoding` {string} The character encoding to decode to. **Default:** `'utf8'`
1936-
* `start` {integer} The byte offset to start decoding at. **Default:** `0`
1935+
* `encoding` {string} The character encoding to decode to. **Default:** `'utf8'`.
1936+
* `start` {integer} The byte offset to start decoding at. **Default:** `0`.
19371937
* `end` {integer} The byte offset to stop decoding at (not inclusive).
1938-
**Default:** [`buf.length`]
1938+
**Default:** [`buf.length`].
19391939
* Returns: {string}
19401940

19411941
Decodes `buf` to a string according to the specified character encoding in
@@ -2009,9 +2009,9 @@ added: v0.1.90
20092009
-->
20102010

20112011
* `string` {string} String to be written to `buf`.
2012-
* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0`
2013-
* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset`
2014-
* `encoding` {string} The character encoding of `string`. **Default:** `'utf8'`
2012+
* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0`.
2013+
* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset`.
2014+
* `encoding` {string} The character encoding of `string`. **Default:** `'utf8'`.
20152015
* Returns: {integer} Number of bytes written.
20162016

20172017
Writes `string` to `buf` at `offset` according to the character encoding in `encoding`.
@@ -2326,7 +2326,7 @@ added: v0.5.5
23262326
* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - byteLength`.
23272327
* `byteLength` {integer} Number of bytes to write. Must satisfy: `0 < byteLength <= 6`.
23282328
* `noAssert` {boolean} Skip `value`, `offset`, and `byteLength` validation?
2329-
**Default:** `false`
2329+
**Default:** `false`.
23302330
* Returns: {integer} `offset` plus the number of bytes written.
23312331

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

0 commit comments

Comments
 (0)