FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: general improvments to events documentation · nodejs/node@3343d46 · GitHub

/ node Public

Commit 3343d46

Browse files
thefourtheye
authored and
evanlucas
committed
doc: general improvments to events documentation
PR-URL: #7480 Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent 61542e8 commit 3343d46

1 file changed

Lines changed: 28 additions & 28 deletions

File tree

‎doc/api/events.md‎

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@ a [stream][] emits an event whenever data is available to be read.
1515

1616
All objects that emit events are instances of the `EventEmitter` class. These
1717
objects expose an `eventEmitter.on()` function that allows one or more
18-
Functions to be attached to named events emitted by the object. Typically,
18+
functions to be attached to named events emitted by the object. Typically,
1919
event names are camel-cased strings but any valid JavaScript property key
2020
can be used.
2121

22-
When the `EventEmitter` object emits an event, all of the Functions attached
22+
When the `EventEmitter` object emits an event, all of the functions attached
2323
to that specific event are called _synchronously_. Any values returned by the
2424
called listeners are _ignored_ and will be discarded.
2525

@@ -109,7 +109,8 @@ myEmitter.emit('event');
109109
```
110110

111111
Using the `eventEmitter.once()` method, it is possible to register a listener
112-
that is unregistered before it is called.
112+
that is called at most once for a particular event. Once the event is emitted,
113+
the listener is unregistered and *then* called.
113114

114115
```js
115116
const myEmitter = new MyEmitter();
@@ -126,7 +127,7 @@ myEmitter.emit('event');
126127
## Error events
127128

128129
When an error occurs within an `EventEmitter` instance, the typical action is
129-
for an `'error'` event to be emitted. These are treated as a special case
130+
for an `'error'` event to be emitted. These are treated as special cases
130131
within Node.js.
131132

132133
If an `EventEmitter` does _not_ have at least one listener registered for the
@@ -139,10 +140,9 @@ myEmitter.emit('error', new Error('whoops!'));
139140
// Throws and crashes Node.js
140141
```
141142

142-
To guard against crashing the Node.js process, developers can either register
143-
a listener for the `process.on('uncaughtException')` event or use the
144-
[`domain`][] module (_Note, however, that the `domain` module has been
145-
deprecated_).
143+
To guard against crashing the Node.js process, a listener can be registered
144+
on the [`process` object's `uncaughtException` event][] or the [`domain`][] module
145+
can be used. (_Note, however, that the `domain` module has been deprecated_)
146146

147147
```js
148148
const myEmitter = new MyEmitter();
@@ -155,8 +155,7 @@ myEmitter.emit('error', new Error('whoops!'));
155155
// Prints: whoops! there was an error
156156
```
157157

158-
As a best practice, developers should always register listeners for the
159-
`'error'` event:
158+
As a best practice, listeners should always be added for the `'error'` events.
160159

161160
```js
162161
const myEmitter = new MyEmitter();
@@ -176,15 +175,15 @@ const EventEmitter = require('events');
176175
```
177176

178177
All EventEmitters emit the event `'newListener'` when new listeners are
179-
added and `'removeListener'` when a listener is removed.
178+
added and `'removeListener'` when existing listeners are removed.
180179

181180
### Event: 'newListener'
182181

183182
* `eventName` {String|Symbol} The name of the event being listened for
184183
* `listener` {Function} The event handler function
185184

186-
The `EventEmitter` instance will emit it's own `'newListener'` event *before*
187-
a listener is added to it's internal array of listeners.
185+
The `EventEmitter` instance will emit its own `'newListener'` event *before*
186+
a listener is added to its internal array of listeners.
188187

189188
Listeners registered for the `'newListener'` event will be passed the event
190189
name and a reference to the listener being added.
@@ -219,7 +218,7 @@ myEmitter.emit('event');
219218
* `eventName` {String|Symbol} The event name
220219
* `listener` {Function} The event handler function
221220

222-
The `'removeListener'` event is emitted *after* a listener is removed.
221+
The `'removeListener'` event is emitted *after* the `listener` is removed.
223222

224223
### EventEmitter.listenerCount(emitter, eventName)
225224

@@ -251,7 +250,7 @@ precedence over `EventEmitter.defaultMaxListeners`.
251250

252251
Note that this is not a hard limit. The `EventEmitter` instance will allow
253252
more listeners to be added but will output a trace warning to stderr indicating
254-
that a `possible EventEmitter memory leak` has been detected. For any single
253+
that a "possible EventEmitter memory leak" has been detected. For any single
255254
`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()`
256255
methods can be used to temporarily avoid this warning:
257256

@@ -301,7 +300,7 @@ set by [`emitter.setMaxListeners(n)`][] or defaults to
301300

302301
### emitter.listenerCount(eventName)
303302

304-
* `eventName` {Value} The name of the event being listened for
303+
* `eventName` {String|Symbol} The name of the event being listened for
305304

306305
Returns the number of listeners listening to the event named `eventName`.
307306

@@ -319,7 +318,7 @@ console.log(util.inspect(server.listeners('connection')));
319318

320319
### emitter.on(eventName, listener)
321320

322-
* `eventName` {string|Symbol} The name of the event.
321+
* `eventName` {String|Symbol} The name of the event.
323322
* `listener` {Function} The callback function
324323

325324
Adds the `listener` function to the end of the listeners array for the
@@ -334,7 +333,7 @@ server.on('connection', (stream) => {
334333
});
335334
```
336335

337-
Returns a reference to the `EventEmitter` so calls can be chained.
336+
Returns a reference to the `EventEmitter`, so that calls can be chained.
338337

339338
By default, event listeners are invoked in the order they are added. The
340339
`emitter.prependListener()` method can be used as an alternative to add the
@@ -352,7 +351,7 @@ myEE.emit('foo');
352351

353352
### emitter.once(eventName, listener)
354353

355-
* `eventName` {string|Symbol} The name of the event.
354+
* `eventName` {String|Symbol} The name of the event.
356355
* `listener` {Function} The callback function
357356

358357
Adds a **one time** `listener` function for the event named `eventName`. The
@@ -364,7 +363,7 @@ server.once('connection', (stream) => {
364363
});
365364
```
366365

367-
Returns a reference to the `EventEmitter` so calls can be chained.
366+
Returns a reference to the `EventEmitter`, so that calls can be chained.
368367

369368
By default, event listeners are invoked in the order they are added. The
370369
`emitter.prependOnceListener()` method can be used as an alternative to add the
@@ -382,7 +381,7 @@ myEE.emit('foo');
382381

383382
### emitter.prependListener(eventName, listener)
384383

385-
* `eventName` {string|Symbol} The name of the event.
384+
* `eventName` {String|Symbol} The name of the event.
386385
* `listener` {Function} The callback function
387386

388387
Adds the `listener` function to the *beginning* of the listeners array for the
@@ -397,11 +396,11 @@ server.prependListener('connection', (stream) => {
397396
});
398397
```
399398

400-
Returns a reference to the `EventEmitter` so calls can be chained.
399+
Returns a reference to the `EventEmitter`, so that calls can be chained.
401400

402401
### emitter.prependOnceListener(eventName, listener)
403402

404-
* `eventName` {string|Symbol} The name of the event.
403+
* `eventName` {String|Symbol} The name of the event.
405404
* `listener` {Function} The callback function
406405

407406
Adds a **one time** `listener` function for the event named `eventName` to the
@@ -414,7 +413,7 @@ server.prependOnceListener('connection', (stream) => {
414413
});
415414
```
416415

417-
Returns a reference to the `EventEmitter` so calls can be chained.
416+
Returns a reference to the `EventEmitter`, so that calls can be chained.
418417

419418
### emitter.removeAllListeners([eventName])
420419

@@ -424,7 +423,7 @@ Note that it is bad practice to remove listeners added elsewhere in the code,
424423
particularly when the `EventEmitter` instance was created by some other
425424
component or module (e.g. sockets or file streams).
426425

427-
Returns a reference to the `EventEmitter` so calls can be chained.
426+
Returns a reference to the `EventEmitter`, so that calls can be chained.
428427

429428
### emitter.removeListener(eventName, listener)
430429

@@ -485,10 +484,10 @@ myEmitter.emit('event');
485484
Because listeners are managed using an internal array, calling this will
486485
change the position indices of any listener registered *after* the listener
487486
being removed. This will not impact the order in which listeners are called,
488-
but it will means that any copies of the listener array as returned by
487+
but it means that any copies of the listener array as returned by
489488
the `emitter.listeners()` method will need to be recreated.
490489

491-
Returns a reference to the `EventEmitter` so calls can be chained.
490+
Returns a reference to the `EventEmitter`, so that calls can be chained.
492491

493492
### emitter.setMaxListeners(n)
494493

@@ -499,12 +498,13 @@ The `emitter.setMaxListeners()` method allows the limit to be modified for this
499498
specific `EventEmitter` instance. The value can be set to `Infinity` (or `0`)
500499
to indicate an unlimited number of listeners.
501500

502-
Returns a reference to the `EventEmitter` so calls can be chained.
501+
Returns a reference to the `EventEmitter`, so that calls can be chained.
503502

504503
[`net.Server`]: net.html#net_class_net_server
505504
[`fs.ReadStream`]: fs.html#fs_class_fs_readstream
506505
[`emitter.setMaxListeners(n)`]: #events_emitter_setmaxlisteners_n
507506
[`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners
508507
[`emitter.listenerCount()`]: #events_emitter_listenercount_eventname
509508
[`domain`]: domain.html
509+
[`process` object's `uncaughtException` event]: process.html#process_event_uncaughtexception
510510
[stream]: stream.html

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL