redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/interactions.mcrs

@@ -11,14 +11,16 @@
 // SETUP - Call once on @load
 // =============================================
 
-/// Initialize interaction scoreboards
+/// Initializes the scoreboard objectives used by this module.
+/// Call once during pack setup before any per-tick interaction checks.
+/// Creates `rs.click`, `rs.sneak`, and `rs.attack`.
 fn interactions_init() {
     // Right click detection (carrot on a stick)
     scoreboard_add_objective("rs.click", "minecraft.used:minecraft.carrot_on_a_stick");
-    
+
     // Sneak time tracking
     scoreboard_add_objective("rs.sneak", "minecraft.custom:minecraft.sneak_time");
-    
+
     // Attack detection (left click on entity)
     scoreboard_add_objective("rs.attack", "minecraft.custom:minecraft.damage_dealt");
 }
@@ -29,8 +31,11 @@ fn interactions_init() {
 // Uses Carrot on a Stick item
 // Give players: /give @p carrot_on_a_stick{CustomModelData:1234}
 
-/// Check if player right-clicked (carrot on stick)
-/// Call this in @tick, resets after detection
+/// Detects right-click input using the `rs.click` scoreboard.
+/// Players with a positive click count are reset and tagged with `rs.clicked`.
+/// The `callback_fn` parameter is reserved for future callback dispatch and is
+/// not used by the current implementation.
+/// @param callback_fn  Reserved callback identifier, currently unused
 fn on_right_click(callback_fn: string) {
     // Players with click score > 0 have clicked
     foreach (p in @a) {
@@ -44,7 +49,8 @@ fn on_right_click(callback_fn: string) {
     }
 }
 
-/// Example: detect right click and do something
+/// Demonstrates how to consume `rs.click` directly.
+/// Broadcasts a message when a player right-clicks and resets the click count.
 fn example_right_click() {
     foreach (p in @a) {
         let clicks: int = scoreboard_get(p, "rs.click");
@@ -57,11 +63,13 @@ fn example_right_click() {
 }
 
 // =============================================
-// SNEAK DETECTION  
+// SNEAK DETECTION
 // =============================================
 
-/// Check if player just started sneaking
-/// Returns 1 if sneaking, 0 otherwise
+/// Returns whether the target is currently sneaking.
+/// This checks whether `rs.sneak` is greater than zero.
+/// @param target  Player selector to inspect
+/// @returns       `1` if sneaking, otherwise `0`
 fn is_sneaking(target: selector) -> int {
     let sneak_time: int = scoreboard_get(target, "rs.sneak");
     if (sneak_time > 0) {
@@ -70,7 +78,9 @@ fn is_sneaking(target: selector) -> int {
     return 0;
 }
 
-/// Detect sneak start (first tick of sneaking)
+/// Tags players who started sneaking on the current tick.
+/// Players with `rs.sneak == 1` receive the `rs.sneak_start` tag, and the tag
+/// is removed from everyone else.
 fn on_sneak_start() {
     foreach (p in @a) {
         let sneak_time: int = scoreboard_get(p, "rs.sneak");
@@ -88,7 +98,8 @@ fn on_sneak_start() {
 // =============================================
 // Uses execute with rotation checks
 
-/// Check if player is looking up (pitch < -45)
+/// Tags players currently looking upward.
+/// Players with pitch from `-90` to `-45` receive the `rs.look_up` tag.
 fn check_look_up() {
     // Now supports p[filters] syntax sugar!
     foreach (p in @a) {
@@ -101,7 +112,8 @@ fn check_look_up() {
     }
 }
 
-/// Check if player is looking down (pitch > 45)
+/// Tags players currently looking downward.
+/// Players with pitch from `45` to `90` receive the `rs.look_down` tag.
 fn check_look_down() {
     foreach (p in @a) {
         execute if entity p[x_rotation=45..90] run {
@@ -113,7 +125,8 @@ fn check_look_down() {
     }
 }
 
-/// Check if player is looking straight (pitch -45 to 45)
+/// Tags players currently looking roughly straight ahead.
+/// Players with pitch from `-45` to `45` receive the `rs.look_straight` tag.
 fn check_look_straight() {
     foreach (p in @a) {
         execute if entity p[x_rotation=-45..45] run {
@@ -130,15 +143,17 @@ fn check_look_straight() {
 // =============================================
 // Use execute if data or predicates
 
-/// Check if holding specific item (by tag)
-/// Usage: check_holding_tag("my_wand") checks for tag rs.holding.my_wand
+/// Placeholder helper for item-in-hand checks.
+/// The current implementation only prints guidance because robust item checks
+/// require predicates or explicit NBT checks.
+/// @param item_id  Expected item identifier or logical item key
 fn check_holding_item(item_id: string) {
     // This requires predicate files in datapack
     // Example predicate: data/ns/predicates/holding_diamond_sword.json
-    // { "condition": "minecraft:entity_properties", 
+    // { "condition": "minecraft:entity_properties",
     //   "entity": "this",
     //   "predicate": { "equipment": { "mainhand": { "items": ["minecraft:diamond_sword"] }}}}
-    
+
     // For now, use NBT check via execute
     say("Use execute if data for item checks");
 }
@@ -148,12 +163,14 @@ fn check_holding_item(item_id: string) {
 // =============================================
 // Common pattern: Sneak + Use for special ability
 
-/// Detect sneak + right click combo
+/// Detects a sneak-plus-right-click combo.
+/// Players who click while sneaking receive `rs.sneak_click`; otherwise they
+/// receive the normal `rs.clicked` tag. Click counters are reset in both cases.
 fn on_sneak_click() {
     foreach (p in @a) {
         let clicks: int = scoreboard_get(p, "rs.click");
         let sneak: int = scoreboard_get(p, "rs.sneak");
-        
+
         if (clicks > 0) {
             if (sneak > 0) {
                 // Sneak + Click!
@@ -174,14 +191,20 @@ fn on_sneak_click() {
 // Detect double-tap sneak (toggle fly, etc)
 
 let last_sneak_tick: int = 0;
+
+/// Double-sneak detection window in ticks.
+/// A second sneak start within this many ticks counts as a double tap.
 const DOUBLE_TAP_WINDOW: int = 10;  // 0.5 second
 
+/// Detects a double-tap sneak pattern.
+/// Requires external scoreboards `rs.last_sneak` and `rs.tick` to be updated by
+/// the caller. Players who qualify receive the `rs.double_sneak` tag.
 fn on_double_sneak() {
     foreach (p in @a) {
         let sneak: int = scoreboard_get(p, "rs.sneak");
         let last: int = scoreboard_get(p, "rs.last_sneak");
         let now: int = scoreboard_get(p, "rs.tick");
-        
+
         // Just started sneaking
         if (sneak == 1) {
             let diff: int = now - last;

package/src/stdlib/inventory.mcrs

@@ -1,11 +1,14 @@
 // Inventory management helpers
 
-/// Clear all items from a player's inventory
+/// Clears all inventory slots from the target selector.
+/// @param target  Player or entity selector whose inventory should be cleared
 fn clear_inventory(target: selector) {
     clear(target);
 }
 
-/// Give a kit of items to a player
+/// Gives a melee-focused warrior kit to the target selector.
+/// The kit includes iron armor, a sword, a shield, and food.
+/// @param target  Player or entity selector receiving the kit
 fn give_kit_warrior(target: selector) {
     give(target, "minecraft:iron_sword", 1);
     give(target, "minecraft:iron_chestplate", 1);
@@ -15,6 +18,9 @@ fn give_kit_warrior(target: selector) {
     give(target, "minecraft:cooked_beef", 16);
 }
 
+/// Gives a ranged archer kit to the target selector.
+/// The kit includes a bow, arrows, light armor, and food.
+/// @param target  Player or entity selector receiving the kit
 fn give_kit_archer(target: selector) {
     give(target, "minecraft:bow", 1);
     give(target, "minecraft:arrow", 64);
@@ -24,6 +30,9 @@ fn give_kit_archer(target: selector) {
     give(target, "minecraft:cooked_beef", 16);
 }
 
+/// Gives a utility-heavy mage kit to the target selector.
+/// The kit includes mobility, consumables, and splash damage items.
+/// @param target  Player or entity selector receiving the kit
 fn give_kit_mage(target: selector) {
     give(target, "minecraft:wooden_sword", 1);
     give(target, "minecraft:golden_apple", 8);
@@ -32,7 +41,9 @@ fn give_kit_mage(target: selector) {
     give(target, "minecraft:cooked_beef", 16);
 }
 
-/// Remove a specific item from player
+/// Removes all copies of a specific item from the target selector.
+/// @param target  Player or entity selector whose inventory will be filtered
+/// @param item    Item ID or item-with-NBT argument accepted by `clear`
 fn remove_item(target: selector, item: string) {
     clear(target, item);
 }

package/src/stdlib/linalg.mcrs

@@ -31,14 +31,30 @@ module library;
 
 // ─── 2D Vector ────────────────────────────────────────────────────────────────
 
-// vec2d_dot(ax, ay, bx, by): dot product of 2D vectors a and b.
+/// Dot product of two 2D vectors.
+///
+/// @since 2.0.0
+/// @param ax  X component of vector A
+/// @param ay  Y component of vector A
+/// @param bx  X component of vector B
+/// @param by  Y component of vector B
+/// @returns   `ax*bx + ay*by`
+/// @example
+/// let d: double = vec2d_dot(1.0d, 0.0d, 0.0d, 1.0d)
 fn vec2d_dot(ax: double, ay: double, bx: double, by: double): double {
     let t0: double = ax * bx;
     let t1: double = ay * by;
     return t0 + t1;
 }
 
-// vec2d_length(x, y): Euclidean length of 2D vector.
+/// Euclidean length of a 2D vector.
+///
+/// @since 2.0.0
+/// @param x  X component
+/// @param y  Y component
+/// @returns  `sqrt(x² + y²)`
+/// @example
+/// let len: double = vec2d_length(3.0d, 4.0d)
 fn vec2d_length(x: double, y: double): double {
     let xx: double = x * x;
     let yy: double = y * y;
@@ -46,14 +62,23 @@ fn vec2d_length(x: double, y: double): double {
     return double_sqrt(s) as double;
 }
 
-// vec2d_dist(ax, ay, bx, by): Euclidean distance between two 2D points.
+/// Euclidean distance between two 2D points.
+///
+/// @since 2.0.0
+/// @param ax  X coordinate of point A
+/// @param ay  Y coordinate of point A
+/// @param bx  X coordinate of point B
+/// @param by  Y coordinate of point B
+/// @returns   `sqrt((ax-bx)² + (ay-by)²)`
+/// @example
+/// let dist: double = vec2d_dist(0.0d, 0.0d, 3.0d, 4.0d)
 fn vec2d_dist(ax: double, ay: double, bx: double, by: double): double {
     let dx: double = ax - bx;
     let dy: double = ay - by;
     return vec2d_length(dx, dy);
 }
 
-// _vec2d_len_sq_fx(x, y): squared length as ×10000 fixed int (for zero-check).
+// _vec2d_len_sq_fx(x, y): squared length as integer (for zero-check).
 fn _vec2d_len_sq_fx(x: double, y: double): int {
     let xx: double = x * x;
     let yy: double = y * y;
@@ -61,8 +86,16 @@ fn _vec2d_len_sq_fx(x: double, y: double): int {
     return sq as int;
 }
 
-// vec2d_normalize_x(x, y): x component of the unit vector.
-//   Returns 0.0 if the vector has zero length.
+/// X component of the normalized unit vector for a 2D vector.
+///
+/// Returns `0.0` if the vector has zero length.
+///
+/// @since 2.0.0
+/// @param x  X component
+/// @param y  Y component
+/// @returns  `x / ||(x, y)||`, or `0.0` for a zero vector
+/// @example
+/// let nx: double = vec2d_normalize_x(3.0d, 4.0d)
 fn vec2d_normalize_x(x: double, y: double): double {
     let sq_fx: int = _vec2d_len_sq_fx(x, y);
     if (sq_fx == 0) {
@@ -72,8 +105,16 @@ fn vec2d_normalize_x(x: double, y: double): double {
     return x / len;
 }
 
-// vec2d_normalize_y(x, y): y component of the unit vector.
-//   Returns 0.0 if the vector has zero length.
+/// Y component of the normalized unit vector for a 2D vector.
+///
+/// Returns `0.0` if the vector has zero length.
+///
+/// @since 2.0.0
+/// @param x  X component
+/// @param y  Y component
+/// @returns  `y / ||(x, y)||`, or `0.0` for a zero vector
+/// @example
+/// let ny: double = vec2d_normalize_y(3.0d, 4.0d)
 fn vec2d_normalize_y(x: double, y: double): double {
     let sq_fx: int = _vec2d_len_sq_fx(x, y);
     if (sq_fx == 0) {
@@ -85,7 +126,18 @@ fn vec2d_normalize_y(x: double, y: double): double {
 
 // ─── 3D Vector ────────────────────────────────────────────────────────────────
 
-// vec3d_dot(ax,ay,az, bx,by,bz): dot product of 3D vectors a and b.
+/// Dot product of two 3D vectors.
+///
+/// @since 2.0.0
+/// @param ax  X component of vector A
+/// @param ay  Y component of vector A
+/// @param az  Z component of vector A
+/// @param bx  X component of vector B
+/// @param by  Y component of vector B
+/// @param bz  Z component of vector B
+/// @returns   `ax*bx + ay*by + az*bz`
+/// @example
+/// let d: double = vec3d_dot(1.0d, 0.0d, 0.0d, 0.0d, 1.0d, 0.0d)
 fn vec3d_dot(ax: double, ay: double, az: double, bx: double, by: double, bz: double): double {
     let t0: double = ax * bx;
     let t1: double = ay * by;
@@ -94,7 +146,15 @@ fn vec3d_dot(ax: double, ay: double, az: double, bx: double, by: double, bz: dou
     return s + t2;
 }
 
-// vec3d_length(x, y, z): Euclidean length of 3D vector.
+/// Euclidean length of a 3D vector.
+///
+/// @since 2.0.0
+/// @param x  X component
+/// @param y  Y component
+/// @param z  Z component
+/// @returns  `sqrt(x² + y² + z²)`
+/// @example
+/// let len: double = vec3d_length(1.0d, 2.0d, 2.0d)
 fn vec3d_length(x: double, y: double, z: double): double {
     let xx: double = x * x;
     let yy: double = y * y;
@@ -104,7 +164,16 @@ fn vec3d_length(x: double, y: double, z: double): double {
     return double_sqrt(s2) as double;
 }
 
-// vec3d_dist(ax,ay,az, bx,by,bz): Euclidean distance between two 3D points.
+/// Euclidean distance between two 3D points.
+///
+/// @since 2.0.0
+/// @param ax  X coordinate of point A
+/// @param ay  Y coordinate of point A
+/// @param az  Z coordinate of point A
+/// @param bx  X coordinate of point B
+/// @param by  Y coordinate of point B
+/// @param bz  Z coordinate of point B
+/// @returns   `sqrt((ax-bx)² + (ay-by)² + (az-bz)²)`
 fn vec3d_dist(ax: double, ay: double, az: double, bx: double, by: double, bz: double): double {
     let dx: double = ax - bx;
     let dy: double = ay - by;
@@ -112,28 +181,43 @@ fn vec3d_dist(ax: double, ay: double, az: double, bx: double, by: double, bz: do
     return vec3d_length(dx, dy, dz);
 }
 
-// vec3d_cross_x: x component of cross product a × b.
+/// X component of the cross product `a × b`.
+///
+/// @since 2.0.0
+/// @param ax  X of A   @param ay  Y of A   @param az  Z of A
+/// @param bx  X of B   @param by  Y of B   @param bz  Z of B
+/// @returns   `ay*bz - az*by`
 fn vec3d_cross_x(ax: double, ay: double, az: double, bx: double, by: double, bz: double): double {
     let t0: double = ay * bz;
     let t1: double = az * by;
     return t0 - t1;
 }
 
-// vec3d_cross_y: y component of cross product a × b.
+/// Y component of the cross product `a × b`.
+///
+/// @since 2.0.0
+/// @param ax  X of A   @param ay  Y of A   @param az  Z of A
+/// @param bx  X of B   @param by  Y of B   @param bz  Z of B
+/// @returns   `az*bx - ax*bz`
 fn vec3d_cross_y(ax: double, ay: double, az: double, bx: double, by: double, bz: double): double {
     let t0: double = az * bx;
     let t1: double = ax * bz;
     return t0 - t1;
 }
 
-// vec3d_cross_z: z component of cross product a × b.
+/// Z component of the cross product `a × b`.
+///
+/// @since 2.0.0
+/// @param ax  X of A   @param ay  Y of A   @param az  Z of A
+/// @param bx  X of B   @param by  Y of B   @param bz  Z of B
+/// @returns   `ax*by - ay*bx`
 fn vec3d_cross_z(ax: double, ay: double, az: double, bx: double, by: double, bz: double): double {
     let t0: double = ax * by;
     let t1: double = ay * bx;
     return t0 - t1;
 }
 
-// _vec3d_len_sq_fx(x, y, z): squared length as ×10000 fixed int (for zero-check).
+// _vec3d_len_sq_fx(x, y, z): squared length as integer (for zero-check).
 fn _vec3d_len_sq_fx(x: double, y: double, z: double): int {
     let xx: double = x * x;
     let yy: double = y * y;
@@ -143,8 +227,15 @@ fn _vec3d_len_sq_fx(x: double, y: double, z: double): int {
     return sq as int;
 }
 
-// vec3d_normalize_x(x, y, z): x component of the unit vector.
-//   Returns 0.0 if the vector has zero length.
+/// X component of the normalized unit vector for a 3D vector.
+///
+/// Returns `0.0` if the vector has zero length.
+///
+/// @since 2.0.0
+/// @param x  X component   @param y  Y component   @param z  Z component
+/// @returns  `x / ||(x, y, z)||`, or `0.0` for a zero vector
+/// @example
+/// let nx: double = vec3d_normalize_x(3.0d, 4.0d, 0.0d)
 fn vec3d_normalize_x(x: double, y: double, z: double): double {
     let sq_fx: int = _vec3d_len_sq_fx(x, y, z);
     if (sq_fx == 0) {
@@ -154,8 +245,13 @@ fn vec3d_normalize_x(x: double, y: double, z: double): double {
     return x / len;
 }
 
-// vec3d_normalize_y(x, y, z): y component of the unit vector.
-//   Returns 0.0 if the vector has zero length.
+/// Y component of the normalized unit vector for a 3D vector.
+///
+/// Returns `0.0` if the vector has zero length.
+///
+/// @since 2.0.0
+/// @param x  X component   @param y  Y component   @param z  Z component
+/// @returns  `y / ||(x, y, z)||`, or `0.0` for a zero vector
 fn vec3d_normalize_y(x: double, y: double, z: double): double {
     let sq_fx: int = _vec3d_len_sq_fx(x, y, z);
     if (sq_fx == 0) {
@@ -165,8 +261,13 @@ fn vec3d_normalize_y(x: double, y: double, z: double): double {
     return y / len;
 }
 
-// vec3d_normalize_z(x, y, z): z component of the unit vector.
-//   Returns 0.0 if the vector has zero length.
+/// Z component of the normalized unit vector for a 3D vector.
+///
+/// Returns `0.0` if the vector has zero length.
+///
+/// @since 2.0.0
+/// @param x  X component   @param y  Y component   @param z  Z component
+/// @returns  `z / ||(x, y, z)||`, or `0.0` for a zero vector
 fn vec3d_normalize_z(x: double, y: double, z: double): double {
     let sq_fx: int = _vec3d_len_sq_fx(x, y, z);
     if (sq_fx == 0) {
@@ -182,49 +283,83 @@ fn vec3d_normalize_z(x: double, y: double, z: double): double {
 //   [ a  b ]   a = m[0,0]  b = m[0,1]
 //   [ c  d ]   c = m[1,0]  d = m[1,1]
 
-// mat2d_det(a,b,c,d): determinant of a 2×2 matrix.
+/// Determinant of a 2×2 matrix `[[a, b], [c, d]]`.
+///
+/// @since 2.0.0
+/// @param a  Element [0,0]   @param b  Element [0,1]
+/// @param c  Element [1,0]   @param d  Element [1,1]
+/// @returns  `a*d - b*c`
+/// @example
+/// let det: double = mat2d_det(1.0d, 2.0d, 3.0d, 4.0d)
 fn mat2d_det(a: double, b: double, c: double, d: double): double {
     let t0: double = a * d;
     let t1: double = b * c;
     return t0 - t1;
 }
 
-// mat2d_mul_r0c0: element [0,0] of matrix product M0 × M1.
+/// Element [0,0] of the 2×2 matrix product `M0 × M1`.
+///
+/// @since 2.0.0
+/// @param a0  M0 row-major elements (a0, b0, c0, d0)
+/// @param a1  M1 row-major elements (a1, b1, c1, d1)
+/// @returns   `a0*a1 + b0*c1`
 fn mat2d_mul_r0c0(a0: double, b0: double, c0: double, d0: double, a1: double, b1: double, c1: double, d1: double): double {
     let t0: double = a0 * a1;
     let t1: double = b0 * c1;
     return t0 + t1;
 }
 
-// mat2d_mul_r0c1: element [0,1] of matrix product M0 × M1.
+/// Element [0,1] of the 2×2 matrix product `M0 × M1`.
+///
+/// @since 2.0.0
+/// @param a0  M0 row-major elements   @param a1  M1 row-major elements
+/// @returns   `a0*b1 + b0*d1`
 fn mat2d_mul_r0c1(a0: double, b0: double, c0: double, d0: double, a1: double, b1: double, c1: double, d1: double): double {
     let t0: double = a0 * b1;
     let t1: double = b0 * d1;
     return t0 + t1;
 }
 
-// mat2d_mul_r1c0: element [1,0] of matrix product M0 × M1.
+/// Element [1,0] of the 2×2 matrix product `M0 × M1`.
+///
+/// @since 2.0.0
+/// @param a0  M0 row-major elements   @param a1  M1 row-major elements
+/// @returns   `c0*a1 + d0*c1`
 fn mat2d_mul_r1c0(a0: double, b0: double, c0: double, d0: double, a1: double, b1: double, c1: double, d1: double): double {
     let t0: double = c0 * a1;
     let t1: double = d0 * c1;
     return t0 + t1;
 }
 
-// mat2d_mul_r1c1: element [1,1] of matrix product M0 × M1.
+/// Element [1,1] of the 2×2 matrix product `M0 × M1`.
+///
+/// @since 2.0.0
+/// @param a0  M0 row-major elements   @param a1  M1 row-major elements
+/// @returns   `c0*b1 + d0*d1`
 fn mat2d_mul_r1c1(a0: double, b0: double, c0: double, d0: double, a1: double, b1: double, c1: double, d1: double): double {
     let t0: double = c0 * b1;
     let t1: double = d0 * d1;
     return t0 + t1;
 }
 
-// mat2d_vecmul_x(a,b,c,d, vx,vy): x component of matrix-vector product M × v.
+/// X component of the 2×2 matrix–vector product `M × v`.
+///
+/// @since 2.0.0
+/// @param a  M[0,0]   @param b  M[0,1]   @param c  M[1,0]   @param d  M[1,1]
+/// @param vx  Vector X component   @param vy  Vector Y component
+/// @returns   `a*vx + b*vy`
 fn mat2d_vecmul_x(a: double, b: double, c: double, d: double, vx: double, vy: double): double {
     let t0: double = a * vx;
     let t1: double = b * vy;
     return t0 + t1;
 }
 
-// mat2d_vecmul_y(a,b,c,d, vx,vy): y component of matrix-vector product M × v.
+/// Y component of the 2×2 matrix–vector product `M × v`.
+///
+/// @since 2.0.0
+/// @param a  M[0,0]   @param b  M[0,1]   @param c  M[1,0]   @param d  M[1,1]
+/// @param vx  Vector X component   @param vy  Vector Y component
+/// @returns   `c*vx + d*vy`
 fn mat2d_vecmul_y(a: double, b: double, c: double, d: double, vx: double, vy: double): double {
     let t0: double = c * vx;
     let t1: double = d * vy;
@@ -241,7 +376,17 @@ fn mat2d_vecmul_y(a: double, b: double, c: double, d: double, vx: double, vy: do
 //
 // NOTE: det must be non-zero; no guard is applied (caller's responsibility).
 
-// solve2d_x: x solution component via Cramer's rule.
+/// X solution of the 2×2 linear system `[a b; c d] * [x; y] = [ex; ey]` via Cramer's rule.
+///
+/// Caller must ensure `det(a, b, c, d) ≠ 0`.
+///
+/// @since 2.0.0
+/// @param a   M[0,0]   @param b   M[0,1]
+/// @param c   M[1,0]   @param d   M[1,1]
+/// @param ex  RHS x    @param ey  RHS y
+/// @returns   `(ex*d - b*ey) / det`
+/// @example
+/// let x: double = solve2d_x(1.0d, 0.0d, 0.0d, 1.0d, 3.0d, 4.0d)
 fn solve2d_x(a: double, b: double, c: double, d: double, ex: double, ey: double): double {
     let num: double = ex * d;
     let sub: double = b * ey;
@@ -250,7 +395,17 @@ fn solve2d_x(a: double, b: double, c: double, d: double, ex: double, ey: double)
     return numer / det;
 }
 
-// solve2d_y: y solution component via Cramer's rule.
+/// Y solution of the 2×2 linear system `[a b; c d] * [x; y] = [ex; ey]` via Cramer's rule.
+///
+/// Caller must ensure `det(a, b, c, d) ≠ 0`.
+///
+/// @since 2.0.0
+/// @param a   M[0,0]   @param b   M[0,1]
+/// @param c   M[1,0]   @param d   M[1,1]
+/// @param ex  RHS x    @param ey  RHS y
+/// @returns   `(a*ey - ex*c) / det`
+/// @example
+/// let y: double = solve2d_y(1.0d, 0.0d, 0.0d, 1.0d, 3.0d, 4.0d)
 fn solve2d_y(a: double, b: double, c: double, d: double, ex: double, ey: double): double {
     let num: double = a * ey;
     let sub: double = ex * c;