doc: correctly 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.

Fixes: https://github.com/nodejs/node/issues/5566
PR-URL: https://github.com/nodejs/node/pull/6371
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Robert Lindstaedt <robert.lindstaedt@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>

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 before 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
+Adds a **one time** `listener` function for the event named `eventName`. The
-listener is invoked only the next time `eventName` is triggered, after which
+next time `eventName` is triggered, this listener is removed and then invoked.
-it is removed.
 
 ```js
 server.once('connection', (stream) => {
@@ -427,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
+*beginning* of the listeners array. The next time `eventName` is triggered, this
-`eventName` is triggered, after which it is removed.
+listener is removed, and then invoked.
 
 ```js
 server.prependOnceListener('connection', (stream) => {