docs: add rustdoc comments to all module options

This part of an upcoming effort to generate documentation from code.

Pushing this out before that stage so that the JSON schema is fully documented.

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 {
-    #[serde(default)]
-    pub position: BarPosition,
-    #[serde(default = "default_true")]
-    pub anchor_to_edges: bool,
-    #[serde(default = "default_bar_height")]
-    pub height: i32,
-    #[serde(default)]
-    pub margin: MarginConfig,
+    /// 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,
+
+    /// 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>>,
-    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 center of the bar.
+    ///
+    /// **Default**: `[]`
+    pub center: Option<Vec<ModuleConfig>>,
+
+    /// 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>,
     },
 }