From 7dfd8def3f3c24e288b4d0b18f9f0281637c12ba Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 29 Sep 2026 06:22:15 -0300 Subject: 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 --- src/builtins.zig | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 66 insertions(+), 3 deletions(-) (limited to 'src/builtins.zig') 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/, 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/. 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, /+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; -- cgit v1.3