From f445244d5f31389479409a675d9af29cf1ddf94b Mon Sep 17 00:00:00 2001 From: Jo Franchetti Date: Tue, 25 Jun 2024 14:52:12 +0100 Subject: [PATCH] adding explanations to interfaces and functions that dont have them --- ext/cache/lib.deno_cache.d.ts | 26 ++++++++--- ext/console/lib.deno_console.d.ts | 6 ++- ext/url/lib.deno_url.d.ts | 14 ++++-- ext/web/lib.deno_web.d.ts | 74 +++++++++++++++++-------------- 4 files changed, 77 insertions(+), 43 deletions(-) diff --git a/ext/cache/lib.deno_cache.d.ts b/ext/cache/lib.deno_cache.d.ts index f28de94cee..df0088008e 100644 --- a/ext/cache/lib.deno_cache.d.ts +++ b/ext/cache/lib.deno_cache.d.ts @@ -5,10 +5,21 @@ /// /// -/** @category Cache */ +/** Returns the CacheStorage object + * associated with the current context. + * + * @category Cache + */ declare var caches: CacheStorage; -/** @category Cache */ +/** Represents the storage for Cache objects. + * The interface maintains a mapping of string names to corresponding + * Cache *objects. + * + * Use CacheStorage.open() to obtain a Cache instance. + * + * @category Cache + */ declare interface CacheStorage { /** Open a cache storage for the provided name. */ open(cacheName: string): Promise; @@ -18,7 +29,12 @@ declare interface CacheStorage { delete(cacheName: string): Promise; } -/** @category Cache */ +/** + * Provides a persistent storage mechanism for Request / Response object pairs + * that are cached in long lived memory. + * + * @category Cache + */ declare interface Cache { /** * Put the provided request/response into the cache. @@ -55,13 +71,13 @@ declare interface Cache { /** @category Cache */ declare var Cache: { readonly prototype: Cache; - new (): never; + new(): never; }; /** @category Cache */ declare var CacheStorage: { readonly prototype: CacheStorage; - new (): never; + new(): never; }; /** @category Cache */ diff --git a/ext/console/lib.deno_console.d.ts b/ext/console/lib.deno_console.d.ts index a4968dc836..79324403ce 100644 --- a/ext/console/lib.deno_console.d.ts +++ b/ext/console/lib.deno_console.d.ts @@ -5,7 +5,11 @@ /// /// -/** @category I/O */ +/** Provides access to the debugging console. + * The specific set of available methods are determined by the environment in + * which the script is running. + * + * @category I/O */ declare interface Console { assert(condition?: boolean, ...data: any[]): void; clear(): void; diff --git a/ext/url/lib.deno_url.d.ts b/ext/url/lib.deno_url.d.ts index ca5b00e607..7f52a54f04 100644 --- a/ext/url/lib.deno_url.d.ts +++ b/ext/url/lib.deno_url.d.ts @@ -5,7 +5,13 @@ /// /// -/** @category URL */ +/** Defines utility methods to work with the + * query string of a URL. An object implementing URLSearchParams can directly + * be used in a `for...of` structure to iterate over key/value pairs in the + * same order as they appear in the query string + * + * @category URL + */ declare interface URLSearchParams { /** Appends a specified key/value pair as a new search parameter. * @@ -160,7 +166,7 @@ declare interface URLSearchParams { /** @category URL */ declare var URLSearchParams: { readonly prototype: URLSearchParams; - new ( + new( init?: Iterable | Record | string, ): URLSearchParams; }; @@ -194,7 +200,7 @@ declare interface URL { */ declare var URL: { readonly prototype: URL; - new (url: string | URL, base?: string | URL): URL; + new(url: string | URL, base?: string | URL): URL; parse(url: string | URL, base?: string | URL): URL | null; canParse(url: string | URL, base?: string | URL): boolean; createObjectURL(blob: Blob): string; @@ -377,5 +383,5 @@ declare interface URLPattern { */ declare var URLPattern: { readonly prototype: URLPattern; - new (input: URLPatternInput, baseURL?: string): URLPattern; + new(input: URLPatternInput, baseURL?: string): URLPattern; }; diff --git a/ext/web/lib.deno_web.d.ts b/ext/web/lib.deno_web.d.ts index 36c77ef818..50f1037e47 100644 --- a/ext/web/lib.deno_web.d.ts +++ b/ext/web/lib.deno_web.d.ts @@ -40,7 +40,7 @@ declare interface DOMException extends Error { /** @category Platform */ declare var DOMException: { readonly prototype: DOMException; - new (message?: string, name?: string): DOMException; + new(message?: string, name?: string): DOMException; readonly INDEX_SIZE_ERR: 1; readonly DOMSTRING_SIZE_ERR: 2; readonly HIERARCHY_REQUEST_ERR: 3; @@ -68,7 +68,10 @@ declare var DOMException: { readonly DATA_CLONE_ERR: 25; }; -/** @category Events */ +/** Specifies the options that can be passed to the constructor of an `Event` + * object. The EventInit interface defines three optional properties: `bubbles`, `cancelable`, and `composed`. + * + * @category Events */ declare interface EventInit { bubbles?: boolean; cancelable?: boolean; @@ -142,7 +145,7 @@ declare interface Event { */ declare var Event: { readonly prototype: Event; - new (type: string, eventInitDict?: EventInit): Event; + new(type: string, eventInitDict?: EventInit): Event; readonly AT_TARGET: number; readonly BUBBLING_PHASE: number; readonly CAPTURING_PHASE: number; @@ -205,15 +208,20 @@ declare interface EventTarget { */ declare var EventTarget: { readonly prototype: EventTarget; - new (): EventTarget; + new(): EventTarget; }; -/** @category Events */ +/** Represents a function type that can be used as an event listener in various + * contexts. Functions matching this type must accept a single parameter, `evt`. + * + * @category Events */ declare interface EventListener { (evt: Event): void | Promise; } -/** @category Events */ +/** EventListenerObject interface defines objects that can handle events + * + * @category Events */ declare interface EventListenerObject { handleEvent(evt: Event): void | Promise; } @@ -264,7 +272,7 @@ declare interface ProgressEvent */ declare var ProgressEvent: { readonly prototype: ProgressEvent; - new (type: string, eventInitDict?: ProgressEventInit): ProgressEvent; + new(type: string, eventInitDict?: ProgressEventInit): ProgressEvent; }; /** Decodes a string of data which has been encoded using base-64 encoding. @@ -314,7 +322,7 @@ declare interface TextDecoder { /** @category Encoding */ declare var TextDecoder: { readonly prototype: TextDecoder; - new (label?: string, options?: TextDecoderOptions): TextDecoder; + new(label?: string, options?: TextDecoderOptions): TextDecoder; }; /** @category Encoding */ @@ -335,7 +343,7 @@ declare interface TextEncoder { /** @category Encoding */ declare var TextEncoder: { readonly prototype: TextEncoder; - new (): TextEncoder; + new(): TextEncoder; }; /** @category Encoding */ @@ -354,7 +362,7 @@ declare interface TextDecoderStream { /** @category Encoding */ declare var TextDecoderStream: { readonly prototype: TextDecoderStream; - new (label?: string, options?: TextDecoderOptions): TextDecoderStream; + new(label?: string, options?: TextDecoderOptions): TextDecoderStream; }; /** @category Encoding */ @@ -369,7 +377,7 @@ declare interface TextEncoderStream { /** @category Encoding */ declare var TextEncoderStream: { readonly prototype: TextEncoderStream; - new (): TextEncoderStream; + new(): TextEncoderStream; }; /** A controller object that allows you to abort one or more DOM requests as and @@ -392,7 +400,7 @@ declare interface AbortController { */ declare var AbortController: { readonly prototype: AbortController; - new (): AbortController; + new(): AbortController; }; /** @category Platform */ @@ -440,7 +448,7 @@ declare interface AbortSignal extends EventTarget { /** @category Platform */ declare var AbortSignal: { readonly prototype: AbortSignal; - new (): never; + new(): never; abort(reason?: any): AbortSignal; any(signals: AbortSignal[]): AbortSignal; timeout(milliseconds: number): AbortSignal; @@ -469,8 +477,8 @@ declare interface FileReader extends EventTarget { onload: ((this: FileReader, ev: ProgressEvent) => any) | null; onloadend: ((this: FileReader, ev: ProgressEvent) => any) | null; onloadstart: - | ((this: FileReader, ev: ProgressEvent) => any) - | null; + | ((this: FileReader, ev: ProgressEvent) => any) + | null; onprogress: ((this: FileReader, ev: ProgressEvent) => any) | null; readonly readyState: number; readonly result: string | ArrayBuffer | null; @@ -507,7 +515,7 @@ declare interface FileReader extends EventTarget { /** @category File */ declare var FileReader: { readonly prototype: FileReader; - new (): FileReader; + new(): FileReader; readonly DONE: number; readonly EMPTY: number; readonly LOADING: number; @@ -547,7 +555,7 @@ declare interface Blob { */ declare var Blob: { readonly prototype: Blob; - new (blobParts?: BlobPart[], options?: BlobPropertyBag): Blob; + new(blobParts?: BlobPart[], options?: BlobPropertyBag): Blob; }; /** @category File */ @@ -572,7 +580,7 @@ declare interface File extends Blob { */ declare var File: { readonly prototype: File; - new (fileBits: BlobPart[], fileName: string, options?: FilePropertyBag): File; + new(fileBits: BlobPart[], fileName: string, options?: FilePropertyBag): File; }; /** @category Streams */ @@ -642,7 +650,7 @@ declare interface ReadableStreamBYOBReader { /** @category Streams */ declare var ReadableStreamBYOBReader: { readonly prototype: ReadableStreamBYOBReader; - new (stream: ReadableStream): ReadableStreamBYOBReader; + new(stream: ReadableStream): ReadableStreamBYOBReader; }; /** @category Streams */ @@ -655,7 +663,7 @@ declare interface ReadableStreamBYOBRequest { /** @category Streams */ declare var ReadableStreamBYOBRequest: { readonly prototype: ReadableStreamBYOBRequest; - new (): never; + new(): never; }; /** @category Streams */ @@ -710,7 +718,7 @@ declare interface ReadableStreamDefaultController { /** @category Streams */ declare var ReadableStreamDefaultController: { readonly prototype: ReadableStreamDefaultController; - new (): never; + new(): never; }; /** @category Streams */ @@ -725,7 +733,7 @@ declare interface ReadableByteStreamController { /** @category Streams */ declare var ReadableByteStreamController: { readonly prototype: ReadableByteStreamController; - new (): never; + new(): never; }; /** @category Streams */ @@ -760,7 +768,7 @@ declare interface CountQueuingStrategy extends QueuingStrategy { /** @category Streams */ declare var CountQueuingStrategy: { readonly prototype: CountQueuingStrategy; - new (options: { highWaterMark: number }): CountQueuingStrategy; + new(options: { highWaterMark: number }): CountQueuingStrategy; }; /** @category Streams */ @@ -773,7 +781,7 @@ declare interface ByteLengthQueuingStrategy /** @category Streams */ declare var ByteLengthQueuingStrategy: { readonly prototype: ByteLengthQueuingStrategy; - new (options: { highWaterMark: number }): ByteLengthQueuingStrategy; + new(options: { highWaterMark: number }): ByteLengthQueuingStrategy; }; /** This Streams API interface represents a readable stream of byte data. The @@ -804,7 +812,7 @@ declare interface ReadableStream { /** @category Streams */ declare var ReadableStream: { readonly prototype: ReadableStream; - new ( + new( underlyingSource: UnderlyingByteSource, strategy?: { highWaterMark?: number; size?: undefined }, ): ReadableStream; @@ -878,7 +886,7 @@ declare interface WritableStreamDefaultController { /** @category Streams */ declare var WritableStreamDefaultController: { readonly prototype: WritableStreamDefaultController; - new (): never; + new(): never; }; /** This Streams API interface is the object returned by @@ -931,7 +939,7 @@ declare interface TransformStreamDefaultController { /** @category Streams */ declare var TransformStreamDefaultController: { readonly prototype: TransformStreamDefaultController; - new (): never; + new(): never; }; /** @category Streams */ @@ -1027,7 +1035,7 @@ declare interface MessageChannel { */ declare var MessageChannel: { readonly prototype: MessageChannel; - new (): MessageChannel; + new(): MessageChannel; }; /** @category Messaging */ @@ -1094,7 +1102,7 @@ declare interface MessagePort extends EventTarget { */ declare var MessagePort: { readonly prototype: MessagePort; - new (): never; + new(): never; }; /** @@ -1167,7 +1175,7 @@ declare var CompressionStream: { * Throws a `TypeError` if the format passed to the constructor is not * supported. */ - new (format: string): CompressionStream; + new(format: string): CompressionStream; }; /** @@ -1214,7 +1222,7 @@ declare var DecompressionStream: { * Throws a `TypeError` if the format passed to the constructor is not * supported. */ - new (format: string): DecompressionStream; + new(format: string): DecompressionStream; }; /** Dispatch an uncaught exception. Similar to a synchronous version of: @@ -1257,8 +1265,8 @@ declare interface ImageData { /** @category Platform */ declare var ImageData: { prototype: ImageData; - new (sw: number, sh: number, settings?: ImageDataSettings): ImageData; - new ( + new(sw: number, sh: number, settings?: ImageDataSettings): ImageData; + new( data: Uint8ClampedArray, sw: number, sh?: number,