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, 66 insertions, 3 deletions

diff --git a/src/builtins.zig b/src/builtins.zig
index 5818ff51..13f04859 100644
--- a/src/builtins.zig
+++ b/src/builtins.zig
@@ -431,6 +431,7 @@ comptime {
 
 // ---- the two acme verbs ----
 
+/// Look at its argument: open the file or address it names, else find the word, as a right click does.
 pub const Look = struct {
     pub const takes_arg = true;
     pub const requires_arg = true;
@@ -442,6 +443,7 @@ pub const Look = struct {
     }
 };
 
+/// Execute its argument as a middle click on it would, a builtin or a shell command.
 pub const Exec = struct {
     pub const takes_arg = true;
     pub const requires_arg = true;
@@ -517,8 +519,9 @@ fn warnModifiedIn(c: Ctx, asking: Pane.Discarding, which: Asked) bool {
     return modified;
 }
 
-/// acme's Exit (editors/acme/exec.c:892): quit, once warnModified has
-/// nothing to say.
+/// Quit the editor, refusing once while a pane holds unsaved text: an Exit
+/// with nothing edited since discards it (acme's Exit, editors/acme/exec.c:892,
+/// asking warnModified first).
 pub const Exit = struct {
     pub const scope: Scope = .session;
     pub fn run(c: Ctx) void {
@@ -580,6 +583,7 @@ pub const Kill = struct {
     }
 };
 
+/// Write the session's panes and layout to a dump file, for Restore.
 pub const Dump = struct {
     pub const scope: Scope = .session;
     pub fn run(c: Ctx) void {
@@ -587,6 +591,7 @@ pub const Dump = struct {
     }
 };
 
+/// Replace every pane with those of a dump file, the last one Dump wrote when bare.
 pub const Restore = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -622,6 +627,7 @@ pub const Restore = struct {
     }
 };
 
+/// Attach this terminal to a detached pardes session by name.
 pub const Attach = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -637,6 +643,7 @@ pub const Attach = struct {
     }
 };
 
+/// Detach this pardes from its terminal, leaving the session running.
 pub const Detach = struct {
     pub const scope: Scope = .session;
     pub const enabled = pardes.can_attach;
@@ -648,6 +655,7 @@ pub const Detach = struct {
     }
 };
 
+/// Mount another pardes's 9P tree under /n/<name>, given its dial address.
 pub const Mount = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -663,6 +671,7 @@ pub const Mount = struct {
     }
 };
 
+/// Unmount the 9P tree mounted under /n/<name>.
 pub const Unmount = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -679,6 +688,7 @@ pub const Unmount = struct {
 
 // ---- the message row ----
 
+/// Show its argument on this pane's message row.
 pub const Msg = struct {
     pub const takes_arg = true;
     pub const requires_arg = true;
@@ -691,6 +701,7 @@ pub const Msg = struct {
     }
 };
 
+/// Switch to the next bundled theme.
 pub const NextColor = struct {
     pub const scope: Scope = .session;
     pub fn run(c: Ctx) void {
@@ -698,6 +709,7 @@ pub const NextColor = struct {
     }
 };
 
+/// List the themes in a pane, each a word to click.
 pub const ThemeSel = struct {
     pub const scope: Scope = .session;
     pub const output: OutputTraits = .{ .name = config.themes_buffer, .steps = true, .commands = true };
@@ -706,6 +718,7 @@ pub const ThemeSel = struct {
     }
 };
 
+/// Load a theme from a file.
 pub const ThemeFile = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -719,6 +732,7 @@ pub const ThemeFile = struct {
     }
 };
 
+/// Write the bundled themes into the config directory's themes, to edit.
 pub const DumpThemes = struct {
     pub const scope: Scope = .session;
     pub const enabled = pardes.hosted;
@@ -733,6 +747,7 @@ pub const DumpThemes = struct {
     }
 };
 
+/// List the fonts in a pane, each a word to click.
 pub const FontSel = struct {
     pub const scope: Scope = .session;
     pub const output: OutputTraits = .{ .name = config.fonts_buffer, .steps = true, .commands = true };
@@ -745,6 +760,7 @@ pub const FontSel = struct {
     }
 };
 
+/// Show the declarations enclosing the top row at the pane's head, on or off.
 pub const TreeContext = struct {
     pub const enabled = pardes.syntax.enabled;
     pub const takes_arg = true;
@@ -769,6 +785,7 @@ pub const TreeContext = struct {
     }
 };
 
+/// Fit the PDF page to the pane by width or by height, flipping between them.
 pub const PdfFit = struct {
     pub const enabled = pardes.pdf_enabled;
     pub fn run(c: Ctx) void {
@@ -779,6 +796,7 @@ pub const PdfFit = struct {
     }
 };
 
+/// Tint the PDF page to the theme, or show it as printed, flipping between them.
 pub const PdfTint = struct {
     pub const enabled = pardes.pdf_enabled;
     pub fn run(c: Ctx) void {
@@ -789,6 +807,7 @@ pub const PdfTint = struct {
     }
 };
 
+/// List the PDF's sections in a pane, each a place to go.
 pub const PdfSections = struct {
     pub const output: OutputTraits = .{ .name = config.pdf_sections_buffer, .steps = true, .locations = true };
     pub const enabled = pardes.pdf_enabled;
@@ -823,6 +842,7 @@ pub const Ascii = struct {
 
 // ---- the system clipboard ----
 
+/// Copy the selection to the system clipboard.
 pub const ClipYank = struct {
     pub fn run(c: Ctx) void {
         edit.clipYank(c.p, c.pane, false);
@@ -837,18 +857,21 @@ pub const ClipYankMain = struct {
     }
 };
 
+/// Paste the system clipboard after the selection.
 pub const ClipPaste = struct {
     pub fn run(c: Ctx) void {
         edit.clipRequest(c.p, c.id, .after);
     }
 };
 
+/// Paste the system clipboard before the selection.
 pub const ClipPasteBefore = struct {
     pub fn run(c: Ctx) void {
         edit.clipRequest(c.p, c.id, .before);
     }
 };
 
+/// Replace the selection with the system clipboard.
 pub const ClipReplace = struct {
     pub fn run(c: Ctx) void {
         edit.clipRequest(c.p, c.id, .replace);
@@ -857,6 +880,7 @@ pub const ClipReplace = struct {
 
 // ---- panes and columns ----
 
+/// Write the pane's text to its file, or to the file its argument names.
 pub const Save = struct {
     pub const takes_arg = true;
     pub fn run(c: Ctx) void {
@@ -867,6 +891,7 @@ pub const Save = struct {
     }
 };
 
+/// Open an empty scratch pane, <dir>/+New, in this pane's directory.
 pub const New = struct {
     pub const output: OutputTraits = .{ .name = config.scratch_buffer, .doc = true, .saves = true };
     pub fn run(c: Ctx) void {
@@ -923,6 +948,7 @@ pub const Del = struct {
     }
 };
 
+/// Recolour a terminal's program colours to the theme, or show them as sent, flipping between them.
 pub const Filter = struct {
     pub fn run(c: Ctx) void {
         if (!c.pane.isTerminal()) return;
@@ -987,6 +1013,7 @@ pub const Undo = struct {
     }
 };
 
+/// Redo the last undone edit.
 pub const Redo = struct {
     pub fn run(c: Ctx) void {
         if (c.pane.file) |f| if (f.history.redo_len == 0) return c.p.setMessage(c.id, "Redo: nothing to redo");
@@ -1001,6 +1028,7 @@ pub const Collapse = struct {
     }
 };
 
+/// Close this column and its panes, refusing once over unsaved text.
 pub const Delcol = struct {
     pub fn run(c: Ctx) void {
         // The column of the tag it came from, else the pane's: a pane ctl's
@@ -1013,12 +1041,14 @@ pub const Delcol = struct {
     }
 };
 
+/// Close the pane, giving its rows to the pane above it.
 pub const DelAbove = struct {
     pub fn run(c: Ctx) void {
         Del.run(.{ .p = c.p, .pane = c.pane, .id = c.id, .txt = c.txt, .arg = "k" });
     }
 };
 
+/// Close the pane, giving its rows to the pane below it.
 pub const DelBelow = struct {
     pub fn run(c: Ctx) void {
         Del.run(.{ .p = c.p, .pane = c.pane, .id = c.id, .txt = c.txt, .arg = "j" });
@@ -1056,7 +1086,8 @@ pub const Tty9p = struct {
     }
 };
 
-/// Binds this terminal as a language's REPL, by the language's name as the
+/// Binds this terminal as a language's REPL, so an exec on that language's
+/// files is typed into it instead of run. The language is named as the
 /// syntax table has it: an exec made on the body of a file in that
 /// language -- a middle click, the execute key, a single word like `ls`
 /// as much as a selection -- and one made on this terminal's own body, is
@@ -1142,6 +1173,7 @@ pub const Joincol = struct {
     }
 };
 
+/// Open the tutor, a document to work through.
 pub const Tutor = struct {
     pub const scope: Scope = .session;
     pub fn run(c: Ctx) void {
@@ -1151,6 +1183,7 @@ pub const Tutor = struct {
     }
 };
 
+/// Open the help: every key and every builtin.
 pub const Help = struct {
     pub const scope: Scope = .session;
     pub const output: OutputTraits = .{ .name = config.help_buffer };
@@ -1159,6 +1192,7 @@ pub const Help = struct {
     }
 };
 
+/// Open the settings in effect, each a word to click.
 pub const Config = struct {
     pub const scope: Scope = .session;
     pub const output: OutputTraits = .{ .name = config.config_buffer };
@@ -1167,6 +1201,7 @@ pub const Config = struct {
     }
 };
 
+/// Set how location rows are drawn, or show how they are when bare.
 pub const LocationsConfig = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -1197,6 +1232,7 @@ pub const LocationsConfig = struct {
     }
 };
 
+/// Open the messages shown so far.
 pub const Messages = struct {
     pub const scope: Scope = .session;
     pub const output: OutputTraits = .{ .name = config.messages_buffer };
@@ -1215,6 +1251,7 @@ pub const Changelog = struct {
     }
 };
 
+/// Open the source of a panel transition or post shader, by name.
 pub const EffectCode = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -1242,6 +1279,7 @@ pub const Pet = struct {
     }
 };
 
+/// Open a minimap of the file in braille dots.
 pub const Mini = struct {
     pub const takes_arg = true;
     pub const output: OutputTraits = .{ .name = "Mini", .doc = true };
@@ -1254,6 +1292,7 @@ pub const Mini = struct {
 
 // ---- search ----
 
+/// List every place a pattern matches in the pane, in a +Search.
 pub const Find = struct {
     pub const takes_arg = true;
     pub const requires_arg = true;
@@ -1290,6 +1329,7 @@ pub const Grep = struct {
 // nothing above it reaches its column's tag, then the workspace's, and Down
 // comes back the same way. Left and Right walk the column tags.
 
+/// Move the keyboard to the pane, or column tag, to the left.
 pub const Left = struct {
     pub fn run(c: Ctx) void {
         if (c.p.header_focus) {
@@ -1300,6 +1340,7 @@ pub const Left = struct {
     }
 };
 
+/// Move the keyboard to the pane below, off a tag onto the pane under it.
 pub const Down = struct {
     pub fn run(c: Ctx) void {
         if (c.p.header_focus) {
@@ -1318,6 +1359,7 @@ pub const Down = struct {
     }
 };
 
+/// Move the keyboard to the pane above, and from a column's top pane to its tag.
 pub const Up = struct {
     pub fn run(c: Ctx) void {
         if (c.p.header_focus) {
@@ -1331,6 +1373,7 @@ pub const Up = struct {
     }
 };
 
+/// Move the keyboard to the pane, or column tag, to the right.
 pub const Right = struct {
     pub fn run(c: Ctx) void {
         if (c.p.header_focus) {
@@ -1359,6 +1402,7 @@ pub const Forward = struct {
     }
 };
 
+/// Go back to the last place jumped from in another pane.
 pub const Last = struct {
     pub fn run(c: Ctx) void {
         var i = c.p.njumps;
@@ -1374,6 +1418,7 @@ pub const Last = struct {
     }
 };
 
+/// List the places jumped from, each a place to go.
 pub const Jumplist = struct {
     pub const scope: Scope = .session;
     pub const output: OutputTraits = .{ .name = config.jumps_buffer, .steps = true, .locations = true };
@@ -1384,66 +1429,77 @@ pub const Jumplist = struct {
 
 // ---- the language group ----
 
+/// Ask the language server about the symbol under the cursor.
 pub const Hover = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .hover, "");
     }
 };
 
+/// List the language server's code actions for the cursor.
 pub const CodeAction = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .code_action, "");
     }
 };
 
+/// Select every reference to the symbol under the cursor.
 pub const SelectRefs = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .select_refs, "");
     }
 };
 
+/// List the file's symbols from the language server.
 pub const Symbols = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .document_symbols, "");
     }
 };
 
+/// List the file's diagnostics from the language server.
 pub const Diagnostics = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .diagnostics, "");
     }
 };
 
+/// List the workspace's diagnostics from the language server.
 pub const WsDiagnostics = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .workspace_diagnostics, "");
     }
 };
 
+/// List the callers of the function under the cursor.
 pub const Callers = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .incoming_calls, "");
     }
 };
 
+/// List the functions the function under the cursor calls.
 pub const Callees = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .outgoing_calls, "");
     }
 };
 
+/// List the supertypes of the type under the cursor.
 pub const Supertypes = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .supertypes, "");
     }
 };
 
+/// List the subtypes of the type under the cursor.
 pub const Subtypes = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .subtypes, "");
     }
 };
 
+/// Rename the symbol under the cursor everywhere, to its argument.
 pub const Rename = struct {
     pub const takes_arg = true;
     pub const requires_arg = true;
@@ -1454,6 +1510,7 @@ pub const Rename = struct {
     }
 };
 
+/// Search the workspace's symbols for its argument.
 pub const WsSymbols = struct {
     pub const takes_arg = true;
     pub const requires_arg = true;
@@ -1464,18 +1521,21 @@ pub const WsSymbols = struct {
     }
 };
 
+/// Show which language servers serve this file and their state.
 pub const Lspinfo = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .status, "");
     }
 };
 
+/// Explain how the last language server request was answered, step by step.
 pub const Lspwhy = struct {
     pub fn run(c: Ctx) void {
         c.p.lspRequest(c.id, .explain, "");
     }
 };
 
+/// Read the board memory at an address, into a pane.
 pub const Peek = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -1490,6 +1550,7 @@ pub const Peek = struct {
     }
 };
 
+/// Write a value to the board memory at an address.
 pub const Poke = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -1503,6 +1564,7 @@ pub const Poke = struct {
     }
 };
 
+/// Dump a range of the board memory in hex, into a pane.
 pub const Hexdump = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;
@@ -1517,6 +1579,7 @@ pub const Hexdump = struct {
     }
 };
 
+/// Read or set the board GPIO pins, into a pane.
 pub const Gpio = struct {
     pub const scope: Scope = .session;
     pub const takes_arg = true;