From 3184ecb7d6d9527176c23588bc94d745578b3452 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Mon, 6 Jul 2020 12:51:46 -0700
Subject: [PATCH 1/2] doc: document behavior for once(ee, 'error')

Fixes: https://github.com/nodejs/node/issues/31244
---
 doc/api/events.md | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index 39950b5c12f581..68310e58b02189 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:

From fe7069167be0d8cbbc527c3def06c5d9e478d244 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Thu, 9 Jul 2020 07:22:34 -0700
Subject: [PATCH 2/2] [squash] nit

Co-authored-by: Luigi Pinca <luigipinca@gmail.com>
---
 doc/api/events.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index 68310e58b02189..2ffd9ce6664769 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -884,7 +884,7 @@ const { EventEmitter, once } = require('events');
 const ee = new EventEmitter();
 
 once(ee, 'error')
-  .then((err) => console.log('ok', err.message))
+  .then(([err]) => console.log('ok', err.message))
   .catch((err) => console.log('error', err.message));
 
 ee.emit('error', new Error('boom'));