[REFACTOR] Stick to LuaCATS-like comments (#51)

Author: DrKJeff16

lua/types/config.lua

@@ -12,8 +12,8 @@
 ---|"Output"
 ---|"Prompt"
 
--- Represents a pre-defined function that can be applied to control `CopyMode`
--- and [Search Mode](https://wezterm.org/scrollback.html#enabledisable-scrollbar)
+---Represents a pre-defined function that can be applied to control `CopyMode`
+---and [Search Mode](https://wezterm.org/scrollback.html#enabledisable-scrollbar)
 ---@alias CopyModeAssignment
 ---|"AcceptPattern" Takes `CopyMode` / `SearchMode` out of editing mode: keyboard input will no longer be directed to the search pattern editor
 ---|"ClearPattern" Clear the `CopyMode` / `SearchMode` search pattern

lua/types/enum/copy-mode-assignment.lua

@@ -1,6 +1,6 @@
 ---@meta
 
--- TODO: Make key and mods more specific
+---TODO: Make key and mods more specific
 
 ---@alias KeyAssignment
 ---|"ActivateCommandPalette"
@@ -85,94 +85,93 @@
 ---|"TogglePaneZoomState"
 
 ---@class KeyNoAction
--- A single unicode character, like 'A' or 'a'. Pay attention to the case of the text that you use
--- and the state of the SHIFT modifier, as this matters whether 'A' or 'a' is matched.
---
--- Alternatively you can use on the following keycode identifiers, although note that not all of
--- these are meaningful on all platforms:
---
--- Hyper, Super, Meta, Cancel, Backspace, Tab, Clear, Enter, Shift, Escape, LeftShift, RightShift,
--- Control, LeftControl, RightControl, Alt, LeftAlt, RightAlt, Menu, LeftMenu, RightMenu, Pause,
--- CapsLock, VoidSymbol, PageUp, PageDown, End, Home, LeftArrow, RightArrow, UpArrow, DownArrow,
--- Select, Print, Execute, PrintScreen, Insert, Delete, Help, LeftWindows, RightWindows,
--- Applications, Sleep, Numpad0, Numpad1, Numpad2, Numpad3, Numpad4, Numpad5, Numpad6, Numpad7,
--- Numpad8, Numpad9, Multiply, Add, Separator, Subtract, Decimal, Divide, NumLock, ScrollLock,
--- BrowserBack, BrowserForward, BrowserRefresh, BrowserStop, BrowserSearch, BrowserFavorites,
--- BrowserHome, VolumeMute, VolumeDown, VolumeUp, MediaNextTrack, MediaPrevTrack, MediaStop,
--- MediaPlayPause, ApplicationLeftArrow, ApplicationRightArrow, ApplicationUpArrow,
--- ApplicationDownArrow, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, F17,
--- F18, F19, F20, F21, F22, F23, F24.
---
--- The key value can refer either to the physical position of a key on an ANSI US keyboard or to the
--- post-keyboard-layout-mapped value produced by a key press.
---
--- You can explicitly assign using the physical position by adding a phys: prefix to the value, for
--- example: `key="phys:A"`. This will match key presses for the key that would be in the position of
--- the A key on an ANSI US keyboard.
---
--- You can explicitly assign the mapped key by adding a mapped:
--- prefix to the value, for example: key="mapped:a" will match a
--- key press where the OS keyboard layout produces a, regardless of
--- its physical position.
---
--- If you omit an explicit prefix, wezterm will assume phys: and use the physical position of the
--- specified key.
---
--- The default key assignments listed above use `phys:`. In previous releases there was no physical
--- position support and those assignments were all `mapped:`.
---
--- When upgrading from earlier releases, if you had `{key="N", mods="CMD", ..}` in your config, you
--- will need to change it to either `{key="N", mods="CMD|SHIFT", ..}` or `{ key="mapped:N",
--- mods="CMD", ..}` in order to continue to respect the SHIFT modifier.
---
--- The `key_map_preference` option controls how keys without an explicit `phys:` or `mapped:` prefix
--- are treated. If `key_map_preference = "Mapped"` (the default), then `mapped:` is assumed. If
--- `key_map_preference = "Physical"` then `phys:` is assumed.
---
--- The default key assignments will respect `key_map_preference`.
---
--- In some cases, wezterm may not know how to represent a key event in either its phys: or mapped:
--- forms. In that case, you may wish to define an assignment in terms of the underlying operating
--- system key code, using a `raw: prefix`.
---
--- Similar in concept to the `phys:` mapping described above, the `raw:` mapping is independent of
--- the OS keyboard layout. Raw codes are hardware and windowing system dependent, so there is no
--- portable way to list which key does what.
---
--- To discover these values, you can set `debug_key_events = true` and press the keys of interest.
---
--- You can specify a raw key value of 123 by using `key="raw:123"` in your config rather than one of
--- the other key values.
---
+---A single unicode character, like 'A' or 'a'. Pay attention to the case of the text that you use
+---and the state of the SHIFT modifier, as this matters whether 'A' or 'a' is matched.
+---
+---Alternatively you can use on the following keycode identifiers, although note that not all of
+---these are meaningful on all platforms:
+---
+---Hyper, Super, Meta, Cancel, Backspace, Tab, Clear, Enter, Shift, Escape, LeftShift, RightShift,
+---Control, LeftControl, RightControl, Alt, LeftAlt, RightAlt, Menu, LeftMenu, RightMenu, Pause,
+---CapsLock, VoidSymbol, PageUp, PageDown, End, Home, LeftArrow, RightArrow, UpArrow, DownArrow,
+---Select, Print, Execute, PrintScreen, Insert, Delete, Help, LeftWindows, RightWindows,
+---Applications, Sleep, Numpad0, Numpad1, Numpad2, Numpad3, Numpad4, Numpad5, Numpad6, Numpad7,
+---Numpad8, Numpad9, Multiply, Add, Separator, Subtract, Decimal, Divide, NumLock, ScrollLock,
+---BrowserBack, BrowserForward, BrowserRefresh, BrowserStop, BrowserSearch, BrowserFavorites,
+---BrowserHome, VolumeMute, VolumeDown, VolumeUp, MediaNextTrack, MediaPrevTrack, MediaStop,
+---MediaPlayPause, ApplicationLeftArrow, ApplicationRightArrow, ApplicationUpArrow,
+---ApplicationDownArrow, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, F17,
+---F18, F19, F20, F21, F22, F23, F24.
+---
+---The key value can refer either to the physical position of a key on an ANSI US keyboard or to the
+---post-keyboard-layout-mapped value produced by a key press.
+---
+---You can explicitly assign using the physical position by adding a phys: prefix to the value, for
+---example: `key="phys:A"`. This will match key presses for the key that would be in the position of
+---the A key on an ANSI US keyboard.
+---
+---You can explicitly assign the mapped key by adding a mapped:
+---prefix to the value, for example: key="mapped:a" will match a
+---key press where the OS keyboard layout produces a, regardless of
+---its physical position.
+---
+---If you omit an explicit prefix, wezterm will assume phys: and use the physical position of the
+---specified key.
+---
+---The default key assignments listed above use `phys:`. In previous releases there was no physical
+---position support and those assignments were all `mapped:`.
+---
+---When upgrading from earlier releases, if you had `{key="N", mods="CMD", ..}` in your config, you
+---will need to change it to either `{key="N", mods="CMD|SHIFT", ..}` or `{ key="mapped:N",
+---mods="CMD", ..}` in order to continue to respect the SHIFT modifier.
+---
+---The `key_map_preference` option controls how keys without an explicit `phys:` or `mapped:` prefix
+---are treated. If `key_map_preference = "Mapped"` (the default), then `mapped:` is assumed. If
+---`key_map_preference = "Physical"` then `phys:` is assumed.
+---
+---The default key assignments will respect `key_map_preference`.
+---
+---In some cases, wezterm may not know how to represent a key event in either its phys: or mapped:
+---forms. In that case, you may wish to define an assignment in terms of the underlying operating
+---system key code, using a `raw: prefix`.
+---
+---Similar in concept to the `phys:` mapping described above, the `raw:` mapping is independent of
+---the OS keyboard layout. Raw codes are hardware and windowing system dependent, so there is no
+---portable way to list which key does what.
+---
+---To discover these values, you can set `debug_key_events = true` and press the keys of interest.
+---
+---You can specify a raw key value of 123 by using `key="raw:123"` in your config rather than one of
+---the other key values.
+---
 ---@field key string
--- Possible Modifier labels are:
---
--- `SUPER`, `CMD`, `WIN` - these are all equivalent: on macOS the Command key, on Windows the
--- Windows key, on Linux this can also be the Super or Hyper key. Left and right are equivalent.
---
--- `CTRL` - The control key. Left and right are equivalent.
---
--- `SHIFT` - The shift key. Left and right are equivalent.
---
--- `ALT`, `OPT`, `META` - these are all equivalent: on macOS the Option key, on other systems the
--- Alt or Meta key. Left and right are equivalent.
---
--- `LEADER` - a special modal modifier state managed by WezTerm.
---
--- `VoidSymbol` - This keycode is emitted in special cases where the original function of the key has
--- been removed. Such as in Linux and using setxkbmap: `setxkbmap -option caps:none`. The CapsLock
--- will no longer function as before in all applications, instead emitting `VoidSymbol`.
-
--- You can also combine modifiers using the `|` symbol, like `"CMD|CTRL"`.
---
+---Possible Modifier labels are:
+---
+---`SUPER`, `CMD`, `WIN` - these are all equivalent: on macOS the Command key, on Windows the
+---Windows key, on Linux this can also be the Super or Hyper key. Left and right are equivalent.
+---
+---`CTRL` - The control key. Left and right are equivalent.
+---
+---`SHIFT` - The shift key. Left and right are equivalent.
+---
+---`ALT`, `OPT`, `META` - these are all equivalent: on macOS the Option key, on other systems the
+---Alt or Meta key. Left and right are equivalent.
+---
+---`LEADER` - a special modal modifier state managed by WezTerm.
+---
+---`VoidSymbol` - This keycode is emitted in special cases where the original function of the key has
+---been removed. Such as in Linux and using setxkbmap: `setxkbmap -option caps:none`. The CapsLock
+---will no longer function as before in all applications, instead emitting `VoidSymbol`.
+---You can also combine modifiers using the `|` symbol, like `"CMD|CTRL"`.
+---
 ---@field mods? string Optional modifiers keys.
 
 ---@class Key :KeyNoAction
 ---@field action KeyAssignment
 
 ---@alias KeyAssignFunction fun(param: any): KeyAssignment
 
--- Can also be called as function like older versions of wezterm did
+---Can also be called as function like older versions of wezterm did
 ---@class ActionFuncClass
 ---@field ActivateCommandPalette KeyAssignFunction
 ---@field ActivateCopyMode KeyAssignFunction
@@ -337,8 +336,8 @@
 ---@field ToggleFullScreen any
 ---@field TogglePaneZoomState any
 
--- Helper for defining key assignment actions in your configuration file.
--- This is really just sugar for the underlying Lua -> Rust deserialation mapping
--- that makes it a bit easier to identify where syntax errors may exist
--- in your configuration file
+---Helper for defining key assignment actions in your configuration file.
+---This is really just sugar for the underlying Lua -> Rust deserialation mapping
+---that makes it a bit easier to identify where syntax errors may exist
+---in your configuration file
 ---@alias Action ActionFuncClass|fun(action: ActionClass)

lua/types/enum/key-assignment.lua

@@ -1,40 +1,40 @@
 ---@meta
 
--- This event is triggered when the GUI is starting up after attaching the selected domain.
--- For example, when you use `wezterm connect DOMAIN` or `wezterm start --domain DOMAIN`to start the GUI,
--- the `gui-attached` event will be triggered and passed the `MuxDomain` object associated with `DOMAIN`.
---
--- In cases where you don't specify the domain, the default domain will be passed instead.
---
--- This event fires after the `gui-startup` event.
---
--- Note that the `gui-startup` event does not fire when invoking `wezterm connect DOMAIN`
--- or `wezterm start --domain DOMAIN --attach`
+---This event is triggered when the GUI is starting up after attaching the selected domain.
+---For example, when you use `wezterm connect DOMAIN` or `wezterm start --domain DOMAIN`to start the GUI,
+---the `gui-attached` event will be triggered and passed the `MuxDomain` object associated with `DOMAIN`.
+---
+---In cases where you don't specify the domain, the default domain will be passed instead.
+---
+---This event fires after the `gui-startup` event.
+---
+---Note that the `gui-startup` event does not fire when invoking `wezterm connect DOMAIN`
+---or `wezterm start --domain DOMAIN --attach`
 ---@alias GuiAttached "gui-attached"
 
--- The `gui-startup` event is emitted once when the GUI server is starting up when running the
--- `wezterm start` subcommand.
---
--- If no explicit program was passed to `wezterm start`, and if the `gui-startup` event
--- causes any panes to be created then those will take precedence
--- over the default program configuration
--- and no additional default program will be spawned.
---
--- This event is useful for starting a set of programs in a standard configuration
--- to save you the effort of doing it manually each time.
---
---
--- - It is triggered before any default program is started
--- - This event fires before `gui-attached`
--- - This event does not fire for `wezterm connect` invocations
--- - The event receives an optional `SpawnCommand` argument that corresponds to
---   any arguments that may have been passed via `wezterm start`.
---   In earlier releases if you implemented this event,
---   you would essentially prevent `wezterm start -- something`
---   from spawning something.
---
--- The intent is for you to use the information in the command object to spawn a new window,
--- but you can choose to use or ignore it as suits your purpose
+---The `gui-startup` event is emitted once when the GUI server is starting up when running the
+---`wezterm start` subcommand.
+---
+---If no explicit program was passed to `wezterm start`, and if the `gui-startup` event
+---causes any panes to be created then those will take precedence
+---over the default program configuration
+---and no additional default program will be spawned.
+---
+---This event is useful for starting a set of programs in a standard configuration
+---to save you the effort of doing it manually each time.
+---
+---
+--- - It is triggered before any default program is started
+--- - This event fires before `gui-attached`
+--- - This event does not fire for `wezterm connect` invocations
+--- - The event receives an optional `SpawnCommand` argument that corresponds to
+---  any arguments that may have been passed via `wezterm start`.
+---  In earlier releases if you implemented this event,
+---  you would essentially prevent `wezterm start -- something`
+---  from spawning something.
+---
+---The intent is for you to use the information in the command object to spawn a new window,
+---but you can choose to use or ignore it as suits your purpose
 ---@alias GuiStartup "gui-startup"
 
 ---@alias GuiEvent

lua/types/events/gui.lua

@@ -1,33 +1,33 @@
 ---@meta
 
--- The `mux-is-process-stateful` event is emitted when the multiplexer layer
--- wants to determine whether a given `Pane` can be closed
--- without prompting the user.
---
--- - This event is synchronous and must return as quickly as possible
---   in order to avoid blocking the multiplexer
--- - The event is passed a `LocalProcessInfo` object representing the process
---   that corresponds to the pane
---
--- The hook can return one of the following values:
--- - `true`: to indicate that this process tree is considered to be stateful
---         and that the user should be prompted before terminating the pane
--- - `false`: to indicate that the process tree can be terminated without prompting the user
---
--- Any other value means to use the default behavior, which is to consider the
--- `skip_close_confirmation_for_processes_named` configuration option
---
+---The `mux-is-process-stateful` event is emitted when the multiplexer layer
+---wants to determine whether a given `Pane` can be closed
+---without prompting the user.
+---
+--- - This event is synchronous and must return as quickly as possible
+---  in order to avoid blocking the multiplexer
+--- - The event is passed a `LocalProcessInfo` object representing the process
+---  that corresponds to the pane
+---
+---The hook can return one of the following values:
+--- - `true`: to indicate that this process tree is considered to be stateful
+---        and that the user should be prompted before terminating the pane
+--- - `false`: to indicate that the process tree can be terminated without prompting the user
+---
+---Any other value means to use the default behavior, which is to consider the
+---`skip_close_confirmation_for_processes_named` configuration option
+---
 ---@alias MuxProcessStateful "mux-is-process-stateful"
 
--- The `mux-startup` event is emitted once when the mux server is starting up.
--- It is triggered before any default program is started.
---
--- If the `mux-startup` event causes any panes to be created then
--- those will take precedence over the default program configuration
--- and no additional default program will be spawned.
---
--- This event is useful for starting a set of programs in a standard configuration
--- to save you the effort of doing it manually each time
+---The `mux-startup` event is emitted once when the mux server is starting up.
+---It is triggered before any default program is started.
+---
+---If the `mux-startup` event causes any panes to be created then
+---those will take precedence over the default program configuration
+---and no additional default program will be spawned.
+---
+---This event is useful for starting a set of programs in a standard configuration
+---to save you the effort of doing it manually each time
 ---@alias MuxStartup "mux-startup"
 
 ---@alias MultiplexerEvent