From 4aebcab8b3eb56eae212adbba7eea2acd51aebef Mon Sep 17 00:00:00 2001
From: Travis Staloch <1562827+travisstaloch@users.noreply.github.com>
Date: Sun, 2 Jun 2024 15:38:13 -0700
Subject: [PATCH] ondemand: document read_buf_cap

---
 README.md        |  4 +++-
 src/ondemand.zig | 15 +++++++++++++--
 src/tests.zig    |  2 ++
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index f8fc6b4..8b52efb 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ No fallback for unsupported CPUs is provided yet.
 # zig compiler support
 The main branch is meant to compile with zig's master branch.  It is tested weekly on linux, windows and macos. 
 
-The zig-0.10.0 branch works with zig's 0.10.0 release.  It is tested on linux only when it is updated.
+For older compiler versions, use a [tagged version](https://github.com/travisstaloch/simdjzon/tags).
 
 # usage
 ```console
@@ -92,6 +92,8 @@ test "at_pointer" {
 }
 
 const ondemand = @import("ondemand.zig");
+// ondemand api users must specify `pub const read_buf_cap = N;` in their
+// root source file.  In tests, this defaults to `std.mem.page_size`. 
 test "ondemand get with struct" {
     const S = struct { a: struct { b: []const u8 } };
     const input =
diff --git a/src/ondemand.zig b/src/ondemand.zig
index 5ce5e47..2241351 100644
--- a/src/ondemand.zig
+++ b/src/ondemand.zig
@@ -12,13 +12,23 @@ const atom_parsing = @import("atom_parsing.zig");
 const CharUtils = string_parsing.CharUtils;
 const root = @import("root");
 const builtin = @import("builtin");
-// TODO: document that this is configurable in root
+
+/// Users may specify `pub const read_buf_cap = N;` in their root source file.
+/// This sets the static `ondemand.Parser.read_buf` size.  `read_buf` is
+/// where chunks of json source are stored.  recommended `std.mem.page_size`.
+/// Larger `read_buf_cap` may improve performance for large json files.
 pub const READ_BUF_CAP = if (@hasDecl(root, "read_buf_cap"))
     root.read_buf_cap
 else if (builtin.is_test)
     mem.page_size
 else
-    unreachable;
+    @compileError(
+        \\root source file is missing a `pub const read_buf_cap` declaration.
+        \\This sets the static `ondemand.Parser.read_buf` size.  `read_buf` is
+        \\where chunks of json source are stored.  recommended
+        \\`std.mem.page_size`.
+        \\
+    );
 
 pub const Value = struct {
     iter: ValueIterator,
@@ -1318,6 +1328,7 @@ pub const Parser = struct {
     parser: dom.Parser,
     src: *std.io.StreamSource,
     end_pos: u32,
+    /// buffer used for reading from `src`
     read_buf: [READ_BUF_CAP]u8 = undefined,
     /// result of src.read() - number of bytes read from src
     read_buf_len: u16 = 0,
diff --git a/src/tests.zig b/src/tests.zig
index dd879ba..d517c2a 100644
--- a/src/tests.zig
+++ b/src/tests.zig
@@ -483,6 +483,8 @@ test "dom object key iterator" {
 }
 
 // const ondemand = simdjzon.ondemand;
+// ondemand api users must specify `pub const read_buf_cap = N;` in their
+// root source file.  In tests, this defaults to `std.mem.page_size`.
 test "ondemand get with struct" {
     const S = struct { a: struct { b: []const u8 } };
     const input =