redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/bigint.mcrs

@@ -19,6 +19,9 @@ module library;
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
+/// Return the bigint base (10000 = base-10000, each chunk holds 4 decimal digits).
+/// @since 1.0.0
+/// @returns  10000
 fn bigint_base(): int { return 10000; }
 
 // ─── Single-chunk helpers ────────────────────────────────────────────────────
@@ -96,20 +99,37 @@ fn bigint3_rem_chunk(chunk: int, rem: int, divisor: int): int {
 
 // ─── Arbitrary-length operations (array by-ref, RedScript ≥ 2.4.0) ──────────
 
-// bigint_zero(arr, len): set all chunks to 0
+/// Set all chunks of a bigint array to zero.
+/// @since 1.0.0
+/// @param arr  BigInt array (most-significant chunk at index 0)
+/// @param len  Number of chunks
+/// @returns  void — arr[0..len-1] set to 0
+/// @example
+/// bigint_zero(result, 4)  // zero out a 4-chunk bigint
 fn bigint_zero(arr: int[], len: int) {
     let i: int = 0;
     while (i < len) { arr[i] = 0; i = i + 1; }
 }
 
-// bigint_copy(src, dst, len): copy src into dst
+/// Copy a bigint from src into dst.
+/// @since 1.0.0
+/// @param src  Source bigint array
+/// @param dst  Destination bigint array (must have length >= len)
+/// @param len  Number of chunks to copy
+/// @returns  void — dst[0..len-1] = src[0..len-1]
 fn bigint_copy(src: int[], dst: int[], len: int) {
     let i: int = 0;
     while (i < len) { dst[i] = src[i]; i = i + 1; }
 }
 
-// bigint_cmp(a, b, len): compare a and b, returns 1 if a>b, -1 if a<b, 0 if equal
-// Most significant chunk is at index 0 (big-endian)
+/// Compare two bigints of equal length.
+/// @since 1.0.0
+/// @param a    First bigint (most-significant chunk at index 0)
+/// @param b    Second bigint
+/// @param len  Number of chunks (must be equal for both)
+/// @returns  1 if a > b, -1 if a < b, 0 if equal
+/// @example
+/// let cmp: int = bigint_cmp(a, b, 4)
 fn bigint_cmp(a: int[], b: int[], len: int): int {
     let i: int = 0;
     while (i < len) {
@@ -120,8 +140,15 @@ fn bigint_cmp(a: int[], b: int[], len: int): int {
     return 0;
 }
 
-// bigint_add(a, b, result, len): result = a + b (in-place into result array)
-// Returns carry out (0 or 1) — caller should handle overflow
+/// Add two bigints of equal length, writing result into a pre-allocated array.
+/// @since 1.0.0
+/// @param a       First bigint addend
+/// @param b       Second bigint addend
+/// @param result  Output bigint array (must have length >= len, may alias a or b)
+/// @param len     Number of chunks
+/// @returns  Carry out: 0 or 1 (overflow if non-zero)
+/// @example
+/// let carry: int = bigint_add(a, b, result, 4)
 fn bigint_add(a: int[], b: int[], result: int[], len: int): int {
     let carry: int = 0;
     let i: int = len - 1;  // start from least significant (rightmost)
@@ -134,7 +161,13 @@ fn bigint_add(a: int[], b: int[], result: int[], len: int): int {
     return carry;
 }
 
-// bigint_sub(a, b, result, len): result = a - b (assumes a >= b)
+/// Subtract bigint b from a, writing result (assumes a >= b, no underflow check).
+/// @since 1.0.0
+/// @param a       Minuend bigint
+/// @param b       Subtrahend bigint (must be <= a)
+/// @param result  Output bigint array
+/// @param len     Number of chunks
+/// @returns  void — result = a - b
 fn bigint_sub(a: int[], b: int[], result: int[], len: int) {
     let borrow: int = 0;
     let i: int = len - 1;
@@ -150,7 +183,15 @@ fn bigint_sub(a: int[], b: int[], result: int[], len: int) {
     }
 }
 
-// bigint_mul_small(a, n, result, len): result = a × n, where n ≤ 9999
+/// Multiply a bigint by a small integer (1 ≤ n ≤ 9999).
+/// @since 1.0.0
+/// @param a       Bigint multiplicand
+/// @param n       Small integer multiplier (must be in [1, 9999] to avoid overflow)
+/// @param result  Output bigint array (must have length >= len)
+/// @param len     Number of chunks
+/// @returns  void — result = a * n; high overflow is silently lost
+/// @example
+/// bigint_mul_small(a, 1000, result, 4)  // result = a × 1000
 fn bigint_mul_small(a: int[], n: int, result: int[], len: int) {
     let carry: int = 0;
     let i: int = len - 1;
@@ -201,8 +242,15 @@ fn bigint_leading_zeros(arr: int[], len: int): int {
 // result[i] = (rem*10000 + a[i]) / divisor
 // rem = (rem*10000 + a[i]) % divisor
 
-// bigint_div_small(a, divisor, result, len): result = a / divisor
-// Returns remainder.
+/// Divide a bigint by a small integer (1 ≤ divisor ≤ 9999), returning quotient and remainder.
+/// @since 1.0.0
+/// @param a        Dividend bigint
+/// @param divisor  Small integer divisor (range [1, 9999])
+/// @param result   Output quotient bigint array
+/// @param len      Number of chunks
+/// @returns  Remainder (0..divisor-1)
+/// @example
+/// let rem: int = bigint_div_small(a, 7, result, 4)
 fn bigint_div_small(a: int[], divisor: int, result: int[], len: int): int {
     let rem: int = 0;
     let i: int = 0;
@@ -215,7 +263,14 @@ fn bigint_div_small(a: int[], divisor: int, result: int[], len: int): int {
     return rem;
 }
 
-// bigint_mod_small(a, divisor, len): return a % divisor (0..divisor-1)
+/// Compute a bigint modulo a small integer without allocating a quotient array.
+/// @since 1.0.0
+/// @param a        Dividend bigint
+/// @param divisor  Small integer divisor (range [1, 9999])
+/// @param len      Number of chunks
+/// @returns  a % divisor, in [0, divisor-1]
+/// @example
+/// let mod: int = bigint_mod_small(a, 10, 4)  // last decimal digit of a
 fn bigint_mod_small(a: int[], divisor: int, len: int): int {
     let rem: int = 0;
     let i: int = 0;
@@ -248,6 +303,17 @@ fn bigint_chunk(a: int[], i: int): int {
 //   let result: int[] = [0, 0, 0, 0, 0, 0, 0]; // la+lb = 7 chunks, pre-zeroed
 //   bigint_mul(a, b, result, 4, 3);
 //
+/// Multiply two bigints using schoolbook O(n²) algorithm.
+/// @since 1.0.0
+/// @param a       First bigint (la chunks)
+/// @param b       Second bigint (lb chunks)
+/// @param result  Output bigint array (must have la+lb chunks, pre-zeroed)
+/// @param la      Number of chunks in a
+/// @param lb      Number of chunks in b
+/// @returns  void — result = a * b; result must not alias a or b
+/// @example
+/// let result: int[] = [0, 0, 0, 0, 0, 0, 0]
+/// bigint_mul(a, b, result, 4, 3)
 fn bigint_mul(a: int[], b: int[], result: int[], la: int, lb: int) {
     // Phase 1: accumulate partial products (big-endian, MSB at index 0)
     // a[i] is the (la-1-i)-th digit from LSB, similarly for b[j]
@@ -286,6 +352,15 @@ fn bigint_mul_result_len(la: int, lb: int): int {
 //   result must have len*2 chunks (pre-zeroed).
 //   Optimized: only compute upper triangle and double (avoids redundant multiplications).
 //
+/// Square a bigint (optimized: computes upper triangle only).
+/// @since 1.0.0
+/// @param a       Bigint to square (len chunks)
+/// @param result  Output bigint array (must have len*2 chunks, pre-zeroed)
+/// @param len     Number of chunks in a
+/// @returns  void — result = a * a
+/// @example
+/// let sq: int[] = [0, 0, 0, 0, 0, 0, 0, 0]
+/// bigint_sq(a, sq, 4)  // sq = a²
 fn bigint_sq(a: int[], result: int[], len: int) {
     // Diagonal terms (i == j)
     let i: int = 0;
@@ -392,6 +467,17 @@ fn bigint_mul_small_into(b: int[], factor: int, out: int[], len: int): void {
 // quotient[0..la-1] is written, remainder[0..lb-1] is written.
 // a and b must not alias quotient or remainder.
 // NOTE: la >= lb required; both arrays most-significant first, base 10000.
+/// Full arbitrary-precision integer division: a / b → quotient and remainder.
+/// @since 1.0.0
+/// @param a          Dividend bigint (la chunks)
+/// @param b          Divisor bigint (lb chunks)
+/// @param quotient   Output quotient array (la chunks, pre-zeroed)
+/// @param remainder  Output remainder array (lb chunks, pre-zeroed)
+/// @param la         Number of chunks in a (must be >= lb)
+/// @param lb         Number of chunks in b
+/// @returns  void — quotient = a/b, remainder = a%b; a and b must not alias outputs
+/// @example
+/// bigint_div(a, b, quotient, remainder, 4, 2)
 fn bigint_div(a: int[], b: int[], quotient: int[], remainder: int[], la: int, lb: int): void {
     // Work on a copy of a (dividend) to allow in-place subtraction
     let work: int[] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];

package/src/stdlib/bits.mcrs

@@ -16,7 +16,13 @@ module library;
 
 // ─── Core: single-bit operations ─────────────────────────────────────────────
 
-// bit_get(x, n): return 1 if bit n is set, 0 otherwise. n ∈ [0, 30]
+/// Test whether bit n of x is set.
+/// @since 1.0.0
+/// @param x  Integer value to test
+/// @param n  Bit index (0 = least significant), range [0, 30]
+/// @returns  1 if bit n is set, 0 otherwise
+/// @example
+/// let b: int = bit_get(0b1010, 1)  // result: 1 (bit 1 of 10 is set)
 fn bit_get(x: int, n: int): int {
     let mask: int = 1;
     let i: int = 0;
@@ -24,7 +30,13 @@ fn bit_get(x: int, n: int): int {
     return (x / mask) % 2;
 }
 
-// bit_set(x, n): set bit n to 1. n ∈ [0, 30]
+/// Set bit n of x to 1 (idempotent if already set).
+/// @since 1.0.0
+/// @param x  Integer value to modify
+/// @param n  Bit index to set, range [0, 30]
+/// @returns  x with bit n set to 1
+/// @example
+/// let v: int = bit_set(0b0100, 0)  // result: 0b0101 = 5
 fn bit_set(x: int, n: int): int {
     let mask: int = 1;
     let i: int = 0;
@@ -33,7 +45,13 @@ fn bit_set(x: int, n: int): int {
     return x;
 }
 
-// bit_clear(x, n): clear bit n to 0. n ∈ [0, 30]
+/// Clear bit n of x to 0 (idempotent if already clear).
+/// @since 1.0.0
+/// @param x  Integer value to modify
+/// @param n  Bit index to clear, range [0, 30]
+/// @returns  x with bit n set to 0
+/// @example
+/// let v: int = bit_clear(0b0111, 1)  // result: 0b0101 = 5
 fn bit_clear(x: int, n: int): int {
     let mask: int = 1;
     let i: int = 0;
@@ -42,7 +60,13 @@ fn bit_clear(x: int, n: int): int {
     return x;
 }
 
-// bit_toggle(x, n): toggle bit n. n ∈ [0, 30]
+/// Toggle bit n of x (flip 0→1 or 1→0).
+/// @since 1.0.0
+/// @param x  Integer value to modify
+/// @param n  Bit index to toggle, range [0, 30]
+/// @returns  x with bit n flipped
+/// @example
+/// let v: int = bit_toggle(0b0101, 1)  // result: 0b0111 = 7
 fn bit_toggle(x: int, n: int): int {
     let mask: int = 1;
     let i: int = 0;
@@ -53,7 +77,13 @@ fn bit_toggle(x: int, n: int): int {
 
 // ─── Shift operations ────────────────────────────────────────────────────────
 
-// bit_shl(x, n): left shift x by n bits (x << n). n ∈ [0, 30]
+/// Left-shift x by n bits (equivalent to x * 2^n).
+/// @since 1.0.0
+/// @param x  Integer to shift
+/// @param n  Number of bit positions to shift left, range [0, 30]
+/// @returns  x << n
+/// @example
+/// let v: int = bit_shl(1, 4)  // result: 16 (1 << 4)
 fn bit_shl(x: int, n: int): int {
     let result: int = x;
     let i: int = 0;
@@ -61,8 +91,13 @@ fn bit_shl(x: int, n: int): int {
     return result;
 }
 
-// bit_shr(x, n): logical right shift x by n bits (x >> n). n ∈ [0, 30]
-// Note: divides by 2^n, truncating toward zero.
+/// Logical right-shift x by n bits (equivalent to x / 2^n, truncating toward zero).
+/// @since 1.0.0
+/// @param x  Integer to shift
+/// @param n  Number of bit positions to shift right, range [0, 30]
+/// @returns  x >> n (logical, not arithmetic for positive values)
+/// @example
+/// let v: int = bit_shr(256, 3)  // result: 32 (256 >> 3)
 fn bit_shr(x: int, n: int): int {
     let result: int = x;
     let i: int = 0;
@@ -73,7 +108,13 @@ fn bit_shr(x: int, n: int): int {
 // ─── Bitwise AND / OR / XOR ──────────────────────────────────────────────────
 // These iterate over 31 bits (signed int32, bit 31 is sign).
 
-// bit_and(a, b): bitwise AND
+/// Bitwise AND of two integers (all 31 non-sign bits).
+/// @since 1.0.0
+/// @param a  First operand
+/// @param b  Second operand
+/// @returns  a & b (bits set in both a and b)
+/// @example
+/// let v: int = bit_and(0b1100, 0b1010)  // result: 0b1000 = 8
 fn bit_and(a: int, b: int): int {
     let result: int = 0;
     let mask: int = 1;
@@ -90,7 +131,13 @@ fn bit_and(a: int, b: int): int {
     return result;
 }
 
-// bit_or(a, b): bitwise OR
+/// Bitwise OR of two integers (all 31 non-sign bits).
+/// @since 1.0.0
+/// @param a  First operand
+/// @param b  Second operand
+/// @returns  a | b (bits set in either a or b)
+/// @example
+/// let v: int = bit_or(0b1100, 0b1010)  // result: 0b1110 = 14
 fn bit_or(a: int, b: int): int {
     let result: int = 0;
     let mask: int = 1;
@@ -110,7 +157,13 @@ fn bit_or(a: int, b: int): int {
     return result;
 }
 
-// bit_xor(a, b): bitwise XOR
+/// Bitwise XOR of two integers (all 31 non-sign bits).
+/// @since 1.0.0
+/// @param a  First operand
+/// @param b  Second operand
+/// @returns  a ^ b (bits set in exactly one of a or b)
+/// @example
+/// let v: int = bit_xor(0b1100, 0b1010)  // result: 0b0110 = 6
 fn bit_xor(a: int, b: int): int {
     let result: int = 0;
     let mask: int = 1;
@@ -127,7 +180,12 @@ fn bit_xor(a: int, b: int): int {
     return result;
 }
 
-// bit_not(x): bitwise NOT (inverts all 31 bits, sign bit excluded)
+/// Bitwise NOT — inverts all 31 non-sign bits of x.
+/// @since 1.0.0
+/// @param x  Integer to invert
+/// @returns  ~x (all 31 lower bits flipped; sign bit excluded)
+/// @example
+/// let v: int = bit_not(0)  // result: 2147483647 (all 31 bits set)
 fn bit_not(x: int): int {
     let result: int = 0;
     let mask: int = 1;
@@ -144,7 +202,12 @@ fn bit_not(x: int): int {
 
 // ─── Popcount ────────────────────────────────────────────────────────────────
 
-// popcount(x): count number of set bits (0-31)
+/// Count the number of set bits in x (population count / Hamming weight).
+/// @since 1.0.0
+/// @param x  Integer value (uses 31 lower bits; sign bit excluded)
+/// @returns  Number of bits set to 1, in [0, 31]
+/// @example
+/// let n: int = popcount(255)  // result: 8 (0xFF has 8 bits set)
 fn popcount(x: int): int {
     let count: int = 0;
     let v: int = x;

package/src/stdlib/bossbar.mcrs

@@ -1,7 +1,14 @@
 // Bossbar helpers for progress bars and timers
 // Usage: import "stdlib/bossbar.mcrs"
 
-/// Create and show a timer bossbar
+/// Creates a visible timer bossbar for all players.
+/// The bossbar max and current value are initialized to `max_seconds * 20`
+/// so callers can update it directly in game ticks.
+/// @param id           Bossbar identifier, usually `<namespace>:<name>`
+/// @param name         Display name shown on the bossbar
+/// @param max_seconds  Duration in seconds; converted to ticks internally
+/// @example
+/// create_timer_bar("game:round", "Round Timer", 90)
 fn create_timer_bar(id: string, name: string, max_seconds: int) {
     bossbar_add(id, name);
     bossbar_set_max(id, max_seconds * 20);
@@ -12,7 +19,13 @@ fn create_timer_bar(id: string, name: string, max_seconds: int) {
     bossbar_set_visible(id, 1);
 }
 
-/// Create a health-style bossbar (red)
+/// Creates a visible red bossbar initialized at full value.
+/// Useful for boss HP or shared health objectives.
+/// @param id       Bossbar identifier, usually `<namespace>:<name>`
+/// @param name     Display name shown on the bossbar
+/// @param max_val  Maximum value and initial value of the bar
+/// @example
+/// create_health_bar("raid:boss_hp", "Warden", 500)
 fn create_health_bar(id: string, name: string, max_val: int) {
     bossbar_add(id, name);
     bossbar_set_max(id, max_val);
@@ -23,7 +36,13 @@ fn create_health_bar(id: string, name: string, max_val: int) {
     bossbar_set_visible(id, 1);
 }
 
-/// Create a progress bossbar (blue)
+/// Creates a visible blue progress bossbar starting at zero.
+/// Useful for charge bars, capture progress, or phase tracking.
+/// @param id       Bossbar identifier, usually `<namespace>:<name>`
+/// @param name     Display name shown on the bossbar
+/// @param max_val  Maximum progress value
+/// @example
+/// create_progress_bar("game:capture", "Capture", 100)
 fn create_progress_bar(id: string, name: string, max_val: int) {
     bossbar_add(id, name);
     bossbar_set_max(id, max_val);
@@ -34,27 +53,37 @@ fn create_progress_bar(id: string, name: string, max_val: int) {
     bossbar_set_visible(id, 1);
 }
 
-/// Update bossbar value
+/// Sets the current value of an existing bossbar.
+/// RedScript does not clamp the value; Minecraft handles display behavior.
+/// @param id     Bossbar identifier
+/// @param value  New current value
 fn update_bar(id: string, value: int) {
     bossbar_set_value(id, value);
 }
 
-/// Hide bossbar
+/// Hides an existing bossbar from all assigned players.
+/// @param id  Bossbar identifier
 fn hide_bar(id: string) {
     bossbar_set_visible(id, 0);
 }
 
-/// Show bossbar
+/// Shows an existing bossbar to all assigned players.
+/// @param id  Bossbar identifier
 fn show_bar(id: string) {
     bossbar_set_visible(id, 1);
 }
 
-/// Remove bossbar
+/// Removes an existing bossbar entirely.
+/// After removal, the same `id` must be recreated before reuse.
+/// @param id  Bossbar identifier
 fn remove_bar(id: string) {
     bossbar_remove(id);
 }
 
-/// Set bossbar color based on percentage
+/// Updates the bossbar color from a percentage threshold.
+/// Values above 66 use green, above 33 use yellow, otherwise red.
+/// @param id       Bossbar identifier
+/// @param percent  Percentage in the expected 0-100 range
 fn update_bar_color(id: string, percent: int) {
     if (percent > 66) {
         bossbar_set_color(id, "green");

package/src/stdlib/calculus.mcrs

@@ -12,24 +12,35 @@ module library;
 
 // ─── Differentiation ─────────────────────────────────────────────────────────
 
-// deriv_forward(f1, f0, h_fx): forward difference derivative
-// f1 = f(x+h), f0 = f(x), h_fx = step size ×10000
-// Returns df/dx ×10000
+/// Forward-difference derivative: (f(x+h) − f(x)) / h.
+/// @since 1.3.0
+/// @param f1 f(x + h) × 10000
+/// @param f0 f(x) × 10000
+/// @param h_fx Step size × 10000 (must not be zero)
+/// @returns df/dx × 10000; returns 0 if h_fx == 0
 fn deriv_forward(f1: int, f0: int, h_fx: int): int {
     if (h_fx == 0) { return 0; }
     return (f1 - f0) * 10000 / h_fx;
 }
 
-// deriv_central(f_plus, f_minus, h_fx): central difference (more accurate)
-// f_plus = f(x+h), f_minus = f(x-h)
-// Returns df/dx ×10000
+/// Central-difference derivative: (f(x+h) − f(x−h)) / (2h). More accurate than forward difference.
+/// @since 1.3.0
+/// @param f_plus f(x + h) × 10000
+/// @param f_minus f(x − h) × 10000
+/// @param h_fx Step size × 10000 (must not be zero)
+/// @returns df/dx × 10000; returns 0 if h_fx == 0
 fn deriv_central(f_plus: int, f_minus: int, h_fx: int): int {
     if (h_fx == 0) { return 0; }
     return (f_plus - f_minus) * 10000 / (2 * h_fx);
 }
 
-// second_deriv(f_plus, f0, f_minus, h_fx): second derivative
-// Returns d²f/dx² ×10000
+/// Second derivative via the central finite-difference formula: (f(x+h) − 2f(x) + f(x−h)) / h².
+/// @since 1.3.0
+/// @param f_plus f(x + h) × 10000
+/// @param f0 f(x) × 10000
+/// @param f_minus f(x − h) × 10000
+/// @param h_fx Step size × 10000 (must not be zero)
+/// @returns d²f/dx² × 10000; returns 0 if h_fx == 0
 fn second_deriv(f_plus: int, f0: int, f_minus: int, h_fx: int): int {
     if (h_fx == 0) { return 0; }
     return (f_plus - 2 * f0 + f_minus) * 100000000 / h_fx / h_fx;
@@ -40,10 +51,15 @@ fn second_deriv(f_plus: int, f0: int, f_minus: int, h_fx: int): int {
 // For integration, the user provides an array of function values at equally
 // spaced points, and the step size.
 
-// integrate_trapezoid(vals, n, h_fx): trapezoidal rule integration
-// vals: array of n function values ×10000, equally spaced by h_fx
-// h_fx: step width ×10000
-// Returns integral ×10000 (area under curve)
+/// Numerical integration using the trapezoidal rule.
+/// @since 1.3.0
+/// @param vals Array of n function values × 10000 at equally spaced points
+/// @param n Number of sample points (must be ≥ 2)
+/// @param h_fx Step width between samples × 10000
+/// @returns Approximate integral × 10000 (area under the curve)
+/// @example
+/// let ys: int[] = [0, 5000, 10000]; // f(0)=0, f(0.5)=0.5, f(1)=1  (linear)
+/// let area: int = integrate_trapezoid(ys, 3, 5000); // ≈ 5000  (∫₀¹ x dx = 0.5)
 fn integrate_trapezoid(vals: int[], n: int, h_fx: int): int {
     if (n < 2) { return 0; }
     // Sum = (vals[0] + vals[n-1]) / 2 + vals[1] + vals[2] + ... + vals[n-2]
@@ -56,8 +72,13 @@ fn integrate_trapezoid(vals: int[], n: int, h_fx: int): int {
     return sum * h_fx / 10000;
 }
 
-// integrate_simpson(vals, n, h_fx): Simpson's 1/3 rule (n must be odd, n ≥ 3)
-// More accurate than trapezoid for smooth functions
+/// Numerical integration using Simpson's 1/3 rule (more accurate than trapezoid for smooth functions).
+/// Uses n−1 intervals if n is even. Requires n ≥ 3.
+/// @since 1.3.0
+/// @param vals Array of n function values × 10000 at equally spaced points
+/// @param n Number of sample points (should be odd and ≥ 3)
+/// @param h_fx Step width × 10000
+/// @returns Approximate integral × 10000
 fn integrate_simpson(vals: int[], n: int, h_fx: int): int {
     if (n < 3) { return integrate_trapezoid(vals, n, h_fx); }
     // Ensure n is odd by using n-1 if even
@@ -80,7 +101,12 @@ fn integrate_simpson(vals: int[], n: int, h_fx: int): int {
 
 // ─── Riemann sums ─────────────────────────────────────────────────────────────
 
-// riemann_left(vals, n, h_fx): left Riemann sum
+/// Left Riemann sum: sum of f(x_i) × h for i = 0 … n−2.
+/// @since 1.3.0
+/// @param vals Array of n function values × 10000
+/// @param n Number of sample points
+/// @param h_fx Step width × 10000
+/// @returns Approximate integral × 10000
 fn riemann_left(vals: int[], n: int, h_fx: int): int {
     let sum: int = 0;
     let i: int = 0;
@@ -88,7 +114,12 @@ fn riemann_left(vals: int[], n: int, h_fx: int): int {
     return sum * h_fx / 10000;
 }
 
-// riemann_right(vals, n, h_fx): right Riemann sum
+/// Right Riemann sum: sum of f(x_i) × h for i = 1 … n−1.
+/// @since 1.3.0
+/// @param vals Array of n function values × 10000
+/// @param n Number of sample points
+/// @param h_fx Step width × 10000
+/// @returns Approximate integral × 10000
 fn riemann_right(vals: int[], n: int, h_fx: int): int {
     let sum: int = 0;
     let i: int = 1;
@@ -96,8 +127,12 @@ fn riemann_right(vals: int[], n: int, h_fx: int): int {
     return sum * h_fx / 10000;
 }
 
-// riemann_mid(vals, n, h_fx): midpoint Riemann sum
-// vals: midpoint values (n-1 midpoints for n-1 intervals)
+/// Midpoint Riemann sum using precomputed midpoint values.
+/// @since 1.3.0
+/// @param vals Array of n midpoint values × 10000 (one per interval)
+/// @param n Number of intervals (i.e. length of vals)
+/// @param h_fx Step width × 10000
+/// @returns Approximate integral × 10000
 fn riemann_mid(vals: int[], n: int, h_fx: int): int {
     let sum: int = 0;
     let i: int = 0;
@@ -107,8 +142,12 @@ fn riemann_mid(vals: int[], n: int, h_fx: int): int {
 
 // ─── Curve length ────────────────────────────────────────────────────────────
 
-// curve_length_2d(xs, ys, n): approximate arc length of a 2D polyline
-// xs, ys: x and y coordinates ×10000 of n points
+/// Approximate arc length of a 2-D polyline through n points using the Euclidean distance between consecutive points.
+/// @since 1.3.0
+/// @param xs X coordinates × 10000 of the n points
+/// @param ys Y coordinates × 10000 of the n points
+/// @param n Number of points (must be ≥ 2)
+/// @returns Approximate arc length × 10000
 fn curve_length_2d(xs: int[], ys: int[], n: int): int {
     let total: int = 0;
     let i: int = 0;
@@ -124,26 +163,43 @@ fn curve_length_2d(xs: int[], ys: int[], n: int): int {
 
 // ─── Running statistics ───────────────────────────────────────────────────────
 
-// running_mean(prev_mean, new_val, n): Welford's online mean update
-// prev_mean ×10000, new_val ×10000, n: count after adding new_val (n ≥ 1)
+/// Welford's online algorithm: update a running mean with a new sample.
+/// @since 1.3.0
+/// @param prev_mean Previous mean × 10000
+/// @param new_val New sample value × 10000
+/// @param n Total count after adding the new sample (n ≥ 1)
+/// @returns Updated mean × 10000
 fn running_mean(prev_mean: int, new_val: int, n: int): int {
     if (n <= 1) { return new_val; }
     return prev_mean + (new_val - prev_mean) * 10000 / (n * 10000);
 }
 
-// running_m2(prev_m2, prev_mean, new_mean, new_val): Welford's M2 update
-// Used to compute variance: variance = m2 / (n-1)
+/// Welford's online algorithm: update the M2 accumulator used to compute variance.
+/// Variance = running_m2 / (n − 1) after n samples.
+/// @since 1.3.0
+/// @param prev_m2 Previous M2 accumulator × 10000
+/// @param prev_mean Mean before adding the new sample × 10000
+/// @param new_mean Mean after adding the new sample × 10000
+/// @param new_val New sample value × 10000
+/// @returns Updated M2 accumulator × 10000
 fn running_m2(prev_m2: int, prev_mean: int, new_mean: int, new_val: int): int {
     return prev_m2 + (new_val - prev_mean) * (new_val - new_mean) / 10000;
 }
 
-// variance_from_m2(m2, n): get variance from Welford's M2, n = number of samples
+/// Compute sample variance from a Welford M2 accumulator and sample count.
+/// @since 1.3.0
+/// @param m2 M2 accumulator from `running_m2` × 10000
+/// @param n Number of samples collected
+/// @returns Sample variance × 10000; returns 0 for n ≤ 1
 fn variance_from_m2(m2: int, n: int): int {
     if (n <= 1) { return 0; }
     return m2 / (n - 1);
 }
 
-// std_dev_approx(variance_fx): approximate std dev = √variance
+/// Approximate standard deviation as the integer square root of the variance.
+/// @since 1.3.0
+/// @param variance_fx Variance × 10000 (e.g. from `variance_from_m2`)
+/// @returns √variance × 10000; returns 0 for non-positive input
 fn std_dev_approx(variance_fx: int): int {
     if (variance_fx <= 0) { return 0; }
     return isqrt(variance_fx * 100) * 100 / 10000;