doc: document behavior for once(ee, 'error')

Fixes: https://github.com/nodejs/node/issues/31244

PR-URL: https://github.com/nodejs/node/pull/34225
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

1 files changed, 20 insertions, 1 deletions

diff --git a/doc/api/events.md b/doc/api/events.md
index 39950b5c12f..2ffd9ce6664 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -837,7 +837,7 @@ added:
 * Returns: {Promise}
 
 Creates a `Promise` that is fulfilled when the `EventEmitter` emits the given
-event or that is rejected when the `EventEmitter` emits `'error'`.
+event or that is rejected if the `EventEmitter` emits `'error'` while waiting.
 The `Promise` will resolve with an array of all the arguments emitted to the
 given event.
 
@@ -873,6 +873,25 @@ async function run() {
 run();
 ```
 
+The special handling of the `'error'` event is only used when `events.once()`
+is used to wait for another event. If `events.once()` is used to wait for the
+'`error'` event itself, then it is treated as any other kind of event without
+special handling:
+
+```js
+const { EventEmitter, once } = require('events');
+
+const ee = new EventEmitter();
+
+once(ee, 'error')
+  .then(([err]) => console.log('ok', err.message))
+  .catch((err) => console.log('error', err.message));
+
+ee.emit('error', new Error('boom'));
+
+// Prints: ok boom
+```
+
 ## `events.captureRejections`
 <!-- YAML
 added: