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, 44 insertions, 42 deletions

diff --git a/src/config.zig b/src/config.zig
index b7662f1a..2fa6f89d 100644
--- a/src/config.zig
+++ b/src/config.zig
@@ -917,6 +917,8 @@ pub const Runtime = struct {
     pub const Setting = struct {
         word: []const u8,
         action: Action,
+        /// What it does, one sentence: /commands lists it after the word.
+        doc: []const u8,
         availability: ?Capability = null,
 
         pub fn enabled(setting: Setting, capabilities: Capabilities) bool {
@@ -929,48 +931,48 @@ pub const Runtime = struct {
 
     // The builtin registry and Config report share this command table.
     pub const settings = [_]Setting{
-        .{ .word = "Colors", .action = .{ .toggle = .colors } },
-        .{ .word = "Wrap", .action = .{ .toggle = .wrap } },
-        .{ .word = "TreeContextTagStyle", .action = .{ .toggle = .tree_context_tag_style } },
-        .{ .word = "Tagbottom", .action = .{ .toggle = .tag_bottom } },
-        .{ .word = "Debug", .action = .{ .toggle = .debug } },
-        .{ .word = "FocusTint", .action = .{ .toggle = .focus_tint } },
-        .{ .word = "SyntaxBold", .action = .{ .toggle = .syntax_bold } },
-        .{ .word = "Verbose", .action = .{ .toggle = .verbose } },
-        .{ .word = "MessageAnimation", .action = .{ .toggle = .message_animation } },
-        .{ .word = "Ligatures", .action = .{ .toggle = .ligatures }, .availability = .ligatures },
-        .{ .word = "CursorBlink", .action = .{ .toggle = .cursor_blink }, .availability = .lift },
-        .{ .word = "Lift", .action = .lift, .availability = .lift },
-        .{ .word = "Motion", .action = .motion },
-        .{ .word = "InactiveDim", .action = .inactive_dim },
-        .{ .word = "GripWidth", .action = .grip_width, .availability = .lift },
-        .{ .word = "MessageLinger", .action = .{ .message_ms = .linger } },
-        .{ .word = "MessageFall", .action = .{ .message_ms = .fall } },
-        .{ .word = "MessageDissolve", .action = .{ .message_ms = .dissolve } },
-        .{ .word = "DumpDir", .action = .dump_dir },
-        .{ .word = "Theme", .action = .theme },
-        .{ .word = "Shell", .action = .shell },
-        .{ .word = "Font", .action = .font, .availability = .font_picker },
-        .{ .word = "TaglineSize", .action = .tagline_size, .availability = .font_picker },
-        .{ .word = "WindowOpacity", .action = .window_opacity, .availability = .window_opacity },
-        .{ .word = "WindowBlur", .action = .window_blur, .availability = .window_blur },
-        .{ .word = "PanelSlide", .action = .{ .transition = .slide }, .availability = .panel_transitions },
-        .{ .word = "PanelZoom", .action = .{ .transition = .zoom }, .availability = .panel_transitions },
-        .{ .word = "PanelDissolve", .action = .{ .transition = .dissolve }, .availability = .panel_transitions },
-        .{ .word = "PanelAscii", .action = .{ .transition = .ascii }, .availability = .panel_transitions },
-        .{ .word = "PanelVertical", .action = .{ .transition = .vertical }, .availability = .panel_transitions },
-        .{ .word = "PanelEdges", .action = .{ .transition = .edges }, .availability = .panel_transitions },
-        .{ .word = "PanelFall", .action = .{ .transition = .fall }, .availability = .panel_transitions },
-        .{ .word = "PanelWave", .action = .{ .transition = .wave }, .availability = .panel_transitions },
-        .{ .word = "PanelCurtain", .action = .{ .transition = .curtain }, .availability = .panel_transitions },
-        .{ .word = "PanelScramble", .action = .{ .transition = .scramble }, .availability = .panel_transitions },
-        .{ .word = "PanelType", .action = .{ .transition = .typewriter }, .availability = .panel_transitions },
-        .{ .word = "Crt", .action = .{ .scene = .crt }, .availability = .scene_shaders },
-        .{ .word = "Shader", .action = .shader, .availability = .scene_shaders },
-        .{ .word = "ShaderAnimation", .action = .shader_animation, .availability = .scene_shaders },
-        .{ .word = "Placement", .action = .{ .choice = .placement } },
-        .{ .word = "BootShell", .action = .{ .choice = .boot_shell } },
-        .{ .word = "LookWord", .action = .{ .choice = .look_word } },
+        .{ .word = "Colors", .action = .{ .toggle = .colors }, .doc = "Syntax colours in text panes, on or off." },
+        .{ .word = "Wrap", .action = .{ .toggle = .wrap }, .doc = "Long lines wrap onto the next row, on or off." },
+        .{ .word = "TreeContextTagStyle", .action = .{ .toggle = .tree_context_tag_style }, .doc = "A pane's TreeContext rows draw in the tag's style, on or off." },
+        .{ .word = "Tagbottom", .action = .{ .toggle = .tag_bottom }, .doc = "Each pane's tag goes at its foot rather than its head, on or off." },
+        .{ .word = "Debug", .action = .{ .toggle = .debug }, .doc = "A small box of frame statistics at the top right, on or off." },
+        .{ .word = "FocusTint", .action = .{ .toggle = .focus_tint }, .doc = "The focused pane's and column's tags are tinted, on or off." },
+        .{ .word = "SyntaxBold", .action = .{ .toggle = .syntax_bold }, .doc = "Keywords and the like are drawn bold, on or off." },
+        .{ .word = "Verbose", .action = .{ .toggle = .verbose }, .doc = "A builtin says its own name on the message row as it runs, on or off." },
+        .{ .word = "MessageAnimation", .action = .{ .toggle = .message_animation }, .doc = "A message falls into its row and dissolves out of it, on or off." },
+        .{ .word = "Ligatures", .action = .{ .toggle = .ligatures }, .availability = .ligatures, .doc = "A font's programming ligatures draw across their cells, on or off." },
+        .{ .word = "CursorBlink", .action = .{ .toggle = .cursor_blink }, .availability = .lift, .doc = "The cursor blinks, solid while typing, on or off." },
+        .{ .word = "Lift", .action = .lift, .availability = .lift, .doc = "How the focused pane stands off the page: off, shadow, rim or auto." },
+        .{ .word = "Motion", .action = .motion, .doc = "How animations move: off, crisp, smooth, bouncy or playful." },
+        .{ .word = "InactiveDim", .action = .inactive_dim, .doc = "Fade the unfocused panes' text by a percentage, 0 through 100, 0 off." },
+        .{ .word = "GripWidth", .action = .grip_width, .availability = .lift, .doc = "The grip and scrollbar width, as a percent of the theme's rail." },
+        .{ .word = "MessageLinger", .action = .{ .message_ms = .linger }, .doc = "How long, in milliseconds, a message stays after what dismisses it." },
+        .{ .word = "MessageFall", .action = .{ .message_ms = .fall }, .doc = "How long, in milliseconds, a message takes to fall into its row." },
+        .{ .word = "MessageDissolve", .action = .{ .message_ms = .dissolve }, .doc = "How long, in milliseconds, a message takes to dissolve." },
+        .{ .word = "DumpDir", .action = .dump_dir, .doc = "The directory Dump writes to and a relative Restore reads from; bare, the default." },
+        .{ .word = "Theme", .action = .theme, .doc = "Switch to the named theme." },
+        .{ .word = "Shell", .action = .shell, .doc = "The shell new terminals run; bare, the login shell." },
+        .{ .word = "Font", .action = .font, .availability = .font_picker, .doc = "The body font, by name or path, and its size." },
+        .{ .word = "TaglineSize", .action = .tagline_size, .availability = .font_picker, .doc = "Scale the tag font, a percentage." },
+        .{ .word = "WindowOpacity", .action = .window_opacity, .availability = .window_opacity, .doc = "The window's opacity, a percentage." },
+        .{ .word = "WindowBlur", .action = .window_blur, .availability = .window_blur, .doc = "The blur behind a translucent window, a radius." },
+        .{ .word = "PanelSlide", .action = .{ .transition = .slide }, .availability = .panel_transitions, .doc = "Panes slide in and out as they open and close, on or off." },
+        .{ .word = "PanelZoom", .action = .{ .transition = .zoom }, .availability = .panel_transitions, .doc = "Panes zoom in and out as they open and close, on or off." },
+        .{ .word = "PanelDissolve", .action = .{ .transition = .dissolve }, .availability = .panel_transitions, .doc = "Panes dissolve in and out as they open and close, on or off." },
+        .{ .word = "PanelAscii", .action = .{ .transition = .ascii }, .availability = .panel_transitions, .doc = "Panes open and close through a scatter of ASCII, on or off." },
+        .{ .word = "PanelVertical", .action = .{ .transition = .vertical }, .availability = .panel_transitions, .doc = "Panes open and close with a vertical wipe, on or off." },
+        .{ .word = "PanelEdges", .action = .{ .transition = .edges }, .availability = .panel_transitions, .doc = "Panes open and close from their edges, on or off." },
+        .{ .word = "PanelFall", .action = .{ .transition = .fall }, .availability = .panel_transitions, .doc = "Panes fall into place as they open, on or off." },
+        .{ .word = "PanelWave", .action = .{ .transition = .wave }, .availability = .panel_transitions, .doc = "Panes open and close in a wave, on or off." },
+        .{ .word = "PanelCurtain", .action = .{ .transition = .curtain }, .availability = .panel_transitions, .doc = "Panes open and close like a curtain, on or off." },
+        .{ .word = "PanelScramble", .action = .{ .transition = .scramble }, .availability = .panel_transitions, .doc = "Panes open and close through scrambled text, on or off." },
+        .{ .word = "PanelType", .action = .{ .transition = .typewriter }, .availability = .panel_transitions, .doc = "Panes type themselves in as they open, on or off." },
+        .{ .word = "Crt", .action = .{ .scene = .crt }, .availability = .scene_shaders, .doc = "The bundled CRT post pass over the window, on or off." },
+        .{ .word = "Shader", .action = .shader, .availability = .scene_shaders, .doc = "A Shadertoy file into the post chain, or out of it; off empties the chain." },
+        .{ .word = "ShaderAnimation", .action = .shader_animation, .availability = .scene_shaders, .doc = "When the post chain animates on its own: off, on (while focused) or always." },
+        .{ .word = "Placement", .action = .{ .choice = .placement }, .doc = "Where a new pane goes: acme, as makenewwindow does, or pardes, the older rules." },
+        .{ .word = "BootShell", .action = .{ .choice = .boot_shell }, .doc = "A document dropped where a lone untouched shell stands: keep the shell, or replace it." },
+        .{ .word = "LookWord", .action = .{ .choice = .look_word }, .doc = "A plain word looked at: search selects its next place in the pane, list lists every place in a +Search." },
     };
 
     pub fn find(name: []const u8) ?Setting {