doc: add more missing backticks

Also, fix some other nits in passing
(formatting, punctuation, typos, redundancy, obsoleteness).

PR-URL: #20438
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>

doc/api/addons.md

@@ -9,7 +9,7 @@ just as if they were an ordinary Node.js module. They are used primarily to
 provide an interface between JavaScript running in Node.js and C/C++ libraries.
 
 At the moment, the method for implementing Addons is rather complicated,
-involving knowledge of several components and APIs :
+involving knowledge of several components and APIs:
 
  - V8: the C++ library Node.js currently uses to provide the
    JavaScript implementation. V8 provides the mechanisms for creating objects,
@@ -93,7 +93,7 @@ There is no semi-colon after `NODE_MODULE` as it's not a function (see
 `node.h`).
 
 The `module_name` must match the filename of the final binary (excluding
-the .node suffix).
+the `.node` suffix).
 
 In the `hello.cc` example, then, the initialization function is `init` and the
 Addon module name is `addon`.
@@ -1085,9 +1085,9 @@ console.log(result);
 
 ### AtExit hooks
 
-An "AtExit" hook is a function that is invoked after the Node.js event loop
+An `AtExit` hook is a function that is invoked after the Node.js event loop
 has ended but before the JavaScript VM is terminated and Node.js shuts down.
-"AtExit" hooks are registered using the `node::AtExit` API.
+`AtExit` hooks are registered using the `node::AtExit` API.
 
 #### void AtExit(callback, args)
 
@@ -1099,12 +1099,12 @@ has ended but before the JavaScript VM is terminated and Node.js shuts down.
 Registers exit hooks that run after the event loop has ended but before the VM
 is killed.
 
-AtExit takes two parameters: a pointer to a callback function to run at exit,
+`AtExit` takes two parameters: a pointer to a callback function to run at exit,
 and a pointer to untyped context data to be passed to that callback.
 
 Callbacks are run in last-in first-out order.
 
-The following `addon.cc` implements AtExit:
+The following `addon.cc` implements `AtExit`:
 
 ```cpp
 // addon.cc

doc/api/assert.md

@@ -165,10 +165,10 @@ added: v0.1.21
 changes:
   - version: v9.0.0
     pr-url: https://github.com/nodejs/node/pull/15001
-    description: Error names and messages are now properly compared
+    description: The `Error` names and messages are now properly compared
   - version: v8.0.0
     pr-url: https://github.com/nodejs/node/pull/12142
-    description: Set and Map content is also compared
+    description: The `Set` and `Map` content is also compared
   - version: v6.4.0, v4.7.1
     pr-url: https://github.com/nodejs/node/pull/8002
     description: Typed array slices are handled correctly now.
@@ -208,7 +208,7 @@ the [`RegExp`][] object are not enumerable:
 assert.deepEqual(/a/gi, new Date());
 ```
 
-An exception is made for [`Map`][] and [`Set`][]. Maps and Sets have their
+An exception is made for [`Map`][] and [`Set`][]. `Map`s and `Set`s have their
 contained items compared too, as expected.
 
 "Deep" equality means that the enumerable "own" properties of child objects
@@ -264,15 +264,15 @@ changes:
     description: Enumerable symbol properties are now compared.
   - version: v9.0.0
     pr-url: https://github.com/nodejs/node/pull/15036
-    description: NaN is now compared using the
+    description: The `NaN` is now compared using the
               [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero)
               comparison.
   - version: v8.5.0
     pr-url: https://github.com/nodejs/node/pull/15001
-    description: Error names and messages are now properly compared
+    description: The `Error` names and messages are now properly compared
   - version: v8.0.0
     pr-url: https://github.com/nodejs/node/pull/12142
-    description: Set and Map content is also compared
+    description: The `Set` and `Map` content is also compared
   - version: v6.4.0, v4.7.1
     pr-url: https://github.com/nodejs/node/pull/8002
     description: Typed array slices are handled correctly now.
@@ -303,8 +303,8 @@ are recursively evaluated also by the following rules.
   enumerable properties.
 * Enumerable own [`Symbol`][] properties are compared as well.
 * [Object wrappers][] are compared both as objects and unwrapped values.
-* Object properties are compared unordered.
-* Map keys and Set items are compared unordered.
+* `Object` properties are compared unordered.
+* `Map` keys and `Set` items are compared unordered.
 * Recursion stops when both sides differ or both sides encounter a circular
   reference.
 * [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values. See
@@ -413,10 +413,10 @@ function and awaits the returned promise to complete. It will then check that
 the promise is not rejected.
 
 If `block` is a function and it throws an error synchronously,
-`assert.doesNotReject()` will return a rejected Promise with that error. If the
-function does not return a promise, `assert.doesNotReject()` will return a
-rejected Promise with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the
-error handler is skipped.
+`assert.doesNotReject()` will return a rejected `Promise` with that error. If
+the function does not return a promise, `assert.doesNotReject()` will return a
+rejected `Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases
+the error handler is skipped.
 
 Please note: Using `assert.doesNotReject()` is actually not useful because there
 is little benefit by catching a rejection and then rejecting it again. Instead,
@@ -494,7 +494,7 @@ assert.doesNotThrow(
 ```
 
 However, the following will result in an `AssertionError` with the message
-'Got unwanted exception (TypeError)..':
+'Got unwanted exception...':
 
 <!-- eslint-disable no-restricted-syntax -->
 ```js
@@ -519,7 +519,7 @@ assert.doesNotThrow(
   /Wrong value/,
   'Whoops'
 );
-// Throws: AssertionError: Got unwanted exception (TypeError). Whoops
+// Throws: AssertionError: Got unwanted exception: Whoops
 ```
 
 ## assert.equal(actual, expected[, message])
@@ -656,7 +656,7 @@ changes:
   - version: v10.0.0
     pr-url: https://github.com/nodejs/node/pull/18247
     description: Instead of throwing the original error it is now wrapped into
-                 a AssertionError that contains the full stack trace.
+                 an `AssertionError` that contains the full stack trace.
   - version: v10.0.0
     pr-url: https://github.com/nodejs/node/pull/18247
     description: Value may now only be `undefined` or `null`. Before any truthy
@@ -701,10 +701,10 @@ added: v0.1.21
 changes:
   - version: v9.0.0
     pr-url: https://github.com/nodejs/node/pull/15001
-    description: Error names and messages are now properly compared
+    description: The `Error` names and messages are now properly compared
   - version: v8.0.0
     pr-url: https://github.com/nodejs/node/pull/12142
-    description: Set and Map content is also compared
+    description: The `Set` and `Map` content is also compared
   - version: v6.4.0, v4.7.1
     pr-url: https://github.com/nodejs/node/pull/8002
     description: Typed array slices are handled correctly now.
@@ -774,18 +774,18 @@ added: v1.2.0
 changes:
   - version: v9.0.0
     pr-url: https://github.com/nodejs/node/pull/15398
-    description: -0 and +0 are not considered equal anymore.
+    description: The `-0` and `+0` are not considered equal anymore.
   - version: v9.0.0
     pr-url: https://github.com/nodejs/node/pull/15036
-    description: NaN is now compared using the
+    description: The `NaN` is now compared using the
               [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero)
               comparison.
   - version: v9.0.0
     pr-url: https://github.com/nodejs/node/pull/15001
-    description: Error names and messages are now properly compared
+    description: The `Error` names and messages are now properly compared
   - version: v8.0.0
     pr-url: https://github.com/nodejs/node/pull/12142
-    description: Set and Map content is also compared
+    description: The `Set` and `Map` content is also compared
   - version: v6.4.0, v4.7.1
     pr-url: https://github.com/nodejs/node/pull/8002
     description: Typed array slices are handled correctly now.
@@ -893,7 +893,8 @@ added: v0.1.21
 changes:
   - version: v10.0.0
     pr-url: https://github.com/nodejs/node/pull/18319
-    description: assert.ok() (no arguments) will now use a predefined error msg.
+    description: The `assert.ok()` (no arguments) will now use a predefined
+                 error message.
 -->
 * `value` {any}
 * `message` {any}
@@ -907,7 +908,7 @@ parameter is `undefined`, a default error message is assigned. If the `message`
 parameter is an instance of an [`Error`][] then it will be thrown instead of the
 `AssertionError`.
 If no arguments are passed in at all `message` will be set to the string:
-"No value argument passed to assert.ok".
+``'No value argument passed to `assert.ok()`'``.
 
 Be aware that in the `repl` the error message will be different to the one
 thrown in a file! See below for further details.
@@ -966,9 +967,9 @@ function and awaits the returned promise to complete. It will then check that
 the promise is rejected.
 
 If `block` is a function and it throws an error synchronously,
-`assert.rejects()` will return a rejected Promise with that error. If the
+`assert.rejects()` will return a rejected `Promise` with that error. If the
 function does not return a promise, `assert.rejects()` will return a rejected
-Promise with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the error
+`Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the error
 handler is skipped.
 
 Besides the async nature to await the completion behaves identically to

doc/api/async_hooks.md

@@ -17,8 +17,8 @@ const async_hooks = require('async_hooks');
 An asynchronous resource represents an object with an associated callback.
 This callback may be called multiple times, for example, the `'connection'`
 event in `net.createServer()`, or just a single time like in `fs.open()`.
-A resource can also be closed before the callback is called. AsyncHook does not
-explicitly distinguish between these different cases but will represent them
+A resource can also be closed before the callback is called. `AsyncHook` does
+not explicitly distinguish between these different cases but will represent them
 as the abstract concept that is a resource.
 
 ## Public API
@@ -188,7 +188,7 @@ const hook = async_hooks.createHook(callbacks).enable();
 * 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
+`AsyncHook` callbacks to be executed. Once a hook has been disabled it will not
 be called again until enabled.
 
 For API consistency `disable()` also returns the `AsyncHook` instance.
@@ -299,10 +299,10 @@ and document their own resource objects. For example, such a resource object
 could contain the SQL query being executed.
 
 In the case of Promises, the `resource` object will have `promise` property
-that refers to the Promise that is being initialized, and a `isChainedPromise`
-property, set to `true` if the promise has a parent promise, and `false`
-otherwise. For example, in the case of `b = a.then(handler)`, `a` is considered
-a parent Promise of `b`. Here, `b` is considered a chained promise.
+that refers to the `Promise` that is being initialized, and an
+`isChainedPromise` property, set to `true` if the promise has a parent promise,
+and `false` otherwise. For example, in the case of `b = a.then(handler)`, `a` is
+considered a parent `Promise` of `b`. Here, `b` is considered a chained promise.
 
 In some cases the resource object is reused for performance reasons, it is
 thus not safe to use it as a key in a `WeakMap` or add properties to it.
@@ -466,7 +466,7 @@ added: v8.1.0
 changes:
   - version: v8.2.0
     pr-url: https://github.com/nodejs/node/pull/13490
-    description: Renamed from currentId
+    description: Renamed from `currentId`
 -->
 
 * Returns: {number} The `asyncId` of the current execution context. Useful to
@@ -498,7 +498,7 @@ const server = net.createServer(function onConnection(conn) {
 });
 ```
 
-Note that promise contexts may not get precise executionAsyncIds by default.
+Note that promise contexts may not get precise `executionAsyncIds` by default.
 See the section on [promise execution tracking][].
 
 #### async_hooks.triggerAsyncId()
@@ -521,12 +521,12 @@ const server = net.createServer((conn) => {
 });
 ```
 
-Note that promise contexts may not get valid triggerAsyncIds by default. See
+Note that promise contexts may not get valid `triggerAsyncId`s by default. See
 the section on [promise execution tracking][].
 
 ## Promise execution tracking
 
-By default, promise executions are not assigned asyncIds due to the relatively
+By default, promise executions are not assigned `asyncId`s due to the relatively
 expensive nature of the [promise introspection API][PromiseHooks] provided by
 V8. This means that programs using promises or `async`/`await` will not get
 correct execution and trigger ids for promise callback contexts by default.
@@ -542,10 +542,10 @@ Promise.resolve(1729).then(() => {
 // eid 1 tid 0
 ```
 
-Observe that the `then` callback claims to have executed in the context of the
+Observe that the `then()` callback claims to have executed in the context of the
 outer scope even though there was an asynchronous hop involved. Also note that
-the triggerAsyncId value is 0, which means that we are missing context about the
-resource that caused (triggered) the `then` callback to be executed.
+the `triggerAsyncId` value is `0`, which means that we are missing context about
+the resource that caused (triggered) the `then()` callback to be executed.
 
 Installing async hooks via `async_hooks.createHook` enables promise execution
 tracking. Example:
@@ -562,15 +562,16 @@ Promise.resolve(1729).then(() => {
 
 In this example, adding any actual hook function enabled the tracking of
 promises. There are two promises in the example above; the promise created by
-`Promise.resolve()` and the promise returned by the call to `then`. In the
-example above, the first promise got the asyncId 6 and the latter got asyncId 7.
-During the execution of the `then` callback, we are executing in the context of
-promise with asyncId 7. This promise was triggered by async resource 6.
+`Promise.resolve()` and the promise returned by the call to `then()`. In the
+example above, the first promise got the `asyncId` `6` and the latter got
+`asyncId` `7`. During the execution of the `then()` callback, we are executing
+in the context of promise with `asyncId` `7`. This promise was triggered by
+async resource `6`.
 
 Another subtlety with promises is that `before` and `after` callbacks are run
-only on chained promises. That means promises not created by `then`/`catch` will
-not have the `before` and `after` callbacks fired on them. For more details see
-the details of the V8 [PromiseHooks][] API.
+only on chained promises. That means promises not created by `then()`/`catch()`
+will not have the `before` and `after` callbacks fired on them. For more details
+see the details of the V8 [PromiseHooks][] API.
 
 ## JavaScript Embedder API
 
@@ -632,8 +633,9 @@ asyncResource.emitAfter();
   async event. **Default:** `executionAsyncId()`.
   * `requireManualDestroy` {boolean} Disables automatic `emitDestroy` when the
   object is garbage collected. This usually does not need to be set (even if
-  `emitDestroy` is called manually), unless the resource's asyncId is retrieved
-  and the sensitive API's `emitDestroy` is called with it. **Default:** `false`.
+  `emitDestroy` is called manually), unless the resource's `asyncId` is
+  retrieved and the sensitive API's `emitDestroy` is called with it.
+  **Default:** `false`.
 
 Example usage: