Merge pull request #597 from JakeStanger/docs/modules

docs: add rustdoc comments to all module options

src/config/common.rs

@@ -7,26 +7,153 @@ use gtk::{EventBox, Orientation, Revealer, RevealerTransitionType};
 use serde::Deserialize;
 use tracing::trace;
 
-/// Common configuration options
-/// which can be set on every module.
+/// The following are module-level options which are present on **all** modules.
+///
+/// Each module also provides options specific to its type.
+/// For details on those, check the relevant module documentation.
+///
+/// For information on the Script type, and embedding scripts in strings,
+/// see [here](script).
+/// For information on styling, please see the [styling guide](styling-guide).
 #[derive(Debug, Default, Deserialize, Clone)]
 pub struct CommonConfig {
-    pub class: Option<String>,
+    /// Sets the unique widget name,
+    /// allowing you to target it in CSS using `#name`.
+    ///
+    /// It is best practise (although not required) to ensure that the value is
+    /// globally unique throughout the Ironbar instance
+    /// to avoid clashes.
+    ///
+    /// **Default**: `null`
     pub name: Option<String>,
 
+    /// Sets one or more CSS classes,
+    /// allowing you to target it in CSS using `.class`.
+    ///
+    /// Unlike [name](#name), the `class` property is not expected to be unique.
+    ///
+    /// **Default**: `null`
+    pub class: Option<String>,
+
+    /// Shows this text on hover.
+    /// Supports embedding scripts between `{{double braces}}`.
+    ///
+    /// Note that full dynamic string support is not currently supported.
+    ///
+    /// **Default**: `null`
+    pub tooltip: Option<String>,
+
+    /// Shows the module only if the dynamic boolean evaluates to true.
+    ///
+    /// This allows for modules to be dynamically shown or hidden
+    /// based on custom events.
+    ///
+    /// **Default**: `null`
     pub show_if: Option<DynamicBool>,
+
+    /// The transition animation to use when showing/hiding the widget.
+    ///
+    /// Note this has no effect if `show_if` is not configured.
+    ///
+    /// **Valid options**: `slide_start`, `slide_end`, `crossfade`, `none`
+    /// <br>
+    /// **Default**: `slide_start`
     pub transition_type: Option<TransitionType>,
+
+    /// The length in milliseconds
+    /// of the transition animation to use when showing/hiding the widget.
+    ///
+    /// Note this has no effect if `show_if` is not configured.
+    ///
+    /// **Default**: `250`
     pub transition_duration: Option<u32>,
 
+    /// A [script](scripts) to run when the module is left-clicked.
+    ///
+    /// **Supported script types**: `oneshot`.
+    /// <br>
+    /// **Default**: `null`
+    ///
+    /// # Example
+    ///
+    /// ```corn
+    /// { on_click_left = "echo 'event' >> log.txt" }
+    /// ```
     pub on_click_left: Option<ScriptInput>,
+
+    /// A [script](scripts) to run when the module is right-clicked.
+    ///
+    /// **Supported script types**: `oneshot`.
+    /// <br>
+    /// **Default**: `null`
+    /// /// # Example
+    ///
+    /// ```corn
+    /// { on_click_right = "echo 'event' >> log.txt" }
+    /// ```
     pub on_click_right: Option<ScriptInput>,
+
+    /// A [script](scripts) to run when the module is middle-clicked.
+    ///
+    /// **Supported script types**: `oneshot`.
+    /// <br>
+    /// **Default**: `null`
+    /// # Example
+    ///
+    /// ```corn
+    /// { on_click_middle = "echo 'event' >> log.txt" }
+    /// ```
     pub on_click_middle: Option<ScriptInput>,
+
+    /// A [script](scripts) to run when the module is scrolled up on.
+    ///
+    /// **Supported script types**: `oneshot`.
+    /// <br>
+    /// **Default**: `null`
+    /// # Example
+    ///
+    /// ```corn
+    /// { on_scroll_up = "echo 'event' >> log.txt" }
+    /// ```
     pub on_scroll_up: Option<ScriptInput>,
+
+    /// A [script](scripts) to run when the module is scrolled down on.
+    ///
+    /// **Supported script types**: `oneshot`.
+    /// <br>
+    /// **Default**: `null`
+    /// # Example
+    ///
+    /// ```corn
+    /// { on_scroll_down = "echo 'event' >> log.txt" }
+    /// ```
     pub on_scroll_down: Option<ScriptInput>,
+
+    /// A [script](scripts) to run when the cursor begins hovering over the module.
+    ///
+    /// **Supported script types**: `oneshot`.
+    /// <br>
+    /// **Default**: `null`
+    /// # Example
+    ///
+    /// ```corn
+    /// { on_mouse_enter = "echo 'event' >> log.txt" }
+    /// ```
     pub on_mouse_enter: Option<ScriptInput>,
+
+    /// A [script](scripts) to run when the cursor stops hovering over the module.
+    ///
+    /// **Supported script types**: `oneshot`.
+    /// <br>
+    /// **Default**: `null`
+    /// # Example
+    ///
+    /// ```corn
+    /// { on_mouse_exit = "echo 'event' >> log.txt" }
+    /// ```
     pub on_mouse_exit: Option<ScriptInput>,
 
-    pub tooltip: Option<String>,
+    /// Prevents the popup from opening on-click for this widget.
     #[serde(default)]
     pub disable_popup: bool,
 }

src/config/mod.rs

@@ -116,12 +116,6 @@ impl ModuleConfig {
     }
 }
 
-#[derive(Debug, Deserialize, Clone)]
-pub enum BarEntryConfig {
-    Single(BarConfig),
-    Monitors(HashMap<String, MonitorConfig>),
-}
-
 #[derive(Debug, Clone)]
 pub enum MonitorConfig {
     Single(BarConfig),
@@ -155,32 +149,107 @@ pub struct MarginConfig {
     pub top: i32,
 }
 
+/// The following is a list of all top-level bar config options.
+///
+/// These options can either be written at the very top object of your config,
+/// or within an object in the [monitors](#monitors) config,
+/// depending on your [use-case](#2-pick-your-use-case).
+///
 #[derive(Debug, Deserialize, Clone)]
 pub struct BarConfig {
+    /// A unique identifier for the bar, used for controlling it over IPC.
+    /// If not set, uses a generated integer suffix.
+    ///
+    /// **Default**: `bar-n`
+    pub name: Option<String>,
+
+    /// The bar's position on screen.
+    ///
+    /// **Valid options**: `top`, `bottom`, `left`, `right`
+    /// <br>
+    /// **Default**: `bottom`
     #[serde(default)]
     pub position: BarPosition,
+
+    /// Whether to anchor the bar to the edges of the screen.
+    /// Setting to false centers the bar.
+    ///
+    /// **Default**: `true`
     #[serde(default = "default_true")]
     pub anchor_to_edges: bool,
+
+    /// The bar's height in pixels.
+    ///
+    /// Note that GTK treats this as a target minimum,
+    /// and if content inside the bar is over this,
+    /// it will automatically expand to fit.
+    ///
+    /// **Default**: `42`
     #[serde(default = "default_bar_height")]
     pub height: i32,
+
+    /// The margin to use on each side of the bar, in pixels.
+    /// Object which takes `top`, `bottom`, `left` and `right` keys.
+    ///
+    /// **Default**: `0` on all sides.
+    ///
+    /// # Example
+    ///
+    /// The following would set a 10px margin around each edge.
+    ///
+    /// ```corn
+    /// {
+    ///     margin.top = 10
+    ///     margin.bottom = 10
+    ///     margin.left = 10
+    ///     margin.right = 10
+    /// }
+    /// ```
     #[serde(default)]
     pub margin: MarginConfig,
-    pub name: Option<String>,
 
+    /// The size of the gap in pixels
+    /// between the bar and the popup window.
+    ///
+    /// **Default**: `5`
+    #[serde(default = "default_popup_gap")]
+    pub popup_gap: i32,
+
+    /// Whether the bar should be hidden when Ironbar starts.
+    ///
+    /// **Default**: `false`, unless `autohide` is set.
     #[serde(default)]
     pub start_hidden: Option<bool>,
+
+    /// The duration in milliseconds before the bar is hidden after the cursor leaves.
+    /// Leave unset to disable auto-hide behaviour.
+    ///
+    /// **Default**: `null`
     #[serde(default)]
     pub autohide: Option<u64>,
 
-    /// GTK icon theme to use.
+    /// The name of the GTK icon theme to use.
+    /// Leave unset to use the default Adwaita theme.
+    ///
+    /// **Default**: `null`
     pub icon_theme: Option<String>,
 
+    /// An array of modules to append to the start of the bar.
+    /// Depending on the orientation, this is either the top of the left edge.
+    ///
+    /// **Default**: `[]`
     pub start: Option<Vec<ModuleConfig>>,
+
+    /// An array of modules to append to the center of the bar.
+    ///
+    /// **Default**: `[]`
     pub center: Option<Vec<ModuleConfig>>,
-    pub end: Option<Vec<ModuleConfig>>,
 
-    #[serde(default = "default_popup_gap")]
-    pub popup_gap: i32,
+    /// An array of modules to append to the end of the bar.
+    /// Depending on the orientation, this is either the bottom or right edge.
+    ///
+    /// **Default**: `[]`
+    pub end: Option<Vec<ModuleConfig>>,
 }
 
 impl Default for BarConfig {
@@ -224,10 +293,41 @@ impl Default for BarConfig {
 
 #[derive(Debug, Deserialize, Clone, Default)]
 pub struct Config {
+    /// A map of [ironvar](ironvar) keys and values
+    /// to initialize Ironbar with on startup.
+    ///
+    /// **Default**: `{}`
+    ///
+    /// # Example
+    ///
+    /// The following initializes an ironvar called `foo` set to `bar` on startup:
+    ///
+    /// ```corn
+    /// { ironvar_defaults.foo = "bar" }
+    /// ```
+    ///
+    /// The variable can then be immediately fetched without needing to be manually set:
+    ///
+    /// ```sh
+    /// $ ironbar get foo
+    /// ok
+    /// bar
+    /// ```
     pub ironvar_defaults: Option<HashMap<Box<str>, String>>,
 
+    /// The configuration for the bar.
+    /// Setting through this will enable a single identical bar on each monitor.
     #[serde(flatten)]
     pub bar: BarConfig,
+
+    /// A map of monitor names to configs.
+    ///
+    /// The config values can be either:
+    ///
+    /// - a single object, which denotes a single bar for that monitor,
+    /// - an array of multiple objects, which denotes multiple for that monitor.
+    ///
+    /// Providing this option overrides the single, global `bar` option.
     pub monitors: Option<HashMap<String, MonitorConfig>>,
 }
 

src/config/truncate.rs

@@ -20,13 +20,68 @@ impl From<EllipsizeMode> for GtkEllipsizeMode {
     }
 }
 
+/// Some modules provide options for truncating text.
+/// This is controlled using a common `TruncateMode` type,
+/// which is defined below.
+///
+/// The option can be configured in one of two modes.
+///
 #[derive(Debug, Deserialize, Clone, Copy)]
 #[serde(untagged)]
 pub enum TruncateMode {
+    /// Auto mode lets GTK decide when to ellipsize.
+    ///
+    /// To use this mode, set the truncate option to a string
+    /// declaring the location to truncate text from and place the ellipsis.
+    ///
+    /// # Example
+    ///
+    /// ```corn
+    /// { truncate = "start" }
+    /// ```
+    ///
+    /// **Valid options**: `start`, `middle`, `end`
+    /// <br>
+    /// **Default**: `null`
     Auto(EllipsizeMode),
+
+    /// Length mode defines a fixed point at which to ellipsize.
+    ///
+    /// Generally you will want to set only one of `length` or `max_length`,
+    /// but you can set both if required.
+    ///
+    /// # Example
+    ///
+    /// ```corn
+    /// {
+    ///     truncate.mode = "start"
+    ///     truncate.length = 50
+    ///     truncate.max_length = 70
+    /// }
+    /// ```
     Length {
+        /// The location to truncate text from and place the ellipsis.
+        /// **Valid options**: `start`, `middle`, `end`
+        /// <br>
+        /// **Default**: `null`
         mode: EllipsizeMode,
+
+        /// The fixed width (in characters) of the widget.
+        ///
+        /// The widget will be expanded to this width
+        /// if it would have otherwise been smaller.
+        ///
+        /// Leave unset to let GTK automatically handle.
+        ///
+        /// **Default**: `null`
         length: Option<i32>,
+
+        /// The maximum number of characters to show
+        /// before truncating.
+        ///
+        /// Leave unset to let GTK automatically handle.
+        ///
+        /// **Default**: `null`
         max_length: Option<i32>,
     },
 }