ondemand: document read_buf_cap

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 =

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 must 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,

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 =