docs: add JSDoc to all class members for JSR score

Author: GlobalTechInfo

lib/gSpeak.ts

@@ -1,3 +1,8 @@
+/**
+ * Core gSpeak class and SaveCallback type.
+ *
+ * @module
+ */
 import generateToken from './gToken.ts'
 import LANGUAGES from './languages.ts'
 
@@ -9,6 +14,8 @@ const escapeRegExp = (s: string): string => s.replace(/[|\\{}()[\]^$+*?.]/g, '\\
 /**
  * Callback passed to the Node-style {@link gSpeak.save} overload.
  * Receives `null` on success or an `Error` on failure.
+ *
+ * @param err - `null` on success, `Error` on failure.
  */
 // deno-lint-ignore no-explicit-any
 export type SaveCallback = (err: any) => void
@@ -17,7 +24,7 @@ export type SaveCallback = (err: any) => void
  * Google Text-to-Speech client.
  *
  * Converts text to spoken MP3 audio via the Google TTS endpoint.
- * Long text is automatically split into ≤100-character chunks and reassembled.
+ * Long text is automatically split into chunks of ≤100 characters and reassembled.
  *
  * Compatible with **Node.js**, **Deno**, **Bun**, **browsers**, and **Cloudflare Workers**.
  * Use {@link stream} or {@link bytes} in browser and worker environments.
@@ -30,9 +37,16 @@ export type SaveCallback = (err: any) => void
  * ```
  */
 export class gSpeak {
+  /** The BCP 47 language code used for this instance. */
   private lang: string
+
+  /** The original text passed to the constructor. */
   private text: string
+
+  /** The text split into ≤100-character chunks ready for requests. */
   private text_parts: string[]
+
+  /** Whether debug logging is enabled. */
   private debug: boolean
 
   /**
@@ -65,6 +79,11 @@ export class gSpeak {
     this.text_parts = parts
   }
 
+  /**
+   * Returns the HTTP headers required by the Google TTS endpoint.
+   *
+   * @returns Headers object with `Referer` and `User-Agent`.
+   */
   private getHeaders(): Record<string, string> {
     return {
       'Referer': 'http://translate.google.com/',
@@ -73,6 +92,13 @@ export class gSpeak {
     }
   }
 
+  /**
+   * Builds the Google TTS request URL for a single text chunk.
+   *
+   * @param part - The text chunk to synthesize.
+   * @param idx - The index of this chunk within the full text.
+   * @returns The fully constructed request URL string.
+   */
   private getUrl(part: string, idx: number): string {
     const params = new URLSearchParams({
       ie: 'UTF-8',
@@ -90,13 +116,16 @@ export class gSpeak {
   /**
    * Returns a Web `ReadableStream<Uint8Array>` of the MP3 audio data.
    *
-   * Uses only the Web Fetch API and Streams API — compatible with
+   * Uses only the Web Fetch and Streams APIs — compatible with
    * **Node.js 18+**, **Deno**, **Bun**, **browsers**, and **Cloudflare Workers**.
    *
+   * @returns A `ReadableStream` that emits MP3 audio chunks.
+   *
    * @example
    * ```ts
+   * // Cloudflare Worker / browser
    * const stream = new gSpeak("Hello", "en").stream()
-   * const response = new Response(stream, { headers: { "Content-Type": "audio/mpeg" } })
+   * return new Response(stream, { headers: { "Content-Type": "audio/mpeg" } })
    * ```
    */
   stream(): ReadableStream<Uint8Array> {
@@ -130,10 +159,11 @@ export class gSpeak {
    *
    * Works in every runtime — **Node.js**, **Deno**, **Bun**, **browsers**, and **Cloudflare Workers**.
    *
+   * @returns A `Promise` that resolves to a `Uint8Array` containing the full MP3 data.
+   *
    * @example
    * ```ts
    * const bytes = await new gSpeak("Hello", "en").bytes()
-   * // bytes is a Uint8Array containing the MP3 data
    * ```
    */
   async bytes(): Promise<Uint8Array> {
@@ -160,10 +190,8 @@ export class gSpeak {
    * - **Deno**: uses `Deno.writeFile`
    * - **Node.js / Bun**: uses `node:fs/promises`
    *
-   * > **Not available in browsers or Cloudflare Workers.** Use {@link stream} or {@link bytes} instead.
-   *
-   * Accepts an optional Node-style callback for backward compatibility.
-   * If no callback is provided, returns a `Promise<void>`.
+   * > **Not available in browsers or Cloudflare Workers.**
+   * > Use {@link stream} or {@link bytes} instead.
    *
    * @param filePath - Path to write the MP3 file to.
    * @param callback - Optional Node-style callback `(err) => void`.
@@ -202,12 +230,27 @@ export class gSpeak {
     }
   }
 
+  /**
+   * Splits text into chunks that respect sentence boundaries and fit within `max_size`.
+   *
+   * @param text - The full text to split.
+   * @param max_size - Maximum character length per chunk.
+   * @returns An array of text chunks.
+   */
   private _tokenize(text: string, max_size: number): string[] {
     const punc = '¡!()[]¿?.,;:—«»\n'.split('').map(escapeRegExp)
     const parts = text.split(new RegExp(punc.join('|')))
     return parts.flatMap(p => this._minimize(p, ' ', max_size))
   }
 
+  /**
+   * Recursively splits a string by `delim` until all parts fit within `max_size`.
+   *
+   * @param str - The string to split.
+   * @param delim - The delimiter to split on.
+   * @param max_size - Maximum character length per part.
+   * @returns An array of strings each within `max_size`.
+   */
   private _minimize(str: string, delim: string, max_size: number): string[] {
     if (str.length <= max_size) return [str]
     const idx = str.lastIndexOf(delim)
@@ -217,10 +260,12 @@ export class gSpeak {
   /**
    * A map of all supported BCP 47 language codes to their display names.
    *
+   * @returns A `Record<string, string>` of language code to display name.
+   *
    * @example
    * ```ts
-   * console.log(gSpeak.languages["en"])  // "English"
-   * console.log(gSpeak.languages["zh-cn"])  // "Chinese (Simplified)"
+   * console.log(gSpeak.languages["en"])    // "English"
+   * console.log(gSpeak.languages["zh-cn"]) // "Chinese (Simplified)"
    * ```
    */
   static get languages(): Record<string, string> {

lib/gToken.ts

@@ -1,7 +1,7 @@
 /**
- * @module
  * Internal token generator for authenticating requests to the Google TTS endpoint.
- * Not part of the public API.
+ *
+ * @module
  */
 
 const SALT_1 = '+-a^+6'

lib/index.ts

@@ -1,25 +1,26 @@
 /**
- * @module
  * gspeak — Google Text-to-Speech for Node.js, Deno, Bun, browsers, and Cloudflare Workers.
  *
- * Uses only Web-standard APIs (`fetch`, `ReadableStream`, `Uint8Array`) so it works
- * in any runtime. File-saving via {@link gSpeak.save} is supported in Node, Deno, and Bun.
+ * Uses only Web-standard APIs (`fetch`, `ReadableStream`, `Uint8Array`) so it runs
+ * in any modern runtime. File saving via {@link gSpeak.save} is available in Node, Deno, and Bun.
  *
  * @example
  * ```ts
  * import gSpeak from "gspeak"
  *
  * const tts = new gSpeak("Hello world", "en")
  *
- * // Stream audio (browsers, Cloudflare Workers, Node 18+, Deno, Bun)
+ * // Stream audio (works everywhere)
  * const stream = tts.stream()
  *
- * // Get raw MP3 bytes
+ * // Get raw MP3 bytes (works everywhere)
  * const bytes = await tts.bytes()
  *
- * // Save to file (Node, Deno, Bun)
+ * // Save to file (Node, Deno, Bun only)
  * await tts.save("hello.mp3")
  * ```
+ *
+ * @module
  */
 export { gSpeak as default, gSpeak } from './gSpeak.ts'
 export type { SaveCallback } from './gSpeak.ts'

lib/languages.ts

@@ -1,7 +1,7 @@
 /**
+ * Map of all BCP 47 language codes supported by the Google TTS API.
+ *
  * @module
- * Map of supported BCP 47 language codes to their display names.
- * Used by {@link gSpeak} to validate the `lang` parameter.
  */
 
 /**
@@ -12,9 +12,8 @@
  * ```ts
  * import { LANGUAGES } from "gspeak"
  *
- * console.log(LANGUAGES["en"])     // "English"
- * console.log(LANGUAGES["zh-cn"])  // "Chinese (Simplified)"
- * console.log(LANGUAGES["fr"])     // "French"
+ * console.log(LANGUAGES["en"])    // "English"
+ * console.log(LANGUAGES["zh-cn"]) // "Chinese (Simplified)"
  * ```
  */
 const LANGUAGES: Record<string, string> = {