From a2ab5eee015b1dafc1a18cd2bc5f5c5756123d74 Mon Sep 17 00:00:00 2001 From: Kitson Kelly Date: Wed, 17 Aug 2022 13:12:24 +1000 Subject: docs: add category tag for built-in APIs (#15480) --- .../lib.deno_broadcast_channel.d.ts | 3 + ext/console/lib.deno_console.d.ts | 1 + ext/crypto/lib.deno_crypto.d.ts | 57 ++++++- ext/fetch/lib.deno_fetch.d.ts | 39 ++++- ext/net/lib.deno_net.d.ts | 44 +++++- ext/url/lib.deno_url.d.ts | 17 ++- ext/web/lib.deno_web.d.ts | 167 +++++++++++++++++++-- ext/websocket/lib.deno_websocket.d.ts | 12 +- ext/webstorage/lib.deno_webstorage.d.ts | 8 +- 9 files changed, 315 insertions(+), 33 deletions(-) (limited to 'ext') diff --git a/ext/broadcast_channel/lib.deno_broadcast_channel.d.ts b/ext/broadcast_channel/lib.deno_broadcast_channel.d.ts index 31df18363..ea415b30a 100644 --- a/ext/broadcast_channel/lib.deno_broadcast_channel.d.ts +++ b/ext/broadcast_channel/lib.deno_broadcast_channel.d.ts @@ -5,11 +5,13 @@ /// /// +/** @category Broadcast Channel */ interface BroadcastChannelEventMap { "message": MessageEvent; "messageerror": MessageEvent; } +/** @category Broadcast Channel */ interface BroadcastChannel extends EventTarget { /** * Returns the channel name (as passed to the constructor). @@ -49,6 +51,7 @@ interface BroadcastChannel extends EventTarget { ): void; } +/** @category Broadcast Channel */ declare var BroadcastChannel: { prototype: BroadcastChannel; new (name: string): BroadcastChannel; diff --git a/ext/console/lib.deno_console.d.ts b/ext/console/lib.deno_console.d.ts index e179ffd4d..ef2dc1cca 100644 --- a/ext/console/lib.deno_console.d.ts +++ b/ext/console/lib.deno_console.d.ts @@ -5,6 +5,7 @@ /// /// +/** @category Console and Debugging */ declare interface Console { assert(condition?: boolean, ...data: any[]): void; clear(): void; diff --git a/ext/crypto/lib.deno_crypto.d.ts b/ext/crypto/lib.deno_crypto.d.ts index f5d06156d..d83be6b24 100644 --- a/ext/crypto/lib.deno_crypto.d.ts +++ b/ext/crypto/lib.deno_crypto.d.ts @@ -5,19 +5,26 @@ /// /// +/** @category Web Crypto API */ declare var crypto: Crypto; +/** @category Web Crypto API */ interface Algorithm { name: string; } +/** @category Web Crypto API */ interface KeyAlgorithm { name: string; } +/** @category Web Crypto API */ type AlgorithmIdentifier = string | Algorithm; +/** @category Web Crypto API */ type HashAlgorithmIdentifier = AlgorithmIdentifier; +/** @category Web Crypto API */ type KeyType = "private" | "public" | "secret"; +/** @category Web Crypto API */ type KeyUsage = | "decrypt" | "deriveBits" @@ -27,15 +34,19 @@ type KeyUsage = | "unwrapKey" | "verify" | "wrapKey"; +/** @category Web Crypto API */ type KeyFormat = "jwk" | "pkcs8" | "raw" | "spki"; +/** @category Web Crypto API */ type NamedCurve = string; +/** @category Web Crypto API */ interface RsaOtherPrimesInfo { d?: string; r?: string; t?: string; } +/** @category Web Crypto API */ interface JsonWebKey { alg?: string; crv?: string; @@ -58,111 +69,138 @@ interface JsonWebKey { y?: string; } +/** @category Web Crypto API */ interface AesCbcParams extends Algorithm { iv: BufferSource; } +/** @category Web Crypto API */ interface AesGcmParams extends Algorithm { iv: BufferSource; additionalData?: BufferSource; tagLength?: number; } +/** @category Web Crypto API */ interface AesCtrParams extends Algorithm { counter: BufferSource; length: number; } +/** @category Web Crypto API */ interface HmacKeyGenParams extends Algorithm { hash: HashAlgorithmIdentifier; length?: number; } +/** @category Web Crypto API */ interface EcKeyGenParams extends Algorithm { namedCurve: NamedCurve; } +/** @category Web Crypto API */ interface EcKeyImportParams extends Algorithm { namedCurve: NamedCurve; } +/** @category Web Crypto API */ interface EcdsaParams extends Algorithm { hash: HashAlgorithmIdentifier; } +/** @category Web Crypto API */ interface RsaHashedImportParams extends Algorithm { hash: HashAlgorithmIdentifier; } +/** @category Web Crypto API */ interface RsaHashedKeyGenParams extends RsaKeyGenParams { hash: HashAlgorithmIdentifier; } +/** @category Web Crypto API */ interface RsaKeyGenParams extends Algorithm { modulusLength: number; publicExponent: Uint8Array; } +/** @category Web Crypto API */ interface RsaPssParams extends Algorithm { saltLength: number; } +/** @category Web Crypto API */ interface RsaOaepParams extends Algorithm { label?: Uint8Array; } +/** @category Web Crypto API */ interface HmacImportParams extends Algorithm { hash: HashAlgorithmIdentifier; length?: number; } +/** @category Web Crypto API */ interface EcKeyAlgorithm extends KeyAlgorithm { namedCurve: NamedCurve; } +/** @category Web Crypto API */ interface HmacKeyAlgorithm extends KeyAlgorithm { hash: KeyAlgorithm; length: number; } +/** @category Web Crypto API */ interface RsaHashedKeyAlgorithm extends RsaKeyAlgorithm { hash: KeyAlgorithm; } +/** @category Web Crypto API */ interface RsaKeyAlgorithm extends KeyAlgorithm { modulusLength: number; publicExponent: Uint8Array; } +/** @category Web Crypto API */ interface HkdfParams extends Algorithm { hash: HashAlgorithmIdentifier; info: BufferSource; salt: BufferSource; } +/** @category Web Crypto API */ interface Pbkdf2Params extends Algorithm { hash: HashAlgorithmIdentifier; iterations: number; salt: BufferSource; } +/** @category Web Crypto API */ interface AesDerivedKeyParams extends Algorithm { length: number; } +/** @category Web Crypto API */ interface EcdhKeyDeriveParams extends Algorithm { public: CryptoKey; } +/** @category Web Crypto API */ interface AesKeyGenParams extends Algorithm { length: number; } +/** @category Web Crypto API */ interface AesKeyAlgorithm extends KeyAlgorithm { length: number; } -/** The CryptoKey dictionary of the Web Crypto API represents a cryptographic key. */ +/** The CryptoKey dictionary of the Web Crypto API represents a cryptographic + * key. + * + * @category Web Crypto API + */ interface CryptoKey { readonly algorithm: KeyAlgorithm; readonly extractable: boolean; @@ -170,23 +208,34 @@ interface CryptoKey { readonly usages: KeyUsage[]; } +/** @category Web Crypto API */ declare var CryptoKey: { prototype: CryptoKey; new (): CryptoKey; }; -/** The CryptoKeyPair dictionary of the Web Crypto API represents a key pair for an asymmetric cryptography algorithm, also known as a public-key algorithm. */ +/** The CryptoKeyPair dictionary of the Web Crypto API represents a key pair for + * an asymmetric cryptography algorithm, also known as a public-key algorithm. + * + * @category Web Crypto API + */ interface CryptoKeyPair { privateKey: CryptoKey; publicKey: CryptoKey; } +/** @category Web Crypto API */ declare var CryptoKeyPair: { prototype: CryptoKeyPair; new (): CryptoKeyPair; }; -/** This Web Crypto API interface provides a number of low-level cryptographic functions. It is accessed via the Crypto.subtle properties available in a window context (via Window.crypto). */ +/** This Web Crypto API interface provides a number of low-level cryptographic + * functions. It is accessed via the Crypto.subtle properties available in a + * window context (via Window.crypto). + * + * @category Web Crypto API + */ interface SubtleCrypto { generateKey( algorithm: RsaHashedKeyGenParams | EcKeyGenParams, @@ -319,6 +368,7 @@ interface SubtleCrypto { ): Promise; } +/** @category Web Crypto API */ declare interface Crypto { readonly subtle: SubtleCrypto; getRandomValues< @@ -338,6 +388,7 @@ declare interface Crypto { randomUUID(): string; } +/** @category Web Crypto API */ declare var SubtleCrypto: { prototype: SubtleCrypto; new (): SubtleCrypto; diff --git a/ext/fetch/lib.deno_fetch.d.ts b/ext/fetch/lib.deno_fetch.d.ts index 79d435468..b4db4385d 100644 --- a/ext/fetch/lib.deno_fetch.d.ts +++ b/ext/fetch/lib.deno_fetch.d.ts @@ -5,6 +5,7 @@ /// /// +/** @category DOM APIs */ interface DomIterable { keys(): IterableIterator; values(): IterableIterator; @@ -16,12 +17,16 @@ interface DomIterable { ): void; } +/** @category Fetch API */ type FormDataEntryValue = File | string; /** Provides a way to easily construct a set of key/value pairs representing * form fields and their values, which can then be easily sent using the * XMLHttpRequest.send() method. It uses the same format a form would use if the - * encoding type were set to "multipart/form-data". */ + * encoding type were set to "multipart/form-data". + * + * @category Fetch API + */ interface FormData { append(name: string, value: string | Blob, fileName?: string): void; delete(name: string): void; @@ -39,11 +44,13 @@ interface FormData { ): void; } +/** @category Fetch API */ declare var FormData: { prototype: FormData; new (): FormData; }; +/** @category Fetch API */ interface Body { /** A simple getter used to expose a `ReadableStream` of the body contents. */ readonly body: ReadableStream | null; @@ -73,6 +80,7 @@ interface Body { text(): Promise; } +/** @category Fetch API */ type HeadersInit = Headers | string[][] | Record; /** This Fetch API interface allows you to perform various actions on HTTP @@ -81,7 +89,10 @@ type HeadersInit = Headers | string[][] | Record; * which is initially empty and consists of zero or more name and value pairs. * You can add to this using methods like append() (see Examples). In all * methods of this interface, header names are matched by case-insensitive byte - * sequence. */ + * sequence. + * + * @category Fetch API + */ interface Headers { append(name: string, value: string): void; delete(name: string): void; @@ -94,6 +105,7 @@ interface Headers { ): void; } +/** @category Fetch API */ declare class Headers implements DomIterable { constructor(init?: HeadersInit); @@ -138,7 +150,9 @@ declare class Headers implements DomIterable { [Symbol.iterator](): IterableIterator<[string, string]>; } +/** @category Fetch API */ type RequestInfo = Request | string; +/** @category Fetch API */ type RequestCache = | "default" | "force-cache" @@ -146,9 +160,13 @@ type RequestCache = | "no-store" | "only-if-cached" | "reload"; +/** @category Fetch API */ type RequestCredentials = "include" | "omit" | "same-origin"; +/** @category Fetch API */ type RequestMode = "cors" | "navigate" | "no-cors" | "same-origin"; +/** @category Fetch API */ type RequestRedirect = "error" | "follow" | "manual"; +/** @category Fetch API */ type ReferrerPolicy = | "" | "no-referrer" @@ -159,6 +177,7 @@ type ReferrerPolicy = | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url"; +/** @category Fetch API */ type BodyInit = | Blob | BufferSource @@ -166,6 +185,7 @@ type BodyInit = | URLSearchParams | ReadableStream | string; +/** @category Fetch API */ type RequestDestination = | "" | "audio" @@ -186,6 +206,7 @@ type RequestDestination = | "worker" | "xslt"; +/** @category Fetch API */ interface RequestInit { /** * A BodyInit object or null to set request's body. @@ -250,7 +271,10 @@ interface RequestInit { window?: any; } -/** This Fetch API interface represents a resource request. */ +/** This Fetch API interface represents a resource request. + * + * @category Fetch API + */ declare class Request implements Body { constructor(input: RequestInfo | URL, init?: RequestInit); @@ -366,12 +390,14 @@ declare class Request implements Body { text(): Promise; } +/** @category Fetch API */ interface ResponseInit { headers?: HeadersInit; status?: number; statusText?: string; } +/** @category Fetch API */ type ResponseType = | "basic" | "cors" @@ -380,7 +406,10 @@ type ResponseType = | "opaque" | "opaqueredirect"; -/** This Fetch API interface represents the response to a request. */ +/** This Fetch API interface represents the response to a request. + * + * @category Fetch API + */ declare class Response implements Body { constructor(body?: BodyInit | null, init?: ResponseInit); static json(data: unknown, init?: ResponseInit): Response; @@ -434,6 +463,8 @@ declare class Response implements Body { * console.log(response.statusText); // e.g. "OK" * const jsonData = await response.json(); * ``` + * + * @category Fetch API */ declare function fetch( input: URL | Request | string, diff --git a/ext/net/lib.deno_net.d.ts b/ext/net/lib.deno_net.d.ts index bb031f60d..25eb893d1 100644 --- a/ext/net/lib.deno_net.d.ts +++ b/ext/net/lib.deno_net.d.ts @@ -4,20 +4,26 @@ /// declare namespace Deno { + /** @category Network */ export interface NetAddr { transport: "tcp" | "udp"; hostname: string; port: number; } + /** @category Network */ export interface UnixAddr { transport: "unix" | "unixpacket"; path: string; } + /** @category Network */ export type Addr = NetAddr | UnixAddr; - /** A generic network listener for stream-oriented protocols. */ + /** A generic network listener for stream-oriented protocols. + * + * @category Network + */ export interface Listener extends AsyncIterable { /** Waits for and resolves to the next connection to the `Listener`. */ accept(): Promise; @@ -33,13 +39,17 @@ declare namespace Deno { [Symbol.asyncIterator](): AsyncIterableIterator; } - /** Specialized listener that accepts TLS connections. */ + /** Specialized listener that accepts TLS connections. + * + * @category Network + */ export interface TlsListener extends Listener, AsyncIterable { /** Waits for a TLS client to connect and accepts the connection. */ accept(): Promise; [Symbol.asyncIterator](): AsyncIterableIterator; } + /** @category Network */ export interface Conn extends Reader, Writer, Closer { /** The local address of the connection. */ readonly localAddr: Addr; @@ -55,9 +65,11 @@ declare namespace Deno { readonly writable: WritableStream; } + /** @category Network */ // deno-lint-ignore no-empty-interface export interface TlsHandshakeInfo {} + /** @category Network */ export interface TlsConn extends Conn { /** Runs the client or server handshake protocol to completion if that has * not happened yet. Calling this method is optional; the TLS handshake @@ -65,6 +77,7 @@ declare namespace Deno { handshake(): Promise; } + /** @category Network */ export interface ListenOptions { /** The port to listen on. */ port: number; @@ -87,11 +100,15 @@ declare namespace Deno { * const listener4 = Deno.listen({ hostname: "golang.org", port: 80, transport: "tcp" }); * ``` * - * Requires `allow-net` permission. */ + * Requires `allow-net` permission. + * + * @category Network + */ export function listen( options: ListenOptions & { transport?: "tcp" }, ): Listener; + /** @category Network */ export interface ListenTlsOptions extends ListenOptions { /** Server private key in PEM format */ key?: string; @@ -119,9 +136,13 @@ declare namespace Deno { * const lstnr = Deno.listenTls({ port: 443, certFile: "./server.crt", keyFile: "./server.key" }); * ``` * - * Requires `allow-net` permission. */ + * Requires `allow-net` permission. + * + * @category Network + */ export function listenTls(options: ListenTlsOptions): TlsListener; + /** @category Network */ export interface ConnectOptions { /** The port to connect to. */ port: number; @@ -142,9 +163,13 @@ declare namespace Deno { * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }); * ``` * - * Requires `allow-net` permission for "tcp". */ + * Requires `allow-net` permission for "tcp". + * + * @category Network + */ export function connect(options: ConnectOptions): Promise; + /** @category Network */ export interface TcpConn extends Conn { /** * **UNSTABLE**: new API, see https://github.com/denoland/deno/issues/13617. @@ -160,9 +185,11 @@ declare namespace Deno { setKeepAlive(keepalive?: boolean): void; } + /** @category Network */ // deno-lint-ignore no-empty-interface export interface UnixConn extends Conn {} + /** @category Network */ export interface ConnectTlsOptions { /** The port to connect to. */ port: number; @@ -197,9 +224,12 @@ declare namespace Deno { * ``` * * Requires `allow-net` permission. + * + * @category Network */ export function connectTls(options: ConnectTlsOptions): Promise; + /** @category Network */ export interface StartTlsOptions { /** A literal IP address or host name that can be resolved to an IP address. * If not specified, defaults to `127.0.0.1`. */ @@ -224,6 +254,8 @@ declare namespace Deno { * ``` * * Requires `allow-net` permission. + * + * @category Network */ export function startTls( conn: Conn, @@ -239,6 +271,8 @@ declare namespace Deno { * const conn = await listener.accept(); * Deno.shutdown(conn.rid); * ``` + * + * @category Network */ export function shutdown(rid: number): Promise; } diff --git a/ext/url/lib.deno_url.d.ts b/ext/url/lib.deno_url.d.ts index d3a51a00e..53298166b 100644 --- a/ext/url/lib.deno_url.d.ts +++ b/ext/url/lib.deno_url.d.ts @@ -5,6 +5,7 @@ /// /// +/** @category Web APIs */ declare class URLSearchParams { constructor( init?: string[][] | Record | string | URLSearchParams, @@ -151,7 +152,11 @@ declare class URLSearchParams { toString(): string; } -/** The URL interface represents an object providing static methods used for creating object URLs. */ +/** The URL interface represents an object providing static methods used for + * creating object URLs. + * + * @category Web APIs + */ declare class URL { constructor(url: string | URL, base?: string | URL); static createObjectURL(blob: Blob): string; @@ -173,6 +178,7 @@ declare class URL { toJSON(): string; } +/** @category Web APIs */ declare interface URLPatternInit { protocol?: string; username?: string; @@ -185,14 +191,19 @@ declare interface URLPatternInit { baseURL?: string; } +/** @category Web APIs */ declare type URLPatternInput = string | URLPatternInit; +/** @category Web APIs */ declare interface URLPatternComponentResult { input: string; groups: Record; } -/** `URLPatternResult` is the object returned from `URLPattern.exec`. */ +/** `URLPatternResult` is the object returned from `URLPattern.exec`. + * + * @category Web APIs + */ declare interface URLPatternResult { /** The inputs provided when matching. */ inputs: [URLPatternInit] | [URLPatternInit, string]; @@ -242,6 +253,8 @@ declare interface URLPatternResult { * console.log(pattern.test("https://blog.example.com/article")); // true * console.log(pattern.test("https://blog.example.com/article/123")); // false * ``` + * + * @category Web APIs */ declare class URLPattern { constructor(input: URLPatternInput, baseURL?: string); diff --git a/ext/web/lib.deno_web.d.ts b/ext/web/lib.deno_web.d.ts index e3fc58be0..8fd43a0c3 100644 --- a/ext/web/lib.deno_web.d.ts +++ b/ext/web/lib.deno_web.d.ts @@ -5,6 +5,7 @@ /// /// +/** @category DOM Events */ declare class DOMException extends Error { constructor(message?: string, name?: string); readonly name: string; @@ -12,13 +13,17 @@ declare class DOMException extends Error { readonly code: number; } +/** @category DOM Events */ interface EventInit { bubbles?: boolean; cancelable?: boolean; composed?: boolean; } -/** An event which takes place in the DOM. */ +/** An event which takes place in the DOM. + * + * @category DOM Events + */ declare class Event { constructor(type: string, eventInitDict?: EventInit); /** Returns true or false depending on how event was initialized. True if @@ -84,6 +89,8 @@ declare class Event { /** * EventTarget is a DOM interface implemented by objects that can receive events * and may have listeners for them. + * + * @category DOM Events */ declare class EventTarget { /** Appends an event listener for events whose type attribute value is type. @@ -127,28 +134,34 @@ declare class EventTarget { ): void; } +/** @category DOM Events */ interface EventListener { (evt: Event): void | Promise; } +/** @category DOM Events */ interface EventListenerObject { handleEvent(evt: Event): void | Promise; } +/** @category DOM Events */ declare type EventListenerOrEventListenerObject = | EventListener | EventListenerObject; +/** @category DOM Events */ interface AddEventListenerOptions extends EventListenerOptions { once?: boolean; passive?: boolean; signal?: AbortSignal; } +/** @category DOM Events */ interface EventListenerOptions { capture?: boolean; } +/** @category DOM Events */ interface ProgressEventInit extends EventInit { lengthComputable?: boolean; loaded?: number; @@ -157,7 +170,10 @@ interface ProgressEventInit extends EventInit { /** Events measuring progress of an underlying process, like an HTTP request * (for an XMLHttpRequest, or the loading of the underlying resource of an - * ,