doc: Backport ee.once doc clarifications to 4.x.

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
Ref: #6371
PR-URL: #7103
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]>

doc/api/events.markdown

@@ -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();
@@ -338,9 +338,8 @@ Returns a reference to the `EventEmitter` so calls can be chained.
 
 ### emitter.once(eventName, listener)
 
-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) => {