Every builtin says what it does in /commands, and a test holds each to it

87 of the listed words had no description: settings have no doc comment
to read, so each now carries a one-sentence doc, and the builtins without
one got theirs. Exit's no longer names an internal function, and Repl's
first sentence is short enough to be read whole.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 23 insertions, 6 deletions

diff --git a/src/ninep/ctl.zig b/src/ninep/ctl.zig
index bed53473..de63c6aa 100644
--- a/src/ninep/ctl.zig
+++ b/src/ninep/ctl.zig
@@ -636,9 +636,9 @@ fn writeCommands(w: *std.Io.Writer) !void {
             var first = true;
             while (parts.next()) |v| : (first = false) try w.print("{s}{s}", .{ if (first) "" else ",", v });
         };
-        // Then ` -- ` and what it does, when its source says.
+        // Then ` -- ` and what it does: a setting's doc, else its source's.
         var summary_buf: [2048]u8 = undefined;
-        const summary = summaryOf(@tagName(b), &summary_buf);
+        const summary = if (config.Runtime.find(@tagName(b))) |setting| setting.doc else summaryOf(@tagName(b), &summary_buf);
         if (summary.len > 0) {
             // The sentence whole unless it is long, then cut between words.
             const kept = @import("../Messages.zig").clip(summary, 240);
@@ -1760,14 +1760,20 @@ test "a looked word is found in its own pane, next place after the dot, wrapping
     try testing.expect(listed);
 }
 
-test "each word's /commands description is its own doc comment's first sentence, no citation" {
+test "every word's /commands description is its own doc comment's first sentence, no citation" {
     const p = try withFile(testing.allocator, "x\n");
     defer p.deinit();
     const listed = rd(p, @intFromEnum(tree.TopFile.commands), 0, 1 << 16).bytes;
     for ([_][]const u8{
-        "\nRepl arg pane -- Binds this terminal as a language's REPL",
+        "\nRepl arg pane -- Binds this terminal as a language's REPL, so an exec on that language's files is typed into it instead of run.\n",
         "\nJoincol root -- Fold the active pane's column into the one on its right, keeping its panes.\n",
-        "\nExit root -- acme's Exit: quit, once warnModified has nothing to say.\n",
+        "\nExit root -- Quit the editor, refusing once while a pane holds unsaved text: an Exit with nothing edited since discards it.\n",
+        "\nColors arg root on,off -- Syntax colours in text panes, on or off.\n",
+        // fs.md's examples, as they read.
+        "\nNewcol root -- An empty column right of the keyboard's, its tag taking the keyboard.\n",
+        "\nSave arg pane -- Write the pane's text to its file, or to the file its argument names.\n",
+        "\nVerbose arg root on,off -- A builtin says its own name on the message row as it runs, on or off.\n",
+        "\nPlacement arg root acme,pardes -- Where a new pane goes: acme, as makenewwindow does, or pardes, the older rules.\n",
         "\nKill arg root -- acme's Kill: stop the commands pardes started",
     }) |row| try testing.expect(std.mem.indexOf(u8, listed, row) != null);
     try testing.expect(std.mem.indexOf(u8, listed, ".c:") == null);
@@ -1775,9 +1781,19 @@ test "each word's /commands description is its own doc comment's first sentence,
     // above its word's declaration in builtins.zig.
     const source = @embedFile("../builtins.zig");
     var it = std.mem.tokenizeScalar(u8, listed, '\n');
+    var undescribed: usize = 0;
     while (it.next()) |line| {
-        const dashes = std.mem.indexOf(u8, line, " -- ") orelse continue;
+        // Every builtin has one: a word nobody can look up is no use.
+        const dashes = std.mem.indexOf(u8, line, " -- ") orelse {
+            std.debug.print("no doc comment: {s}\n", .{line});
+            undescribed += 1;
+            continue;
+        };
         const word = line[0 .. std.mem.indexOfScalar(u8, line, ' ').?];
+        if (config.Runtime.find(word)) |setting| {
+            try testing.expect(std.mem.endsWith(u8, line, setting.doc));
+            continue;
+        }
         var needle: [64]u8 = undefined;
         const at = std.mem.indexOf(u8, source, try std.fmt.bufPrint(&needle, "\npub const {s} = struct", .{word})).?;
         const said = std.mem.trimEnd(u8, line[dashes + 4 ..], "…");
@@ -1786,6 +1802,7 @@ test "each word's /commands description is its own doc comment's first sentence,
         const block_start = std.mem.lastIndexOf(u8, source[0..at], "\n\n") orelse 0;
         try testing.expect(std.mem.indexOf(u8, source[block_start..at], head) != null);
     }
+    try testing.expectEqual(0, undescribed);
 }
 
 test "Newcol at the column cap fails the write and says the cap" {