doc: clarify add/removeListener semantics

Clarify that adding or removing a listener is not idempotent.

RE: #8853
PR: #8911
PR-URL: https://github.com/joyent/node/pull/8911
Signed-off-by: Timothy J Fontaine <tjfontaine@gmail.com>

1 files changed, 13 insertions, 5 deletions

diff --git a/doc/api/events.markdown b/doc/api/events.markdown
index 07c5b0e2b..2d74b5795 100644
--- a/doc/api/events.markdown
+++ b/doc/api/events.markdown
@@ -33,7 +33,10 @@ added and `'removeListener'` when a listener is removed.
 ### emitter.addListener(event, listener)
 ### emitter.on(event, listener)
 
-Adds a listener to the end of the listeners array for the specified event.
+Adds a listener to the end of the listeners array for the specified `event`.
+No checks are made to see if the `listener` has already been added. Multiple
+calls passing the same combination of `event` and `listener` will result in the
+`listener` being added multiple times.
 
     server.on('connection', function (stream) {
       console.log('someone connected!');
@@ -65,6 +68,11 @@ Remove a listener from the listener array for the specified event.
     // ...
     server.removeListener('connection', callback);
 
+`removeListener` will remove, at most, one instance of a listener from the
+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.
+
 Returns emitter, so calls can be chained.
 
 ### emitter.removeAllListeners([event])
@@ -110,8 +118,8 @@ Return the number of listeners for a given event.
 * `event` {String} The event name
 * `listener` {Function} The event handler function
 
-This event is emitted any time someone adds a new listener.  It is unspecified
-if `listener` is in the list returned by `emitter.listeners(event)`.
+This event is emitted any time a listener is added. When this event is triggered,
+the listener may not yet have been added to the array of listeners for the `event`.
 
 
 ### Event: 'removeListener'
@@ -119,5 +127,5 @@ if `listener` is in the list returned by `emitter.listeners(event)`.
 * `event` {String} The event name
 * `listener` {Function} The event handler function
 
-This event is emitted any time someone removes a listener.  It is unspecified
-if `listener` is in the list returned by `emitter.listeners(event)`.
+This event is emitted any time someone removes a listener.  When this event is triggered,
+the listener may not yet have been removed from the array of listeners for the `event`.