doc: sort events alphabetically

Reorders, with minimal contextual duplication, the events documentation
alphabetically.

PR-URL: #3662
Reviewed-By: Evan Lucas <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>

Author: tflanagan

doc/api/events.markdown

@@ -36,67 +36,68 @@ a stack trace and exit the program.
 All EventEmitters emit the event `'newListener'` when new listeners are
 added and `'removeListener'` when a listener is removed.
 
-### emitter.addListener(event, listener)
-### emitter.on(event, listener)
+### Inheriting from 'EventEmitter'
 
-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.
+Inheriting from `EventEmitter` is no different from inheriting from any other
+constructor function. For example:
 
-    server.on('connection', function (stream) {
-      console.log('someone connected!');
-    });
+    'use strict';
+    const util = require('util');
+    const EventEmitter = require('events');
 
-Returns emitter, so calls can be chained.
+    function MyEventEmitter() {
+      // Initialize necessary properties from `EventEmitter` in this instance
+      EventEmitter.call(this);
+    }
 
-### emitter.once(event, listener)
+    // Inherit functions from `EventEmitter`'s prototype
+    util.inherits(MyEventEmitter, EventEmitter);
 
-Adds a **one time** listener for the event. This listener is
-invoked only the next time the event is fired, after which
-it is removed.
+### Class Method: EventEmitter.listenerCount(emitter, event)
 
-    server.once('connection', function (stream) {
-      console.log('Ah, we have our first user!');
-    });
+    Stability: 0 - Deprecated: Use [emitter.listenerCount][] instead.
 
-Returns emitter, so calls can be chained.
+Returns the number of listeners for a given event.
 
-### emitter.removeListener(event, listener)
+### Event: 'newListener'
 
-Removes a listener from the listener array for the specified event.
-**Caution**: changes array indices in the listener array behind the listener.
+* `event` {String} The event name
+* `listener` {Function} The event handler function
 
-    var callback = function(stream) {
-      console.log('someone connected!');
-    };
-    server.on('connection', callback);
-    // ...
-    server.removeListener('connection', callback);
+This event is emitted *before* a listener is added. When this event is
+triggered, the listener has not been added to the array of listeners for the
+`event`. Any listeners added to the event `name` in the newListener event
+callback will be added *before* the listener that is in the process of being
+added.
 
-`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.
+### Event: 'removeListener'
 
-Returns emitter, so calls can be chained.
+* `event` {String} The event name
+* `listener` {Function} The event handler function
 
-### emitter.removeAllListeners([event])
+This event is emitted *after* a listener is removed.  When this event is
+triggered, the listener has been removed from the array of listeners for the
+`event`.
 
-Removes all listeners, or those of the specified event. It's not a good idea to
-remove listeners that were added elsewhere in the code, especially when it's on
-an emitter that you didn't create (e.g. sockets or file streams).
+### EventEmitter.defaultMaxListeners
 
-Returns emitter, so calls can be chained.
+[`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n) sets the
+maximum on a per-instance basis.
+This class property lets you set it for *all* `EventEmitter` instances,
+current and future, effective immediately. Use with care.
 
-### emitter.setMaxListeners(n)
+Note that [`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n)
+still has precedence over `EventEmitter.defaultMaxListeners`.
 
-By default EventEmitters will print a warning if more than 10 listeners are
-added for a particular event. This is a useful default which helps finding
-memory leaks. Obviously not all Emitters should be limited to 10. This function
-allows that to be increased. Set to `Infinity` (or `0`) for unlimited.
+### emitter.addListener(event, listener)
 
-Returns emitter, so calls can be chained.
+Alias for `emitter.on(event, listener)`.
+
+### emitter.emit(event[, arg1][, arg2][, ...])
+
+Calls each of the listeners in order with the supplied arguments.
+
+Returns `true` if event had listeners, `false` otherwise.
 
 ### emitter.getMaxListeners()
 
@@ -113,16 +114,11 @@ while not being irresponsible and setting a too big number.
       emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
     });
 
-### EventEmitter.defaultMaxListeners
-
-[`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n) sets the
-maximum on a per-instance basis.
-This class property lets you set it for *all* `EventEmitter` instances,
-current and future, effective immediately. Use with care.
+### emitter.listenerCount(type)
 
-Note that [`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n)
-still has precedence over `EventEmitter.defaultMaxListeners`.
+* `type` {Value} The type of event
 
+Returns the number of listeners listening to the `type` of event.
 
 ### emitter.listeners(event)
 
@@ -133,63 +129,65 @@ Returns a copy of the array of listeners for the specified event.
     });
     console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
 
+### emitter.on(event, listener)
 
-### emitter.emit(event[, arg1][, arg2][, ...])
-
-Calls each of the listeners in order with the supplied arguments.
-
-Returns `true` if event had listeners, `false` otherwise.
-
-
-### emitter.listenerCount(type)
-
-* `type` {Value} The type of 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.
 
-Returns the number of listeners listening to the `type` of event.
+    server.on('connection', function (stream) {
+      console.log('someone connected!');
+    });
 
-### Class Method: EventEmitter.listenerCount(emitter, event)
+Returns emitter, so calls can be chained.
 
-    Stability: 0 - Deprecated: Use [emitter.listenerCount][] instead.
+### emitter.once(event, listener)
 
-Returns the number of listeners for a given event.
+Adds a **one time** listener for the event. This listener is
+invoked only the next time the event is fired, after which
+it is removed.
 
-### Event: 'newListener'
+    server.once('connection', function (stream) {
+      console.log('Ah, we have our first user!');
+    });
 
-* `event` {String} The event name
-* `listener` {Function} The event handler function
+Returns emitter, so calls can be chained.
 
-This event is emitted *before* a listener is added. When this event is
-triggered, the listener has not been added to the array of listeners for the
-`event`. Any listeners added to the event `name` in the newListener event
-callback will be added *before* the listener that is in the process of being
-added.
+### emitter.removeAllListeners([event])
 
+Removes all listeners, or those of the specified event. It's not a good idea to
+remove listeners that were added elsewhere in the code, especially when it's on
+an emitter that you didn't create (e.g. sockets or file streams).
 
-### Event: 'removeListener'
+Returns emitter, so calls can be chained.
 
-* `event` {String} The event name
-* `listener` {Function} The event handler function
+### emitter.removeListener(event, listener)
 
-This event is emitted *after* a listener is removed.  When this event is
-triggered, the listener has been removed from the array of listeners for the
-`event`.
+Removes a listener from the listener array for the specified event.
+**Caution**: changes array indices in the listener array behind the listener.
 
-### Inheriting from 'EventEmitter'
+    var callback = function(stream) {
+      console.log('someone connected!');
+    };
+    server.on('connection', callback);
+    // ...
+    server.removeListener('connection', callback);
 
-Inheriting from `EventEmitter` is no different from inheriting from any other
-constructor function. For example:
+`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.
 
-    'use strict';
-    const util = require('util');
-    const EventEmitter = require('events');
+Returns emitter, so calls can be chained.
 
-    function MyEventEmitter() {
-      // Initialize necessary properties from `EventEmitter` in this instance
-      EventEmitter.call(this);
-    }
+### emitter.setMaxListeners(n)
 
-    // Inherit functions from `EventEmitter`'s prototype
-    util.inherits(MyEventEmitter, EventEmitter);
+By default EventEmitters will print a warning if more than 10 listeners are
+added for a particular event. This is a useful default which helps finding
+memory leaks. Obviously not all Emitters should be limited to 10. This function
+allows that to be increased. Set to `Infinity` (or `0`) for unlimited.
 
+Returns emitter, so calls can be chained.
 
 [emitter.listenerCount]: #events_emitter_listenercount_type