From af4915894b9da3780c91f2cd48c99d168a78e315 Mon Sep 17 00:00:00 2001 From: Sakthipriyan Vairamani Date: Wed, 29 Jun 2016 23:20:23 +0530 Subject: [PATCH] doc: general improvments to events documentation PR-URL: https://github.com/nodejs/node/pull/7480 Reviewed-By: James M Snell --- doc/api/events.md | 56 +++++++++++++++++++++++------------------------ 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/doc/api/events.md b/doc/api/events.md index 185213cf9e..0e2d495439 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -15,11 +15,11 @@ a [stream][] emits an event whenever data is available to be read. All objects that emit events are instances of the `EventEmitter` class. These objects expose an `eventEmitter.on()` function that allows one or more -Functions to be attached to named events emitted by the object. Typically, +functions to be attached to named events emitted by the object. Typically, event names are camel-cased strings but any valid JavaScript property key can be used. -When the `EventEmitter` object emits an event, all of the Functions attached +When the `EventEmitter` object emits an event, all of the functions attached to that specific event are called _synchronously_. Any values returned by the called listeners are _ignored_ and will be discarded. @@ -109,7 +109,8 @@ myEmitter.emit('event'); ``` Using the `eventEmitter.once()` method, it is possible to register a listener -that is unregistered before it is called. +that is called at most once for a particular event. Once the event is emitted, +the listener is unregistered and *then* called. ```js const myEmitter = new MyEmitter(); @@ -126,7 +127,7 @@ myEmitter.emit('event'); ## Error events When an error occurs within an `EventEmitter` instance, the typical action is -for an `'error'` event to be emitted. These are treated as a special case +for an `'error'` event to be emitted. These are treated as special cases within Node.js. If an `EventEmitter` does _not_ have at least one listener registered for the @@ -139,10 +140,9 @@ myEmitter.emit('error', new Error('whoops!')); // Throws and crashes Node.js ``` -To guard against crashing the Node.js process, developers can either register -a listener for the `process.on('uncaughtException')` event or use the -[`domain`][] module (_Note, however, that the `domain` module has been -deprecated_). +To guard against crashing the Node.js process, a listener can be registered +on the [`process` object's `uncaughtException` event][] or the [`domain`][] module +can be used. (_Note, however, that the `domain` module has been deprecated_) ```js const myEmitter = new MyEmitter(); @@ -155,8 +155,7 @@ myEmitter.emit('error', new Error('whoops!')); // Prints: whoops! there was an error ``` -As a best practice, developers should always register listeners for the -`'error'` event: +As a best practice, listeners should always be added for the `'error'` events. ```js const myEmitter = new MyEmitter(); @@ -176,15 +175,15 @@ const EventEmitter = require('events'); ``` All EventEmitters emit the event `'newListener'` when new listeners are -added and `'removeListener'` when a listener is removed. +added and `'removeListener'` when existing listeners are removed. ### Event: 'newListener' * `eventName` {String|Symbol} The name of the event being listened for * `listener` {Function} The event handler function -The `EventEmitter` instance will emit it's own `'newListener'` event *before* -a listener is added to it's internal array of listeners. +The `EventEmitter` instance will emit its own `'newListener'` event *before* +a listener is added to its internal array of listeners. Listeners registered for the `'newListener'` event will be passed the event name and a reference to the listener being added. @@ -219,7 +218,7 @@ myEmitter.emit('event'); * `eventName` {String|Symbol} The event name * `listener` {Function} The event handler function -The `'removeListener'` event is emitted *after* a listener is removed. +The `'removeListener'` event is emitted *after* the `listener` is removed. ### EventEmitter.listenerCount(emitter, eventName) @@ -251,7 +250,7 @@ precedence over `EventEmitter.defaultMaxListeners`. Note that this is not a hard limit. The `EventEmitter` instance will allow more listeners to be added but will output a trace warning to stderr indicating -that a `possible EventEmitter memory leak` has been detected. For any single +that a "possible EventEmitter memory leak" has been detected. For any single `EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()` methods can be used to temporarily avoid this warning: @@ -301,7 +300,7 @@ set by [`emitter.setMaxListeners(n)`][] or defaults to ### emitter.listenerCount(eventName) -* `eventName` {Value} The name of the event being listened for +* `eventName` {String|Symbol} The name of the event being listened for Returns the number of listeners listening to the event named `eventName`. @@ -319,7 +318,7 @@ console.log(util.inspect(server.listeners('connection'))); ### emitter.on(eventName, listener) -* `eventName` {string|Symbol} The name of the event. +* `eventName` {String|Symbol} The name of the event. * `listener` {Function} The callback function Adds the `listener` function to the end of the listeners array for the @@ -334,7 +333,7 @@ server.on('connection', (stream) => { }); ``` -Returns a reference to the `EventEmitter` so calls can be chained. +Returns a reference to the `EventEmitter`, so that calls can be chained. By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the @@ -352,7 +351,7 @@ myEE.emit('foo'); ### emitter.once(eventName, listener) -* `eventName` {string|Symbol} The name of the event. +* `eventName` {String|Symbol} The name of the event. * `listener` {Function} The callback function Adds a **one time** `listener` function for the event named `eventName`. The @@ -364,7 +363,7 @@ server.once('connection', (stream) => { }); ``` -Returns a reference to the `EventEmitter` so calls can be chained. +Returns a reference to the `EventEmitter`, so that calls can be chained. By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the @@ -382,7 +381,7 @@ myEE.emit('foo'); ### emitter.prependListener(eventName, listener) -* `eventName` {string|Symbol} The name of the event. +* `eventName` {String|Symbol} The name of the event. * `listener` {Function} The callback function Adds the `listener` function to the *beginning* of the listeners array for the @@ -397,11 +396,11 @@ server.prependListener('connection', (stream) => { }); ``` -Returns a reference to the `EventEmitter` so calls can be chained. +Returns a reference to the `EventEmitter`, so that calls can be chained. ### emitter.prependOnceListener(eventName, listener) -* `eventName` {string|Symbol} The name of the event. +* `eventName` {String|Symbol} The name of the event. * `listener` {Function} The callback function Adds a **one time** `listener` function for the event named `eventName` to the @@ -414,7 +413,7 @@ server.prependOnceListener('connection', (stream) => { }); ``` -Returns a reference to the `EventEmitter` so calls can be chained. +Returns a reference to the `EventEmitter`, so that calls can be chained. ### emitter.removeAllListeners([eventName]) @@ -424,7 +423,7 @@ Note that it is bad practice to remove listeners added elsewhere in the code, particularly when the `EventEmitter` instance was created by some other 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 that calls can be chained. ### emitter.removeListener(eventName, listener) @@ -485,10 +484,10 @@ myEmitter.emit('event'); Because listeners are managed using an internal array, calling this will change the position indices of any listener registered *after* the listener being removed. This will not impact the order in which listeners are called, -but it will means that any copies of the listener array as returned by +but it means that any copies of the listener array as returned by 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 that calls can be chained. ### emitter.setMaxListeners(n) @@ -499,7 +498,7 @@ The `emitter.setMaxListeners()` method allows the limit to be modified for this specific `EventEmitter` instance. The value can be set to `Infinity` (or `0`) to indicate an unlimited number of listeners. -Returns a reference to the `EventEmitter` so calls can be chained. +Returns a reference to the `EventEmitter`, so that calls can be chained. [`net.Server`]: net.html#net_class_net_server [`fs.ReadStream`]: fs.html#fs_class_fs_readstream @@ -507,4 +506,5 @@ Returns a reference to the `EventEmitter` so calls can be chained. [`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners [`emitter.listenerCount()`]: #events_emitter_listenercount_eventname [`domain`]: domain.html +[`process` object's `uncaughtException` event]: process.html#process_event_uncaughtexception [stream]: stream.html