Add doc comments to public APIs

Author: ItsMeSamey

build.zig

@@ -1,5 +1,6 @@
 const std = @import("std");
 
+/// Configures build artifacts, helper steps, and test/check pipelines.
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});

src/main.zig

@@ -13,6 +13,7 @@ pub fn bufferedPrint() !void {
     try stdout.flush();
 }
 
+/// Demo executable entrypoint that parses a tiny document and prints one query result.
 pub fn main() !void {
     try bufferedPrint();
 

tools/bench/bench.zig

@@ -25,6 +25,7 @@ fn parseDocForBench(noalias doc: *Document, input: []u8, mode: BenchMode) !void
     }
 }
 
+/// Runs a built-in synthetic parse/query workload and prints elapsed ns.
 pub fn runSynthetic() !void {
     const alloc = std.heap.page_allocator;
 
@@ -51,6 +52,7 @@ pub fn runSynthetic() !void {
     std.debug.print("query ns: {d}\n", .{query_end - query_start});
 }
 
+/// Benchmarks parse throughput for one fixture and mode; returns total elapsed ns.
 pub fn runParseFile(path: []const u8, iterations: usize, mode: BenchMode) !u64 {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
     defer _ = gpa.deinit();
@@ -89,6 +91,7 @@ pub fn runParseFile(path: []const u8, iterations: usize, mode: BenchMode) !u64 {
     return @intCast(end - start);
 }
 
+/// Benchmarks runtime selector parse cost; returns total elapsed ns.
 pub fn runQueryParse(selector: []const u8, iterations: usize) !u64 {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
     defer _ = gpa.deinit();
@@ -108,6 +111,7 @@ pub fn runQueryParse(selector: []const u8, iterations: usize) !u64 {
     return @intCast(end - start);
 }
 
+/// Benchmarks runtime query execution over a pre-parsed document.
 pub fn runQueryMatch(path: []const u8, selector: []const u8, iterations: usize, mode: BenchMode) !u64 {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
     defer _ = gpa.deinit();
@@ -133,6 +137,7 @@ pub fn runQueryMatch(path: []const u8, selector: []const u8, iterations: usize,
     return @intCast(end - start);
 }
 
+/// Benchmarks cached-selector query execution over a pre-parsed document.
 pub fn runQueryCached(path: []const u8, selector: []const u8, iterations: usize, mode: BenchMode) !u64 {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
     defer _ = gpa.deinit();
@@ -163,6 +168,7 @@ pub fn runQueryCached(path: []const u8, selector: []const u8, iterations: usize,
     return @intCast(end - start);
 }
 
+/// CLI entrypoint for parser/query benchmarking utilities.
 pub fn main() !void {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
     defer _ = gpa.deinit();

tools/common.zig

@@ -1,14 +1,17 @@
 const std = @import("std");
 
+/// Returns true when `path` exists relative to the current working directory.
 pub fn fileExists(path: []const u8) bool {
     std.fs.cwd().access(path, .{}) catch return false;
     return true;
 }
 
+/// Creates `path` and any missing parent directories.
 pub fn ensureDir(path: []const u8) !void {
     try std.fs.cwd().makePath(path);
 }
 
+/// Renders argv-like tokens as a shell-style debug string.
 pub fn joinArgs(alloc: std.mem.Allocator, argv: []const []const u8) ![]u8 {
     var out = std.ArrayList(u8).empty;
     errdefer out.deinit(alloc);
@@ -26,6 +29,7 @@ pub fn joinArgs(alloc: std.mem.Allocator, argv: []const []const u8) ![]u8 {
     return out.toOwnedSlice(alloc);
 }
 
+/// Runs a child process inheriting stdio, returning error on non-zero exit.
 pub fn runInherit(alloc: std.mem.Allocator, argv: []const []const u8, cwd: ?[]const u8) !void {
     const pretty = try joinArgs(alloc, argv);
     defer alloc.free(pretty);
@@ -44,6 +48,7 @@ pub fn runInherit(alloc: std.mem.Allocator, argv: []const []const u8, cwd: ?[]co
     }
 }
 
+/// Runs a child process and returns combined stdout/stderr output.
 pub fn runCaptureCombined(alloc: std.mem.Allocator, argv: []const []const u8, cwd: ?[]const u8) ![]u8 {
     const res = try std.process.Child.run(.{
         .allocator = alloc,
@@ -68,6 +73,7 @@ pub fn runCaptureCombined(alloc: std.mem.Allocator, argv: []const []const u8, cw
     return out.toOwnedSlice(alloc);
 }
 
+/// Runs a child process and returns trimmed stdout output.
 pub fn runCaptureStdout(alloc: std.mem.Allocator, argv: []const []const u8, cwd: ?[]const u8) ![]u8 {
     const res = try std.process.Child.run(.{
         .allocator = alloc,
@@ -84,6 +90,7 @@ pub fn runCaptureStdout(alloc: std.mem.Allocator, argv: []const []const u8, cwd:
     return alloc.dupe(u8, std.mem.trim(u8, res.stdout, " \r\n\t"));
 }
 
+/// Parses the last decimal integer token found in `text`.
 pub fn parseLastInt(text: []const u8) !u64 {
     var i: usize = text.len;
     while (i > 0) : (i -= 1) {
@@ -96,6 +103,7 @@ pub fn parseLastInt(text: []const u8) !u64 {
     return std.fmt.parseInt(u64, text[start..i], 10);
 }
 
+/// Returns median value from `vals` (upper median for even length).
 pub fn medianU64(alloc: std.mem.Allocator, vals: []const u64) !u64 {
     if (vals.len == 0) return error.EmptyInput;
     const copy = try alloc.dupe(u64, vals);
@@ -104,16 +112,19 @@ pub fn medianU64(alloc: std.mem.Allocator, vals: []const u64) !u64 {
     return copy[copy.len / 2];
 }
 
+/// Writes `bytes` to `path`, truncating any existing file.
 pub fn writeFile(path: []const u8, bytes: []const u8) !void {
     const file = try std.fs.cwd().createFile(path, .{ .truncate = true });
     defer file.close();
     try file.writeAll(bytes);
 }
 
+/// Reads an entire file into allocator-owned memory.
 pub fn readFileAlloc(alloc: std.mem.Allocator, path: []const u8) ![]u8 {
     return try std.fs.cwd().readFileAlloc(alloc, path, std.math.maxInt(usize));
 }
 
+/// Returns current UNIX timestamp in seconds.
 pub fn nowUnix() i64 {
     return std.time.timestamp();
 }

tools/scripts.zig

@@ -2630,6 +2630,7 @@ fn usage() void {
     , .{});
 }
 
+/// CLI entrypoint for repository maintenance, benchmarking, and conformance tasks.
 pub fn main() !void {
     var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
     defer arena.deinit();

tools/suite_runner.zig

@@ -165,6 +165,7 @@ fn usage() noreturn {
     std.process.exit(2);
 }
 
+/// CLI entrypoint used by external-suite tooling to execute selector/parser probes.
 pub fn main() !void {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
     defer _ = gpa.deinit();