doc: revise AbortSignal text and example using events.once()

Add a line to the example code to clarify what happens if an event is emitted after listening is canceled. Make minor revisions to surrounding text. PR-URL: #35005 Backport-PR-URL: #38386 Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>
nodejs · Apr 30, 2021 · 1a362d8 · 1a362d8
1 parent 3f33b5a
commit 1a362d8
Showing 1 changed file with 3 additions and 3 deletions.
diff --git a/doc/api/events.md b/doc/api/events.md
@@ -839,8 +839,7 @@ added:
 * `emitter` {EventEmitter}
 * `name` {string}
 * `options` {Object}
-  * `signal` {AbortSignal} An {AbortSignal} that may be used to cancel waiting
-    for the event.
+  * `signal` {AbortSignal} Can be used to cancel waiting for the event.
 * Returns: {Promise}
 
 Creates a `Promise` that is fulfilled when the `EventEmitter` emits the given
@@ -899,7 +898,7 @@ ee.emit('error', new Error('boom'));
 // Prints: ok boom
 ```
 
-An {AbortSignal} may be used to cancel waiting for the event early:
+An {AbortSignal} can be used to cancel waiting for the event:
 
 ```js
 const { EventEmitter, once } = require('events');
@@ -922,6 +921,7 @@ async function foo(emitter, event, signal) {
 
 foo(ee, 'foo', ac.signal);
 ac.abort(); // Abort waiting for the event
+ee.emit('foo'); // Prints: Waiting for the event was canceled!
 ```
 
 ### Awaiting multiple events emitted on `process.nextTick()`