doc: cleanup events.md structure

Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: #36100 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
nodejs · Jun 11, 2021 · 9f67c08 · 9f67c08
1 parent 41cfe64
commit 9f67c08
Show file tree

Hide file tree

Showing 2 changed files with 115 additions and 110 deletions.
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -710,7 +710,7 @@ changes:
 
 Type: Documentation-only
 
-The [`EventEmitter.listenerCount(emitter, eventName)`][] API is
+The [`events.listenerCount(emitter, eventName)`][] API is
 deprecated. Please use [`emitter.listenerCount(eventName)`][] instead.
 
 ### DEP0034: `fs.exists(path, callback)`
@@ -2665,7 +2665,6 @@ Use `fs.rm(path, { recursive: true, force: true })` instead.
 [`Buffer.isBuffer()`]: buffer.md#buffer_static_method_buffer_isbuffer_obj
 [`Cipher`]: crypto.md#crypto_class_cipher
 [`Decipher`]: crypto.md#crypto_class_decipher
-[`EventEmitter.listenerCount(emitter, eventName)`]: events.md#events_eventemitter_listenercount_emitter_eventname
 [`REPLServer.clearBufferedCommand()`]: repl.md#repl_replserver_clearbufferedcommand
 [`ReadStream.open()`]: fs.md#fs_class_fs_readstream
 [`Server.connections`]: net.md#net_server_connections
@@ -2695,6 +2694,7 @@ Use `fs.rm(path, { recursive: true, force: true })` instead.
 [`domain`]: domain.md
 [`ecdh.setPublicKey()`]: crypto.md#crypto_ecdh_setpublickey_publickey_encoding
 [`emitter.listenerCount(eventName)`]: events.md#events_emitter_listenercount_eventname
+[`events.listenerCount(emitter, eventName)`]: events.md#events_events_listenercount_emitter_eventname
 [`fs.FileHandle`]: fs.md#fs_class_filehandle
 [`fs.access()`]: fs.md#fs_fs_access_path_mode_callback
 [`fs.createReadStream()`]: fs.md#fs_fs_createreadstream_path_options

diff --git a/doc/api/events.md b/doc/api/events.md
@@ -158,11 +158,13 @@ myEmitter.emit('error', new Error('whoops!'));
 ```
 
 It is possible to monitor `'error'` events without consuming the emitted error
-by installing a listener using the symbol `errorMonitor`.
+by installing a listener using the symbol `events.errorMonitor`.
 
 ```js
-const myEmitter = new MyEmitter();
-myEmitter.on(EventEmitter.errorMonitor, (err) => {
+const { EventEmitter, errorMonitor } = require('events');
+
+const myEmitter = new EventEmitter();
+myEmitter.on(errorMonitor, (err) => {
   MyMonitoringTool.log(err);
 });
 myEmitter.emit('error', new Error('whoops!'));
@@ -205,12 +207,13 @@ ee2.on('something', async (value) => {
 ee2[Symbol.for('nodejs.rejection')] = console.log;
 ```
 
-Setting `EventEmitter.captureRejections = true` will change the default for all
+Setting `events.captureRejections = true` will change the default for all
 new instances of `EventEmitter`.
 
 ```js
-EventEmitter.captureRejections = true;
-const ee1 = new EventEmitter();
+const events = require('events');
+events.captureRejections = true;
+const ee1 = new events.EventEmitter();
 ee1.on('something', async (value) => {
   throw new Error('kaboom');
 });
@@ -306,106 +309,6 @@ changes:
 
 The `'removeListener'` event is emitted *after* the `listener` is removed.
 
-### `EventEmitter.listenerCount(emitter, eventName)`
-<!-- YAML
-added: v0.9.12
-deprecated: v3.2.0
--->
-
-> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead.
-
-* `emitter` {EventEmitter} The emitter to query
-* `eventName` {string|symbol} The event name
-
-A class method that returns the number of listeners for the given `eventName`
-registered on the given `emitter`.
-
-```js
-const myEmitter = new EventEmitter();
-myEmitter.on('event', () => {});
-myEmitter.on('event', () => {});
-console.log(EventEmitter.listenerCount(myEmitter, 'event'));
-// Prints: 2
-```
-
-### `EventEmitter.defaultMaxListeners`
-<!-- YAML
-added: v0.11.2
--->
-
-By default, a maximum of `10` listeners can be registered for any single
-event. This limit can be changed for individual `EventEmitter` instances
-using the [`emitter.setMaxListeners(n)`][] method. To change the default
-for *all* `EventEmitter` instances, the `EventEmitter.defaultMaxListeners`
-property can be used. If this value is not a positive number, a `RangeError`
-is thrown.
-
-Take caution when setting the `EventEmitter.defaultMaxListeners` because the
-change affects *all* `EventEmitter` instances, including those created before
-the change is made. However, calling [`emitter.setMaxListeners(n)`][] still has
-precedence over `EventEmitter.defaultMaxListeners`.
-
-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
-`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()`
-methods can be used to temporarily avoid this warning:
-
-```js
-emitter.setMaxListeners(emitter.getMaxListeners() + 1);
-emitter.once('event', () => {
-  // do stuff
-  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
-});
-```
-
-The [`--trace-warnings`][] command-line flag can be used to display the
-stack trace for such warnings.
-
-The emitted warning can be inspected with [`process.on('warning')`][] and will
-have the additional `emitter`, `type` and `count` properties, referring to
-the event emitter instance, the event’s name and the number of attached
-listeners, respectively.
-Its `name` property is set to `'MaxListenersExceededWarning'`.
-
-### `EventEmitter.errorMonitor`
-<!-- YAML
-added:
- - v13.6.0
- - v12.16.0
--->
-
-This symbol shall be used to install a listener for only monitoring `'error'`
-events. Listeners installed using this symbol are called before the regular
-`'error'` listeners are called.
-
-Installing a listener using this symbol does not change the behavior once an
-`'error'` event is emitted, therefore the process will still crash if no
-regular `'error'` listener is installed.
-
-### `EventEmitter.setMaxListeners(n[, ...eventTargets])`
-<!-- YAML
-added: v14.17.0
--->
-
-* `n` {number} A non-negative number. The maximum number of listeners per
-  `EventTarget` event.
-* `...eventsTargets` {EventTarget[]|EventEmitter[]} Zero or more {EventTarget}
-  or {EventEmitter} instances. If none are specified, `n` is set as the default
-  max for all newly created {EventTarget} and {EventEmitter} objects.
-
-```js
-const {
-  setMaxListeners,
-  EventEmitter
-} = require('events');
-
-const target = new EventTarget();
-const emitter = new EventEmitter();
-
-setMaxListeners(5, target, emitter);
-```
-
 ### `emitter.addListener(eventName, listener)`
 <!-- YAML
 added: v0.1.26
@@ -496,7 +399,7 @@ added: v1.0.0
 
 Returns the current max listener value for the `EventEmitter` which is either
 set by [`emitter.setMaxListeners(n)`][] or defaults to
-[`EventEmitter.defaultMaxListeners`][].
+[`events.defaultMaxListeners`][].
 
 ### `emitter.listenerCount(eventName)`
 <!-- YAML
@@ -852,6 +755,61 @@ class MyClass extends EventEmitter {
 }
 ```
 
+## `events.defaultMaxListeners`
+<!-- YAML
+added: v0.11.2
+-->
+
+By default, a maximum of `10` listeners can be registered for any single
+event. This limit can be changed for individual `EventEmitter` instances
+using the [`emitter.setMaxListeners(n)`][] method. To change the default
+for *all* `EventEmitter` instances, the `events.defaultMaxListeners`
+property can be used. If this value is not a positive number, a `RangeError`
+is thrown.
+
+Take caution when setting the `events.defaultMaxListeners` because the
+change affects *all* `EventEmitter` instances, including those created before
+the change is made. However, calling [`emitter.setMaxListeners(n)`][] still has
+precedence over `events.defaultMaxListeners`.
+
+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
+`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()`
+methods can be used to temporarily avoid this warning:
+
+```js
+emitter.setMaxListeners(emitter.getMaxListeners() + 1);
+emitter.once('event', () => {
+  // do stuff
+  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
+});
+```
+
+The [`--trace-warnings`][] command-line flag can be used to display the
+stack trace for such warnings.
+
+The emitted warning can be inspected with [`process.on('warning')`][] and will
+have the additional `emitter`, `type` and `count` properties, referring to
+the event emitter instance, the event’s name and the number of attached
+listeners, respectively.
+Its `name` property is set to `'MaxListenersExceededWarning'`.
+
+## `events.errorMonitor`
+<!-- YAML
+added:
+ - v13.6.0
+ - v12.17.0
+-->
+
+This symbol shall be used to install a listener for only monitoring `'error'`
+events. Listeners installed using this symbol are called before the regular
+`'error'` listeners are called.
+
+Installing a listener using this symbol does not change the behavior once an
+`'error'` event is emitted, therefore the process will still crash if no
+regular `'error'` listener is installed.
+
 ## `events.getEventListeners(emitterOrTarget, eventName)`
 <!-- YAML
 added:
@@ -1065,6 +1023,29 @@ Value: `Symbol.for('nodejs.rejection')`
 
 See how to write a custom [rejection handler][rejection].
 
+## `events.listenerCount(emitter, eventName)`
+<!-- YAML
+added: v0.9.12
+deprecated: v3.2.0
+-->
+
+> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead.
+
+* `emitter` {EventEmitter} The emitter to query
+* `eventName` {string|symbol} The event name
+
+A class method that returns the number of listeners for the given `eventName`
+registered on the given `emitter`.
+
+```js
+const { EventEmitter, listenerCount } = require('events');
+const myEmitter = new EventEmitter();
+myEmitter.on('event', () => {});
+myEmitter.on('event', () => {});
+console.log(listenerCount(myEmitter, 'event'));
+// Prints: 2
+```
+
 ## `events.on(emitter, eventName[, options])`
 <!-- YAML
 added:
@@ -1132,6 +1113,30 @@ const ac = new AbortController();
 process.nextTick(() => ac.abort());
 ```
 
+## `events.setMaxListeners(n[, ...eventTargets])`
+<!-- YAML
+added: v14.17.0
+-->
+
+* `n` {number} A non-negative number. The maximum number of listeners per
+  `EventTarget` event.
+* `...eventsTargets` {EventTarget[]|EventEmitter[]} Zero or more {EventTarget}
+  or {EventEmitter} instances. If none are specified, `n` is set as the default
+  max for all newly created {EventTarget} and {EventEmitter} objects.
+
+```js
+const {
+  setMaxListeners,
+  EventEmitter
+} = require('events');
+
+const target = new EventTarget();
+const emitter = new EventEmitter();
+
+setMaxListeners(5, target, emitter);
+```
+
+<a id="event-target-and-event-api"></a>
 ## `EventTarget` and `Event` API
 <!-- YAML
 added: v14.5.0
@@ -1604,14 +1609,14 @@ to the `EventTarget`.
 
 [WHATWG-EventTarget]: https://dom.spec.whatwg.org/#interface-eventtarget
 [`--trace-warnings`]: cli.md#cli_trace_warnings
-[`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners
 [`EventTarget` Web API]: https://dom.spec.whatwg.org/#eventtarget
 [`EventTarget` error handling]: #events_eventtarget_error_handling
 [`Event` Web API]: https://dom.spec.whatwg.org/#event
 [`domain`]: domain.md
 [`emitter.listenerCount()`]: #events_emitter_listenercount_eventname
 [`emitter.removeListener()`]: #events_emitter_removelistener_eventname_listener
 [`emitter.setMaxListeners(n)`]: #events_emitter_setmaxlisteners_n
+[`events.defaultMaxListeners`]: #events_events_defaultmaxlisteners
 [`fs.ReadStream`]: fs.md#fs_class_fs_readstream
 [`net.Server`]: net.md#net_class_net_server
 [`process.on('warning')`]: process.md#process_event_warning