Comments to describe each functionality in-depth

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);