docs: code example to `structuredClone`, `CompressionStream`, `DecompressionStream` (#13719)

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

4 files changed, 85 insertions, 13 deletions

diff --git a/cli/dts/lib.deno.ns.d.ts b/cli/dts/lib.deno.ns.d.ts
index d759bdd58..14cf2a316 100644
--- a/cli/dts/lib.deno.ns.d.ts
+++ b/cli/dts/lib.deno.ns.d.ts
@@ -2910,11 +2910,13 @@ declare namespace Deno {
    * If `pid` is negative, the signal will be sent to the process group
    * identified by `pid`.
    *
-   *      const p = Deno.run({
-   *        cmd: ["sleep", "10000"]
-   *      });
+   * ```ts
+   * const p = Deno.run({
+   *   cmd: ["sleep", "10000"]
+   * });
    *
-   *      Deno.kill(p.pid, "SIGINT");
+   * Deno.kill(p.pid, "SIGINT");
+   * ```
    *
    * Requires `allow-run` permission. */
   export function kill(pid: number, signo: Signal): void;
diff --git a/cli/dts/lib.deno.window.d.ts b/cli/dts/lib.deno.window.d.ts
index 1c8cdeae8..fbd0a967b 100644
--- a/cli/dts/lib.deno.window.d.ts
+++ b/cli/dts/lib.deno.window.d.ts
@@ -71,9 +71,11 @@ declare function prompt(message?: string, defaultValue?: string): string | null;
 /** Registers an event listener in the global scope, which will be called
  * synchronously whenever the event `type` is dispatched.
  *
- *     addEventListener('unload', () => { console.log('All finished!'); });
- *     ...
- *     dispatchEvent(new Event('unload'));
+ * ```ts
+ * addEventListener('unload', () => { console.log('All finished!'); });
+ * ...
+ * dispatchEvent(new Event('unload'));
+ * ```
  */
 declare function addEventListener(
   type: string,
@@ -83,9 +85,11 @@ declare function addEventListener(
 
 /** Remove a previously registered event listener from the global scope
  *
- *     const lstnr = () => { console.log('hello'); };
- *     addEventListener('load', lstnr);
- *     removeEventListener('load', lstnr);
+ * ```ts
+ * const listener = () => { console.log('hello'); };
+ * addEventListener('load', listener);
+ * removeEventListener('load', listener);
+ * ```
  */
 declare function removeEventListener(
   type: string,
diff --git a/ext/web/lib.deno_web.d.ts b/ext/web/lib.deno_web.d.ts
index 1233b842f..e8f7f26cd 100644
--- a/ext/web/lib.deno_web.d.ts
+++ b/ext/web/lib.deno_web.d.ts
@@ -167,13 +167,17 @@ declare class ProgressEvent<T extends EventTarget = EventTarget> extends Event {
 
 /** Decodes a string of data which has been encoded using base-64 encoding.
  *
- *     console.log(atob("aGVsbG8gd29ybGQ=")); // outputs 'hello world'
+ * ```
+ * console.log(atob("aGVsbG8gd29ybGQ=")); // outputs 'hello world'
+ * ```
  */
 declare function atob(s: string): string;
 
 /** Creates a base-64 ASCII encoded string from the input string.
  *
- *     console.log(btoa("hello world"));  // outputs "aGVsbG8gd29ybGQ="
+ * ```
+ * console.log(btoa("hello world"));  // outputs "aGVsbG8gd29ybGQ="
+ * ```
  */
 declare function btoa(s: string): string;
 
@@ -805,19 +809,81 @@ declare class MessagePort extends EventTarget {
   ): void;
 }
 
+/**
+ * Creates a deep copy of a given value using the structured clone algorithm.
+ *
+ * Unlike a shallow copy, a deep copy does not hold the same references as the
+ * source object, meaning its properties can be changed without affecting the
+ * source. For more details, see
+ * [MDN](https://developer.mozilla.org/en-US/docs/Glossary/Deep_copy).
+ *
+ * Throws a `DataCloneError` if any part of the input value is not
+ * serializable.
+ *
+ * @example
+ * ```ts
+ * const object = { x: 0, y: 1 };
+ *
+ * const deepCopy = structuredClone(object);
+ * deepCopy.x = 1;
+ * console.log(deepCopy.x, object.x); // 1 0
+ *
+ * const shallowCopy = object;
+ * shallowCopy.x = 1;
+ * // shallowCopy.x is pointing to the same location in memory as object.x
+ * console.log(shallowCopy.x, object.x); // 1 1
+ * ```
+ */
 declare function structuredClone(
   value: any,
   options?: StructuredSerializeOptions,
 ): any;
 
+/**
+ * An API for compressing a stream of data.
+ *
+ * @example
+ * ```ts
+ * await Deno.stdin.readable
+ *   .pipeThrough(new CompressionStream("gzip"))
+ *   .pipeTo(Deno.stdout.writable);
+ * ```
+ */
 declare class CompressionStream {
+  /**
+   * Creates a new `CompressionStream` object which compresses a stream of
+   * data.
+   *
+   * Throws a `TypeError` if the format passed to the constructor is not
+   * supported.
+   */
   constructor(format: string);
 
   readonly readable: ReadableStream<Uint8Array>;
   readonly writable: WritableStream<Uint8Array>;
 }
 
+/**
+ * An API for decompressing a stream of data.
+ *
+ * @example
+ * ```ts
+ * const input = await Deno.open("./file.txt.gz");
+ * const output = await Deno.create("./file.txt");
+ *
+ * await input.readable
+ *   .pipeThrough(new DecompressionStream("gzip"))
+ *   .pipeTo(output.writable);
+ * ```
+ */
 declare class DecompressionStream {
+  /**
+   * Creates a new `DecompressionStream` object which decompresses a stream of
+   * data.
+   *
+   * Throws a `TypeError` if the format passed to the constructor is not
+   * supported.
+   */
   constructor(format: string);
 
   readonly readable: ReadableStream<Uint8Array>;
diff --git a/ext/websocket/lib.deno_websocket.d.ts b/ext/websocket/lib.deno_websocket.d.ts
index af9026d41..8b79fa5cc 100644
--- a/ext/websocket/lib.deno_websocket.d.ts
+++ b/ext/websocket/lib.deno_websocket.d.ts
@@ -37,7 +37,7 @@ 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.
  *
- * 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()`.
  */
 declare class WebSocket extends EventTarget {
   constructor(url: string, protocols?: string | string[]);