docs: add category tag for built-in APIs (#15480)

9 files changed, 315 insertions, 33 deletions

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 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
+/** @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 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
+/** @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 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
+/** @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<CryptoKey>;
 }
 
+/** @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 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
+/** @category DOM APIs */
 interface DomIterable<K, V> {
   keys(): IterableIterator<K>;
   values(): IterableIterator<V>;
@@ -16,12 +17,16 @@ interface DomIterable<K, V> {
   ): 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<Uint8Array> | null;
@@ -73,6 +80,7 @@ interface Body {
   text(): Promise<string>;
 }
 
+/** @category Fetch API */
 type HeadersInit = Headers | string[][] | Record<string, string>;
 
 /** This Fetch API interface allows you to perform various actions on HTTP
@@ -81,7 +89,10 @@ type HeadersInit = Headers | string[][] | Record<string, string>;
  * 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<string, string> {
   constructor(init?: HeadersInit);
 
@@ -138,7 +150,9 @@ declare class Headers implements DomIterable<string, string> {
   [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<Uint8Array>
   | 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<string>;
 }
 
+/** @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 @@
 /// <reference lib="esnext" />
 
 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<Conn> {
     /** Waits for and resolves to the next connection to the `Listener`. */
     accept(): Promise<Conn>;
@@ -33,13 +39,17 @@ declare namespace Deno {
     [Symbol.asyncIterator](): AsyncIterableIterator<Conn>;
   }
 
-  /** Specialized listener that accepts TLS connections. */
+  /** Specialized listener that accepts TLS connections.
+   *
+   * @category Network
+   */
   export interface TlsListener extends Listener, AsyncIterable<TlsConn> {
     /** Waits for a TLS client to connect and accepts the connection. */
     accept(): Promise<TlsConn>;
     [Symbol.asyncIterator](): AsyncIterableIterator<TlsConn>;
   }
 
+  /** @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<Uint8Array>;
   }
 
+  /** @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<TlsHandshakeInfo>;
   }
 
+  /** @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<TcpConn>;
 
+  /** @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<TlsConn>;
 
+  /** @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<void>;
 }
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 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
+/** @category Web APIs */
 declare class URLSearchParams {
   constructor(
     init?: string[][] | Record<string, string> | 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<string, string>;
 }
 
-/** `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 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
+/** @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<void>;
 }
 
+/** @category DOM Events */
 interface EventListenerObject {
   handleEvent(evt: Event): void | Promise<void>;
 }
 
+/** @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
- * <img>, <audio>, <video>, <style> or <link>). */
+ * <img>, <audio>, <video>, <style> or <link>).
+ *
+ * @category DOM Events
+ */
 declare class ProgressEvent<T extends EventTarget = EventTarget> extends Event {
   constructor(type: string, eventInitDict?: ProgressEventInit);
   readonly lengthComputable: boolean;
@@ -171,6 +187,8 @@ declare class ProgressEvent<T extends EventTarget = EventTarget> extends Event {
  * ```
  * console.log(atob("aGVsbG8gd29ybGQ=")); // outputs 'hello world'
  * ```
+ *
+ * @category Encoding API
  */
 declare function atob(s: string): string;
 
@@ -179,18 +197,23 @@ declare function atob(s: string): string;
  * ```
  * console.log(btoa("hello world"));  // outputs "aGVsbG8gd29ybGQ="
  * ```
+ *
+ * @category Encoding API
  */
 declare function btoa(s: string): string;
 
+/** @category Encoding API */
 declare interface TextDecoderOptions {
   fatal?: boolean;
   ignoreBOM?: boolean;
 }
 
+/** @category Encoding API */
 declare interface TextDecodeOptions {
   stream?: boolean;
 }
 
+/** @category Encoding API */
 interface TextDecoder {
   /** Returns encoding's name, lowercased. */
   readonly encoding: string;
@@ -203,16 +226,19 @@ interface TextDecoder {
   decode(input?: BufferSource, options?: TextDecodeOptions): string;
 }
 
+/** @category Encoding API */
 declare var TextDecoder: {
   prototype: TextDecoder;
   new (label?: string, options?: TextDecoderOptions): TextDecoder;
 };
 
+/** @category Encoding API */
 declare interface TextEncoderEncodeIntoResult {
   read: number;
   written: number;
 }
 
+/** @category Encoding API */
 interface TextEncoder {
   /** Returns "utf-8". */
   readonly encoding: "utf-8";
@@ -221,11 +247,13 @@ interface TextEncoder {
   encodeInto(input: string, dest: Uint8Array): TextEncoderEncodeIntoResult;
 }
 
+/** @category Encoding API */
 declare var TextEncoder: {
   prototype: TextEncoder;
   new (): TextEncoder;
 };
 
+/** @category Encoding API */
 interface TextDecoderStream {
   /** Returns encoding's name, lowercased. */
   readonly encoding: string;
@@ -238,11 +266,13 @@ interface TextDecoderStream {
   readonly [Symbol.toStringTag]: string;
 }
 
+/** @category Encoding API */
 declare var TextDecoderStream: {
   prototype: TextDecoderStream;
   new (label?: string, options?: TextDecoderOptions): TextDecoderStream;
 };
 
+/** @category Encoding API */
 interface TextEncoderStream {
   /** Returns "utf-8". */
   readonly encoding: "utf-8";
@@ -251,13 +281,17 @@ interface TextEncoderStream {
   readonly [Symbol.toStringTag]: string;
 }
 
+/** @category Encoding API */
 declare var TextEncoderStream: {
   prototype: TextEncoderStream;
   new (): TextEncoderStream;
 };
 
 /** A controller object that allows you to abort one or more DOM requests as and
- * when desired. */
+ * when desired.
+ *
+ * @category Web APIs
+ */
 declare class AbortController {
   /** Returns the AbortSignal object associated with this object. */
   readonly signal: AbortSignal;
@@ -266,12 +300,16 @@ declare class AbortController {
   abort(reason?: any): void;
 }
 
+/** @category Web APIs */
 interface AbortSignalEventMap {
   abort: Event;
 }
 
 /** A signal object that allows you to communicate with a DOM request (such as a
- * Fetch) and abort it if required via an AbortController object. */
+ * Fetch) and abort it if required via an AbortController object.
+ *
+ * @category Web APIs
+ */
 interface AbortSignal extends EventTarget {
   /** Returns true if this AbortSignal's AbortController has signaled to abort,
    * and false otherwise. */
@@ -304,6 +342,7 @@ interface AbortSignal extends EventTarget {
   throwIfAborted(): void;
 }
 
+/** @category Web APIs */
 declare var AbortSignal: {
   prototype: AbortSignal;
   new (): AbortSignal;
@@ -311,6 +350,7 @@ declare var AbortSignal: {
   timeout(milliseconds: number): AbortSignal;
 };
 
+/** @category Web File API */
 interface FileReaderEventMap {
   "abort": ProgressEvent<FileReader>;
   "error": ProgressEvent<FileReader>;
@@ -320,7 +360,12 @@ interface FileReaderEventMap {
   "progress": ProgressEvent<FileReader>;
 }
 
-/** Lets web applications asynchronously read the contents of files (or raw data buffers) stored on the user's computer, using File or Blob objects to specify the file or data to read. */
+/** Lets web applications asynchronously read the contents of files (or raw data
+ * buffers) stored on the user's computer, using File or Blob objects to specify
+ * the file or data to read.
+ *
+ * @category Web File API
+ */
 interface FileReader extends EventTarget {
   readonly error: DOMException | null;
   onabort: ((this: FileReader, ev: ProgressEvent<FileReader>) => any) | null;
@@ -363,6 +408,7 @@ interface FileReader extends EventTarget {
   ): void;
 }
 
+/** @category Web File API */
 declare var FileReader: {
   prototype: FileReader;
   new (): FileReader;
@@ -371,14 +417,22 @@ declare var FileReader: {
   readonly LOADING: number;
 };
 
+/** @category Web File API */
 type BlobPart = BufferSource | Blob | string;
 
+/** @category Web File API */
 interface BlobPropertyBag {
   type?: string;
   endings?: "transparent" | "native";
 }
 
-/** A file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The File interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system. */
+/** A file-like object of immutable, raw data. Blobs represent data that isn't
+ * necessarily in a JavaScript-native format. The File interface is based on
+ * Blob, inheriting blob functionality and expanding it to support files on the
+ * user's system.
+ *
+ * @category Web File API
+ */
 declare class Blob {
   constructor(blobParts?: BlobPart[], options?: BlobPropertyBag);
 
@@ -390,12 +444,16 @@ declare class Blob {
   text(): Promise<string>;
 }
 
+/** @category Web File API */
 interface FilePropertyBag extends BlobPropertyBag {
   lastModified?: number;
 }
 
 /** Provides information about files and allows JavaScript in a web page to
- * access their content. */
+ * access their content.
+ *
+ * @category Web File API
+ */
 declare class File extends Blob {
   constructor(
     fileBits: BlobPart[],
@@ -407,20 +465,24 @@ declare class File extends Blob {
   readonly name: string;
 }
 
+/** @category Streams API */
 interface ReadableStreamReadDoneResult<T> {
   done: true;
   value?: T;
 }
 
+/** @category Streams API */
 interface ReadableStreamReadValueResult<T> {
   done: false;
   value: T;
 }
 
+/** @category Streams API */
 type ReadableStreamReadResult<T> =
   | ReadableStreamReadValueResult<T>
   | ReadableStreamReadDoneResult<T>;
 
+/** @category Streams API */
 interface ReadableStreamDefaultReader<R = any> {
   readonly closed: Promise<void>;
   cancel(reason?: any): Promise<void>;
@@ -428,20 +490,24 @@ interface ReadableStreamDefaultReader<R = any> {
   releaseLock(): void;
 }
 
+/** @category Streams API */
 interface ReadableStreamBYOBReadDoneResult<V extends ArrayBufferView> {
   done: true;
   value?: V;
 }
 
+/** @category Streams API */
 interface ReadableStreamBYOBReadValueResult<V extends ArrayBufferView> {
   done: false;
   value: V;
 }
 
+/** @category Streams API */
 type ReadableStreamBYOBReadResult<V extends ArrayBufferView> =
   | ReadableStreamBYOBReadDoneResult<V>
   | ReadableStreamBYOBReadValueResult<V>;
 
+/** @category Streams API */
 interface ReadableStreamBYOBReader {
   readonly closed: Promise<void>;
   cancel(reason?: any): Promise<void>;
@@ -451,32 +517,38 @@ interface ReadableStreamBYOBReader {
   releaseLock(): void;
 }
 
+/** @category Streams API */
 interface ReadableStreamBYOBRequest {
   readonly view: ArrayBufferView | null;
   respond(bytesWritten: number): void;
   respondWithNewView(view: ArrayBufferView): void;
 }
 
+/** @category Streams API */
 declare var ReadableStreamDefaultReader: {
   prototype: ReadableStreamDefaultReader;
   new <R>(stream: ReadableStream<R>): ReadableStreamDefaultReader<R>;
 };
 
+/** @category Streams API */
 interface ReadableStreamReader<R = any> {
   cancel(): Promise<void>;
   read(): Promise<ReadableStreamReadResult<R>>;
   releaseLock(): void;
 }
 
+/** @category Streams API */
 declare var ReadableStreamReader: {
   prototype: ReadableStreamReader;
   new (): ReadableStreamReader;
 };
 
+/** @category Streams API */
 interface ReadableByteStreamControllerCallback {
   (controller: ReadableByteStreamController): void | PromiseLike<void>;
 }
 
+/** @category Streams API */
 interface UnderlyingByteSource {
   autoAllocateChunkSize?: number;
   cancel?: ReadableStreamErrorCallback;
@@ -485,6 +557,7 @@ interface UnderlyingByteSource {
   type: "bytes";
 }
 
+/** @category Streams API */
 interface UnderlyingSink<W = any> {
   abort?: WritableStreamErrorCallback;
   close?: WritableStreamDefaultControllerCloseCallback;
@@ -493,6 +566,7 @@ interface UnderlyingSink<W = any> {
   write?: WritableStreamDefaultControllerWriteCallback<W>;
 }
 
+/** @category Streams API */
 interface UnderlyingSource<R = any> {
   cancel?: ReadableStreamErrorCallback;
   pull?: ReadableStreamDefaultControllerCallback<R>;
@@ -500,14 +574,17 @@ interface UnderlyingSource<R = any> {
   type?: undefined;
 }
 
+/** @category Streams API */
 interface ReadableStreamErrorCallback {
   (reason: any): void | PromiseLike<void>;
 }
 
+/** @category Streams API */
 interface ReadableStreamDefaultControllerCallback<R> {
   (controller: ReadableStreamDefaultController<R>): void | PromiseLike<void>;
 }
 
+/** @category Streams API */
 interface ReadableStreamDefaultController<R = any> {
   readonly desiredSize: number | null;
   close(): void;
@@ -515,11 +592,13 @@ interface ReadableStreamDefaultController<R = any> {
   error(error?: any): void;
 }
 
+/** @category Streams API */
 declare var ReadableStreamDefaultController: {
   prototype: ReadableStreamDefaultController;
   new (): ReadableStreamDefaultController;
 };
 
+/** @category Streams API */
 interface ReadableByteStreamController {
   readonly byobRequest: ReadableStreamBYOBRequest | null;
   readonly desiredSize: number | null;
@@ -528,11 +607,13 @@ interface ReadableByteStreamController {
   error(error?: any): void;
 }
 
+/** @category Streams API */
 declare var ReadableByteStreamController: {
   prototype: ReadableByteStreamController;
   new (): ReadableByteStreamController;
 };
 
+/** @category Streams API */
 interface PipeOptions {
   preventAbort?: boolean;
   preventCancel?: boolean;
@@ -540,32 +621,40 @@ interface PipeOptions {
   signal?: AbortSignal;
 }
 
+/** @category Streams API */
 interface QueuingStrategySizeCallback<T = any> {
   (chunk: T): number;
 }
 
+/** @category Streams API */
 interface QueuingStrategy<T = any> {
   highWaterMark?: number;
   size?: QueuingStrategySizeCallback<T>;
 }
 
 /** This Streams API interface provides a built-in byte length queuing strategy
- * that can be used when constructing streams. */
+ * that can be used when constructing streams.
+ *
+ * @category Streams API
+ */
 interface CountQueuingStrategy extends QueuingStrategy {
   highWaterMark: number;
   size(chunk: any): 1;
 }
 
+/** @category Streams API */
 declare var CountQueuingStrategy: {
   prototype: CountQueuingStrategy;
   new (options: { highWaterMark: number }): CountQueuingStrategy;
 };
 
+/** @category Streams API */
 interface ByteLengthQueuingStrategy extends QueuingStrategy<ArrayBufferView> {
   highWaterMark: number;
   size(chunk: ArrayBufferView): number;
 }
 
+/** @category Streams API */
 declare var ByteLengthQueuingStrategy: {
   prototype: ByteLengthQueuingStrategy;
   new (options: { highWaterMark: number }): ByteLengthQueuingStrategy;
@@ -573,7 +662,10 @@ declare var ByteLengthQueuingStrategy: {
 
 /** This Streams API interface represents a readable stream of byte data. The
  * Fetch API offers a concrete instance of a ReadableStream through the body
- * property of a Response object. */
+ * property of a Response object.
+ *
+ * @category Streams API
+ */
 interface ReadableStream<R = any> {
   readonly locked: boolean;
   cancel(reason?: any): Promise<void>;
@@ -593,6 +685,7 @@ interface ReadableStream<R = any> {
   }): AsyncIterableIterator<R>;
 }
 
+/** @category Streams API */
 declare var ReadableStream: {
   prototype: ReadableStream;
   new (
@@ -605,14 +698,17 @@ declare var ReadableStream: {
   ): ReadableStream<R>;
 };
 
+/** @category Streams API */
 interface WritableStreamDefaultControllerCloseCallback {
   (): void | PromiseLike<void>;
 }
 
+/** @category Streams API */
 interface WritableStreamDefaultControllerStartCallback {
   (controller: WritableStreamDefaultController): void | PromiseLike<void>;
 }
 
+/** @category Streams API */
 interface WritableStreamDefaultControllerWriteCallback<W> {
   (chunk: W, controller: WritableStreamDefaultController):
     | void
@@ -621,13 +717,17 @@ interface WritableStreamDefaultControllerWriteCallback<W> {
     >;
 }
 
+/** @category Streams API */
 interface WritableStreamErrorCallback {
   (reason: any): void | PromiseLike<void>;
 }
 
 /** This Streams API interface provides a standard abstraction for writing
  * streaming data to a destination, known as a sink. This object comes with
- * built-in backpressure and queuing. */
+ * built-in backpressure and queuing.
+ *
+ * @category Streams API
+ */
 interface WritableStream<W = any> {
   readonly locked: boolean;
   abort(reason?: any): Promise<void>;
@@ -635,6 +735,7 @@ interface WritableStream<W = any> {
   getWriter(): WritableStreamDefaultWriter<W>;
 }
 
+/** @category Streams API */
 declare var WritableStream: {
   prototype: WritableStream;
   new <W = any>(
@@ -646,18 +747,25 @@ declare var WritableStream: {
 /** This Streams API interface represents a controller allowing control of a
  * WritableStream's state. When constructing a WritableStream, the underlying
  * sink is given a corresponding WritableStreamDefaultController instance to
- * manipulate. */
+ * manipulate.
+ *
+ * @category Streams API
+ */
 interface WritableStreamDefaultController {
   signal: AbortSignal;
   error(error?: any): void;
 }
 
+/** @category Streams API */
 declare var WritableStreamDefaultController: WritableStreamDefaultController;
 
 /** This Streams API interface is the object returned by
  * WritableStream.getWriter() and once created locks the < writer to the
  * WritableStream ensuring that no other streams can write to the underlying
- * sink. */
+ * sink.
+ *
+ * @category Streams API
+ */
 interface WritableStreamDefaultWriter<W = any> {
   readonly closed: Promise<void>;
   readonly desiredSize: number | null;
@@ -668,16 +776,19 @@ interface WritableStreamDefaultWriter<W = any> {
   write(chunk: W): Promise<void>;
 }
 
+/** @category Streams API */
 declare var WritableStreamDefaultWriter: {
   prototype: WritableStreamDefaultWriter;
   new (): WritableStreamDefaultWriter;
 };
 
+/** @category Streams API */
 interface TransformStream<I = any, O = any> {
   readonly readable: ReadableStream<O>;
   readonly writable: WritableStream<I>;
 }
 
+/** @category Streams API */
 declare var TransformStream: {
   prototype: TransformStream;
   new <I = any, O = any>(
@@ -687,6 +798,7 @@ declare var TransformStream: {
   ): TransformStream<I, O>;
 };
 
+/** @category Streams API */
 interface TransformStreamDefaultController<O = any> {
   readonly desiredSize: number | null;
   enqueue(chunk: O): void;
@@ -694,8 +806,10 @@ interface TransformStreamDefaultController<O = any> {
   terminate(): void;
 }
 
+/** @category Streams API */
 declare var TransformStreamDefaultController: TransformStreamDefaultController;
 
+/** @category Streams API */
 interface Transformer<I = any, O = any> {
   flush?: TransformStreamDefaultControllerCallback<O>;
   readableType?: undefined;
@@ -704,10 +818,12 @@ interface Transformer<I = any, O = any> {
   writableType?: undefined;
 }
 
+/** @category Streams API */
 interface TransformStreamDefaultControllerCallback<O> {
   (controller: TransformStreamDefaultController<O>): void | PromiseLike<void>;
 }
 
+/** @category Streams API */
 interface TransformStreamDefaultControllerTransformCallback<I, O> {
   (
     chunk: I,
@@ -715,12 +831,14 @@ interface TransformStreamDefaultControllerTransformCallback<I, O> {
   ): void | PromiseLike<void>;
 }
 
+/** @category Streams API */
 interface MessageEventInit<T = any> extends EventInit {
   data?: T;
   origin?: string;
   lastEventId?: string;
 }
 
+/** @category Streams API */
 declare class MessageEvent<T = any> extends Event {
   /**
    * Returns the data of the message.
@@ -740,26 +858,32 @@ declare class MessageEvent<T = any> extends Event {
 type Transferable = ArrayBuffer | MessagePort;
 
 /**
- * @deprecated
- *
  * This type has been renamed to StructuredSerializeOptions. Use that type for
  * new code.
+ *
+ * @deprecated use `StructuredSerializeOptions` instead.
+ * @category DOM APIs
  */
 type PostMessageOptions = StructuredSerializeOptions;
 
+/** @category DOM APIs */
 interface StructuredSerializeOptions {
   transfer?: Transferable[];
 }
 
 /** The MessageChannel interface of the Channel Messaging API allows us to
  * create a new message channel and send data through it via its two MessagePort
- * properties. */
+ * properties.
+ *
+ * @category DOM APIs
+ */
 declare class MessageChannel {
   constructor();
   readonly port1: MessagePort;
   readonly port2: MessagePort;
 }
 
+/** @category DOM APIs */
 interface MessagePortEventMap {
   "message": MessageEvent;
   "messageerror": MessageEvent;
@@ -767,7 +891,10 @@ interface MessagePortEventMap {
 
 /** The MessagePort interface of the Channel Messaging API represents one of the
  * two ports of a MessageChannel, allowing messages to be sent from one port and
- * listening out for them arriving at the other. */
+ * listening out for them arriving at the other.
+ *
+ * @category DOM APIs
+ */
 declare class MessagePort extends EventTarget {
   onmessage: ((this: MessagePort, ev: MessageEvent) => any) | null;
   onmessageerror: ((this: MessagePort, ev: MessageEvent) => any) | null;
@@ -836,6 +963,8 @@ declare class MessagePort extends EventTarget {
  * // shallowCopy.x is pointing to the same location in memory as object.x
  * console.log(shallowCopy.x, object.x); // 1 1
  * ```
+ *
+ * @category DOM APIs
  */
 declare function structuredClone(
   value: any,
@@ -851,6 +980,8 @@ declare function structuredClone(
  *   .pipeThrough(new CompressionStream("gzip"))
  *   .pipeTo(Deno.stdout.writable);
  * ```
+ *
+ * @category Compression Streams API
  */
 declare class CompressionStream {
   /**
@@ -878,6 +1009,8 @@ declare class CompressionStream {
  *   .pipeThrough(new DecompressionStream("gzip"))
  *   .pipeTo(output.writable);
  * ```
+ *
+ * @category Compression Streams API
  */
 declare class DecompressionStream {
   /**
@@ -907,6 +1040,8 @@ declare class DecompressionStream {
  * reportError(new Error("foo")); // Will not be reported.
  * ```
  * In Deno, this error will terminate the process if not intercepted like above.
+ *
+ * @category Web APIs
  */
 declare function reportError(
   error: any,
diff --git a/ext/websocket/lib.deno_websocket.d.ts b/ext/websocket/lib.deno_websocket.d.ts
index 70d0bd61d..537eabf21 100644
--- a/ext/websocket/lib.deno_websocket.d.ts
+++ b/ext/websocket/lib.deno_websocket.d.ts
@@ -5,12 +5,14 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
+/** @category Web Sockets */
 interface CloseEventInit extends EventInit {
   code?: number;
   reason?: string;
   wasClean?: boolean;
 }
 
+/** @category Web Sockets */
 declare class CloseEvent extends Event {
   constructor(type: string, eventInitDict?: CloseEventInit);
   /**
@@ -27,6 +29,7 @@ declare class CloseEvent extends Event {
   readonly wasClean: boolean;
 }
 
+/** @category Web Sockets */
 interface WebSocketEventMap {
   close: CloseEvent;
   error: Event;
@@ -35,9 +38,13 @@ interface WebSocketEventMap {
 }
 
 /**
- * Provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.
+ * Provides the API for creating and managing a WebSocket connection to a
+ * server, as well as for sending and receiving data on the connection.
  *
- * If you are looking to create a WebSocket server, please take a look at `Deno.upgradeWebSocket()`.
+ * If you are looking to create a WebSocket server, please take a look at
+ * `Deno.upgradeWebSocket()`.
+ *
+ * @category Web Sockets
  */
 declare class WebSocket extends EventTarget {
   constructor(url: string | URL, protocols?: string | string[]);
@@ -113,4 +120,5 @@ declare class WebSocket extends EventTarget {
   ): void;
 }
 
+/** @category Web Sockets */
 type BinaryType = "arraybuffer" | "blob";
diff --git a/ext/webstorage/lib.deno_webstorage.d.ts b/ext/webstorage/lib.deno_webstorage.d.ts
index 1b87c5ff8..14a34187f 100644
--- a/ext/webstorage/lib.deno_webstorage.d.ts
+++ b/ext/webstorage/lib.deno_webstorage.d.ts
@@ -5,7 +5,12 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
-/** This Web Storage API interface provides access to a particular domain's session or local storage. It allows, for example, the addition, modification, or deletion of stored data items. */
+/** This Web Storage API interface provides access to a particular domain's
+ * session or local storage. It allows, for example, the addition, modification,
+ * or deletion of stored data items.
+ *
+ * @category Web Storage API
+ */
 interface Storage {
   /**
    * Returns the number of key/value pairs currently present in the list associated with the object.
@@ -36,6 +41,7 @@ interface Storage {
   [name: string]: any;
 }
 
+/** @category Web Storage API */
 declare var Storage: {
   prototype: Storage;
   new (): Storage;