docs: improve binding actions documentation clarity and consistency

- Add consistent format for action documentation
- Standardize argument descriptions and example format
- Add missing documentation actions descriptions
- Make platform limitations explicit

src/input/Binding.zig

@@ -193,188 +193,286 @@ pub fn lessThan(_: void, lhs: Binding, rhs: Binding) bool {
 
 /// The set of actions that a keybinding can take.
 pub const Action = union(enum) {
-    /// Ignore this key combination, don't send it to the child process, just
+    /// Ignore this key combination, don't send it to the child process.
-    /// black hole it.
     ignore: void,
 
-    /// This action is used to flag that the binding should be removed from
+    /// Remove this binding from the set. This should never exist in an active set
-    /// the set. This should never exist in an active set and `set.put` has an
+    /// and `set.put` has an assertion to verify this.
-    /// assertion to verify this.
     unbind: void,
 
-    /// Send a CSI sequence. The value should be the CSI sequence without the
+    /// Send a CSI sequence without the CSI header (ESC ] or \x1b]).
-    /// CSI header (`ESC ]` or `\x1b]`).
+    ///
+    /// Arguments:
+    ///   - The CSI sequence to send (without the CSI header)
+    ///
+    /// Example: Hide cursor
+    ///   keybind = ctrl+h=csi:?25l
     csi: []const u8,
 
-    /// Send an `ESC` sequence.
+    /// Send an ESC sequence.
+    ///
+    /// Arguments:
+    ///   - The ESC sequence to send
+    ///
+    /// Example: Save cursor position
+    ///   keybind = ctrl+e=esc:7
     esc: []const u8,
 
-    // Send the given text. Uses Zig string literal syntax. This is currently
+    /// Send text using string literal syntax. Invalid escape sequences will
-    // not validated. If the text is invalid (i.e. contains an invalid escape
+    /// show errors only in logs.
-    // sequence), the error will currently only show up in logs.
+    ///
+    /// Arguments:
+    ///   - The text to send (using string literal syntax)
+    ///
+    /// Example: Send greeting text
+    ///   keybind = ctrl+t=text:"Hello Ghostty!"
     text: []const u8,
 
-    /// Send data to the pty depending on whether cursor key mode is enabled
+    /// Send data to the pty based on cursor key mode setting.
-    /// (`application`) or disabled (`normal`).
+    ///
+    /// Arguments:
+    ///   - Mode: normal or application
+    ///
+    /// Example: Send normal cursor key
+    ///   keybind = up=cursor_key:normal
     cursor_key: CursorKey,
 
-    /// Reset the terminal. This can fix a lot of issues when a running
+    /// Reset the terminal to fix issues from broken program states.
-    /// program puts the terminal into a broken state. This is equivalent to
+    /// Equivalent to typing "reset" and pressing enter.
-    /// when you type "reset" and press enter.
+    /// Warning: May break TUI programs like vim. In shells, you may need
-    ///
+    /// to press enter for a new prompt.
-    /// If you do this while in a TUI program such as vim, this may break
-    /// the program. If you do this while in a shell, you may have to press
-    /// enter after to get a new prompt.
     reset: void,
 
-    /// Copy and paste.
+    /// Copy the current selection to the system clipboard.
     copy_to_clipboard: void,
+
+    /// Paste the contents of the system clipboard.
     paste_from_clipboard: void,
+
+    /// Paste the contents of the current selection.
     paste_from_selection: void,
 
-    /// Increase/decrease the font size by a certain amount.
+    /// Increase the font size by a specified amount.
+    ///
+    /// Arguments:
+    ///   - The amount to increase (1.0 = 100%)
+    ///
+    /// Example: Increase font size by 100%
+    ///   keybind = cmd+plus=increase_font_size:1.0
     increase_font_size: f32,
+
+    /// Decrease the font size by a specified amount.
+    ///
+    /// Arguments:
+    ///   - The amount to decrease (1.0 = 100%)
+    ///
+    /// Example: Decrease font size by 100%
+    ///   keybind = cmd+minus=decrease_font_size:1.0
     decrease_font_size: f32,
 
     /// Reset the font size to the original configured size.
     reset_font_size: void,
 
-    /// Clear the screen. This also clears all scrollback.
+    /// Clear the screen and all scrollback history.
     clear_screen: void,
 
-    /// Select all text on the screen.
+    /// Select all text in the terminal.
     select_all: void,
 
-    /// Scroll the screen varying amounts.
+    /// Move viewport to the top of the terminal history.
     scroll_to_top: void,
+
+    /// Move viewport to the bottom of the terminal history.
     scroll_to_bottom: void,
+
+    /// Move viewport up by one full page.
     scroll_page_up: void,
+
+    /// Move viewport down by one full page.
     scroll_page_down: void,
+
+    /// Scroll the viewport by a fraction of the page.
+    ///
+    /// Arguments:
+    ///   - The fraction of a page (positive = down, negative = up)
+    ///
+    /// Example: Scroll down half a page
+    ///   keybind = alt+j=scroll_page_fractional:0.5
     scroll_page_fractional: f32,
+
+    /// Scroll the viewport by a specific number of lines.
+    ///
+    /// Arguments:
+    ///   - Number of lines (positive = down, negative = up)
+    ///
+    /// Example: Scroll down 10 lines
+    ///   keybind = alt+k=scroll_page_lines:10
     scroll_page_lines: i16,
 
-    /// Adjust an existing selection in a given direction. This action
+    /// Adjust the current selection in a specified direction. Does nothing
-    /// does nothing if there is no active selection.
+    /// if no selection exists.
+    ///
+    /// Arguments:
+    ///   - Direction: left, right, up, down, page_up, page_down, home,
+    ///     end, beginning_of_line, end_of_line
+    ///
+    /// Example: Extend selection to the right
+    ///   keybind = shift+right=adjust_selection:right
     adjust_selection: AdjustSelection,
 
-    /// Jump the viewport forward or back by prompt. Positive number is the
+    /// Navigate between shell prompts in the terminal history.
-    /// number of prompts to jump forward, negative is backwards.
+    ///
+    /// Arguments:
+    ///   - Number of prompts (positive = forward, negative = backward)
+    ///
+    /// Example: Jump to previous prompt
+    ///   keybind = alt+up=jump_to_prompt:-1
     jump_to_prompt: i16,
 
-    /// Write the entire scrollback into a temporary file. The action
+    /// Write scrollback to a file and perform an action.
-    /// determines what to do with the filepath. Valid values are:
     ///
-    ///   - "paste": Paste the file path into the terminal.
+    /// Arguments:
-    ///   - "open": Open the file in the default OS editor for text files.
+    ///   - Action: paste (paste filepath), open (open in default text editor using
-    ///     The default OS editor is determined by using `open` on macOS
+    ///     'open' on macOS or 'xdg-open' on Linux)
-    ///     and `xdg-open` on Linux.
     ///
+    /// Example: Open scrollback in editor
+    ///   keybind = cmd+s=write_scrollback_file:open
     write_scrollback_file: WriteScreenAction,
 
-    /// Same as write_scrollback_file but writes the full screen contents.
+    /// Write current screen contents to a file and perform an action.
-    /// See write_scrollback_file for available values.
+    ///
+    /// Arguments:
+    ///   - Action: paste (paste filepath), open (open in default text editor using
+    ///     'open' on macOS or 'xdg-open' on Linux)
+    ///
+    /// Example: Paste screen contents filepath
+    ///   keybind = cmd+p=write_screen_file:paste
     write_screen_file: WriteScreenAction,
 
-    /// Same as write_scrollback_file but writes the selected text.
+    /// Write selected text to a file and perform an action.
-    /// If there is no selected text this does nothing (it doesn't
+    ///
-    /// even create an empty file). See write_scrollback_file for
+    /// Arguments:
-    /// available values.
+    ///   - Action: paste (paste filepath), open (open in default text editor using
+    ///     'open' on macOS or 'xdg-open' on Linux)
+    ///
+    /// Example: Open selection in editor
+    ///   keybind = cmd+shift+s=write_selection_file:open
     write_selection_file: WriteScreenAction,
 
-    /// Open a new window. If the application isn't currently focused,
+    /// Create a new window and bring application to front.
-    /// this will bring it to the front.
     new_window: void,
 
-    /// Open a new tab.
+    /// Create a new tab in the current window.
     new_tab: void,
 
-    /// Go to the previous tab.
+    /// Switch to the previous tab.
     previous_tab: void,
 
-    /// Go to the next tab.
+    /// Switch to the next tab.
     next_tab: void,
 
-    /// Go to the last tab (the one with the highest index)
+    /// Switch to the last tab (highest index).
     last_tab: void,
 
-    /// Go to the tab with the specific number, 1-indexed. If the tab number
+    /// Switch to a specific tab by number.
-    /// is higher than the number of tabs, this will go to the last tab.
+    ///
+    /// Arguments:
+    ///   - Tab number (1-based index). If the tab number is higher than the number
+    ///     of tabs, this will go to the last tab.
+    ///
+    /// Example: Switch to first tab
+    ///   keybind = cmd+1=goto_tab:1
     goto_tab: usize,
 
-    /// Moves a tab by a relative offset.
+    /// Move the current tab to a new position. Adjusts the tab position based on
-    /// Adjusts the tab position based on `offset` (e.g., -1 for left, +1 for right).
+    /// the offset (e.g., -1 for left, +1 for right). If the new position is out
-    /// If the new position is out of bounds, it wraps around cyclically within the tab range.
+    /// of bounds, it wraps around cyclically within the tab range.
+    ///
+    /// Arguments:
+    ///   - Position offset (negative = left, positive = right)
+    ///
+    /// Example: Move tab one position right
+    ///   keybind = cmd+shift+right=move_tab:1
     move_tab: isize,
 
-    /// Toggle the tab overview.
+    /// Toggle the tab overview (requires libadwaita).
-    /// This only works with libadwaita enabled currently.
     toggle_tab_overview: void,
 
-    /// Create a new split in the given direction. The new split will appear in
+    /// Create a new split terminal.
-    /// the direction given. For example `new_split:up`. Valid values are left, right, up, down and auto.
+    ///
+    /// Arguments:
+    ///   - Direction: right, down, left, up, or auto
+    ///
+    /// Example: Create split on the right
+    ///   keybind = cmd+shift+d=new_split:right
     new_split: SplitDirection,
 
-    /// Focus on a split in a given direction. For example `goto_split:top`. Valid values are top, bottom, left, right, previous and next.
+    /// Focus a split in a specified direction.
+    ///
+    /// Arguments:
+    ///   - Direction: top/up, bottom/down, left, right, previous, next
+    ///
+    /// Example: Focus split on the right
+    ///   keybind = cmd+right=goto_split:right
     goto_split: SplitFocusDirection,
 
-    /// zoom/unzoom the current split.
+    /// Toggle zoom state of the current split.
     toggle_split_zoom: void,
 
-    /// Resize the current split by moving the split divider in the given
+    /// Resize the current split.
-    /// direction. For example `resize_split:left,10`. The valid directions are up, down, left and right.
+    ///
+    /// Arguments:
+    ///   - Direction and pixels (separated by comma)
+    ///
+    /// Example: Move divider up 10 pixels
+    ///   keybind = cmd+shift+up=resize_split:up,10
     resize_split: SplitResizeParameter,
 
-    /// Equalize all splits in the current window
+    /// Make all splits equal size in the current window.
     equalize_splits: void,
 
-    /// Show, hide, or toggle the terminal inspector for the currently focused
+    /// Control the terminal inspector visibility.
-    /// terminal.
+    ///
+    /// Arguments:
+    ///   - Mode: toggle, show, or hide
+    ///
+    /// Example: Toggle inspector visibility
+    ///   keybind = cmd+i=inspector:toggle
     inspector: InspectorMode,
 
-    /// Open the configuration file in the default OS editor. If your default OS
+    /// Open configuration file in the default OS editor.
-    /// editor isn't configured then this will fail. Currently, any failures to
+    /// Failures appear only in logs if editor isn't configured.
-    /// open the configuration will show up only in the logs.
     open_config: void,
 
-    /// Reload the configuration. The exact meaning depends on the app runtime
+    /// Reload configuration and apply changes where possible.
-    /// in use but this usually involves re-reading the configuration file
+    /// Some changes may require restart.
-    /// and applying any changes. Note that not all changes can be applied at
-    /// runtime.
     reload_config: void,
 
-    /// Close the current "surface", whether that is a window, tab, split, etc.
+    /// Close the current surface (window, tab, or split).
-    /// This only closes ONE surface. This will trigger close confirmation as
+    /// Will trigger close confirmation if configured.
-    /// configured.
     close_surface: void,
 
-    /// Close the window, regardless of how many tabs or splits there may be.
+    /// Close the entire window regardless of tabs/splits.
-    /// This will trigger close confirmation as configured.
+    /// Will trigger close confirmation if configured.
     close_window: void,
 
-    /// Close all windows. This will trigger close confirmation as configured.
+    /// Close all windows (macOS only).
-    /// This only works for macOS currently.
+    /// Will trigger close confirmation if configured.
     close_all_windows: void,
 
-    /// Toggle fullscreen mode of window.
+    /// Toggle window fullscreen mode.
     toggle_fullscreen: void,
 
-    /// Toggle window decorations on and off. This only works on Linux.
+    /// Toggle window decorations (Linux only).
     toggle_window_decorations: void,
 
-    /// Toggle secure input mode on or off. This is used to prevent apps
+    /// Toggle secure input mode to prevent input monitoring.
-    /// that monitor input from seeing what you type. This is useful for
+    /// Applies application-wide and requires manual disable.
-    /// entering passwords or other sensitive information.
+    /// Available on macOS only.
-    ///
-    /// This applies to the entire application, not just the focused
-    /// terminal. You must toggle it off to disable it, or quit Ghostty.
-    ///
-    /// This only works on macOS, since this is a system API on macOS.
     toggle_secure_input: void,
 
-    /// Toggle the "quick" terminal. The quick terminal is a terminal that
+    /// Toggle the quick terminal that appears on demand, sliding in from a screen
-    /// appears on demand from a keybinding, often sliding in from a screen
+    /// edge such as the top.
-    /// edge such as the top. This is useful for quick access to a terminal
-    /// without having to open a new window or tab.
     ///
     /// When the quick terminal loses focus, it disappears. The terminal state
     /// is preserved between appearances, so you can always press the keybinding
@@ -401,17 +499,15 @@ pub const Action = union(enum) {
     /// See the various configurations for the quick terminal in the
     /// configuration file to customize its behavior.
     ///
-    /// This currently only works on macOS.
+    /// Available on macOS only.
     toggle_quick_terminal: void,
 
-    /// Show/hide all windows. If all windows become shown, we also ensure
+    /// Toggle visibility of all windows.
-    /// Ghostty is focused.
+    /// Shows and focuses Ghostty when showing windows.
-    ///
+    /// Available on macOS only.
-    /// This currently only works on macOS. When hiding all windows, we do
-    /// not yield focus to the previous application.
     toggle_visibility: void,
 
-    /// Quit ghostty.
+    /// Exit the application.
     quit: void,
 
     /// Crash ghostty in the desired thread for the focused surface.
@@ -422,12 +518,11 @@ pub const Action = union(enum) {
     /// users, it may be useful to test crash reporting functionality in
     /// order to determine if it all works as expected.
     ///
-    /// The value determines the crash location:
+    /// Arguments:
-    ///
+    ///   - Thread: main (GUI thread), io (IO thread), or render (render thread)
-    ///   - "main" - crash on the main (GUI) thread.
-    ///   - "io" - crash on the IO thread for the focused surface.
-    ///   - "render" - crash on the render thread for the focused surface.
     ///
+    /// Example: Crash main thread for testing
+    ///   keybind = ctrl+shift+c=crash:main
     crash: CrashThread,
 
     pub const Key = @typeInfo(Action).Union.tag_type.?;