From baeeceb445288e446a0a1ee45d2bcbf3136ae571 Mon Sep 17 00:00:00 2001
From: Anton-4 <17049058+Anton-4@users.noreply.github.com>
Date: Mon, 10 Mar 2025 20:04:11 +0100
Subject: [PATCH 1/2] more comments

---
 src/check/parse/IR.zig | 25 ++++++++++++++++++++++---
 src/fuzz-cli.zig       |  2 +-
 src/types.zig          |  8 +++++---
 3 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/src/check/parse/IR.zig b/src/check/parse/IR.zig
index 83ef3d0a98..fdfb86957e 100644
--- a/src/check/parse/IR.zig
+++ b/src/check/parse/IR.zig
@@ -1,3 +1,15 @@
+//!
+//! This file implements the Intermediate Representation (IR) for Roc's parser.
+//!
+//! The IR provides a structured, tree-based representation of Roc source code after parsing
+//!
+//! The design uses an arena-based memory allocation strategy with a "multi-list" approach where nodes
+//! are stored in a flat list but cross-referenced via indices rather than pointers. This improves
+//! memory locality and efficiency.
+//!
+//! The implementation includes comprehensive facilities for building, manipulating, and traversing
+//! the IR, as well as converting it to S-expressions for debugging and visualization.
+
 const std = @import("std");
 const base = @import("../../base.zig");
 const sexpr = @import("../../base/sexpr.zig");
@@ -19,7 +31,6 @@ tokens: TokenizedBuffer,
 store: NodeStore,
 errors: []const Diagnostic,
 
-/// deinit the IR's memory
 pub fn deinit(self: *IR) void {
     defer self.tokens.deinit();
     defer self.store.deinit();
@@ -641,6 +652,7 @@ pub const NodeStore = struct {
                     .qualified = 0,
                     .num_exposes = @as(u30, @intCast(i.exposes.span.len)),
                 };
+                
                 const extra_data_start = store.extra_data.items.len;
                 if (i.qualifier_tok) |tok| {
                     rhs.qualified = 1;
@@ -2504,8 +2516,15 @@ pub fn resolve(self: *IR, token: TokenIdx) []const u8 {
     return self.source[@intCast(range.start.offset)..@intCast(range.end.offset)];
 }
 
-/// todo -- I'm not sure what this is
-pub const ImportRhs = packed struct { aliased: u1, qualified: u1, num_exposes: u30 };
+/// Contains properties of the thing to the right of the `import` keyword.
+pub const ImportRhs = packed struct {
+    /// e.g. 1 in case `SomeModule` is an alias in `import SomeModule exposing [...]`
+    aliased: u1,
+    /// 1 in case the import is qualified, e.g. `pf` in `import pf.Stdout ...`
+    qualified: u1,
+    /// The number of things in the exposes list. e.g. 3 in `import SomeModule exposing [a1, a2, a3]`
+    num_exposes: u30,
+};
 
 // Check that all packed structs are 4 bytes size as they as cast to
 // and from a u32
diff --git a/src/fuzz-cli.zig b/src/fuzz-cli.zig
index 328e6bde6e..f3c1f93357 100644
--- a/src/fuzz-cli.zig
+++ b/src/fuzz-cli.zig
@@ -1,5 +1,5 @@
 //! This is just a silly fuzz test to start getting the infra setup.
-//! It shows the basic that other fuzz tests likely should build off of.
+//! It shows the basics that other fuzz tests likely should build off of.
 //!
 //! Note: Compiling the fuzz tests requires llvm and does not currently work in our nix shell on all systems.
 //!
diff --git a/src/types.zig b/src/types.zig
index a1a86157be..da3fd7e4db 100644
--- a/src/types.zig
+++ b/src/types.zig
@@ -12,7 +12,7 @@ pub const Primitive = union(enum) {
     Crash,
 };
 
-/// todo
+/// All Roc Int types
 pub const Int = enum {
     U8,
     I8,
@@ -25,13 +25,15 @@ pub const Int = enum {
     U128,
     I128,
 };
-/// todo
+
+/// All Roc Float types
 pub const Float = enum {
     F32,
     F64,
     Dec,
 };
-/// todo
+
+/// Roc Num types; Int and Float
 pub const Num = union(enum) {
     Int: Int,
     Float: Float,

From 487355c60f991eeccdc3ca30e0980795356ba6ab Mon Sep 17 00:00:00 2001
From: Anton-4 <17049058+Anton-4@users.noreply.github.com>
Date: Mon, 10 Mar 2025 20:07:21 +0100
Subject: [PATCH 2/2] fmt

---
 src/check/parse/IR.zig | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/check/parse/IR.zig b/src/check/parse/IR.zig
index fdfb86957e..d9cb41be02 100644
--- a/src/check/parse/IR.zig
+++ b/src/check/parse/IR.zig
@@ -652,7 +652,7 @@ pub const NodeStore = struct {
                     .qualified = 0,
                     .num_exposes = @as(u30, @intCast(i.exposes.span.len)),
                 };
-                
+
                 const extra_data_start = store.extra_data.items.len;
                 if (i.qualifier_tok) |tok| {
                     rhs.qualified = 1;