Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(async): improve docs for stabilization #4803

Merged
merged 5 commits into from
May 22, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions _tools/check_docs.ts
Original file line number Diff line number Diff line change
@@ -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",
36 changes: 28 additions & 8 deletions async/abortable.ts
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: It would've been nice to have a snippet title to avoid having it as "Example 1" in JSR. Ditto for other @example code snippets.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i feel like if its a single example, it being Example 1 is fine. most scenarios have only really one example that makes sense to have, and describing it will seem a bit too much. though definitively should be enforced for multiple examples

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've now added example titles to the list of checks for the doc checker. Please feel free to review #4841.

* ```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,
30 changes: 17 additions & 13 deletions async/deadline.ts
Original file line number Diff line number Diff line change
@@ -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";
*
4 changes: 3 additions & 1 deletion async/debounce.ts
Original file line number Diff line number Diff line change
@@ -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>>(
3 changes: 3 additions & 0 deletions async/delay.ts
Original file line number Diff line number Diff line change
@@ -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";
70 changes: 66 additions & 4 deletions async/mux_async_iterator.ts
Original file line number Diff line number Diff line change
@@ -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();
}
3 changes: 3 additions & 0 deletions async/pool.ts
Original file line number Diff line number Diff line change
@@ -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,
17 changes: 16 additions & 1 deletion async/retry.ts
Original file line number Diff line number Diff line change
@@ -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),
6 changes: 6 additions & 0 deletions async/tee.ts
Original file line number Diff line number Diff line change
@@ -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>,
2 changes: 1 addition & 1 deletion deno.json
Original file line number Diff line number Diff line change
@@ -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",
2 changes: 1 addition & 1 deletion webgpu/create_capture.ts
Original file line number Diff line number Diff line change
@@ -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";
*
2 changes: 1 addition & 1 deletion webgpu/texture_with_data.ts
Original file line number Diff line number Diff line change
@@ -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();