docs(plugins): document the zellij-tile events and commands api (#2554)

2 files changed, 123 insertions, 29 deletions

diff --git a/zellij-tile/src/shim.rs b/zellij-tile/src/shim.rs
index 671532158..bba146894 100644
--- a/zellij-tile/src/shim.rs
+++ b/zellij-tile/src/shim.rs
@@ -5,11 +5,13 @@ use zellij_utils::errors::prelude::*;
 
 // Subscription Handling
 
+/// Subscribe to a list of [`Event`]s represented by their [`EventType`]s that will then trigger the `update` method
 pub fn subscribe(event_types: &[EventType]) {
     object_to_stdout(&event_types);
     unsafe { host_subscribe() };
 }
 
+/// Unsubscribe to a list of [`Event`]s represented by their [`EventType`]s.
 pub fn unsubscribe(event_types: &[EventType]) {
     object_to_stdout(&event_types);
     unsafe { host_unsubscribe() };
@@ -17,16 +19,19 @@ pub fn unsubscribe(event_types: &[EventType]) {
 
 // Plugin Settings
 
+/// Sets the plugin as selectable or unselectable to the user. Unselectable plugins might be desired when they do not accept user input.
 pub fn set_selectable(selectable: bool) {
     unsafe { host_set_selectable(selectable as i32) };
 }
 
 // Query Functions
+/// Returns the unique Zellij pane ID for the plugin as well as the Zellij process id.
 pub fn get_plugin_ids() -> PluginIds {
     unsafe { host_get_plugin_ids() };
     object_from_stdin().unwrap()
 }
 
+/// Returns the version of the running Zellij instance - can be useful to check plugin compatibility
 pub fn get_zellij_version() -> String {
     unsafe { host_get_zellij_version() };
     object_from_stdin().unwrap()
@@ -34,36 +39,43 @@ pub fn get_zellij_version() -> String {
 
 // Host Functions
 
+/// Open a file in the user's default `$EDITOR` in a new pane
 pub fn open_file<P: AsRef<Path>>(path: P) {
     object_to_stdout(&path.as_ref());
     unsafe { host_open_file() };
 }
 
+/// Open a file in the user's default `$EDITOR` in a new floating pane
 pub fn open_file_floating<P: AsRef<Path>>(path: P) {
     object_to_stdout(&path.as_ref());
     unsafe { host_open_file_floating() };
 }
 
+/// Open a file to a specific line in the user's default `$EDITOR` (if it supports it, most do) in a new pane
 pub fn open_file_with_line<P: AsRef<Path>>(path: P, line: usize) {
     object_to_stdout(&(path.as_ref(), line));
     unsafe { host_open_file_with_line() };
 }
 
+/// Open a file to a specific line in the user's default `$EDITOR` (if it supports it, most do) in a new floating pane
 pub fn open_file_with_line_floating<P: AsRef<Path>>(path: P, line: usize) {
     object_to_stdout(&(path.as_ref(), line));
     unsafe { host_open_file_with_line_floating() };
 }
 
+/// Open a new terminal pane to the specified location on the host filesystem
 pub fn open_terminal<P: AsRef<Path>>(path: P) {
     object_to_stdout(&path.as_ref());
     unsafe { host_open_terminal() };
 }
 
+/// Open a new floating terminal pane to the specified location on the host filesystem
 pub fn open_terminal_floating<P: AsRef<Path>>(path: P) {
     object_to_stdout(&path.as_ref());
     unsafe { host_open_terminal_floating() };
 }
 
+/// Open a new command pane with the specified command and args (this sort of pane allows the user to control the command, re-run it and see its exit status through the Zellij UI).
 pub fn open_command_pane<P: AsRef<Path>, A: AsRef<str>>(path: P, args: Vec<A>) {
     object_to_stdout(&(
         path.as_ref(),
@@ -72,6 +84,7 @@ pub fn open_command_pane<P: AsRef<Path>, A: AsRef<str>>(path: P, args: Vec<A>) {
     unsafe { host_open_command_pane() };
 }
 
+/// Open a new floating command pane with the specified command and args (this sort of pane allows the user to control the command, re-run it and see its exit status through the Zellij UI).
 pub fn open_command_pane_floating<P: AsRef<Path>, A: AsRef<str>>(path: P, args: Vec<A>) {
     object_to_stdout(&(
         path.as_ref(),
@@ -80,44 +93,55 @@ pub fn open_command_pane_floating<P: AsRef<Path>, A: AsRef<str>>(path: P, args:
     unsafe { host_open_command_pane_floating() };
 }
 
+/// Change the focused tab to the specified index (corresponding with the default tab names, to starting at `1`, `0` will be considered as `1`).
 pub fn switch_tab_to(tab_idx: u32) {
     unsafe { host_switch_tab_to(tab_idx) };
 }
 
+/// Set a timeout in seconds (or fractions thereof) after which the plugins [update](./plugin-api-events#update) method will be called with the [`Timer`](./plugin-api-events.md#timer) event.
 pub fn set_timeout(secs: f64) {
     unsafe { host_set_timeout(secs) };
 }
+
+#[doc(hidden)]
 pub fn exec_cmd(cmd: &[&str]) {
     object_to_stdout(&cmd);
     unsafe { host_exec_cmd() };
 }
 
+/// Hide the plugin pane (suppress it) from the UI
 pub fn hide_self() {
     unsafe { host_hide_self() };
 }
 
+/// Show the plugin pane (unsuppress it if it is suppressed), focus it and switch to its tab
 pub fn show_self(should_float_if_hidden: bool) {
     unsafe { host_show_self(should_float_if_hidden as i32) };
 }
 
+/// Switch to the specified Input Mode (eg. `Normal`, `Tab`, `Pane`)
 pub fn switch_to_input_mode(mode: &InputMode) {
     object_to_stdout(&mode);
     unsafe { host_switch_to_mode() };
 }
 
+/// Provide a stringified [`layout`](https://zellij.dev/documentation/layouts.html) to be applied to the current session. If the layout has multiple tabs, they will all be opened.
 pub fn new_tabs_with_layout(layout: &str) {
     println!("{}", layout);
     unsafe { host_new_tabs_with_layout() }
 }
 
+/// Open a new tab with the default layout
 pub fn new_tab() {
     unsafe { host_new_tab() }
 }
 
+/// Change focus to the next tab or loop back to the first
 pub fn go_to_next_tab() {
     unsafe { host_go_to_next_tab() }
 }
 
+/// Change focus to the previous tab or loop back to the last
 pub fn go_to_previous_tab() {
     unsafe { host_go_to_previous_tab() }
 }
@@ -129,101 +153,124 @@ pub fn report_panic(info: &std::panic::PanicInfo) {
     unsafe { host_report_panic() };
 }
 
+/// Either Increase or Decrease the size of the focused pane
 pub fn resize_focused_pane(resize: Resize) {
     object_to_stdout(&resize);
     unsafe { host_resize() };
 }
 
+/// Either Increase or Decrease the size of the focused pane in a specified direction (eg. `Left`, `Right`, `Up`, `Down`).
 pub fn resize_focused_pane_with_direction(resize: Resize, direction: Direction) {
     object_to_stdout(&(resize, direction));
     unsafe { host_resize_with_direction() };
 }
 
+/// Change focus tot he next pane in chronological order
 pub fn focus_next_pane() {
     unsafe { host_focus_next_pane() };
 }
 
+/// Change focus to the previous pane in chronological order
 pub fn focus_previous_pane() {
     unsafe { host_focus_previous_pane() };
 }
 
+/// Change the focused pane in the specified direction
 pub fn move_focus(direction: Direction) {
     object_to_stdout(&direction);
     unsafe { host_move_focus() };
 }
 
+/// Change the focused pane in the specified direction, if the pane is on the edge of the screen, the next tab is focused (next if right edge, previous if left edge).
 pub fn move_focus_or_tab(direction: Direction) {
     object_to_stdout(&direction);
     unsafe { host_move_focus_or_tab() };
 }
 
+/// Detach the user from the active session
 pub fn detach() {
     unsafe { host_detach() };
 }
 
+/// Edit the scrollback of the focused pane in the user's default `$EDITOR`
 pub fn edit_scrollback() {
     unsafe { host_edit_scrollback() };
 }
 
+/// Write bytes to the `STDIN` of the focused pane
 pub fn write(bytes: Vec<u8>) {
     object_to_stdout(&bytes);
     unsafe { host_write() };
 }
 
+/// Write characters to the `STDIN` of the focused pane
 pub fn write_chars(chars: &str) {
     println!("{}", chars);
     unsafe { host_write_chars() };
 }
 
+/// Focused the previously focused tab (regardless of the tab position)
 pub fn toggle_tab() {
     unsafe { host_toggle_tab() };
 }
 
+/// Switch the position of the focused pane with a different pane
 pub fn move_pane() {
     unsafe { host_move_pane() };
 }
 
+/// Switch the position of the focused pane with a different pane in the specified direction (eg. `Down`, `Up`, `Left`, `Right`).
 pub fn move_pane_with_direction(direction: Direction) {
     object_to_stdout(&direction);
     unsafe { host_move_pane_with_direction() };
 }
 
+/// Clear the scroll buffer of the focused pane
 pub fn clear_screen() {
     unsafe { host_clear_screen() };
 }
 
+/// Scroll the focused pane up 1 line
 pub fn scroll_up() {
     unsafe { host_scroll_up() };
 }
 
+/// Scroll the focused pane down 1 line
 pub fn scroll_down() {
     unsafe { host_scroll_down() };
 }
 
+/// Scroll the focused pane all the way to the top of the scrollbuffer
 pub fn scroll_to_top() {
     unsafe { host_scroll_to_top() };
 }
 
+/// Scroll the focused pane all the way to the bottom of the scrollbuffer
 pub fn scroll_to_bottom() {
     unsafe { host_scroll_to_bottom() };
 }
 
+/// Scroll the focused pane up one page
 pub fn page_scroll_up() {
     unsafe { host_page_scroll_up() };
 }
 
+/// Scroll the focused pane down one page
 pub fn page_scroll_down() {
     unsafe { host_page_scroll_down() };
 }
 
+/// Toggle the focused pane to be fullscreen or normal sized
 pub fn toggle_focus_fullscreen() {
     unsafe { host_toggle_focus_fullscreen() };
 }
 
+/// Toggle the UI pane frames on or off
 pub fn toggle_pane_frames() {
     unsafe { host_toggle_pane_frames() };
 }
 
+/// Embed the currently focused pane (make it stop floating) or turn it to a float pane if it is not
 pub fn toggle_pane_embed_or_eject() {
     unsafe { host_toggle_pane_embed_or_eject() };
 }
@@ -232,14 +279,17 @@ pub fn undo_rename_pane() {
     unsafe { host_undo_rename_pane() };
 }
 
+/// Close the focused pane
 pub fn close_focus() {
     unsafe { host_close_focus() };
 }
 
+/// Turn the `STDIN` synchronization of the current tab on or off
 pub fn toggle_active_tab_sync() {
     unsafe { host_toggle_active_tab_sync() };
 }
 
+/// Close the focused tab
 pub fn close_focused_tab() {
     unsafe { host_close_focused_tab() };
 }
@@ -248,23 +298,28 @@ pub fn undo_rename_tab() {
     unsafe { host_undo_rename_tab() };
 }
 
+/// Compeltely quit Zellij for this and all other connected clients
 pub fn quit_zellij() {
     unsafe { host_quit_zellij() };
 }
 
+/// Change to the previous [swap layout](https://zellij.dev/documentation/swap-layouts.html)
 pub fn previous_swap_layout() {
     unsafe { host_previous_swap_layout() };
 }
 
+/// Change to the next [swap layout](https://zellij.dev/documentation/swap-layouts.html)
 pub fn next_swap_layout() {
     unsafe { host_next_swap_layout() };
 }
 
+/// Change focus to the tab with the specified name
 pub fn go_to_tab_name(tab_name: &str) {
     println!("{}", tab_name);
     unsafe { host_go_to_tab_name() };
 }
 
+/// Change focus to the tab with the specified name or create it if it does not exist
 pub fn focus_or_create_tab(tab_name: &str) {
     print!("{}", tab_name);
     unsafe { host_focus_or_create_tab() };
@@ -279,32 +334,39 @@ pub fn start_or_reload_plugin(url: &str) {
     unsafe { host_start_or_reload_plugin() };
 }
 
+/// Closes a terminal pane with the specified id
 pub fn close_terminal_pane(terminal_pane_id: i32) {
     unsafe { host_close_terminal_pane(terminal_pane_id) };
 }
 
+/// Closes a plugin pane with the specified id
 pub fn close_plugin_pane(plugin_pane_id: i32) {
     unsafe { host_close_plugin_pane(plugin_pane_id) };
 }
 
+/// Changes the focus to the terminal pane with the specified id, unsuppressing it if it was suppressed and switching to its tab and layer (eg. floating/tiled).
 pub fn focus_terminal_pane(terminal_pane_id: i32, should_float_if_hidden: bool) {
     unsafe { host_focus_terminal_pane(terminal_pane_id, should_float_if_hidden as i32) };
 }
 
+/// Changes the focus to the plugin pane with the specified id, unsuppressing it if it was suppressed and switching to its tab and layer (eg. floating/tiled).
 pub fn focus_plugin_pane(plugin_pane_id: i32, should_float_if_hidden: bool) {
     unsafe { host_focus_plugin_pane(plugin_pane_id, should_float_if_hidden as i32) };
 }
 
+/// Changes the name (the title that appears in the UI) of the terminal pane with the specified id.
 pub fn rename_terminal_pane<S: AsRef<str>>(terminal_pane_id: i32, new_name: S) {
     object_to_stdout(&(terminal_pane_id, new_name.as_ref()));
     unsafe { host_rename_terminal_pane() };
 }
 
+/// Changes the name (the title that appears in the UI) of the plugin pane with the specified id.
 pub fn rename_plugin_pane<S: AsRef<str>>(plugin_pane_id: i32, new_name: S) {
     object_to_stdout(&(plugin_pane_id, new_name.as_ref()));
     unsafe { host_rename_plugin_pane() };
 }
 
+/// Changes the name (the title that appears in the UI) of the tab with the specified position.
 pub fn rename_tab<S: AsRef<str>>(tab_position: i32, new_name: S) {
     object_to_stdout(&(tab_position, new_name.as_ref()));
     unsafe { host_rename_tab() };
@@ -327,7 +389,7 @@ pub fn object_to_stdout(object: &impl Serialize) {
     println!("{}", serde_json::to_string(object).unwrap());
 }
 
-#[doc(hidden)]
+/// Post a message to a worker of this plugin, for more information please see [Plugin Workers](https://zellij.dev/documentation/plugin-api-workers.md)
 pub fn post_message_to<S: AsRef<str>>(worker_name: S, message: S, payload: S) {
     match serde_json::to_string(&(worker_name.as_ref(), message.as_ref(), payload.as_ref())) {
         Ok(serialized) => println!("{}", serialized),
@@ -336,7 +398,7 @@ pub fn post_message_to<S: AsRef<str>>(worker_name: S, message: S, payload: S) {
     unsafe { host_post_message_to() };
 }
 
-#[doc(hidden)]
+/// Post a message to this plugin, for more information please see [Plugin Workers](https://zellij.dev/documentation/plugin-api-workers.md)
 pub fn post_message_to_plugin<S: AsRef<str>>(message: S, payload: S) {
     match serde_json::to_string(&(message.as_ref(), payload.as_ref())) {
         Ok(serialized) => println!("{}", serialized),
diff --git a/zellij-utils/src/data.rs b/zellij-utils/src/data.rs
index 9a228c72d..a12821c42 100644
--- a/zellij-utils/src/data.rs
+++ b/zellij-utils/src/data.rs
@@ -196,7 +196,6 @@ impl fmt::Display for CharOrArrow {
     }
 }
 
-/// The four directions (left, right, up, down).
 #[derive(Eq, Clone, Copy, Debug, PartialEq, Hash, Deserialize, Serialize, PartialOrd, Ord)]
 pub enum Direction {
     Left,
@@ -457,6 +456,8 @@ pub enum Mouse {
     Release(isize, usize),    // line and column
 }
 
+/// These events can be subscribed to with subscribe method exported by `zellij-tile`.
+/// Once subscribed to, they will trigger the `update` method of the `ZellijPlugin` trait.
 #[derive(Debug, Clone, PartialEq, EnumDiscriminants, ToString, Serialize, Deserialize)]
 #[strum_discriminants(derive(EnumString, Hash, Serialize, Deserialize))]
 #[strum_discriminants(name(EventType))]
@@ -465,20 +466,32 @@ pub enum Event {
     ModeUpdate(ModeInfo),
     TabUpdate(Vec<TabInfo>),
     PaneUpdate(PaneManifest),
+    /// A key was pressed while the user is focused on this plugin's pane
     Key(Key),
+    /// A mouse event happened while the user is focused on this plugin's pane
     Mouse(Mouse),
+    /// A timer expired set by the `set_timeout` method exported by `zellij-tile`.
     Timer(f64),
+    /// Text was copied to the clipboard anywhere in the app
     CopyToClipboard(CopyDestination),
+    /// Failed to copy text to clipboard anywhere in the app
     SystemClipboardFailure,
+    /// Input was received anywhere in the app
     InputReceived,
+    /// This plugin became visible or invisible
     Visible(bool),
+    /// A message from one of the plugin's workers
     CustomMessage(
         String, // message
         String, // payload
     ),
+    /// A file was created somewhere in the Zellij CWD folder
     FileSystemCreate(Vec<PathBuf>),
+    /// A file was accessed somewhere in the Zellij CWD folder
     FileSystemRead(Vec<PathBuf>),
+    /// A file was modified somewhere in the Zellij CWD folder
     FileSystemUpdate(Vec<PathBuf>),
+    /// A file was deleted somewhere in the Zellij CWD folder
     FileSystemDelete(Vec<PathBuf>),
 }
 
@@ -544,27 +557,6 @@ pub enum InputMode {
     Tmux,
 }
 
-// impl TryFrom<&str> for InputMode {
-//     type Error = String;
-//     fn try_from(mode: &str) -> Result<Self, String> {
-//         match mode {
-//             "normal" | "Normal" => Ok(InputMode::Normal),
-//             "locked" | "Locked" => Ok(InputMode::Locked),
-//             "resize" | "Resize" => Ok(InputMode::Resize),
-//             "pane" | "Pane" => Ok(InputMode::Pane),
-//             "tab" | "Tab" => Ok(InputMode::Tab),
-//             "search" | "Search" => Ok(InputMode::Search),
-//             "renametab" | "RenameTab" => Ok(InputMode::RenameTab),
-//             "renamepane" | "RenamePane" => Ok(InputMode::RenamePane),
-//             "session" | "Session" => Ok(InputMode::Session),
-//             "move" | "Move" => Ok(InputMode::Move),
-//             "prompt" | "Prompt" => Ok(InputMode::Prompt),
-//             "tmux" | "Tmux" => Ok(InputMode::Tmux),
-//             _ => Err(format!("Unrecognized mode: {}", mode)),
-//         }
-//     }
-// }
-
 impl Default for InputMode {
     fn default() -> InputMode {
         InputMode::Normal
@@ -660,9 +652,7 @@ pub struct Style {
 // FIXME: Poor devs hashtable since HashTable can't derive `Default`...
 pub type KeybindsVec = Vec<(InputMode, Vec<(Key, Vec<Action>)>)>;
 
-/// Represents the contents of the help message that is printed in the status bar,
-/// which indicates the current [`InputMode`] and what the keybinds for that mode
-/// are. Related to the default `status-bar` plugin.
+/// Provides information helpful in rendering the Zellij controls for UI bars
 #[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct ModeInfo {
     pub mode: InputMode,
@@ -687,37 +677,70 @@ impl ModeInfo {
     }
 }
 
+/// Contains all the information for a currently opened tab.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Hash, Deserialize, Serialize)]
 pub struct TabInfo {
-    /* subset of fields to publish to plugins */
+    /// The Tab's 0 indexed position
     pub position: usize,
+    /// The name of the tab as it appears in the UI (if there's enough room for it)
     pub name: String,
+    /// Whether this tab is focused
     pub active: bool,
+    /// The number of suppressed panes this tab has
     pub panes_to_hide: usize,
+    /// Whether there's one pane taking up the whole display area on this tab
     pub is_fullscreen_active: bool,
+    /// Whether input sent to this tab will be synced to all panes in it
     pub is_sync_panes_active: bool,
     pub are_floating_panes_visible: bool,
     pub other_focused_clients: Vec<ClientId>,
     pub active_swap_layout_name: Option<String>,
+    /// Whether the user manually changed the layout, moving out of the swap layout scheme
     pub is_swap_layout_dirty: bool,
 }
 
+/// The `PaneManifest` contains a dictionary of panes, indexed by the tab position (0 indexed).
+/// Panes include all panes in the relevant tab, including `tiled` panes, `floating` panes and
+/// `suppressed` panes.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize, Serialize)]
 pub struct PaneManifest {
     pub panes: HashMap<usize, Vec<PaneInfo>>, // usize is the tab position
 }
 
+/// Contains all the information for a currently open pane
+///
+/// # Difference between coordinates/size and content coordinates/size
+///
+/// The pane basic coordinates and size (eg. `pane_x` or `pane_columns`) are the entire space taken
+/// up by this pane - including its frame and title if it has a border.
+///
+/// The pane content coordinates and size (eg. `pane_content_x` or `pane_content_columns`)
+/// represent the area taken by the pane's content, excluding its frame and title if it has a
+/// border.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Hash, Deserialize, Serialize)]
 pub struct PaneInfo {
+    /// The id of the pane, unique to all panes of this kind (eg. id in terminals or id in panes)
     pub id: u32,
+    /// Whether this pane is a plugin (`true`) or a terminal (`false`), used along with `id` can represent a unique pane ID across
+    /// the running session
     pub is_plugin: bool,
+    /// Whether the pane is focused in its layer (tiled or floating)
     pub is_focused: bool,
     pub is_fullscreen: bool,
+    /// Whether a pane is floating or tiled (embedded)
     pub is_floating: bool,
+    /// Whether a pane is suppressed - suppressed panes are not visible to the user, but still run
+    /// in the background
     pub is_suppressed: bool,
+    /// The full title of the pane as it appears in the UI (if there is room for it)
     pub title: String,
+    /// Whether a pane exited or not, note that most panes close themselves before setting this
+    /// flag, so this is only relevant to command panes
     pub exited: bool,
+    /// The exit status of a pane if it did exit and is still in the UI
     pub exit_status: Option<i32>,
+    /// A "held" pane is a paused pane that is waiting for user input (eg. a command pane that
+    /// exited and is waiting to be re-run or closed)
     pub is_held: bool,
     pub pane_x: usize,
     pub pane_content_x: usize,
@@ -727,9 +750,17 @@ pub struct PaneInfo {
     pub pane_content_rows: usize,
     pub pane_columns: usize,
     pub pane_content_columns: usize,
+    /// The coordinates of the cursor - if this pane is focused - relative to the pane's
+    /// coordinates
     pub cursor_coordinates_in_pane: Option<(usize, usize)>, // x, y if cursor is visible
+    /// If this is a command pane, this will show the stringified version of the command and its
+    /// arguments
     pub terminal_command: Option<String>,
+    /// The URL from which this plugin was loaded (eg. `zellij:strider` for the built-in `strider`
+    /// plugin or `file:/path/to/my/plugin.wasm` for a local plugin)
     pub plugin_url: Option<String>,
+    /// Unselectable panes are often used for UI elements that do not have direct user interaction
+    /// (eg. the default `status-bar` or `tab-bar`).
     pub is_selectable: bool,
 }
 
@@ -739,7 +770,7 @@ pub struct PluginIds {
     pub zellij_pid: u32,
 }
 
-/// Tag used to identify the plugin in layout and config yaml files
+/// Tag used to identify the plugin in layout and config kdl files
 #[derive(Debug, Default, Clone, PartialEq, Eq, Hash, Deserialize, Serialize, PartialOrd, Ord)]
 pub struct PluginTag(String);
 
@@ -772,6 +803,7 @@ impl Default for PluginCapabilities {
     }
 }
 
+/// Represents a Clipboard type
 #[derive(Debug, Copy, Clone, PartialEq, Serialize, Deserialize)]
 pub enum CopyDestination {
     Command,