Browse Source

doc: add `added:` information for events

Ref: https://github.com/nodejs/node/pull/8879

PR-URL: https://github.com/nodejs/node/pull/7822
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
v4.x
Luigi Pinca 9 years ago
committed by Myles Borins
parent
commit
578bf511f9
  1. 46
      doc/api/events.md

46
doc/api/events.md

@ -189,6 +189,9 @@ myEmitter.emit('error', new Error('whoops!'));
``` ```
## Class: EventEmitter ## Class: EventEmitter
<!-- YAML
added: v0.1.26
-->
The `EventEmitter` class is defined and exposed by the `events` module: The `EventEmitter` class is defined and exposed by the `events` module:
@ -200,6 +203,9 @@ All EventEmitters emit the event `'newListener'` when new listeners are
added and `'removeListener'` when a listener is removed. added and `'removeListener'` when a listener is removed.
### Event: 'newListener' ### Event: 'newListener'
<!-- YAML
added: v0.1.26
-->
* `eventName` {String|Symbol} The name of the event being listened for * `eventName` {String|Symbol} The name of the event being listened for
* `listener` {Function} The event handler function * `listener` {Function} The event handler function
@ -236,6 +242,9 @@ myEmitter.emit('event');
``` ```
### Event: 'removeListener' ### Event: 'removeListener'
<!-- YAML
added: v0.9.3
-->
* `eventName` {String|Symbol} The event name * `eventName` {String|Symbol} The event name
* `listener` {Function} The event handler function * `listener` {Function} The event handler function
@ -243,6 +252,10 @@ myEmitter.emit('event');
The `'removeListener'` event is emitted *after* a listener is removed. The `'removeListener'` event is emitted *after* a listener is removed.
### EventEmitter.listenerCount(emitter, eventName) ### EventEmitter.listenerCount(emitter, eventName)
<!-- YAML
added: v0.9.12
deprecated: v4.0.0
-->
> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead. > Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead.
@ -258,6 +271,9 @@ console.log(EventEmitter.listenerCount(myEmitter, 'event'));
``` ```
### EventEmitter.defaultMaxListeners ### EventEmitter.defaultMaxListeners
<!-- YAML
added: v0.11.2
-->
By default, a maximum of `10` listeners can be registered for any single By default, a maximum of `10` listeners can be registered for any single
event. This limit can be changed for individual `EventEmitter` instances event. This limit can be changed for individual `EventEmitter` instances
@ -285,10 +301,16 @@ emitter.once('event', () => {
``` ```
### emitter.addListener(eventName, listener) ### emitter.addListener(eventName, listener)
<!-- YAML
added: v0.1.26
-->
Alias for `emitter.on(eventName, listener)`. Alias for `emitter.on(eventName, listener)`.
### emitter.emit(eventName[, arg1][, arg2][, ...]) ### emitter.emit(eventName[, arg1][, arg2][, ...])
<!-- YAML
added: v0.1.26
-->
Synchronously calls each of the listeners registered for the event named Synchronously calls each of the listeners registered for the event named
`eventName`, in the order they were registered, passing the supplied arguments `eventName`, in the order they were registered, passing the supplied arguments
@ -297,18 +319,27 @@ to each.
Returns `true` if the event had listeners, `false` otherwise. Returns `true` if the event had listeners, `false` otherwise.
### emitter.getMaxListeners() ### emitter.getMaxListeners()
<!-- YAML
added: v1.0.0
-->
Returns the current max listener value for the `EventEmitter` which is either Returns the current max listener value for the `EventEmitter` which is either
set by [`emitter.setMaxListeners(n)`][] or defaults to set by [`emitter.setMaxListeners(n)`][] or defaults to
[`EventEmitter.defaultMaxListeners`][]. [`EventEmitter.defaultMaxListeners`][].
### emitter.listenerCount(eventName) ### emitter.listenerCount(eventName)
<!-- YAML
added: v3.2.0
-->
* `eventName` {Value} The name of the event being listened for * `eventName` {Value} The name of the event being listened for
Returns the number of listeners listening to the event named `eventName`. Returns the number of listeners listening to the event named `eventName`.
### emitter.listeners(eventName) ### emitter.listeners(eventName)
<!-- YAML
added: v0.1.26
-->
Returns a copy of the array of listeners for the event named `eventName`. Returns a copy of the array of listeners for the event named `eventName`.
@ -321,6 +352,9 @@ console.log(util.inspect(server.listeners('connection')));
``` ```
### emitter.on(eventName, listener) ### emitter.on(eventName, listener)
<!-- YAML
added: v0.1.101
-->
Adds the `listener` function to the end of the listeners array for the Adds the `listener` function to the end of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has event named `eventName`. No checks are made to see if the `listener` has
@ -337,6 +371,9 @@ server.on('connection', (stream) => {
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter` so calls can be chained.
### emitter.once(eventName, listener) ### emitter.once(eventName, listener)
<!-- YAML
added: v0.3.0
-->
Adds a **one time** `listener` function for the event named `eventName`. The Adds a **one time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked. next time `eventName` is triggered, this listener is removed and then invoked.
@ -350,6 +387,9 @@ server.once('connection', (stream) => {
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter` so calls can be chained.
### emitter.removeAllListeners([eventName]) ### emitter.removeAllListeners([eventName])
<!-- YAML
added: v0.1.26
-->
Removes all listeners, or those of the specified `eventName`. Removes all listeners, or those of the specified `eventName`.
@ -360,6 +400,9 @@ component or module (e.g. sockets or file streams).
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter` so calls can be chained.
### emitter.removeListener(eventName, listener) ### emitter.removeListener(eventName, listener)
<!-- YAML
added: v0.1.26
-->
Removes the specified `listener` from the listener array for the event named Removes the specified `listener` from the listener array for the event named
`eventName`. `eventName`.
@ -424,6 +467,9 @@ the `emitter.listeners()` method will need to be recreated.
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter` so calls can be chained.
### emitter.setMaxListeners(n) ### emitter.setMaxListeners(n)
<!-- YAML
added: v0.3.5
-->
By default EventEmitters will print a warning if more than `10` listeners are By default EventEmitters will print a warning if more than `10` listeners are
added for a particular event. This is a useful default that helps finding added for a particular event. This is a useful default that helps finding

Loading…
Cancel
Save