update docs

Author: zigster64

README.md

@@ -98,14 +98,16 @@ This code is interesting for the following reasons :
 
 - Its all written in Zig
 - It uses the excellent http.zig library https://github.com/karlseguin/http.zig
-- Note that the router is decorated inside the Game object ... the implications of this are that it is possible to create 'web components' using this
-zig/htmx approach that are all self contained, and can be imported into other projects, without having to know about connecting up routes. Interesting.
-- Uses SSE / Event Streams to keep it all realtime updates with pub/sub from multiple players
+- Its about as simple as doing the same thing in Go, there is really nothing too nasty required in the code.  
+- The router, and all the HTML contents is part of the Game object ... the implications of this are that it is possible to create 'web components' using this
+zig/htmx approach that are all self contained, and can be imported into other projects, without having to know about connecting up routes, or pulling in content. Interesting.
+- Uses SSE / Event Streams to keep it all realtime updates with pub/sub from multiple players. Is simple, and it works.
+- Demonstrates how to do threading, thread conditions / signalling, and using mutexes to make object updates thread safe.
 - No websockets needed
 - There is pretty much NO JAVASCRIPT on the frontend. It uses HTMX https://htmx.org ... which is an alternative approach to web clients, where the frontend is pure hypertext, and everything is done on the backend
 - There is a tiny bit of JS, to update the session ID, but im still thinking up a way of getting rid of that as well.
-- Uses std.fmt.print() as the templating engine.  I didnt know before, but you can used named tags inside the comptime format string, and use those to reference fields in the args param. 
-Actually makes for a half decent templating tool.
+- Uses std.fmt.print() as the templating engine.  I didnt know before, but you can use named tags inside the comptime format string, and use those to reference fields in the args param. 
+Actually makes for a half decent templating tool, without having to find and import a templating lib.
 
 
 ## HTMX thoughts
@@ -115,7 +117,10 @@ Yeah, its pretty cool, worth adding to your toolbelt. Not sure its really a 'rep
 What it is 100% excellent for though is for doing apps where there is a lot of shared state between users. (Like a turn based game !) In that case, doing everything on the server, and not having any state
 at all on the frontend to sync, is really ideal.  Its a good fit to this sort of problem.
 
+Its super robust. You can do horrible things like reboot the backend, or hard refresh the front end(s) ... and it maintains state without a hiccup, and without needing any exception handling code at all. 
+Very nice. It would be a nightmare doing this in react.
+
 There are some very complex things you could do with a turn-based-multiplayer-game type of model though (doesnt have to be a game even) And being able to do that without touching JS, or
 writing a tonne of code to synch state on the frontends is really nice.
 
-Its also a reasonable model for doing shared state between GUI frontends, just using the HTTP/SSE protocol too.
+Its also a reasonable model for doing shared state between GUI frontends, just using the HTTP/SSE protocol too. Its just HTTP requests, so the networking is totally portable.

src/game.zig

@@ -56,6 +56,7 @@ current_player: u8 = 0,
 prng: std.rand.Xoshiro256 = undefined,
 watcher: std.Thread = undefined,
 
+/// init returns a new Game object
 pub fn init(grid_x: u8, grid_y: u8, players: u8, needed_to_win: u8, flipper: u8) !Self {
     if (players > 8) {
         return Errors.GameError.TooManyPlayers;
@@ -80,11 +81,13 @@ pub fn init(grid_x: u8, grid_y: u8, players: u8, needed_to_win: u8, flipper: u8)
     return s;
 }
 
+/// startWatcher starts a thread to watch a given game
 pub fn startWatcher(self: *Self) !void {
     self.watcher = try std.Thread.spawn(.{}, Self.watcherThread, .{self});
     self.watcher.detach();
 }
 
+/// watcherThread loops forever, updating the state based upon expiring clocks
 fn watcherThread(self: *Self) void {
     while (true) {
         self.game_mutex.lock();
@@ -107,6 +110,8 @@ fn watcherThread(self: *Self) void {
     }
 }
 
+/// randPlayerMode will return a newly generated mode base of the % chance of things in the current game settings.
+/// use this to get a random mode for the next player's turn at the end of the turn.
 fn randPlayerMode(self: *Self) PlayerMode {
     const dice = (self.prng.random().int(u8) % (11)) * 10;
     if (dice < self.flipper_chance) {
@@ -118,6 +123,7 @@ fn randPlayerMode(self: *Self) PlayerMode {
     return .normal;
 }
 
+/// addRoutes sets up the routes and handlers used in this game object
 pub fn addRoutes(self: *Self, router: anytype) void {
     _ = self;
     router.get("/events", Self.events); // SSE event stream of game state changes
@@ -140,6 +146,7 @@ fn signal(self: *Self, ev: Event) void {
     std.log.info("signal event {}", .{ev});
 }
 
+/// reboot will reboot the server back to the vanilla state. Call this when everything has timed out, and we want to go right back to the original start
 fn reboot(self: *Self) void {
     self.game_mutex.lock();
     defer self.game_mutex.unlock();
@@ -153,6 +160,7 @@ fn reboot(self: *Self) void {
     self.signal(.init);
 }
 
+/// restart will set the game back to the setup phase, using the current Game parameters
 fn restart(self: *Self, req: *httpz.Request, res: *httpz.Response) !void {
     _ = req;
     self.game_mutex.lock();
@@ -163,7 +171,7 @@ fn restart(self: *Self, req: *httpz.Request, res: *httpz.Response) !void {
     self.signal(.init);
 }
 
-// clock() function emits an event of type clock with the current elapsed duration
+/// clock() function emits an event of type clock with the current number of remaining seconds until the next expiry time
 fn clock(self: *Self, stream: std.net.Stream) !void {
     self.game_mutex.lock();
     defer self.game_mutex.unlock();
@@ -183,13 +191,14 @@ fn getPlayer(self: *Self, req: *httpz.Request) u8 {
     return std.fmt.parseInt(u8, req.headers.get("x-player") orelse "", 10) catch @as(u8, 0);
 }
 
+/// zeroWing handler to get the background image
 fn zeroWing(self: *Self, req: *httpz.Request, res: *httpz.Response) !void {
     _ = self;
     _ = req;
     res.body = @embedFile("images/zero-wing-gradient.jpg");
 }
 
-// header() GET req returns the title header, depending on the game state
+/// header() GET req returns the title header, depending on the game state
 fn header(self: *Self, req: *httpz.Request, res: *httpz.Response) !void {
     const player = self.getPlayer(req);
     std.log.info("GET /header {} player {}", .{ self.state, player });
@@ -261,6 +270,7 @@ fn app(self: *Self, req: *httpz.Request, res: *httpz.Response) !void {
     }
 }
 
+/// calcBoardClass is used to get the CSS class for the board, based on whether it's this players turn, and what mode they are in
 fn calcBoardClass(self: *Self, player: u8) []const u8 {
     if (player == self.current_player) {
         return switch (self.player_mode) {
@@ -272,6 +282,7 @@ fn calcBoardClass(self: *Self, player: u8) []const u8 {
     return "inactive-player";
 }
 
+/// showBoard writes the current board to the HTTP response, based on the current player and what state they are in
 fn showBoard(self: *Self, player: u8, res: *httpz.Response) !void {
     const w = res.writer();
 
@@ -518,6 +529,8 @@ fn setup(self: *Self, req: *httpz.Request, res: *httpz.Response) !void {
     }
 }
 
+/// events GET handler is an SSE stream that emits events whenever the state changes
+/// or a clock event expires. Uses the Game.event_condition to synch with the outer threads
 fn events(self: *Self, req: *httpz.Request, res: *httpz.Response) !void {
     std.log.info("(event-source) GET /events {}", .{self.state});
     _ = req;