docs: TSDoc + reference of fulfillment service (#5761)

www/apps/docs/content/references/js-client/EventEmitter/classes/internal.EventEmitter.EventEmitterAsyncResource.mdx

@@ -6,18 +6,43 @@ import ParameterTypes from "@site/src/components/ParameterTypes"
 
 # EventEmitterAsyncResource
 
-Integrates `EventEmitter` with `AsyncResource` for `EventEmitter`s that require
-manual async tracking. Specifically, all events emitted by instances of
-`EventEmitterAsyncResource` will run within its async context.
+Integrates `EventEmitter` with `AsyncResource` for `EventEmitter`s that
+require manual async tracking. Specifically, all events emitted by instances
+of `events.EventEmitterAsyncResource` will run within its `async context`.
 
-The EventEmitterAsyncResource class has the same methods and takes the
-same options as EventEmitter and AsyncResource themselves.
+```js
+import { EventEmitterAsyncResource, EventEmitter } from 'node:events';
+import { notStrictEqual, strictEqual } from 'node:assert';
+import { executionAsyncId, triggerAsyncId } from 'node:async_hooks';
 
-#### Throws
+// Async tracking tooling will identify this as 'Q'.
+const ee1 = new EventEmitterAsyncResource({ name: 'Q' });
 
-if `options.name` is not provided when instantiated directly.
+// 'foo' listeners will run in the EventEmitters async context.
+ee1.on('foo', () => {
+  strictEqual(executionAsyncId(), ee1.asyncId);
+  strictEqual(triggerAsyncId(), ee1.triggerAsyncId);
+});
 
-#### Since
+const ee2 = new EventEmitter();
+
+// 'foo' listeners on ordinary EventEmitters that do not track async
+// context, however, run in the same async context as the emit().
+ee2.on('foo', () => {
+  notStrictEqual(executionAsyncId(), ee2.asyncId);
+  notStrictEqual(triggerAsyncId(), ee2.triggerAsyncId);
+});
+
+Promise.resolve().then(() => {
+  ee1.emit('foo');
+  ee2.emit('foo');
+});
+```
+
+The `EventEmitterAsyncResource` class has the same methods and takes the
+same options as `EventEmitter` and `AsyncResource` themselves.
+
+## Since
 
 v17.4.0, v16.14.0
 
@@ -27,7 +52,7 @@ v17.4.0, v16.14.0
   {
     "name": "asyncId",
     "type": "`number`",
-    "description": "The unique asyncId assigned to the resource.",
+    "description": "The unique `asyncId` assigned to the resource.",
     "optional": false,
     "defaultValue": "",
     "expandable": false,
@@ -36,7 +61,7 @@ v17.4.0, v16.14.0
   {
     "name": "asyncResource",
     "type": "[EventEmitterReferencingAsyncResource](../interfaces/internal.EventEmitter.EventEmitterReferencingAsyncResource.mdx)",
-    "description": "The underlying AsyncResource",
+    "description": "The returned `AsyncResource` object has an additional `eventEmitter` property that provides a reference to this `EventEmitterAsyncResource`.",
     "optional": false,
     "defaultValue": "",
     "expandable": false,
@@ -89,11 +114,13 @@ v17.4.0, v16.14.0
   }
 ]} />
 
+___
+
 ## Methods
 
-#### [captureRejectionSymbol]
+### [captureRejectionSymbol]
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -125,7 +152,7 @@ v17.4.0, v16.14.0
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -141,11 +168,11 @@ v17.4.0, v16.14.0
 
 ___
 
-#### addListener
+### addListener
 
 Alias for `emitter.on(eventName, listener)`.
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -168,7 +195,7 @@ Alias for `emitter.on(eventName, listener)`.
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -188,7 +215,7 @@ v0.1.26
 
 ___
 
-#### emit
+### emit
 
 Synchronously calls each of the listeners registered for the event named`eventName`, in the order they were registered, passing the supplied arguments
 to each.
@@ -228,7 +255,7 @@ myEmitter.emit('event', 1, 2, 3, 4, 5);
 // event with parameters 1, 2, 3, 4, 5 in third listener
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -251,7 +278,7 @@ myEmitter.emit('event', 1, 2, 3, 4, 5);
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -271,14 +298,14 @@ v0.1.26
 
 ___
 
-#### emitDestroy
+### emitDestroy
 
-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 the resource is left to be collected by the GC then
-the destroy hooks will never be called.
+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
+the resource is left to be collected by the GC then the `destroy` hooks will
+never be called.
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -294,7 +321,7 @@ the destroy hooks will never be called.
 
 ___
 
-#### eventNames
+### eventNames
 
 Returns an array listing the events for which the emitter has registered
 listeners. The values in the array are strings or `Symbol`s.
@@ -313,7 +340,7 @@ console.log(myEE.eventNames());
 // Prints: [ 'foo', 'bar', Symbol(symbol) ]
 ```
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -333,12 +360,12 @@ v6.0.0
 
 ___
 
-#### getMaxListeners
+### getMaxListeners
 
 Returns the current max listener value for the `EventEmitter` which is either
 set by `emitter.setMaxListeners(n)` or defaults to [defaultMaxListeners](internal.EventEmitter.EventEmitterAsyncResource.mdx#defaultmaxlisteners).
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -358,13 +385,13 @@ v1.0.0
 
 ___
 
-#### listenerCount
+### listenerCount
 
 Returns the number of listeners listening for the event named `eventName`.
 If `listener` is provided, it will return how many times the listener is found
 in the list of the listeners of the event.
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -387,7 +414,7 @@ in the list of the listeners of the event.
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -407,7 +434,7 @@ v3.2.0
 
 ___
 
-#### listeners
+### listeners
 
 Returns a copy of the array of listeners for the event named `eventName`.
 
@@ -419,7 +446,7 @@ console.log(util.inspect(server.listeners('connection')));
 // Prints: [ [Function] ]
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -433,7 +460,7 @@ console.log(util.inspect(server.listeners('connection')));
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -453,11 +480,11 @@ v0.1.26
 
 ___
 
-#### off
+### off
 
 Alias for `emitter.removeListener()`.
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -480,7 +507,7 @@ Alias for `emitter.removeListener()`.
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -500,7 +527,7 @@ v10.0.0
 
 ___
 
-#### on
+### on
 
 Adds the `listener` function to the end of the listeners array for the
 event named `eventName`. No checks are made to see if the `listener` has
@@ -529,7 +556,7 @@ myEE.emit('foo');
 //   a
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -552,7 +579,7 @@ myEE.emit('foo');
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -572,7 +599,7 @@ v0.1.101
 
 ___
 
-#### once
+### once
 
 Adds a **one-time**`listener` function for the event named `eventName`. The
 next time `eventName` is triggered, this listener is removed and then invoked.
@@ -599,7 +626,7 @@ myEE.emit('foo');
 //   a
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -622,7 +649,7 @@ myEE.emit('foo');
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -642,7 +669,7 @@ v0.3.0
 
 ___
 
-#### prependListener
+### prependListener
 
 Adds the `listener` function to the \_beginning\_ of the listeners array for the
 event named `eventName`. No checks are made to see if the `listener` has
@@ -657,7 +684,7 @@ server.prependListener('connection', (stream) => {
 
 Returns a reference to the `EventEmitter`, so that calls can be chained.
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -680,7 +707,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -700,7 +727,7 @@ v6.0.0
 
 ___
 
-#### prependOnceListener
+### prependOnceListener
 
 Adds a **one-time**`listener` function for the event named `eventName` to the \_beginning\_ of the listeners array. The next time `eventName` is triggered, this
 listener is removed, and then invoked.
@@ -713,7 +740,7 @@ server.prependOnceListener('connection', (stream) => {
 
 Returns a reference to the `EventEmitter`, so that calls can be chained.
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -736,7 +763,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -756,7 +783,7 @@ v6.0.0
 
 ___
 
-#### rawListeners
+### rawListeners
 
 Returns a copy of the array of listeners for the event named `eventName`,
 including any wrappers (such as those created by `.once()`).
@@ -786,7 +813,7 @@ newListeners[0]();
 emitter.emit('log');
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -800,7 +827,7 @@ emitter.emit('log');
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -820,7 +847,7 @@ v9.4.0
 
 ___
 
-#### removeAllListeners
+### removeAllListeners
 
 Removes all listeners, or those of the specified `eventName`.
 
@@ -830,7 +857,7 @@ component or module (e.g. sockets or file streams).
 
 Returns a reference to the `EventEmitter`, so that calls can be chained.
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -844,7 +871,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -864,7 +891,7 @@ v0.1.26
 
 ___
 
-#### removeListener
+### removeListener
 
 Removes the specified `listener` from the listener array for the event named`eventName`.
 
@@ -946,7 +973,7 @@ ee.emit('ping');
 
 Returns a reference to the `EventEmitter`, so that calls can be chained.
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -969,7 +996,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -989,7 +1016,7 @@ v0.1.26
 
 ___
 
-#### setMaxListeners
+### setMaxListeners
 
 By default `EventEmitter`s will print a warning if more than `10` listeners are
 added for a particular event. This is a useful default that helps finding
@@ -998,7 +1025,7 @@ modified for this specific `EventEmitter` instance. The value can be set to`Infi
 
 Returns a reference to the `EventEmitter`, so that calls can be chained.
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1012,7 +1039,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -1032,7 +1059,7 @@ v0.3.5
 
 ___
 
-#### addAbortListener
+### addAbortListener
 
 Listens once to the `abort` event on the provided `signal`.
 
@@ -1064,7 +1091,7 @@ function example(signal) {
 }
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1087,7 +1114,7 @@ function example(signal) {
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -1107,7 +1134,7 @@ v20.5.0
 
 ___
 
-#### getEventListeners
+### getEventListeners
 
 Returns a copy of the array of listeners for the event named `eventName`.
 
@@ -1134,7 +1161,7 @@ import { getEventListeners, EventEmitter } from 'node:events';
 }
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1157,7 +1184,7 @@ import { getEventListeners, EventEmitter } from 'node:events';
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -1177,7 +1204,7 @@ v15.2.0, v14.17.0
 
 ___
 
-#### getMaxListeners
+### getMaxListeners
 
 Returns the currently set max amount of listeners.
 
@@ -1205,7 +1232,7 @@ import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';
 }
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1219,7 +1246,7 @@ import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -1239,7 +1266,7 @@ v19.9.0
 
 ___
 
-#### listenerCount
+### listenerCount
 
 A class method that returns the number of listeners for the given `eventName`registered on the given `emitter`.
 
@@ -1253,7 +1280,7 @@ console.log(listenerCount(myEmitter, 'event'));
 // Prints: 2
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1276,7 +1303,7 @@ console.log(listenerCount(myEmitter, 'event'));
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -1300,7 +1327,7 @@ Since v3.2.0 - Use `listenerCount` instead.
 
 ___
 
-#### on
+### on
 
 ```js
 import { on, EventEmitter } from 'node:events';
@@ -1357,7 +1384,7 @@ const ac = new AbortController();
 process.nextTick(() => ac.abort());
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1389,7 +1416,7 @@ process.nextTick(() => ac.abort());
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -1409,7 +1436,7 @@ v13.6.0, v12.16.0
 
 ___
 
-#### once
+### once
 
 `Static **once**(emitter, eventName, options?): Promise&#60;any[]&#62;`
 
@@ -1490,7 +1517,7 @@ ac.abort(); // Abort waiting for the event
 ee.emit('foo'); // Prints: Waiting for the event was canceled!
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1522,7 +1549,7 @@ ee.emit('foo'); // Prints: Waiting for the event was canceled!
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -1542,7 +1569,7 @@ v11.13.0, v10.16.0
 
 `Static **once**(emitter, eventName, options?): Promise&#60;any[]&#62;`
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1574,7 +1601,7 @@ v11.13.0, v10.16.0
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {
@@ -1590,7 +1617,7 @@ v11.13.0, v10.16.0
 
 ___
 
-#### setMaxListeners
+### setMaxListeners
 
 ```js
 import { setMaxListeners, EventEmitter } from 'node:events';
@@ -1601,7 +1628,7 @@ const emitter = new EventEmitter();
 setMaxListeners(5, target, emitter);
 ```
 
-##### Parameters
+#### Parameters
 
 <ParameterTypes parameters={[
   {
@@ -1624,7 +1651,7 @@ setMaxListeners(5, target, emitter);
   }
 ]} />
 
-##### Returns
+#### Returns
 
 <ParameterTypes parameters={[
   {