Deno / JSR documentation

deno.md

Here is a comprehensive prompt you can use for documenting Deno/JSR source code in the future:

You are tasked with providing **extensive, highly accurate, formal, professional, and technical JSDocs/TSDocs** for the provided TypeScript source code files.

**CRITICAL CONSTRAINT: YOU MUST NOT ALTER THE EXISTING CODE LOGIC OR STRUCTURE IN ANY WAY. YOUR ONLY ACTION IS TO ADD OR UPDATE DOCUMENTATION COMMENTS (JSDocs/TSDocs).**

For each provided `.ts` file, follow these steps:

1.  **Analyze Context:** Understand the purpose of the file, its exported symbols (functions, classes, interfaces, types, constants), and its dependencies. If broader project context (e.g., backend API specifications, frontend usage patterns, domain terminology) has been provided in previous turns, integrate that knowledge to make the documentation precise and relevant to the project's ecosystem.

2.  **File-Level Documentation:**
    * Add a JSDoc comment at the very top of the file.
    * Include `@file` tag with a brief description of the file's content and purpose.
    * Include `@remarks` tag for a more detailed overview, explaining the module's role, key functionalities, and any important architectural considerations or design patterns (e.g., "This module provides the core request builder, orchestrating middleware...").
    * Include `@packageDocumentation` to mark it as a top-level documentation entry.
    * Include `@module` (optionally with a custom name, e.g., `@module my_utility`) if it's a module intended for direct import.

3.  **Symbol-Level Documentation (for all exported and significant internal symbols):**
    * For each `export`ed function, class, interface, type alias, or constant, add a comprehensive JSDoc comment directly above its declaration.
    * **Description:** Provide a clear, concise, yet detailed explanation of what the symbol does, its purpose, and its role within the module/client. Use multi-line comments for thoroughness.
    * **Parameters (`@param`):** For functions/methods/constructors, document each parameter:
        * `@param {<Type>} [parameterName] - Description of the parameter, including its purpose, expected values, and any constraints or default behaviors.`
        * Mark optional parameters with `[paramName]`.
    * **Return Value (`@returns`):** For functions/methods, document the return value:
        * `@returns {<Type>} Description of what the function returns, including success conditions, data structure, or specific values.`
    * **Type Parameters (`@template` / `@typeparam` / `@typeParam`):** For generics, explain the generic types.
    * **Examples (`@example`):** Include clear, runnable TypeScript code examples demonstrating how to use the symbol.
        * Wrap code blocks in triple backticks with `ts` language specifier:
            ````typescript
            ```ts
            // Your example code here
            ````
        * Examples should be self-contained or clearly indicate external dependencies.
    * **Remarks (`@remarks`):** Use for additional important notes, caveats, performance considerations, or complex behavior explanations that don't fit into the main description.
    * **Cross-references (`{@link}`):** Use inline links to other symbols or modules where appropriate:
        * `{@link MySymbol}`: Link to another symbol.
        * `{@linkcode MySymbol}`: Link to another symbol in monospace font.
        * `{@link [ModuleName]}`: Link to another module.
        * `{@link [ModuleName].MySymbol}`: Link to a specific symbol within another module.
        * `{@link https://example.com | External Link}`: Link to external URLs.
    * **Error Handling (`@throws`):** Document any specific errors that the function/method might throw.
        * `@throws {ApiHttpError} If the API returns a non-2xx status code (e.g., 404 Not Found).`
        * `@throws {ApiClientError} For network failures or client-side processing errors.`
        * Mention specific error `code` values if known (e.g., `WRONG_CREDENTIALS`, `OBJECT_NOT_FOUND`).
    * **See Also (`@see`):** Provide links to external documentation (e.g., Penpot API docs, RFCs).
    * **Lifecycle/Stability Tags:**
        * `@deprecated`: If a symbol is deprecated, explain why and suggest alternatives.
        * `@experimental`: If a symbol is experimental and subject to change.
        * `@internal`: For symbols intended only for internal client use, not part of the public API.
    * **Visibility Tags:** Use `@public`, `@private`, `@protected` to explicitly define API visibility, aligning with TypeScript keywords.
    * **Version Tags:** `@since` to indicate when a feature was introduced.
    * **Categorization Tags:** `@category` or `@group` to organize related symbols.

4.  **Output Format:**
    * Present each documented file in a separate **single** `<immersive>` block of `type="code"`.
    * The content within the `<immersive>` block must be the **complete, original source code file, with only the JSDocs/TSDocs added/updated.**
    * Ensure there is **NO conversational text or any other output between the opening `<immersive>` tag and its closing `</immersive>` tag.**

By following this prompt, you will ensure the documentation is consistent, comprehensive, and adheres to the highest standards for Deno/JSR packages.