FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: standardize function param/object prop style · nodejs/node@9c247c5 · GitHub

/ node Public

Commit 9c247c5

Browse files
gibfahn
authored and
MylesBorins
committed
doc: standardize function param/object prop style
PR-URL: #13769 Backport-PR-URL: #15687 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
1 parent 827f843 commit 9c247c5

10 files changed

Lines changed: 258 additions & 252 deletions

File tree

‎doc/STYLE_GUIDE.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,16 @@
6565
* Make the "Note:" label italic, i.e. `*Note*:`.
6666
* Use a capital letter after the "Note:" label.
6767
* Preferably, make the note a new paragraph for better visual distinction.
68+
* Function arguments or object properties should use the following format:
69+
* <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`</code>
70+
* E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`</code>
71+
* The `type` should refer to a Node.js type or a [JavaScript type][]
72+
* Function returns should use the following format:
73+
* <code>* Returns: {type|type2} Optional description.</code>
74+
* E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code>
6875

69-
[plugin]: http://editorconfig.org/#download
70-
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
7176
[Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash
77+
[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
78+
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
7279
[The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage
80+
[plugin]: http://editorconfig.org/#download

‎doc/api/addons.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1060,8 +1060,8 @@ has ended but before the JavaScript VM is terminated and Node.js shuts down.
10601060

10611061
#### void AtExit(callback, args)
10621062

1063-
* `callback`: `void (*)(void*)` - A pointer to the function to call at exit.
1064-
* `args`: `void*` - A pointer to pass to the callback at exit.
1063+
* `callback` {void (\*)(void\*)} A pointer to the function to call at exit.
1064+
* `args` {void\*} A pointer to pass to the callback at exit.
10651065

10661066
Registers exit hooks that run after the event loop has ended but before the VM
10671067
is killed.

‎doc/api/assert.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -275,8 +275,8 @@ added: v0.1.21
275275
* `actual` {any}
276276
* `expected` {any}
277277
* `message` {any}
278-
* `operator` {string} (default: '!=')
279-
* `stackStartFunction` {function} (default: `assert.fail`)
278+
* `operator` {string} **Default:** '!='
279+
* `stackStartFunction` {function} **Default:** `assert.fail`
280280

281281
Throws an `AssertionError`. If `message` is falsy, the error message is set as
282282
the values of `actual` and `expected` separated by the provided `operator`.

‎doc/api/async_hooks.md‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -79,12 +79,12 @@ function promiseResolve(asyncId) { }
7979
added: v8.1.0
8080
-->
8181

82-
* `callbacks` {Object} the [Hook Callbacks][] to register
82+
* `callbacks` {Object} The [Hook Callbacks][] to register
8383
* `init` {Function} The [`init` callback][].
8484
* `before` {Function} The [`before` callback][].
8585
* `after` {Function} The [`after` callback][].
8686
* `destroy` {Function} The [`destroy` callback][].
87-
* Returns: `{AsyncHook}` instance used for disabling and enabling hooks
87+
* Returns: `{AsyncHook}` Instance used for disabling and enabling hooks
8888

8989
Registers functions to be called for different lifetime events of each async
9090
operation.
@@ -168,7 +168,7 @@ doing this the otherwise infinite recursion is broken.
168168

169169
#### `asyncHook.enable()`
170170

171-
* Returns {AsyncHook} A reference to `asyncHook`.
171+
* Returns: {AsyncHook} A reference to `asyncHook`.
172172

173173
Enable the callbacks for a given `AsyncHook` instance. If no callbacks are
174174
provided enabling is a noop.
@@ -184,7 +184,7 @@ const hook = async_hooks.createHook(callbacks).enable();
184184

185185
#### `asyncHook.disable()`
186186

187-
* Returns {AsyncHook} A reference to `asyncHook`.
187+
* Returns: {AsyncHook} A reference to `asyncHook`.
188188

189189
Disable the callbacks for a given `AsyncHook` instance from the global pool of
190190
AsyncHook callbacks to be executed. Once a hook has been disabled it will not
@@ -200,12 +200,12 @@ instance is destructed.
200200

201201
##### `init(asyncId, type, triggerAsyncId, resource)`
202202

203-
* `asyncId` {number} a unique ID for the async resource
204-
* `type` {string} the type of the async resource
205-
* `triggerAsyncId` {number} the unique ID of the async resource in whose
206-
execution context this async resource was created
207-
* `resource` {Object} reference to the resource representing the async operation,
208-
needs to be released during _destroy_
203+
* `asyncId` {number} A unique ID for the async resource.
204+
* `type` {string} The type of the async resource.
205+
* `triggerAsyncId` {number} The unique ID of the async resource in whose
206+
execution context this async resource was created.
207+
* `resource` {Object} Reference to the resource representing the async operation,
208+
needs to be released during _destroy_.
209209

210210
Called when a class is constructed that has the _possibility_ to emit an
211211
asynchronous event. This _does not_ mean the instance must call
@@ -468,7 +468,7 @@ init for PROMISE with id 6, trigger id: 5 # the Promise returned by then()
468468

469469
#### `async_hooks.executionAsyncId()`
470470

471-
* Returns {number} the `asyncId` of the current execution context. Useful to
471+
* Returns: {number} The `asyncId` of the current execution context. Useful to
472472
track when something calls.
473473

474474
For example:
@@ -502,7 +502,7 @@ const server = net.createServer(function onConnection(conn) {
502502

503503
#### `async_hooks.triggerAsyncId()`
504504

505-
* Returns {number} the ID of the resource responsible for calling the callback
505+
* Returns: {number} The ID of the resource responsible for calling the callback
506506
that is currently being executed.
507507

508508
For example:
@@ -569,9 +569,9 @@ asyncResource.triggerAsyncId();
569569
#### `AsyncResource(type[, triggerAsyncId])`
570570

571571
* arguments
572-
* `type` {string} the type of async event
573-
* `triggerAsyncId` {number} the ID of the execution context that created this
574-
async event
572+
* `type` {string} The type of async event.
573+
* `triggerAsyncId` {number} The ID of the execution context that created this
574+
async event.
575575

576576
Example usage:
577577

@@ -599,15 +599,15 @@ class DBQuery extends AsyncResource {
599599

600600
#### `asyncResource.emitBefore()`
601601

602-
* Returns {undefined}
602+
* Returns: {undefined}
603603

604604
Call all `before` callbacks to notify that a new asynchronous execution context
605605
is being entered. If nested calls to `emitBefore()` are made, the stack of
606606
`asyncId`s will be tracked and properly unwound.
607607

608608
#### `asyncResource.emitAfter()`
609609

610-
* Returns {undefined}
610+
* Returns: {undefined}
611611

612612
Call all `after` callbacks. If nested calls to `emitBefore()` were made, then
613613
make sure the stack is unwound properly. Otherwise an error will be thrown.
@@ -618,7 +618,7 @@ called for all `asyncId`s on the stack if the error is handled by a domain or
618618

619619
#### `asyncResource.emitDestroy()`
620620

621-
* Returns {undefined}
621+
* Returns: {undefined}
622622

623623
Call all `destroy` hooks. This should only ever be called once. An error will
624624
be thrown if it is called more than once. This **must** be manually called. If
@@ -627,11 +627,11 @@ never be called.
627627

628628
#### `asyncResource.asyncId()`
629629

630-
* Returns {number} the unique `asyncId` assigned to the resource.
630+
* Returns: {number} The unique `asyncId` assigned to the resource.
631631

632632
#### `asyncResource.triggerAsyncId()`
633633

634-
* Returns {number} the same `triggerAsyncId` that is passed to the `AsyncResource`
634+
* Returns: {number} The same `triggerAsyncId` that is passed to the `AsyncResource`
635635
constructor.
636636

637637
[`after` callback]: #async_hooks_after_asyncid

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL