doc: standardize function param/object prop style

PR-URL: nodejs#13769 Backport-PR-URL: nodejs#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]>
lev-kazakov · Oct 11, 2017 · 9c247c5 · 9c247c5
1 parent 827f843
commit 9c247c5
Show file tree

Hide file tree

Showing 10 changed files with 258 additions and 252 deletions.
diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md
@@ -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
diff --git a/doc/api/addons.md b/doc/api/addons.md
@@ -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.

diff --git a/doc/api/assert.md b/doc/api/assert.md
@@ -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`.

diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md
@@ -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.
@@ -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.
@@ -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
@@ -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
@@ -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:
@@ -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:
@@ -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:
 
@@ -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.
@@ -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
@@ -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