Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: standardize function param/object prop style #13769

Closed
wants to merge 2 commits into from
Closed

doc: standardize function param/object prop style #13769

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1f6748
doc: standardize function param/object prop style
gibfahn Jun 18, 2017
14f68e2
fixup! Address nits
gibfahn Sep 16, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions doc/STYLE_GUIDE.md
View file
Open in desktop
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
View file
Open in desktop
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
6 changes: 3 additions & 3 deletions doc/api/assert.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,9 +306,9 @@ added: v0.1.21
-->
* `actual` {any}
* `expected` {any}
* `message` {any} (default: 'Failed')
* `operator` {string} (default: '!=')
* `stackStartFunction` {function} (default: `assert.fail`)
* `message` {any} **Default:** `'Failed'`
* `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`. If
Expand Down
40 changes: 20 additions & 20 deletions doc/api/async_hooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,12 +79,12 @@ function promiseResolve(asyncId) { }
added: REPLACEME
-->

* `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}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Usually we just omit the return type if it's undefined, though I'm interested to hear another opinion.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think given that our docs aren't 100% complete in terms of listing return types, being explicit here is probably helpful for people.


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