doc: standardize function param/object prop style

Backport-PR-URL: #16560 PR-URL: #13769 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]>
nodejs · Nov 3, 2017 · 0f3901a · 0f3901a
1 parent 748d3e5
commit 0f3901a
Show file tree

Hide file tree

Showing 8 changed files with 270 additions and 235 deletions.
diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md
@@ -59,8 +59,16 @@
 * References to constructor instances should use camelCase.
 * References to methods should be used with parentheses: for example,
   `socket.end()` instead of `socket.end`.
+* 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
@@ -1040,8 +1040,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
@@ -202,8 +202,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`.