From df85b7eb5c69c794a35031259200457fdcc885f8 Mon Sep 17 00:00:00 2001
From: zachir <zachir@librem.one>
Date: Sat, 23 Mar 2024 17:59:13 -0500
Subject: Add doc comments

This is to document the functions, constants, and what they do/how they
work/how they can fail.
---
 src/main.zig | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/src/main.zig b/src/main.zig
index 47d7f7e..ecc14a4 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -1,4 +1,11 @@
+//! zhttpd is a very basic http server written in Zig, by ZachIR. It is single
+//! threaded, and does not yet support every error code, nor does it support
+//! TLS/SSL, but it does display web pages.
+
 const std = @import("std");
+
+/// zhttpd relies on mime in addition to std, which is included as made by
+/// andrewrk at https://github.com/andrewrk/mime.git
 const mime = @import("mime/mime.zig");
 
 const Address = std.net.Address;
@@ -13,11 +20,23 @@ const mem = std.mem;
 const bufferedReader = std.io.bufferedReader;
 const getcwd = std.os.getcwd;
 
+/// The server has a hardcoded address and port of 127.0.0.1:8080
+/// The path requested for a file has the limit of fs.MAX_PATH_BYTES, which is
+/// the maxmimum length for a file path in the OS
+/// The maximum file size is 1 << 21, aka (1 * 2^20), which is 2 MB.
 const server_addr = "127.0.0.1";
 const server_port = 8080;
 const MAX_PATH_BYTES = fs.MAX_PATH_BYTES;
 const BUFFER_LIMIT = 1 << 21;
 
+/// read_files() reads the file to a provided buffer, and returns the number of
+/// bytes read.
+/// read_files() can fail from fmt.allocPrint(), fs.cwd().openFile(),
+/// file.stat(), and file.readAll()
+/// fmt.allocPrint() will return an AllocPrintError
+/// fs.cwd().openFile() will return a File.OpenError
+/// file.stat() will return a StatError
+/// file.readAll() will return a ReadError
 fn read_files(target: []const u8, buffer: []u8, allocator: mem.Allocator) !usize {
     var file_path = try allocator.alloc(u8, MAX_PATH_BYTES);
     defer allocator.free(file_path);
@@ -47,6 +66,21 @@ fn read_files(target: []const u8, buffer: []u8, allocator: mem.Allocator) !usize
     }
 }
 
+/// handle_request() handles the requests from the server and, if necessary,
+/// calls read_files to read requested files.
+/// handle_request() can fail from response.headers.append(), response.do(),
+/// response.writeAll(), response.finish(), and read_files()
+/// response.headers.append() does not define what error types it will return
+/// response.do() does not define what error types it will return
+/// response.writeAll() will return a WriteError
+/// response.finish() will return a FinishError
+/// read_files() does not define what error types it will return
+/// handle_request handles the following status codes:
+/// - 200 OK
+/// - 403 Forbidden
+/// - 404 Not Found
+/// - 413 Payload Too Large
+/// - 414 URI Too Long
 fn handle_request(response: *http.Server.Response, allocator: mem.Allocator) !void {
     // Log the request details
     log.info("{s} {s} {s}", .{ @tagName(response.request.method), @tagName(response.request.version), response.request.target });
@@ -151,6 +185,14 @@ fn handle_request(response: *http.Server.Response, allocator: mem.Allocator) !vo
     }
 }
 
+/// run_server() accepts inputs from the server, and passes the requests on to
+/// handle_request().
+/// run_server() can fail from server.accept(), response.wait(), and
+/// handle_request().
+/// server.accept() will return an AcceptError
+/// resonse.wait() will return a WaitError
+/// run_server() handles the following error codes:
+/// - 500 (Internal Server Error)
 fn run_server(server: *http.Server, allocator: mem.Allocator) !void {
     outer: while (true) {
         // Accept incoming connection
@@ -178,6 +220,12 @@ fn run_server(server: *http.Server, allocator: mem.Allocator) !void {
     }
 }
 
+/// main() initializes the server, parses the IP and port, and beings
+/// run_server.
+/// main() can fail exit from server.listen() and run_server(), which do not
+/// specify the error types they can return.
+/// main() also defines the allocator used by everything else, the
+/// heap.GeneralPurposeAllocator.
 pub fn main() !void {
     // Define allocator
     var gpa = heap.GeneralPurposeAllocator(.{}){};
-- 
cgit v1.2.3