Improve `AddEventListenerOptions` docs

Open
#2,135 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
38/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
typescript

Research direction

Locate the generator input and output for the AddEventListenerOptions interface, then compare nearby documented interfaces to learn how comments are propagated into generated declarations. Add the supplied documentation through the project’s established source and verify that the generated output contains it and relevant checks pass.

Written by the indexing model from the issue text.

Description

I spent 10 minutes and couldn't figure out how to add these docs to the generated output, so here's a recommended declaration from the Deno repo:

/**
 * 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;
}

I can contribute it if someone points out how to add this or feel free to go ahead and add it.

Dominant language
TypeScript
Stars
740
Forks
474
Avg merge
2d 8h
Merged PRs (30d)
15

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/TypeScript-DOM-lib-generator

All issues in microsoft/TypeScript-DOM-lib-generator

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.