docs: improve TextDecoder and TextEncoder jsdoc (#24890)

1 files changed, 38 insertions, 2 deletions

diff --git a/ext/web/lib.deno_web.d.ts b/ext/web/lib.deno_web.d.ts
index d0b32cd59..3fadfa429 100644
--- a/ext/web/lib.deno_web.d.ts
+++ b/ext/web/lib.deno_web.d.ts
@@ -306,9 +306,24 @@ declare interface TextDecodeOptions {
   stream?: boolean;
 }
 
-/** @category Encoding */
+/**
+ * Represents a decoder for a specific text encoding, allowing you to convert
+ * binary data into a string given the encoding.
+ *
+ * @example
+ * ```ts
+ * const decoder = new TextDecoder('utf-8');
+ * const buffer = new Uint8Array([72, 101, 108, 108, 111]);
+ * const decodedString = decoder.decode(buffer);
+ * console.log(decodedString); // Outputs: "Hello"
+ * ```
+ *
+ * @category Encoding
+ */
 declare interface TextDecoder extends TextDecoderCommon {
-  /** Returns the result of running encoding's decoder. */
+  /** Turns binary data, often in the form of a Uint8Array, into a string given
+   * the encoding.
+   */
   decode(input?: BufferSource, options?: TextDecodeOptions): string;
 }
 
@@ -340,6 +355,27 @@ declare interface TextEncoder extends TextEncoderCommon {
   encode(input?: string): Uint8Array;
   encodeInto(input: string, dest: Uint8Array): TextEncoderEncodeIntoResult;
 }
+/**
+ * Allows you to convert a string into binary data (in the form of a Uint8Array)
+ * given the encoding.
+ *
+ * @example
+ * ```ts
+ * const encoder = new TextEncoder();
+ * const str = "Hello";
+ * const encodedData = encoder.encode(str);
+ * console.log(encodedData); // Outputs: Uint8Array(5) [72, 101, 108, 108, 111]
+ * ```
+ *
+ * @category Encoding
+ */
+declare interface TextEncoder extends TextEncoderCommon {
+  /** Turns a string into binary data (in the form of a Uint8Array) using UTF-8 encoding. */
+  encode(input?: string): Uint8Array;
+
+  /** Encodes a string into the destination Uint8Array and returns the result of the encoding. */
+  encodeInto(input: string, dest: Uint8Array): TextEncoderEncodeIntoResult;
+}
 
 /** @category Encoding */
 declare var TextEncoder: {