Fix inaccurate comments, add missing module docs

crdt-demo/runner.zig

@@ -1,3 +1,6 @@
+//! Demo runner. Spawns a Python HTTP server for static files and the
+//! CRDT server binary, then waits for the server to exit.
+
 const std = @import("std");
 
 pub fn main(init: std.process.Init) !void {

crdt-demo/src/demo.zig

@@ -1,9 +1,9 @@
-/// WASM module for collaborative text editing via RGA CRDT.
-///
-/// Exports functions callable from JavaScript for insert, remove, text
-/// readout, JSON state snapshot/merge, and memory management. Each
-/// replica gets a Handle with its own RGA and monotonic sequence
-/// counter. JS glue in www/demo.js drives a contenteditable editor.
+//! WASM module for collaborative text editing via RGA CRDT.
+//!
+//! Exports functions callable from JavaScript for insert, remove, text
+//! readout, JSON state snapshot/merge, and memory management. Each
+//! replica gets a Handle with its own RGA and monotonic sequence
+//! counter. JS glue in www/demo.js drives a contenteditable editor.
 const std = @import("std");
 const crdt = @import("crdt");
 

crdt-lib/src/mv_register.zig

@@ -1,6 +1,7 @@
 //! MV-Register (multi-value register) CRDT.
-//! Retains all concurrent writes; a value is dominated if its tag
-//! is less than another in both replica and seq.
+//! Retains all concurrent writes; within the same replica only the
+//! highest seq survives, so concurrent writes from different replicas
+//! are preserved.
 
 const std = @import("std");
 const Allocator = std.mem.Allocator;

crdt-server/src/main.zig

@@ -1,3 +1,6 @@
+//! CRDT server entry point. Parses CLI args, sets up the TCP listener,
+//! actor task, and I/O selector loop.
+
 const std = @import("std");
 const builtin = @import("builtin");
 const crdt_server = @import("crdt-server");

crdt-server/src/operation.zig

@@ -49,7 +49,8 @@ pub const SubChannel = struct {
 /// actor via the operation queue.
 pub const Operation = union(enum) {
     /// Create a new CRDT at `key` with initial `value`. The actor sets
-    /// `result_ptr` to `true` on success and fires `event` to wake the caller.
+    /// `result_ptr` to `CreateState.success` on success and fires
+    /// `event` to wake the caller.
     create: struct { key: RcStr, value: *crdt.Crdt, result_ptr: *Allocator.Error!CreateState, event: *Event },
     /// Merge `replica` into the CRDT at `key`. Idempotent — safe to replay.
     /// When `result_ptr` and `event` are provided, the actor signals `event`

crdt-server/src/state.zig

@@ -1,5 +1,5 @@
 //! Shared state between HTTP handlers and the actor task.
-//! Contains the lock-free operation queue and allocator.
+//! Contains the operation queue (bounded, mutex-guarded) and allocator.
 
 const std = @import("std");
 const Operation = @import("operation.zig").Operation;