docs(plugins): better zellij-tile-docs (#2560)

* docs(plugins): better zellij-tile-docs

* docs(code): fix examples - thanks cargo!

1 files changed, 78 insertions, 0 deletions

diff --git a/zellij-tile/src/lib.rs b/zellij-tile/src/lib.rs
index cca2a8769..98f141942 100644
--- a/zellij-tile/src/lib.rs
+++ b/zellij-tile/src/lib.rs
@@ -1,20 +1,61 @@
+//! The zellij-tile crate acts as the Rust API for developing plugins for Zellij.
+//!
+//! To read more about Zellij plugins:
+//! [https://zellij.dev/documentation/plugins](https://zellij.dev/documentation/plugins)
+//!
+//! ### Interesting things in this libary:
+//! - The [`ZellijPlugin`] trait for implementing plugins combined with the
+//! [`register_plugin!`](register_plugin) macro to register them.
+//! - The list of [commands](shim) representing what a plugin can do.
+//! - The list of [`Events`](prelude::Event) a plugin can subscribe to
+//! - The [`ZellijWorker`] trait for implementing background workers combined with the
+//! [`register_worker!`](register_worker) macro to register them
+//!
+//! ### Full Example and Development Environment
+//! For a working plugin example as well as a development environment, please see:
+//! [https://github.com/zellij-org/rust-plugin-example](https://github.com/zellij-org/rust-plugin-example)
+//!
 pub mod prelude;
 pub mod shim;
 
 use serde::{Deserialize, Serialize};
 use zellij_utils::data::Event;
 
+/// This trait should be implemented - once per plugin - on a struct (normally representing the
+/// plugin state). This struct should then be registered with the
+/// [`register_plugin!`](register_plugin) macro.
 #[allow(unused_variables)]
 pub trait ZellijPlugin: Default {
+    /// Will be called when the plugin is loaded, this is a good place to [`subscribe`](shim::subscribe) to events that are interesting for this plugin.
     fn load(&mut self) {}
+    /// Will be called with an [`Event`](prelude::Event) if the plugin is subscribed to said event.
+    /// If the plugin returns `true` from this function, Zellij will know it should be rendered and call its `render` function.
     fn update(&mut self, event: Event) -> bool {
         false
     } // return true if it should render
+    /// Will be called either after an `update` that requested it, or when the plugin otherwise needs to be re-rendered (eg. on startup, or when the plugin is resized).
+    /// The `rows` and `cols` values represent the "content size" of the plugin (this will not include its surrounding frame if the user has pane frames enabled).
     fn render(&mut self, rows: usize, cols: usize) {}
 }
 
+/// This trait is used to create workers. Workers can be used by plugins to run longer running
+/// background tasks without blocking their own rendering (eg. and showing some sort of loading
+/// indication in part of the UI as needed while waiting for the task to complete).
+///
+/// ## Starting workers on plugin load
+/// Implement this trait on a struct (typically representing the worker state) and register it with
+/// the [`register_worker!`](register_worker) macro.
+///
+/// ## Sending messages to workers and back to the plugin
+/// Send messages to workers with the [`post_message_to`](shim::post_message_to) method.
+/// Send messages from workers back to plugins with the
+/// [`post_message_to_plugin`](shim::post_message_to_plugin) method (but be sure the plugin has
+/// [`subscribe`](shim::subscribe)d to the [`CustomMessage`](prelude::Event::CustomMessage)) event
+/// first!
 #[allow(unused_variables)]
 pub trait ZellijWorker<'de>: Default + Serialize + Deserialize<'de> {
+    /// Triggered whenever the plugin sends the worker a message using the
+    /// [`post_message_to`](shim::post_message_to) method.
     fn on_message(&mut self, message: String, payload: String) {}
 }
 
@@ -30,6 +71,21 @@ Please refer to the documentation for further information:
     https://github.com/zellij-org/zellij/blob/main/CONTRIBUTING.md#building
 ";
 
+/// Used to register a plugin implementing the [`ZellijPlugin`] trait.
+///
+/// eg.
+/// ```rust
+/// use zellij_tile::prelude::*;
+///
+/// #[derive(Default)]
+/// pub struct MyPlugin {}
+///
+/// impl ZellijPlugin for MyPlugin {
+///    // ...
+/// }
+///
+/// register_plugin!(MyPlugin);
+/// ```
 #[macro_export]
 macro_rules! register_plugin {
     ($t:ty) => {
@@ -76,6 +132,28 @@ macro_rules! register_plugin {
     };
 }
 
+/// Used to register a plugin worker implementing the [`ZellijWorker`] trait.
+///
+/// eg.
+/// ```rust
+/// use zellij_tile::prelude::*;
+/// use serde::{Deserialize, Serialize};
+///
+/// #[derive(Default, Serialize, Deserialize)]
+/// pub struct FileSearchWorker {}
+///
+/// impl ZellijWorker<'_> for FileSearchWorker {
+///     fn on_message(&mut self, message: String, payload: String) {
+///         // ...
+///     }
+/// }
+///
+/// register_worker!(
+///     FileSearchWorker,
+///     file_search_worker, // registers the worker as the namespace "file_search"
+///     FILE_SEARCH_WORKER  // expanded to a static variable in which the worker state it held
+/// );
+/// ```
 #[macro_export]
 macro_rules! register_worker {
     ($worker:ty, $worker_name:ident, $worker_static_name:ident) => {