docs: JSDocs for events API (#29569)

Signed-off-by: Jo Franchetti <jofranchetti@gmail.com>
Co-authored-by: Phil Hawksworth <phil@deno.com>

cli/tsc/dts/lib.deno_web.d.ts

@@ -218,10 +218,76 @@ declare var EventTarget: {
 
 /** @category Events */
 interface EventListener {
+  /**
+   * The `EventListener` interface represents a callback function to be called
+   * whenever an event of a specific type occurs on a target object.
+   *
+   * This is a basic event listener, represented by a simple function
+   * that receives an Event object as its only parameter.
+   *
+   * @example
+   * ```ts
+   * // Create an event listener function
+   * const handleEvent = (event: Event) => {
+   *   console.log(`Event of type "${event.type}" occurred`);
+   *   console.log(`Event phase: ${event.eventPhase}`);
+   *
+   *   // Access event properties
+   *   if (event.cancelable) {
+   *     event.preventDefault();
+   *   }
+   * };
+   *
+   * // Attach the event listener to a target
+   * const target = new EventTarget();
+   * target.addEventListener('custom', handleEvent);
+   *
+   * // Or create a listener inline
+   * target.addEventListener('message', (event) => {
+   *   console.log('Message received:', event);
+   * });
+   * ```
+   *
+   * @category Events
+   */
   (evt: Event): void;
 }
 
-/** @category Events */
+/**
+ * The `EventListenerObject` interface represents an object that can handle events
+ * dispatched by an `EventTarget` object.
+ *
+ * This interface provides an alternative to using a function as an event listener.
+ * When implementing an object with this interface, the `handleEvent()` method
+ * will be called when the event is triggered.
+ *
+ * @example
+ * ```ts
+ * // Creating an object that implements `EventListenerObject`
+ * const myEventListener = {
+ *   handleEvent(event) {
+ *     console.log(`Event of type ${event.type} occurred`);
+ *
+ *     // You can use 'this' to access other methods or properties
+ *     this.additionalProcessing(event);
+ *   },
+ *
+ *   additionalProcessing(event) {
+ *     // Additional event handling logic
+ *     console.log('Additional processing for:', event);
+ *   }
+ * };
+ *
+ * // Using with any EventTarget (server or client contexts)
+ * const target = new EventTarget();
+ * target.addEventListener('message', myEventListener);
+ *
+ * // Later, to remove it:
+ * target.removeEventListener('message', myEventListener);
+ * ```
+ *
+ * @category Events
+ */
 interface EventListenerObject {
   handleEvent(evt: Event): void;
 }
@@ -231,10 +297,48 @@ type EventListenerOrEventListenerObject =
   | EventListener
   | EventListenerObject;
 
-/** @category Events */
+/**
+ * Options for configuring an event listener via `addEventListener`.
+ *
+ * This interface extends `EventListenerOptions` and provides additional configuration
+ * options to control event listener behavior.
+ *
+ * @example
+ * ```ts
+ * eventTarget.addEventListener('message', handler, {
+ *   once: true,
+ *   passive: true,
+ *   signal: controller.signal
+ * });
+ * ```
+ *
+ * @category Events */
 interface AddEventListenerOptions extends EventListenerOptions {
+  /**
+   * When set to true, the listener will automatically be removed after it has been invoked once.
+   */
   once?: boolean;
+
+  /**
+   * When set to true, indicates that the listener will never call `preventDefault()`.
+   * This provides a performance optimization opportunity for event processing.
+   * If a passive listener attempts to call `preventDefault()`, the call will be ignored
+   * and a warning may be generated.
+   */
   passive?: boolean;
+
+  /**
+   * An `AbortSignal` that can be used to remove the event listener when aborted.
+   *
+   * @example
+   * ```ts
+   * const controller = new AbortController();
+   * eventTarget.addEventListener('message', handler, { signal: controller.signal });
+   *
+   * // Later, to remove the listener:
+   * controller.abort();
+   * ```
+   */
   signal?: AbortSignal;
 }
 

cli/tsc/dts/lib.webworker.d.ts

@@ -20,9 +20,70 @@ and limitations under the License.
 /// Worker APIs
 /////////////////////////////
 
+/**
+ * Specifies characteristics about the event listener or the event handler it can invoke.
+ *
+ * This interface extends `EventListenerOptions` and provides additional configuration
+ * options for controlling event listener behavior.
+ *
+ * @example
+ * ```ts
+ * target.addEventListener('message', handler, {
+ *   once: true,
+ *   passive: true,
+ *   signal: controller.signal
+ * });
+ * ```
+ */
+/**
+ * Options that can be specified when adding an event listener via `addEventListener`.
+ *
+ * This interface extends `EventListenerOptions` and provides additional configuration
+ * options for controlling event listener behavior in a worker context.
+ *
+ * @example
+ * ```ts
+ * // Register a message event handler that automatically removes itself after one invocation
+ * worker.addEventListener('message', handleMessageOnce, { once: true });
+ *
+ * // Register a message event handler that doesn't block the runtime while processing events
+ * worker.addEventListener('message', handleMessage, { passive: true });
+ *
+ * // Register a message event handler that can be removed via an AbortController
+ * const controller = new AbortController();
+ * worker.addEventListener('message', handleMessage, { signal: controller.signal });
+ *
+ * // Later, to remove the listener:
+ * controller.abort();
+ * ```
+ */
 interface AddEventListenerOptions extends EventListenerOptions {
+    /**
+     * When set to true, the listener will be automatically removed after being invoked once.
+     * If not specified, defaults to false.
+     */
     once?: boolean;
+
+    /**
+     * When set to true, indicates that the function specified by the listener will never call
+     * `preventDefault()`. This allows optimization of the processing of events.
+     * If a passive listener does try to call `preventDefault()`, it will be ignored.
+     */
     passive?: boolean;
+
+    /**
+     * An `AbortSignal` that can be used to remove the event listener by calling `abort()`
+     * on the controller that created the signal.
+     *
+     * @example
+     * ```ts
+     * const controller = new AbortController();
+     * target.addEventListener('mousemove', handler, { signal: controller.signal });
+     *
+     * // Later, to remove the listener:
+     * controller.abort();
+     * ```
+     */
     signal?: AbortSignal;
 }