typings: add JSDoc typings for events

Added JSDoc typings for the `events` lib module.

PR-URL: #38712
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Masashi Hirano <shisama07@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

lib/events.js

@@ -79,6 +79,11 @@ const kMaxEventTargetListeners = Symbol('events.maxEventTargetListeners');
 const kMaxEventTargetListenersWarned =
   Symbol('events.maxEventTargetListenersWarned');
 
+/**
+ * Creates a new `EventEmitter` instance.
+ * @param {{ captureRejections?: boolean; }} [opts]
+ * @returns {EventEmitter}
+ */
 function EventEmitter(opts) {
   EventEmitter.init.call(this, opts);
 }
@@ -156,6 +161,12 @@ ObjectDefineProperties(EventEmitter, {
   }
 });
 
+/**
+ * Sets the max listeners.
+ * @param {number} n
+ * @param {EventTarget[] | EventEmitter[]} [eventTargets]
+ * @returns {void}
+ */
 EventEmitter.setMaxListeners =
   function(n = defaultMaxListeners, ...eventTargets) {
     if (typeof n !== 'number' || n < 0 || NumberIsNaN(n))
@@ -247,8 +258,11 @@ function emitUnhandledRejectionOrErr(ee, err, type, args) {
   }
 }
 
-// Obviously not all Emitters should be limited to 10. This function allows
-// that to be increased. Set to zero for unlimited.
+/**
+ * Increases the max listeners of the event emitter.
+ * @param {number} n
+ * @returns {EventEmitter}
+ */
 EventEmitter.prototype.setMaxListeners = function setMaxListeners(n) {
   if (typeof n !== 'number' || n < 0 || NumberIsNaN(n)) {
     throw new ERR_OUT_OF_RANGE('n', 'a non-negative number', n);
@@ -263,6 +277,10 @@ function _getMaxListeners(that) {
   return that._maxListeners;
 }
 
+/**
+ * Returns the current max listener value for the event emitter.
+ * @returns {number}
+ */
 EventEmitter.prototype.getMaxListeners = function getMaxListeners() {
   return _getMaxListeners(this);
 };
@@ -315,6 +333,13 @@ function enhanceStackTrace(err, own) {
   return err.stack + sep + ArrayPrototypeJoin(ownStack, '\n');
 }
 
+/**
+ * Synchronously calls each of the listeners registered
+ * for the event.
+ * @param {string | symbol} type
+ * @param {...any} [args]
+ * @returns {boolean}
+ */
 EventEmitter.prototype.emit = function emit(type, ...args) {
   let doError = (type === 'error');
 
@@ -456,12 +481,25 @@ function _addListener(target, type, listener, prepend) {
   return target;
 }
 
+/**
+ * Adds a listener to the event emitter.
+ * @param {string | symbol} type
+ * @param {Function} listener
+ * @returns {EventEmitter}
+ */
 EventEmitter.prototype.addListener = function addListener(type, listener) {
   return _addListener(this, type, listener, false);
 };
 
 EventEmitter.prototype.on = EventEmitter.prototype.addListener;
 
+/**
+ * Adds the `listener` function to the beginning of
+ * the listeners array.
+ * @param {string | symbol} type
+ * @param {Function} listener
+ * @returns {EventEmitter}
+ */
 EventEmitter.prototype.prependListener =
     function prependListener(type, listener) {
       return _addListener(this, type, listener, true);
@@ -485,13 +523,26 @@ function _onceWrap(target, type, listener) {
   return wrapped;
 }
 
+/**
+ * Adds a one-time `listener` function to the event emitter.
+ * @param {string | symbol} type
+ * @param {Function} listener
+ * @returns {EventEmitter}
+ */
 EventEmitter.prototype.once = function once(type, listener) {
   checkListener(listener);
 
   this.on(type, _onceWrap(this, type, listener));
   return this;
 };
 
+/**
+ * Adds a one-time `listener` function to the beginning of
+ * the listeners array.
+ * @param {string | symbol} type
+ * @param {Function} listener
+ * @returns {EventEmitter}
+ */
 EventEmitter.prototype.prependOnceListener =
     function prependOnceListener(type, listener) {
       checkListener(listener);
@@ -500,7 +551,12 @@ EventEmitter.prototype.prependOnceListener =
       return this;
     };
 
-// Emits a 'removeListener' event if and only if the listener was removed.
+/**
+ * Removes the specified `listener` from the listeners array.
+ * @param {string | symbol} type
+ * @param {Function} listener
+ * @returns {EventEmitter}
+ */
 EventEmitter.prototype.removeListener =
     function removeListener(type, listener) {
       checkListener(listener);
@@ -554,6 +610,13 @@ EventEmitter.prototype.removeListener =
 
 EventEmitter.prototype.off = EventEmitter.prototype.removeListener;
 
+/**
+ * Removes all listeners from the event emitter. (Only
+ * removes listeners for a specific event name if specified
+ * as `type`).
+ * @param {string | symbol} [type]
+ * @returns {EventEmitter}
+ */
 EventEmitter.prototype.removeAllListeners =
     function removeAllListeners(type) {
       const events = this._events;
@@ -617,14 +680,34 @@ function _listeners(target, type, unwrap) {
     unwrapListeners(evlistener) : arrayClone(evlistener);
 }
 
+/**
+ * Returns a copy of the array of listeners for the event name
+ * specified as `type`.
+ * @param {string | symbol} type
+ * @returns {Function[]}
+ */
 EventEmitter.prototype.listeners = function listeners(type) {
   return _listeners(this, type, true);
 };
 
+/**
+ * Returns a copy of the array of listeners and wrappers for
+ * the event name specified as `type`.
+ * @param {string | symbol} type
+ * @returns {Function[]}
+ */
 EventEmitter.prototype.rawListeners = function rawListeners(type) {
   return _listeners(this, type, false);
 };
 
+/**
+ * Returns the number of listeners listening to the event name
+ * specified as `type`.
+ * @deprecated since v3.2.0
+ * @param {EventEmitter} emitter
+ * @param {string | symbol} type
+ * @returns {number}
+ */
 EventEmitter.listenerCount = function(emitter, type) {
   if (typeof emitter.listenerCount === 'function') {
     return emitter.listenerCount(type);
@@ -633,6 +716,13 @@ EventEmitter.listenerCount = function(emitter, type) {
 };
 
 EventEmitter.prototype.listenerCount = listenerCount;
+
+/**
+ * Returns the number of listeners listening to event name
+ * specified as `type`.
+ * @param {string | symbol} type
+ * @returns {number}
+ */
 function listenerCount(type) {
   const events = this._events;
 
@@ -649,6 +739,11 @@ function listenerCount(type) {
   return 0;
 }
 
+/**
+ * Returns an array listing the events for which
+ * the emitter has registered listeners.
+ * @returns {any[]}
+ */
 EventEmitter.prototype.eventNames = function eventNames() {
   return this._eventsCount > 0 ? ReflectOwnKeys(this._events) : [];
 };
@@ -676,6 +771,13 @@ function unwrapListeners(arr) {
   return ret;
 }
 
+/**
+ * Returns a copy of the array of listeners for the event name
+ * specified as `type`.
+ * @param {EventEmitter | EventTarget} emitterOrTarget
+ * @param {string | symbol} type
+ * @returns {Function[]}
+ */
 function getEventListeners(emitterOrTarget, type) {
   // First check if EventEmitter
   if (typeof emitterOrTarget.listeners === 'function') {
@@ -700,6 +802,14 @@ function getEventListeners(emitterOrTarget, type) {
                                  emitterOrTarget);
 }
 
+/**
+ * Creates a `Promise` that is fulfilled when the emitter
+ * emits the given event.
+ * @param {EventEmitter} emitter
+ * @param {string} name
+ * @param {{ signal: AbortSignal; }} [options]
+ * @returns {Promise}
+ */
 async function once(emitter, name, options = {}) {
   const signal = options?.signal;
   validateAbortSignal(signal, 'options.signal');
@@ -771,6 +881,13 @@ function eventTargetAgnosticAddListener(emitter, name, listener, flags) {
   }
 }
 
+/**
+ * Returns an `AsyncIterator` that iterates `event` events.
+ * @param {EventEmitter} emitter
+ * @param {string | symbol} event
+ * @param {{ signal: AbortSignal; }} [options]
+ * @returns {AsyncIterator}
+ */
 function on(emitter, event, options) {
   const signal = options?.signal;
   validateAbortSignal(signal, 'options.signal');