From 89f036f9c53555d596d584e460fa63778f12dc80 Mon Sep 17 00:00:00 2001
From: Jeeves <guydoodlesdev@gmail.com>
Date: Tue, 26 Mar 2024 09:02:10 -0600
Subject: [PATCH] basic doc comments

---
 src/main.zig | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/src/main.zig b/src/main.zig
index 6603f4a..b94ec24 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -17,10 +17,10 @@ pub fn main() !void {
     });
     defer listener.deinit();
 
-    try listener.router.addRoute("/", &handle);
-    try listener.router.addRoute("/error", &handleError);
-    try listener.router.addRoute("//pee", &handleError);
-    try listener.router.addRoute("/error/*", &handleError);
+    try listener.router.putRoute("/", &handle);
+    try listener.router.putRoute("/error", &handleError);
+    try listener.router.putRoute("//pee", &handleError);
+    try listener.router.putRoute("/error/*", &handleError);
 
     try listener.listen();
 }
@@ -34,11 +34,14 @@ pub fn handleError(event: *Listener.Event) anyerror!void {
 }
 
 pub const Listener = struct {
-    address: net.Address,
     allocator: mem.Allocator,
 
+    /// Listen address
+    address: net.Address,
+    /// Main router
     router: Router,
 
+    /// Initialization options
     pub const Options = struct {
         address: net.Address,
         allocator: mem.Allocator,
@@ -57,6 +60,7 @@ pub const Listener = struct {
         self.router.deinit();
     }
 
+    /// Listens for new connections forever
     pub fn listen(self: *Listener) !void {
         var arena = heap.ArenaAllocator.init(self.allocator);
         defer arena.deinit();
@@ -111,6 +115,7 @@ pub const Listener = struct {
         });
     }
 
+    /// Single request-response context
     pub const Event = struct {
         req: Request,
         res: Response,
@@ -129,6 +134,8 @@ pub const Listener = struct {
 
     pub const HandlerFn = *const fn (event: *Event) anyerror!void;
 
+    /// HTTP router
+    /// Some code taken from [unjs/radix3](https://github.com/unjs/radix3)
     pub const Router = struct {
         allocator: mem.Allocator,
 
@@ -156,11 +163,12 @@ pub const Listener = struct {
         }
 
         pub fn handle(self: *Router, event: *Listener.Event) !void {
-            const handlerFn = try self.route(event.req.uri.path);
+            const handlerFn = try self.getRoute(event.req.uri.path);
             try handlerFn(event);
         }
 
-        pub fn addRoute(self: *Router, path: []const u8, handler: HandlerFn) !void {
+        /// Insert a route if the path is not already present, otherwise overwrite preexisting HandlerFn.
+        pub fn putRoute(self: *Router, path: []const u8, handler: HandlerFn) !void {
             // std.debug.print("\npath {s}\n", .{path});
             var is_static_route = true;
             var sections = mem.splitScalar(u8, path, '/');
@@ -217,7 +225,8 @@ pub const Listener = struct {
             if (is_static_route) try self.static_routes.put(path, node);
         }
 
-        pub fn route(self: *Router, path: []const u8) !HandlerFn {
+        /// Get the HandlerFn associated with path, otherwise get root_handler.
+        pub fn getRoute(self: *Router, path: []const u8) !HandlerFn {
             if (self.static_routes.get(path)) |rt| return rt.handler;
 
             var params = std.StringHashMap([]const u8).init(self.allocator);
@@ -271,7 +280,7 @@ pub const Listener = struct {
             return self.root_node.handler;
         }
 
-        pub const Node = struct {
+        const Node = struct {
             type: Type,
             max_depth: usize, // TODO: what is best here
             parent: ?*Node = null,