Skip to content

Commit

Permalink
doc: format doc/api/*.md with markdown formatter
Browse files Browse the repository at this point in the history
PR-URL: #40403
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Zijian Liu <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
  • Loading branch information
Trott authored and targos committed Oct 20, 2021
1 parent 3f7c503 commit 8dce85a
Show file tree
Hide file tree
Showing 58 changed files with 4,253 additions and 1,138 deletions.
1 change: 1 addition & 0 deletions doc/api/addons.md
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,7 @@ NODE_MODULE_INIT(/* exports, module, context */) {
```
#### Worker support
<!-- YAML
changes:
- version:
Expand Down
26 changes: 26 additions & 0 deletions doc/api/assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ The `assert` module provides a set of assertion functions for verifying
invariants.

## Strict assertion mode

<!-- YAML
added: v9.9.0
changes:
Expand Down Expand Up @@ -138,6 +139,7 @@ Indicates the failure of an assertion. All errors thrown by the `assert` module
will be instances of the `AssertionError` class.

### `new assert.AssertionError(options)`

<!-- YAML
added: v0.1.21
-->
Expand Down Expand Up @@ -216,6 +218,7 @@ try {
```

## Class: `assert.CallTracker`

<!-- YAML
added:
- v14.2.0
Expand All @@ -227,6 +230,7 @@ added:
This feature is currently experimental and behavior might still change.

### `new assert.CallTracker()`

<!-- YAML
added:
- v14.2.0
Expand Down Expand Up @@ -278,6 +282,7 @@ process.on('exit', () => {
```

### `tracker.calls([fn][, exact])`

<!-- YAML
added:
- v14.2.0
Expand Down Expand Up @@ -320,6 +325,7 @@ const callsfunc = tracker.calls(func);
```

### `tracker.report()`

<!-- YAML
added:
- v14.2.0
Expand Down Expand Up @@ -396,6 +402,7 @@ tracker.report();
```

### `tracker.verify()`

<!-- YAML
added:
- v14.2.0
Expand Down Expand Up @@ -443,6 +450,7 @@ tracker.verify();
```

## `assert(value[, message])`

<!-- YAML
added: v0.5.9
-->
Expand All @@ -453,6 +461,7 @@ added: v0.5.9
An alias of [`assert.ok()`][].

## `assert.deepEqual(actual, expected[, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -629,6 +638,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
[`AssertionError`][].

## `assert.deepStrictEqual(actual, expected[, message])`

<!-- YAML
added: v1.2.0
changes:
Expand Down Expand Up @@ -879,6 +889,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.

## `assert.doesNotMatch(string, regexp[, message])`

<!-- YAML
added:
- v13.6.0
Expand Down Expand Up @@ -929,6 +940,7 @@ instance of an [`Error`][] then it will be thrown instead of the
[`AssertionError`][].

## `assert.doesNotReject(asyncFn[, error][, message])`

<!-- YAML
added: v10.0.0
-->
Expand Down Expand Up @@ -1001,6 +1013,7 @@ assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
```

## `assert.doesNotThrow(fn[, error][, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -1117,6 +1130,7 @@ assert.doesNotThrow(
```

## `assert.equal(actual, expected[, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -1187,6 +1201,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.

## `assert.fail([message])`

<!-- YAML
added: v0.1.21
-->
Expand Down Expand Up @@ -1227,6 +1242,7 @@ Using `assert.fail()` with more than two arguments is possible but deprecated.
See below for further details.

## `assert.fail(actual, expected[, message[, operator[, stackStartFn]]])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -1324,6 +1340,7 @@ suppressFrame();
```

## `assert.ifError(value)`

<!-- YAML
added: v0.1.97
changes:
Expand Down Expand Up @@ -1397,6 +1414,7 @@ let err;
```

## `assert.match(string, regexp[, message])`

<!-- YAML
added:
- v13.6.0
Expand Down Expand Up @@ -1447,6 +1465,7 @@ instance of an [`Error`][] then it will be thrown instead of the
[`AssertionError`][].

## `assert.notDeepEqual(actual, expected[, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -1570,6 +1589,7 @@ If the values are deeply equal, an [`AssertionError`][] is thrown with a
instead of the `AssertionError`.

## `assert.notDeepStrictEqual(actual, expected[, message])`

<!-- YAML
added: v1.2.0
changes:
Expand Down Expand Up @@ -1629,6 +1649,7 @@ the `message` parameter is an instance of an [`Error`][] then it will be thrown
instead of the [`AssertionError`][].

## `assert.notEqual(actual, expected[, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -1693,6 +1714,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.

## `assert.notStrictEqual(actual, expected[, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -1745,6 +1767,7 @@ If the values are strictly equal, an [`AssertionError`][] is thrown with a
instead of the `AssertionError`.

## `assert.ok(value[, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -1862,6 +1885,7 @@ assert(0);
```

## `assert.rejects(asyncFn[, error][, message])`

<!-- YAML
added: v10.0.0
-->
Expand Down Expand Up @@ -1982,6 +2006,7 @@ example in [`assert.throws()`][] carefully if using a string as the second
argument gets considered.

## `assert.strictEqual(actual, expected[, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down Expand Up @@ -2060,6 +2085,7 @@ If the values are not strictly equal, an [`AssertionError`][] is thrown with a
instead of the [`AssertionError`][].

## `assert.throws(fn[, error][, message])`

<!-- YAML
added: v0.1.21
changes:
Expand Down
13 changes: 13 additions & 0 deletions doc/api/async_context.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
<!-- source_link=lib/async_hooks.js -->

## Introduction

These classes are used to associate state and propagate it throughout
callbacks and promise chains.
They allow storing data throughout the lifetime of a web request
Expand All @@ -25,6 +26,7 @@ const async_hooks = require('async_hooks');
```

## Class: `AsyncLocalStorage`

<!-- YAML
added:
- v13.10.0
Expand Down Expand Up @@ -115,6 +117,7 @@ Multiple instances can safely exist simultaneously without risk of interfering
with each other data.

### `new AsyncLocalStorage()`

<!-- YAML
added:
- v13.10.0
Expand All @@ -125,6 +128,7 @@ Creates a new instance of `AsyncLocalStorage`. Store is only provided within a
`run()` call or after an `enterWith()` call.

### `asyncLocalStorage.disable()`

<!-- YAML
added:
- v13.10.0
Expand All @@ -149,6 +153,7 @@ Use this method when the `asyncLocalStorage` is not in use anymore
in the current process.

### `asyncLocalStorage.getStore()`

<!-- YAML
added:
- v13.10.0
Expand All @@ -163,6 +168,7 @@ calling `asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()`, it
returns `undefined`.

### `asyncLocalStorage.enterWith(store)`

<!-- YAML
added:
- v13.11.0
Expand Down Expand Up @@ -212,6 +218,7 @@ asyncLocalStorage.getStore(); // Returns the same object
```

### `asyncLocalStorage.run(store, callback[, ...args])`

<!-- YAML
added:
- v13.10.0
Expand Down Expand Up @@ -251,6 +258,7 @@ try {
```

### `asyncLocalStorage.exit(callback[, ...args])`

<!-- YAML
added:
- v13.10.0
Expand Down Expand Up @@ -326,6 +334,7 @@ the loss. When the code logs `undefined`, the last callback called is probably
responsible for the context loss.

## Class: `AsyncResource`

<!-- YAML
changes:
- version: v16.4.0
Expand Down Expand Up @@ -434,6 +443,7 @@ class DBQuery extends AsyncResource {
```

### Static method: `AsyncResource.bind(fn[, type, [thisArg]])`

<!-- YAML
added:
- v14.8.0
Expand All @@ -455,6 +465,7 @@ The returned function will have an `asyncResource` property referencing
the `AsyncResource` to which the function is bound.

### `asyncResource.bind(fn[, thisArg])`

<!-- YAML
added:
- v14.8.0
Expand All @@ -474,6 +485,7 @@ The returned function will have an `asyncResource` property referencing
the `AsyncResource` to which the function is bound.

### `asyncResource.runInAsyncScope(fn[, thisArg, ...args])`

<!-- YAML
added: v9.6.0
-->
Expand Down Expand Up @@ -507,6 +519,7 @@ never be called.
`AsyncResource` constructor.

<a id="async-resource-worker-pool"></a>

### Using `AsyncResource` for a `Worker` thread pool

The following example shows how to use the `AsyncResource` class to properly
Expand Down
14 changes: 7 additions & 7 deletions doc/api/async_hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ const asyncHook = async_hooks.createHook(new MyAddedCallbacks());

Because promises are asynchronous resources whose lifecycle is tracked
via the async hooks mechanism, the `init()`, `before()`, `after()`, and
`destroy()` callbacks *must not* be async functions that return promises.
`destroy()` callbacks _must not_ be async functions that return promises.

### Error handling

Expand Down Expand Up @@ -350,8 +350,8 @@ listening to the hooks.

`triggerAsyncId` is the `asyncId` of the resource that caused (or "triggered")
the new resource to initialize and that caused `init` to call. This is different
from `async_hooks.executionAsyncId()` that only shows *when* a resource was
created, while `triggerAsyncId` shows *why* a resource was created.
from `async_hooks.executionAsyncId()` that only shows _when_ a resource was
created, while `triggerAsyncId` shows _why_ a resource was created.

The following is a simple demonstration of `triggerAsyncId`:

Expand Down Expand Up @@ -499,13 +499,13 @@ TickObject(6)

The `TCPSERVERWRAP` is not part of this graph, even though it was the reason for
`console.log()` being called. This is because binding to a port without a host
name is a *synchronous* operation, but to maintain a completely asynchronous
name is a _synchronous_ operation, but to maintain a completely asynchronous
API the user's callback is placed in a `process.nextTick()`. Which is why
`TickObject` is present in the output and is a 'parent' for `.listen()`
callback.

The graph only shows *when* a resource was created, not *why*, so to track
the *why* use `triggerAsyncId`. Which can be represented with the following
The graph only shows _when_ a resource was created, not _why_, so to track
the _why_ use `triggerAsyncId`. Which can be represented with the following
graph:

```console
Expand Down Expand Up @@ -545,7 +545,7 @@ it only once.
Called immediately after the callback specified in `before` is completed.

If an uncaught exception occurs during execution of the callback, then `after`
will run *after* the `'uncaughtException'` event is emitted or a `domain`'s
will run _after_ the `'uncaughtException'` event is emitted or a `domain`'s
handler runs.

#### `destroy(asyncId)`
Expand Down
Loading

0 comments on commit 8dce85a

Please sign in to comment.