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: #5566
PR-URL: #6371
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Robert Lindstaedt <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>

Author: lance

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