docs(async): improve docs for stabilization (#4803)

_tools/check_docs.ts

@@ -27,6 +27,7 @@ type DocNodeWithJsDoc<T = DocNodeBase> = T & {
 
 const ENTRY_POINTS = [
   "../bytes/mod.ts",
+  "../async/mod.ts",
   "../datetime/mod.ts",
   "../collections/mod.ts",
   "../internal/mod.ts",

async/abortable.ts

@@ -4,10 +4,15 @@
 import { createAbortError } from "./_util.ts";
 
 /**
- * Make {@linkcode Promise} abortable with the given signal.
+ * Make a {@linkcode Promise} abortable with the given signal.
+ *
+ * @typeParam T The type of the provided and returned promise.
+ * @param p The promise to make abortable.
+ * @param signal The signal to abort the promise with.
+ * @returns A promise that can be aborted.
  *
  * @example
- * ```ts
+ * ```ts no-eval
  * import {
  *   abortable,
  *   delay,
@@ -23,10 +28,15 @@ import { createAbortError } from "./_util.ts";
  */
 export function abortable<T>(p: Promise<T>, signal: AbortSignal): Promise<T>;
 /**
- * Make {@linkcode AsyncIterable} abortable with the given signal.
+ * Make an {@linkcode AsyncIterable} abortable with the given signal.
+ *
+ * @typeParam T The type of the provided and returned async iterable.
+ * @param p The async iterable to make abortable.
+ * @param signal The signal to abort the promise with.
+ * @returns An async iterable that can be aborted.
  *
  * @example
- * ```ts
+ * ```ts no-eval
  * import {
  *   abortable,
  *   delay,
@@ -64,10 +74,15 @@ export function abortable<T>(
 }
 
 /**
- * Make Promise abortable with the given signal.
+ * Make a {@linkcode Promise} abortable with the given signal.
+ *
+ * @typeParam T The type of the provided and returned promise.
+ * @param p The promise to make abortable.
+ * @param signal The signal to abort the promise with.
+ * @returns A promise that can be aborted.
  *
  * @example
- * ```ts
+ * ```ts no-eval
  * import { abortablePromise } from "@std/async/abortable";
  *
  * const request = fetch("https://example.com");
@@ -97,10 +112,15 @@ export function abortablePromise<T>(
 }
 
 /**
- * Make AsyncIterable abortable with the given signal.
+ * Make an {@linkcode AsyncIterable} abortable with the given signal.
+ *
+ * @typeParam T The type of the provided and returned async iterable.
+ * @param p The async iterable to make abortable.
+ * @param signal The signal to abort the promise with.
+ * @returns An async iterable that can be aborted.
  *
  * @example
- * ```ts
+ * ```ts no-eval
  * import {
  *   abortableAsyncIterable,
  *   delay,

async/deadline.ts

@@ -3,24 +3,22 @@
 
 import { delay } from "./delay.ts";
 
-/** Options for {@linkcode Deadline}. */
+/** Options for {@linkcode deadline}. */
 export interface DeadlineOptions {
   /** Signal used to abort the deadline. */
   signal?: AbortSignal;
 }
 
-/** Error thrown when {@linkcode Deadline} times out. */
+/**
+ * Error thrown when {@linkcode deadline} times out.
+ *
+ * @example
+ * ```ts
+ * import { DeadlineError } from "@std/async/deadline";
+ * const error = new DeadlineError();
+ * ```
+ */
 export class DeadlineError extends Error {
-  /**
-   * Constructs a new {@linkcode DeadlineError} instance.
-   *
-   * @example
-   * ```ts
-   * import { DeadlineError } from "@std/async/deadline";
-   *
-   * throw new DeadlineError();
-   * ```
-   */
   constructor() {
     super("Deadline");
     this.name = this.constructor.name;
@@ -34,8 +32,14 @@ export class DeadlineError extends Error {
  * Note: Prefer to use {@linkcode AbortSignal.timeout} instead for the APIs
  * that accept {@linkcode AbortSignal}.
  *
+ * @typeParam T The type of the provided and returned promise.
+ * @param p The promise to make rejectable.
+ * @param ms Duration in milliseconds for when the promise should time out.
+ * @param options Additional options.
+ * @returns A promise that will reject if the provided duration runs out before resolving.
+ *
  * @example
- * ```ts
+ * ```ts no-eval
  * import { deadline } from "@std/async/deadline";
  * import { delay } from "@std/async/delay";
  *

async/debounce.ts

@@ -23,7 +23,7 @@ export interface DebouncedFunction<T extends Array<unknown>> {
  * aborted.
  *
  * @example
- * ```ts
+ * ```ts no-eval
  * import { debounce } from "@std/async/debounce";
  *
  * await Array.fromAsync(
@@ -36,8 +36,10 @@ export interface DebouncedFunction<T extends Array<unknown>> {
  * // output: Function debounced after 200ms with baz
  * ```
  *
+ * @typeParam T The arguments of the provided function.
  * @param fn    The function to debounce.
  * @param wait  The time in milliseconds to delay the function.
+ * @returns     The debounced function.
  */
 // deno-lint-ignore no-explicit-any
 export function debounce<T extends Array<any>>(

async/delay.ts

@@ -15,6 +15,9 @@ export interface DelayOptions {
 /**
  * Resolve a {@linkcode Promise} after a given amount of milliseconds.
  *
+ * @param ms Duration in milliseconds for how long the delay should last.
+ * @param options Additional options.
+ *
  * @example
  * ```ts
  * import { delay } from "@std/async/delay";

async/mux_async_iterator.ts

@@ -34,8 +34,10 @@ interface TaggedYieldedValue<T> {
  * for await (const value of mux) {
  *   // ...
  * }
- * // ..
+ * // ...
  * ```
+ *
+ * @typeParam T The type of the provided async iterables and generated async iterable.
  */
 export class MuxAsyncIterator<T> implements AsyncIterable<T> {
   #iteratorCount = 0;
@@ -44,7 +46,25 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
   #throws: any[] = [];
   #signal = Promise.withResolvers<void>();
 
-  /** Add an async iterable to the stream. */
+  /**
+   * Add an async iterable to the stream.
+   *
+   * @param iterable The async iterable to add.
+   *
+   * @example
+   * ```ts
+   * import { MuxAsyncIterator } from "@std/async/mux-async-iterator";
+   *
+   * async function* gen123(): AsyncIterableIterator<number> {
+   *   yield 1;
+   *   yield 2;
+   *   yield 3;
+   * }
+   *
+   * const mux = new MuxAsyncIterator<number>();
+   * mux.add(gen123());
+   * ```
+   */
   add(iterable: AsyncIterable<T>) {
     ++this.#iteratorCount;
     this.#callIteratorNext(iterable[Symbol.asyncIterator]());
@@ -66,7 +86,28 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
     this.#signal.resolve();
   }
 
-  /** Returns an async iterator of the stream. */
+  /**
+   * Returns an async iterator of the stream.
+   * @returns the async iterator for all the added async iterables.
+   *
+   * @example
+   * ```ts
+   * import { MuxAsyncIterator } from "@std/async/mux-async-iterator";
+   *
+   * async function* gen123(): AsyncIterableIterator<number> {
+   *   yield 1;
+   *   yield 2;
+   *   yield 3;
+   * }
+   *
+   * const mux = new MuxAsyncIterator<number>();
+   * mux.add(gen123());
+   *
+   * for await (const value of mux) {
+   *   // ...
+   * }
+   * ```
+   */
   async *iterate(): AsyncIterableIterator<T> {
     while (this.#iteratorCount > 0) {
       // Sleep until any of the wrapped iterators yields.
@@ -89,7 +130,28 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
     }
   }
 
-  /** Implements an async iterator for the stream. */
+  /**
+   * Implements an async iterator for the stream.
+   * @returns the async iterator for all the added async iterables.
+   *
+   * @example
+   * ```ts
+   * import { MuxAsyncIterator } from "@std/async/mux-async-iterator";
+   *
+   * async function* gen123(): AsyncIterableIterator<number> {
+   *   yield 1;
+   *   yield 2;
+   *   yield 3;
+   * }
+   *
+   * const mux = new MuxAsyncIterator<number>();
+   * mux.add(gen123());
+   *
+   * for await (const value of mux) {
+   *   // ...
+   * }
+   * ```
+   */
   [Symbol.asyncIterator](): AsyncIterator<T> {
     return this.iterate();
   }

async/pool.ts

@@ -29,9 +29,12 @@ export const ERROR_WHILE_MAPPING_MESSAGE = "Threw while mapping.";
  * }
  * ```
  *
+ * @typeParam T the input type.
+ * @typeParam R the output type.
  * @param poolLimit The maximum count of items being processed concurrently.
  * @param array The input array for mapping.
  * @param iteratorFn The function to call for every item of the array.
+ * @returns The async iterator with the transformed values.
  */
 export function pooledMap<T, R>(
   poolLimit: number,

async/retry.ts

@@ -7,16 +7,26 @@ import { exponentialBackoffWithJitter } from "./_util.ts";
 /**
  * Error thrown in {@linkcode retry} once the maximum number of failed attempts
  * has been reached.
+ *
+ * @example
+ * ```ts
+ * import { RetryError } from "@std/async/retry";
+ *
+ * const error = new RetryError({ foo: "bar" }, 3);
+ * ```
  */
 export class RetryError extends Error {
   /**
    * Constructs a new {@linkcode RetryError} instance.
    *
+   * @param cause the cause for this error.
+   * @param attempts the number of retry attempts made.
+   *
    * @example
    * ```ts
    * import { RetryError } from "@std/async/retry";
    *
-   * throw new RetryError({ foo: "bar" }, 3);
+   * const error = new RetryError({ foo: "bar" }, 3);
    * ```
    */
   constructor(cause: unknown, attempts: number) {
@@ -117,6 +127,11 @@ const defaultRetryOptions: Required<RetryOptions> = {
  *  jitter: 0.5,
  * });
  * ```
+ *
+ * @typeParam T The return type of the function to retry and returned promise.
+ * @param fn The function to retry.
+ * @param opts Additional options.
+ * @returns The promise that resolves with the value returned by the function to retry.
  */
 export async function retry<T>(
   fn: (() => Promise<T>) | (() => T),

async/tee.ts

@@ -71,6 +71,12 @@ class Queue<T> {
  *   console.log(n); // => 1, 2, 3
  * }
  * ```
+ *
+ * @typeParam T The type of the provided async iterable and the returned async iterables.
+ * @typeParam N The amount of branches to tee into.
+ * @param iterable The iterable to tee.
+ * @param n The amount of branches to tee into.
+ * @returns The tuple where each element is an async iterable.
  */
 export function tee<T, N extends number = 2>(
   iterable: AsyncIterable<T>,

deno.json

@@ -19,7 +19,7 @@
     "lint:circular": "deno run --allow-env --allow-read --allow-net=deno.land,jsr.io ./_tools/check_circular_package_dependencies.ts",
     "lint:mod-exports": "deno run --allow-env --allow-read ./_tools/check_mod_exports.ts",
     "lint:tools-types": "deno check _tools/*.ts",
-    "lint:docs": "deno doc --lint collections/mod.ts bytes/mod.ts datetime/mod.ts internal/mod.ts media_types/mod.ts url/mod.ts webgpu/mod.ts && deno run -A _tools/check_docs.ts",
+    "lint:docs": "deno doc --lint async/mod.ts collections/mod.ts bytes/mod.ts datetime/mod.ts internal/mod.ts media_types/mod.ts url/mod.ts webgpu/mod.ts && deno run -A _tools/check_docs.ts",
     "lint": "deno lint && deno task fmt:licence-headers --check && deno task lint:circular && deno task lint:deprecations && deno task lint:tools-types && deno task lint:mod-exports && deno task lint:docs",
     "typos": "typos -c ./.github/workflows/typos.toml",
     "build:crypto": "deno task --cwd crypto/_wasm wasmbuild",

webgpu/create_capture.ts

@@ -20,7 +20,7 @@ export interface CreateCapture {
  * Creates a texture and buffer to use as a capture.
  *
  * @example
- * ```ts, no-eval
+ * ```ts no-eval
  * import { createCapture } from "@std/webgpu/create-capture";
  * import { getRowPadding } from "@std/webgpu/row-padding";
  *

webgpu/texture_with_data.ts

@@ -84,7 +84,7 @@ function textureMipLevelSize(
  * Create a {@linkcode GPUTexture} with data.
  *
  * @example
- * ```ts, no-eval
+ * ```ts no-eval
  * import { createTextureWithData } from "@std/webgpu/texture-with-data";
  *
  * const adapter = await navigator.gpu.requestAdapter();