doc: update removeListener behaviour

doc/api/events.markdown

@@ -377,6 +377,42 @@ listener array. If any single listener has been added multiple times to the
 listener array for the specified `event`, then `removeListener` must be called
 multiple times to remove each instance.
 
+Note that once an event has been emitted, all listeners attached to it at the
+time of emitting will be called in order. This implies that any `removeListener`
+call *after* emitting and *before* the last listener finishes execution will
+not affect the current listener array. Subsequent events will behave as expected.
+
+```js
+const myEmitter = new MyEmitter();
+
+var callbackA = () => {
+  console.log('A');
+  myEmitter.removeListener('event', callbackB);
+};
+
+var callbackB = () => {
+  console.log('B');
+};
+
+myEmitter.on('event', callbackA);
+
+myEmitter.on('event', callbackB);
+
+// callbackA removes listener callbackB but it will still be called.
+// Interal listener array at time of emit [callbackA, callbackB]
+myEmitter.emit('event');
+  // Prints:
+  //   B
+  //   A
+
+// callbackB is now removed.
+// Interal listener array [callbackA]
+myEmitter.emit('event');
+  // Prints:
+  //   A
+
+```
+
 Because listeners are managed using an internal array, calling this will
 change the position indices of any listener registered *after* the listener
 being removed. This will not impact the order in which listeners are called,

test/parallel/test-event-emitter-remove-listeners.js

@@ -83,3 +83,25 @@ e5.once('removeListener', common.mustCall(function(name, cb) {
 }));
 e5.removeListener('hello', listener1);
 assert.deepEqual([], e5.listeners('hello'));
+
+const e6 = new events.EventEmitter();
+
+var listener3 = common.mustCall(() => {
+  console.log('listener3');
+  e6.removeListener('hello', listener4);
+}, 2);
+
+var listener4 = common.mustCall(() => {
+  console.log('listener4');
+}, 1);
+
+e6.on('hello', listener3);
+e6.on('hello', listener4);
+
+// listener4 will still be called although it is removed by listener 3.
+e6.emit('hello');
+// This is so because the interal listener array at time of emit
+// was [listener3,listener4]
+
+// Interal listener array [listener3]
+e6.emit('hello');