From ca27aedae74ff9be7355caa40911fa766535e23c Mon Sep 17 00:00:00 2001
From: Judah Caruso <judahrcr@gmail.com>
Date: Sat, 17 May 2025 04:17:08 -0600
Subject: [PATCH] organizing, documentation

---
 macros.jai      | 19 +++++++++++--------
 test/module.jai | 12 ++++++++++++
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/macros.jai b/macros.jai
index 55f54fe..6b33cd7 100644
--- a/macros.jai
+++ b/macros.jai
@@ -5,18 +5,18 @@
       old := Vector3.{ 10, 20, 30 };  // 10,  20, 30
       new := with(old, .{ y = -20 }); // 10, -20, 30
 */
-with :: (old: $T, $new: Code, location := #caller_location) -> T
+with :: (old: $T, $fields: Code, location := #caller_location) -> T
 #modify { return T.(*Type_Info).type == .STRUCT, "with can only be used on structs"; }
 #expand {
-   using compiler;
-
-   ensure :: (cond: bool, message: string, args: ..Any, loc := location) {
-      if !cond compiler_report(basic.tprint(message, ..args), loc);
-   }
-
    #insert,scope() -> string {
+      using compiler;
+
+      ensure :: (cond: bool, message: string, args: ..Any, loc := location) {
+         if !cond compiler_report(basic.tprint(message, ..args), loc);
+      }
+
       b: basic.String_Builder;
-      root := compiler_get_nodes(new).(*Code_Literal);
+      root := compiler_get_nodes(fields).(*Code_Literal);
       ensure(root.kind == .LITERAL, "argument must be a struct literal");
       ensure(root.value_type == .STRUCT, "argument must be a struct literal");
 
@@ -32,6 +32,9 @@ with :: (old: $T, $new: Code, location := #caller_location) -> T
          ensure(n_type.result == t_info, "mismatched types, % vs. %", t_info.name, n_typename);
       }
 
+      // @note(judah): if the value we're trying to copy is a constant,
+      // we have to create a local so we can assign to the fields.
+      // Doing this allows this usecase: 'with(Default_Entity, .{ kind = .Player })'
       receiver := "old";
       #if is_constant(old) {
          receiver = "copy";
diff --git a/test/module.jai b/test/module.jai
index 5f10221..e22a754 100644
--- a/test/module.jai
+++ b/test/module.jai
@@ -1,3 +1,15 @@
+/*
+   A very simple test runner that can be used at compile-time.
+
+   Usage:
+      test :: #import "jx/test";
+
+      #if RUN_TESTS #run {
+         test.run("collection of tests", t => {
+            test.expect(t, some_condition, "error message: %", value);
+         });
+      }
+*/
 T :: struct {
    location:    Source_Code_Location;
    expects_run: sint;