docs: jsdocs for websockets api (#29580)

Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>

cli/tsc/dts/lib.deno_websocket.d.ts

@@ -5,14 +5,52 @@
 /// <reference no-default-lib="true" />
 /// <reference lib="esnext" />
 
-/** @category WebSockets */
+/**
+ * Configuration options for a `WebSocket` "close" event.
+ *
+ * @example
+ * ```ts
+ * // Creating a custom close event with specific parameters
+ * const closeEventInit: CloseEventInit = {
+ *   code: 1000,
+ *   reason: "Normal closure",
+ *   wasClean: true,
+ * };
+ * const event = new CloseEvent("close", closeEventInit);
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/CloseEvent
+ * @category WebSockets
+ */
 interface CloseEventInit extends EventInit {
   code?: number;
   reason?: string;
   wasClean?: boolean;
 }
 
-/** @category WebSockets */
+/**
+ * The `CloseEvent` interface represents an event that occurs when a `WebSocket` connection is closed.
+ *
+ * This event is sent to the client when the connection is closed, providing information about
+ * why the connection was closed through the `code`, `reason`, and `wasClean` properties.
+ *
+ * @example
+ * ```ts
+ * // Handling a close event
+ * ws.addEventListener("close", (event: CloseEvent) => {
+ *   console.log(`Connection closed with code ${event.code}`);
+ *   console.log(`Reason: ${event.reason}`);
+ *   console.log(`Clean close: ${event.wasClean}`);
+ *
+ *   if (event.code === 1006) {
+ *     console.log("Connection closed abnormally");
+ *   }
+ * });
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent
+ * @category WebSockets
+ */
 interface CloseEvent extends Event {
   /**
    * Returns the WebSocket connection close code provided by the server.
@@ -28,13 +66,50 @@ interface CloseEvent extends Event {
   readonly wasClean: boolean;
 }
 
-/** @category WebSockets */
+/**
+ * Constructor interface for creating `CloseEvent` instances.
+ *
+ * @example
+ * ```ts
+ * // Creating a custom close event
+ * const event = new CloseEvent("close", {
+ *   code: 1000,
+ *   reason: "Normal closure",
+ *   wasClean: true,
+ * });
+ *
+ * // Dispatching the event
+ * myWebSocket.dispatchEvent(event);
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/CloseEvent
+ * @category WebSockets
+ */
 declare var CloseEvent: {
   readonly prototype: CloseEvent;
   new (type: string, eventInitDict?: CloseEventInit): CloseEvent;
 };
 
-/** @category WebSockets */
+/**
+ * Interface mapping `WebSocket` event names to their corresponding event types.
+ * Used for strongly typed event handling with `addEventListener` and `removeEventListener`.
+ *
+ * @example
+ * ```ts
+ * // Using with TypeScript for strongly-typed event handling
+ * const ws = new WebSocket("ws://localhost:8080");
+ *
+ * ws.addEventListener("open", (event) => {
+ *   console.log("Connection established");
+ * });
+ *
+ * ws.addEventListener("message", (event: MessageEvent) => {
+ *   console.log(`Received: ${event.data}`);
+ * });
+ * ```
+ *
+ * @category WebSockets
+ */
 interface WebSocketEventMap {
   close: CloseEvent;
   error: Event;
@@ -49,8 +124,31 @@ interface WebSocketEventMap {
  * If you are looking to create a WebSocket server, please take a look at
  * `Deno.upgradeWebSocket()`.
  *
- * @see https://developer.mozilla.org/docs/Web/API/WebSocket
+ * @example
+ * ```ts
+ * // Creating a WebSocket connection
+ * const ws = new WebSocket("ws://localhost:8080");
  *
+ * // Setting up event handlers
+ * ws.onopen = (event) => {
+ *   console.log("Connected to the server");
+ *   ws.send("Hello Server!");
+ * };
+ *
+ * ws.onmessage = (event) => {
+ *   console.log(`Received: ${event.data}`);
+ * };
+ *
+ * ws.onerror = (event) => {
+ *   console.error("WebSocket error observed:", event);
+ * };
+ *
+ * ws.onclose = (event) => {
+ *   console.log(`WebSocket closed: Code=${event.code}, Reason=${event.reason}`);
+ * };
+ * ```
+ *
+ * @see https://developer.mozilla.org/docs/Web/API/WebSocket
  * @tags allow-net
  * @category WebSockets
  */
@@ -149,7 +247,31 @@ interface WebSocket extends EventTarget {
   ): void;
 }
 
-/** @category WebSockets */
+/**
+ * Constructor interface for creating `WebSocket` instances.
+ *
+ * The `WebSocket` constructor creates and returns a new `WebSocket` object
+ * that represents a connection to a `WebSocket` server.
+ *
+ * @example
+ * ```ts
+ * // Basic WebSocket connection
+ * const ws = new WebSocket("ws://localhost:8080");
+ *
+ * // WebSocket with protocol specification
+ * const wsWithProtocol = new WebSocket("ws://localhost:8080", "json");
+ *
+ * // WebSocket with multiple protocol options (server will select one)
+ * const wsWithProtocols = new WebSocket("ws://localhost:8080", ["json", "xml"]);
+ *
+ * // Using URL object instead of string
+ * const url = new URL("ws://localhost:8080/path");
+ * const wsWithUrl = new WebSocket(url);
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket
+ * @category WebSockets
+ */
 declare var WebSocket: {
   readonly prototype: WebSocket;
   new (url: string | URL, protocols?: string | string[]): WebSocket;
@@ -159,5 +281,35 @@ declare var WebSocket: {
   readonly OPEN: number;
 };
 
-/** @category WebSockets */
+/**
+ * Specifies the type of binary data being received over a `WebSocket` connection.
+ *
+ * - `"blob"`: Binary data is returned as `Blob` objects
+ * - `"arraybuffer"`: Binary data is returned as `ArrayBuffer` objects
+ *
+ * @example
+ * ```ts
+ * // Setting up WebSocket for binary data as ArrayBuffer
+ * const ws = new WebSocket("ws://localhost:8080");
+ * ws.binaryType = "arraybuffer";
+ *
+ * ws.onmessage = (event) => {
+ *   if (event.data instanceof ArrayBuffer) {
+ *     // Process binary data
+ *     const view = new Uint8Array(event.data);
+ *     console.log(`Received binary data of ${view.length} bytes`);
+ *   } else {
+ *     // Process text data
+ *     console.log(`Received text: ${event.data}`);
+ *   }
+ * };
+ *
+ * // Sending binary data
+ * const binaryData = new Uint8Array([1, 2, 3, 4]);
+ * ws.send(binaryData.buffer);
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType
+ * @category WebSockets
+ */
 type BinaryType = "arraybuffer" | "blob";