From 28b9da8ebb5cd0ed9992af1fdcbd58ebae49081a Mon Sep 17 00:00:00 2001
From: Lance Ball <lball@redhat.com>
Date: Mon, 25 Apr 2016 09:35:30 -0400
Subject: [PATCH 1/4] docs: Clearly document the behavior of ee.once().

Addresses #5566. The `ee.once()` function is currently documented as
invoking the listener, and then removing it when the event is
triggered. However, this is not really the case. The listener is removed
and _then_ invoked. This only matters in a narrow set of use cases, but
when it matters, it matters that the docs are correct.

See the issue (#5566) for a discussion on why the code has not been
modified to match the documentation, but instead the documentation has
been modified to match the code.
---
 doc/api/events.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index 501a94b79d7dc7..79c89aa63aeecf 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -130,7 +130,7 @@ myEmitter.emit('event');
 ```
 
 Using the `eventEmitter.once()` method, it is possible to register a listener
-that is immediately unregistered after it is called.
+that is unregistered as it is called.
 
 ```js
 const myEmitter = new MyEmitter();
@@ -376,9 +376,8 @@ myEE.emit('foo');
 * `eventName` {string|Symbol} The name of the event.
 * `listener` {Function} The callback function
 
-Adds a **one time** `listener` function for the event named `eventName`. This
-listener is invoked only the next time `eventName` is triggered, after which
-it is removed.
+Adds a **one time** `listener` function for the event named `eventName`. The
+next time `eventName` is triggered, this listener is removed and then invoked.
 
 ```js
 server.once('connection', (stream) => {

From 0fa1c90beb74c5affc9f271f4326782b65224b48 Mon Sep 17 00:00:00 2001
From: Lance Ball <lball@redhat.com>
Date: Mon, 25 Apr 2016 10:10:29 -0400
Subject: [PATCH 2/4] doc: Clarity about timing for `once` listeners.

Based on comments from @cjihrig.
---
 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 79c89aa63aeecf..8f380d68f97e00 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -130,7 +130,7 @@ myEmitter.emit('event');
 ```
 
 Using the `eventEmitter.once()` method, it is possible to register a listener
-that is unregistered as it is called.
+that is unregistered before it is called.
 
 ```js
 const myEmitter = new MyEmitter();

From dc1049fc75426e9a57775fef7518cd5c58a3a474 Mon Sep 17 00:00:00 2001
From: Lance Ball <lball@redhat.com>
Date: Mon, 25 Apr 2016 11:38:00 -0400
Subject: [PATCH 3/4] doc: Clarify behavior of `ee.prependOnceListener`.

Additional documentation changes required for `ee.prependOnceListener`
as per https://github.com/nodejs/node/issues/5566.
---
 doc/api/events.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index 8f380d68f97e00..a2c420ca1b589a 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -426,8 +426,8 @@ Returns a reference to the `EventEmitter` so calls can be chained.
 * `listener` {Function} The callback function
 
 Adds a **one time** `listener` function for the event named `eventName` to the
-*beginning* of the listeners array. This listener is invoked only the next time
-`eventName` is triggered, after which it is removed.
+*beginning* of the listeners array. This listener is removed, and then invoked
+only the next time `eventName` is triggered.
 
 ```js
 server.prependOnceListener('connection', (stream) => {

From 4102e92896ef427d9a7d0b0c58143964eee40ec9 Mon Sep 17 00:00:00 2001
From: Lance Ball <lball@redhat.com>
Date: Mon, 25 Apr 2016 11:52:42 -0400
Subject: [PATCH 4/4] doc: Clarify wording for `ee.prependOnceListener`.

Address comments from @addaleax.

Fixes: https://github.com/nodejs/node/issues/5566
---
 doc/api/events.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index a2c420ca1b589a..6e74760d8f35df 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -426,8 +426,8 @@ Returns a reference to the `EventEmitter` so calls can be chained.
 * `listener` {Function} The callback function
 
 Adds a **one time** `listener` function for the event named `eventName` to the
-*beginning* of the listeners array. This listener is removed, and then invoked
-only the next time `eventName` is triggered.
+*beginning* of the listeners array. The next time `eventName` is triggered, this
+listener is removed, and then invoked.
 
 ```js
 server.prependOnceListener('connection', (stream) => {