Skip to content

Commit

Permalink
doc: sort events alphabetically
Browse files Browse the repository at this point in the history 
Reorders, with minimal contextual duplication, the events documentation
alphabetically.

PR-URL: #3662
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
  • Loading branch information
@tflanagan @rvagg
tflanagan authored and rvagg committed Nov 13, 2015
1 parent 63a7874 commit ce3ac8d
Showing 1 changed file with 89 additions and 91 deletions.
180 changes: 89 additions & 91 deletions doc/api/events.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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()

Expand All @@ -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)

Expand All @@ -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

0 comments on commit ce3ac8d

Please sign in to comment.