doc: sort events alphabetically

Reorders, with minimal contextual duplication, the events documentation alphabetically. PR-URL: https://github.com/nodejs/node/pull/3662 Reviewed-By: Evan Lucas <evanlucas@me.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
9 years ago · ce3ac8dd1e
1 changed files with 89 additions and 91 deletions
--- a/doc/api/events.markdown
+++ b/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)
+### Inheriting from 'EventEmitter'
 ### emitter.on(event, listener)
-Adds a listener to the end of the listeners array for the specified `event`.
+Inheriting from `EventEmitter` is no different from inheriting from any other
-No checks are made to see if the `listener` has already been added. Multiple
+constructor function. For example:
 calls passing the same combination of `event` and `listener` will result in the
 `listener` being added multiple times.
-    server.on('connection', function (stream) {
+    'use strict';
-      console.log('someone connected!');
+    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
+### Class Method: EventEmitter.listenerCount(emitter, event)
 invoked only the next time the event is fired, after which
 it is removed.
-    server.once('connection', function (stream) {
+    Stability: 0 - Deprecated: Use [emitter.listenerCount][] instead.
      console.log('Ah, we have our first user!');
    });
-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.
+* `event` {String} The event name
-**Caution**: changes array indices in the listener array behind the listener.
+* `listener` {Function} The event handler function
-    var callback = function(stream) {
+This event is emitted *before* a listener is added. When this event is
-      console.log('someone connected!');
+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
-    server.on('connection', callback);
+callback will be added *before* the listener that is in the process of being
-    // ...
+added.
    server.removeListener('connection', callback);
-`removeListener` will remove, at most, one instance of a listener from the
+### Event: 'removeListener'
 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.
+* `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
+### EventEmitter.defaultMaxListeners
 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).
-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
+### emitter.addListener(event, listener)
 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.
+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.listenerCount(type)
 [`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.
-Note that [`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n)
+* `type` {Value} The type of event
 still has precedence over `EventEmitter.defaultMaxListeners`.
 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][, ...])
+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 each of the listeners in order with the supplied arguments.
+calls passing the same combination of `event` and `listener` will result in the
-
+`listener` being added multiple times.
 Returns `true` if event had listeners, `false` otherwise.
 ### emitter.listenerCount(type)
 * `type` {Value} The type of event
-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
+Returns emitter, so calls can be chained.
 * `listener` {Function} The event handler function
-This event is emitted *before* a listener is added. When this event is
+### emitter.removeAllListeners([event])
 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.
 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
+### emitter.removeListener(event, listener)
 * `listener` {Function} The event handler function
-This event is emitted *after* a listener is removed.  When this event is
+Removes a listener from the listener array for the specified event.
-triggered, the listener has been removed from the array of listeners for the
+**Caution**: changes array indices in the listener array behind the listener.
 `event`.
-### 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
+`removeListener` will remove, at most, one instance of a listener from the
-constructor function. For example:
+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';
+Returns emitter, so calls can be chained.
    const util = require('util');
    const EventEmitter = require('events');
-    function MyEventEmitter() {
+### emitter.setMaxListeners(n)
      // Initialize necessary properties from `EventEmitter` in this instance
      EventEmitter.call(this);
    }
-    // Inherit functions from `EventEmitter`'s prototype
+By default EventEmitters will print a warning if more than 10 listeners are
-    util.inherits(MyEventEmitter, EventEmitter);
+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