From 9d7c573a1aa4eb20e41d40245ae0dc15dc3bede2 Mon Sep 17 00:00:00 2001
From: Judah Caruso <judah@tuta.io>
Date: Mon, 19 May 2025 13:13:31 -0600
Subject: [PATCH] math docs

---
 _run_all_tests.jai |  1 +
 math/vec.jai       | 20 +++++++++++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/_run_all_tests.jai b/_run_all_tests.jai
index 93c6518..d8fb2f3 100644
--- a/_run_all_tests.jai
+++ b/_run_all_tests.jai
@@ -5,6 +5,7 @@
    #import,file "./module.jai"(true);
    #import,file "./encoding/module.jai"(true);
    #import,file "./hash/module.jai"(true);
+
    rmath :: #import,file "./math/module.jai"(.radians, true);
    dmath :: #import,file "./math/module.jai"(.degrees, true);
    tmath :: #import,file "./math/module.jai"(.turns, true);
diff --git a/math/vec.jai b/math/vec.jai
index eb3b3f7..37d5db3 100644
--- a/math/vec.jai
+++ b/math/vec.jai
@@ -1,5 +1,5 @@
 /*
-   Vec is a generic set of N named values of type T.
+   Vec is a generic set of N named values of type T (aka. a mathematical vector)
 
    The values can be accessed via array index or their common component names:
 
@@ -14,13 +14,31 @@
       Vec3 : Vec(3, float)
       Vec4 : Vec(4, float)
       Quat : Vec(4, float)
+
+   Sadly, Vec does *NOT* solve the problem of interfacing with
+   external vector types (including Jai's 'Math' module).
+
+   To fix this, create two helper macros:
+
+      to_jai :: (v: Vec4) -> jmath.Vector4 #expand {
+         return v.(jmath.Vector4,force);
+      }
+      to_jai :: (v: *Vec4) -> *jmath.Vector4 #expand {
+         return v.(*jmath.Vector4);
+      }
 */
 Vec :: struct(N: int, T: Type)
 #modify {
+
    info := T.(*Type_Info);
    return info.type == .INTEGER || info.type == .FLOAT, "Vec T must be a numeric type (int or float)";
 } {
+   #assert (N > 0) "Vec N cannot be <= 0";
+
+   // Vecs are backed by an array internally. The #insert block below
+   // generates #place'd unions of named fields or cN fields when N is > 4.
    #as components: [N]T;
+
    #insert -> string {
       b: basic.String_Builder;
       basic.append(*b, "#place components;\n");