From e5f75cf82ec182cc97e94dc121623bc493444d94 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Fri, 19 Oct 2018 11:57:19 -0700
Subject: [PATCH] doc: add note about removeListener order

Fixes: https://github.com/nodejs/node/issues/21635

PR-URL: https://github.com/nodejs/node/pull/23762
Reviewed-By: Matheus Marchini <mat@mmarchini.me>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
---
 doc/api/events.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/api/events.md b/doc/api/events.md
index 8eaa8cae102b75..a24a5efcb20ded 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -557,6 +557,26 @@ being removed. This will not impact the order in which listeners are called,
 but it means that any copies of the listener array as returned by
 the `emitter.listeners()` method will need to be recreated.
 
+When a single function has been added as a handler multiple times for a single
+event (as in the example below), `removeListener()` will remove the most
+recently added instance. In the example the `once('ping')`
+listener is removed:
+
+```js
+const ee = new EventEmitter();
+
+function pong() {
+  console.log('pong');
+}
+
+ee.on('ping', pong);
+ee.once('ping', pong);
+ee.removeListener('ping', pong);
+
+ee.emit('ping');
+ee.emit('ping');
+```
+
 Returns a reference to the `EventEmitter`, so that calls can be chained.
 
 ### emitter.setMaxListeners(n)