Skip to content

Commit

Permalink
doc: standardize function param/object prop style
Browse files Browse the repository at this point in the history
PR-URL: #13769
Backport-PR-URL: #15687
Reviewed-By: Vse Mozhet Byt <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
  • Loading branch information
gibfahn authored and MylesBorins committed Sep 29, 2017
1 parent cd19e5f commit e4c6698
Show file tree
Hide file tree
Showing 10 changed files with 258 additions and 252 deletions.
12 changes: 10 additions & 2 deletions doc/STYLE_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,16 @@
* Make the "Note:" label italic, i.e. `*Note*:`.
* Use a capital letter after the "Note:" label.
* Preferably, make the note a new paragraph for better visual distinction.
* Function arguments or object properties should use the following format:
* <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`</code>
* E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`</code>
* The `type` should refer to a Node.js type or a [JavaScript type][]
* Function returns should use the following format:
* <code>* Returns: {type|type2} Optional description.</code>
* E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code>

[plugin]: http://editorconfig.org/#download
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
[Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash
[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
[The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage
[plugin]: http://editorconfig.org/#download
4 changes: 2 additions & 2 deletions doc/api/addons.md
Original file line number Diff line number Diff line change
Expand Up @@ -1060,8 +1060,8 @@ has ended but before the JavaScript VM is terminated and Node.js shuts down.

#### void AtExit(callback, args)

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

Registers exit hooks that run after the event loop has ended but before the VM
is killed.
Expand Down
4 changes: 2 additions & 2 deletions doc/api/assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -275,8 +275,8 @@ added: v0.1.21
* `actual` {any}
* `expected` {any}
* `message` {any}
* `operator` {string} (default: '!=')
* `stackStartFunction` {function} (default: `assert.fail`)
* `operator` {string} **Default:** '!='
* `stackStartFunction` {function} **Default:** `assert.fail`

Throws an `AssertionError`. If `message` is falsy, the error message is set as
the values of `actual` and `expected` separated by the provided `operator`.
Expand Down
40 changes: 20 additions & 20 deletions doc/api/async_hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,12 +79,12 @@ function promiseResolve(asyncId) { }
added: v8.1.0
-->

* `callbacks` {Object} the [Hook Callbacks][] to register
* `callbacks` {Object} The [Hook Callbacks][] to register
* `init` {Function} The [`init` callback][].
* `before` {Function} The [`before` callback][].
* `after` {Function} The [`after` callback][].
* `destroy` {Function} The [`destroy` callback][].
* Returns: `{AsyncHook}` instance used for disabling and enabling hooks
* Returns: `{AsyncHook}` Instance used for disabling and enabling hooks

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

#### `asyncHook.enable()`

* Returns {AsyncHook} A reference to `asyncHook`.
* Returns: {AsyncHook} A reference to `asyncHook`.

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

#### `asyncHook.disable()`

* Returns {AsyncHook} A reference to `asyncHook`.
* Returns: {AsyncHook} A reference to `asyncHook`.

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

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

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

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

#### `async_hooks.executionAsyncId()`

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

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

#### `async_hooks.triggerAsyncId()`

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

For example:
Expand Down Expand Up @@ -569,9 +569,9 @@ asyncResource.triggerAsyncId();
#### `AsyncResource(type[, triggerAsyncId])`

* arguments
* `type` {string} the type of async event
* `triggerAsyncId` {number} the ID of the execution context that created this
async event
* `type` {string} The type of async event.
* `triggerAsyncId` {number} The ID of the execution context that created this
async event.

Example usage:

Expand Down Expand Up @@ -599,15 +599,15 @@ class DBQuery extends AsyncResource {

#### `asyncResource.emitBefore()`

* Returns {undefined}
* Returns: {undefined}

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

#### `asyncResource.emitAfter()`

* Returns {undefined}
* Returns: {undefined}

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

#### `asyncResource.emitDestroy()`

* Returns {undefined}
* Returns: {undefined}

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

#### `asyncResource.asyncId()`

* Returns {number} the unique `asyncId` assigned to the resource.
* Returns: {number} The unique `asyncId` assigned to the resource.

#### `asyncResource.triggerAsyncId()`

* Returns {number} the same `triggerAsyncId` that is passed to the `AsyncResource`
* Returns: {number} The same `triggerAsyncId` that is passed to the `AsyncResource`
constructor.

[`after` callback]: #async_hooks_after_asyncid
Expand Down
Loading

0 comments on commit e4c6698

Please sign in to comment.