Comments to describe each functionality in-depth

src/infrastructure/node_manager.zig

@@ -7,10 +7,14 @@ const Node = @import("node.zig").Node;
 const Road = @import("road.zig").Road;
 
 pub const NodeManager = struct {
+    /// Tracks which ID the next added node will get
     next_id: usize,
+    /// Tracks all the node (pointers)
     nodes: std.ArrayList(*Node),
+    /// Tracks the temporary node, being part of the newly built road
     temp_node: ?*Node,
 
+    /// Constructor (for convenience)
     pub fn init() NodeManager {
         return .{
             .next_id = 0,
@@ -19,6 +23,7 @@ pub const NodeManager = struct {
         };
     }
 
+    /// Deinitialises every node (pointer) within the list and then deinits the list containing the nodes itself
     pub fn deinit(self: *NodeManager, allocator: std.mem.Allocator) !void {
         for (self.nodes.items) |node| {
             try node.deinit(allocator);
@@ -26,6 +31,7 @@ pub const NodeManager = struct {
         self.nodes.deinit(allocator);
     }
 
+    /// Regular draw function
     pub fn draw(self: *const NodeManager, pos: Vector2) void {
         for (self.nodes.items) |node| {
             node.draw(null);
@@ -43,6 +49,8 @@ pub const NodeManager = struct {
         }
     }
 
+    /// Checks if there is a node pointer within the snap radius of pos coordinate;
+    /// otherwise creates a new node and returns its pointer
     pub fn getSelectedNode(self: *NodeManager, allocator: std.mem.Allocator, pos: Vector2) !*Node {
         for (self.nodes.items) |node| {
             if (node.posWithinRadius(pos)) return node;
@@ -57,6 +65,7 @@ pub const NodeManager = struct {
         return self.nodes.items[self.nodes.items.len - 1];
     }
 
+    /// Gets next id, resets only on clear()
     fn getNextID(self: *NodeManager) usize {
         const id = self.next_id;
         self.next_id += 1;
@@ -64,6 +73,7 @@ pub const NodeManager = struct {
         return id;
     }
 
+    /// Clears all existing nodes connected, not deinitialisation
     pub fn clear(self: *NodeManager, allocator: std.mem.Allocator) !void {
         self.temp_node = null;
         for (self.nodes.items) |node| {
@@ -73,6 +83,7 @@ pub const NodeManager = struct {
         self.next_id = 0;
     }
 
+    /// Deletes node, returns error if node still has road references
     pub fn deleteNode(self: *NodeManager, allocator: std.mem.Allocator, node_to_delete: *Node) !void {
         if (node_to_delete.roads.items.len != 0) return e.Entity.HasReferences;
 

src/infrastructure/road_manager.zig

@@ -17,6 +17,7 @@ pub const RoadManager = struct {
         };
     }
 
+    /// Deinitialises every road (pointer) and then the list itself
     pub fn deinit(self: *RoadManager, allocator: std.mem.Allocator) void {
         for (self.roads.items) |road| {
             road.deinit(allocator);
@@ -24,6 +25,7 @@ pub const RoadManager = struct {
         self.roads.deinit(allocator);
     }
 
+    /// Draws all the roads in the list, sends the information ahead whether the road drawn should be highlighted
     pub fn draw(self: *const RoadManager, delete_mode: bool) void {
         for (self.roads.items) |road| {
             const is_highlighted = delete_mode and self.highlighted_road != null and self.highlighted_road.? == road;
@@ -31,6 +33,8 @@ pub const RoadManager = struct {
         }
     }
 
+    /// Function which creates the road object, its pointer, adds it to the list
+    /// and then also references that same road to the bounding nodes
     pub fn addRoad(self: *RoadManager, allocator: std.mem.Allocator, start: *Node, end: *Node) !void {
         const road: Road = .init(self.getNextID(), start, end);
         const road_ptr = try allocator.create(Road);
@@ -42,6 +46,7 @@ pub const RoadManager = struct {
         try end.referenceRoad(allocator, ref);
     }
 
+    /// Returns the id, and increases it by one; used for generating ID's for new entities
     fn getNextID(self: *RoadManager) usize {
         const id = self.next_id;
         self.next_id += 1;
@@ -49,6 +54,7 @@ pub const RoadManager = struct {
         return id;
     }
 
+    /// Deinits all the roads, clears them but not deiniting the list itself; also resets the next ID var
     pub fn clear(self: *RoadManager, allocator: std.mem.Allocator) void {
         for (self.roads.items) |road| {
             road.deinit(allocator);
@@ -57,6 +63,11 @@ pub const RoadManager = struct {
         self.next_id = 0;
     }
 
+    /// Removes the references of the road, from the nodes that bound that road
+    ///
+    /// Then it deinitialises the road and removes it from the list
+    ///
+    /// Will return an error if the road itself is not present in the list
     pub fn deleteRoad(self: *RoadManager, allocator: std.mem.Allocator, road_to_delete: *Road) !void {
         // unreference the road from its bounding functions
         road_to_delete.unreferenceNodes() catch |err| {

src/simulator.zig

@@ -6,13 +6,20 @@ const NodeManager = @import("infrastructure/node_manager.zig").NodeManager;
 const RoadManager = @import("infrastructure/road_manager.zig").RoadManager;
 
 pub const Simulator = struct {
+    /// allocator for convenience
     allocator: std.mem.Allocator,
+    /// 'class' tracking all the nodes (and appropriate functions)
     node_man: NodeManager,
+    /// 'class' tracking all the roads (and appropriate functions)
     road_man: RoadManager,
     // vars
+    /// Tracks whether next road will start building from the node the last road was built at
     auto_continue: bool,
+    /// Tracks whether the system will delete the road cursor is pointed at
+    /// (in such case, the road-to-be-deleted will also be highlighted)
     delete_mode: bool,
 
+    /// Constructor for convenience
     pub fn init(new_allocator: std.mem.Allocator) Simulator {
         return .{
             .allocator = new_allocator,
@@ -23,11 +30,13 @@ pub const Simulator = struct {
         };
     }
 
+    /// Deinitialisation of node and road objects
     pub fn deinit(self: *Simulator) !void {
         self.road_man.deinit(self.allocator);
         try self.node_man.deinit(self.allocator);
     }
 
+    /// Main draw function exposed to RayLib's loop
     pub fn draw(self: *const Simulator, pos: rl.Vector2) void {
         rl.clearBackground(c.BACKGROUND_COLOR);
 
@@ -35,15 +44,18 @@ pub const Simulator = struct {
         self.node_man.draw(pos);
     }
 
+    /// Update tick
     pub fn update(self: *Simulator, pos: rl.Vector2) void {
         self.road_man.update_highlighted_road(pos);
     }
 
+    /// Exposed input handling function exposed to raylib
     pub fn handleInput(self: *Simulator, pos: rl.Vector2) void {
         self.handleKeyboardInput();
         self.handleMouseInput(pos);
     }
 
+    /// Sub input handling function for keyboard input only
     fn handleKeyboardInput(self: *Simulator) void {
         self.auto_continue = rl.isKeyDown(.left_control);
         self.delete_mode = rl.isKeyDown(.left_shift);
@@ -53,10 +65,12 @@ pub const Simulator = struct {
         };
     }
 
+    /// Sub input handling function for mouse input only
     fn handleMouseInput(self: *Simulator, pos: rl.Vector2) void {
         if (rl.isMouseButtonReleased(.left)) self.leftClickEvent(pos);
     }
 
+    /// Function that handles functionality that executes upon left click
     fn leftClickEvent(self: *Simulator, pos: rl.Vector2) void {
         if (self.delete_mode) {
             self.delete_road() catch |err| {
@@ -67,6 +81,7 @@ pub const Simulator = struct {
         self.new_road(pos);
     }
 
+    /// User initiated road building functionality
     fn new_road(self: *Simulator, pos: rl.Vector2) void {
         const cur_node = self.node_man.getSelectedNode(self.allocator, pos) catch |err| {
             std.debug.panic("Failed to append the newly created node at pos ({d}, {d}) to node list: {}\n", .{
@@ -87,6 +102,7 @@ pub const Simulator = struct {
         self.node_man.temp_node = cur_node;
     }
 
+    /// User initiated road destroying functionality
     fn delete_road(self: *Simulator) !void {
         if (self.road_man.highlighted_road == null) return;
         const h_road = self.road_man.highlighted_road.?;
@@ -106,6 +122,7 @@ pub const Simulator = struct {
             try self.node_man.deleteNode(self.allocator, end_node);
     }
 
+    /// Clearing node and road lists without deinitialising them (only the children)
     fn clear(self: *Simulator) !void {
         self.road_man.clear(self.allocator);
         try self.node_man.clear(self.allocator);