Merge pull request #597 from JakeStanger/docs/modules

docs: add rustdoc comments to all module options

src/modules/cairo.rs

@@ -19,16 +19,33 @@ use tracing::{debug, error};
 
 #[derive(Debug, Clone, Deserialize)]
 pub struct CairoModule {
+    /// The path to the Lua script to load.
+    /// This can be absolute, or relative to the working directory.
+    ///
+    /// The script must contain the entry `draw` function.
+    ///
+    /// **Required**
     path: PathBuf,
 
+    /// The number of milliseconds between each draw call.
+    ///
+    /// **Default**: `200`
     #[serde(default = "default_frequency")]
     frequency: u64,
 
+    /// The canvas width in pixels.
+    ///
+    /// **Default**: `42`
     #[serde(default = "default_size")]
     width: u32,
+
+    /// The canvas height in pixels.
+    ///
+    /// **Default**: `42`
     #[serde(default = "default_size")]
     height: u32,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/clipboard.rs

@@ -18,18 +18,34 @@ use tracing::{debug, error};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct ClipboardModule {
+    /// The icon to show on the bar widget button.
+    /// Supports [image](images) icons.
+    ///
+    /// **Default**: `󰨸`
     #[serde(default = "default_icon")]
     icon: String,
 
+    /// The size to render the icon at.
+    /// Note this only applies to image-type icons.
+    ///
+    /// **Default**: `32`
     #[serde(default = "default_icon_size")]
     icon_size: i32,
 
+    /// The maximum number of items to keep in the history,
+    /// and to show in the popup.
+    ///
+    /// **Default**: `10`
     #[serde(default = "default_max_items")]
     max_items: usize,
 
     // -- Common --
+    /// See [truncate options](module-level-options#truncate-mode).
+    ///
+    /// **Default**: `null`
     truncate: Option<TruncateMode>,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/clock.rs

@@ -17,23 +17,47 @@ use crate::{glib_recv, module_impl, send_async, spawn, try_send};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct ClockModule {
-    /// Date/time format string.
-    /// Default: `%d/%m/%Y %H:%M`
+    /// The format string to use for the date/time shown on the bar.
+    /// Pango markup is supported.
     ///
     /// Detail on available tokens can be found here:
     /// <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
+    ///
+    /// **Default**: `%d/%m/%Y %H:%M`
     #[serde(default = "default_format")]
     format: String,
 
+    /// The format string to use for the date/time shown in the popup header.
+    /// Pango markup is supported.
+    ///
+    /// Detail on available tokens can be found here:
+    /// <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
+    ///
+    /// **Default**: `%H:%M:%S`
     #[serde(default = "default_popup_format")]
     format_popup: String,
 
+    /// The locale to use when formatting dates.
+    ///
+    /// Note this will not control the calendar -
+    /// for that you must set `LC_TIME`.
+    ///
+    /// **Valid options**: See [here](https://docs.rs/pure-rust-locales/0.8.1/pure_rust_locales/enum.Locale.html#variants)
+    /// <br>
+    /// **Default**: `$LC_TIME` or `$LANG` or `'POSIX'`
     #[serde(default = "default_locale")]
     locale: String,
 
+    /// The orientation to display the widget contents.
+    /// Setting to vertical will rotate text 90 degrees.
+    ///
+    /// **Valid options**: `horizontal`, `vertical`
+    /// <br>
+    /// **Default**: `horizontal`
     #[serde(default)]
     orientation: ModuleOrientation,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/custom/box.rs

@@ -7,9 +7,26 @@ use serde::Deserialize;
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct BoxWidget {
+    /// Widget name.
+    ///
+    /// **Default**: `null`
     name: Option<String>,
+
+    /// Widget class name.
+    ///
+    /// **Default**: `null`
     class: Option<String>,
+
+    /// Whether child widgets should be horizontally or vertically added.
+    ///
+    /// **Valid options**: `horizontal`, `vertical`, `h`, `v`
+    /// <br />
+    /// **Default**: `horizontal`
     orientation: Option<ModuleOrientation>,
+
+    /// Modules and widgets to add to this box.
+    ///
+    /// **Default**: `null`
     widgets: Option<Vec<WidgetConfig>>,
 }
 

src/modules/custom/button.rs

@@ -11,13 +11,43 @@ use super::{CustomWidget, CustomWidgetContext, ExecEvent, WidgetConfig};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct ButtonWidget {
+    /// Widget name.
+    ///
+    /// **Default**: `null`
     name: Option<String>,
+
+    /// Widget class name.
+    ///
+    /// **Default**: `null`
     class: Option<String>,
+
+    /// Widget text label. Pango markup and embedded scripts are supported.
+    ///
+    /// This is a shorthand for adding a label widget to the button.
+    /// Ignored if `widgets` is set.
+    ///
+    /// This is a [Dynamic String](dynamic-values#dynamic-string).
+    ///
+    /// **Default**: `null`
     label: Option<String>,
+
+    /// Command to execute. More on this [below](#commands).
+    ///
+    /// **Default**: `null`
     on_click: Option<String>,
-    widgets: Option<Vec<WidgetConfig>>,
+
+    /// Orientation of the button.
+    ///
+    /// **Valid options**: `horizontal`, `vertical`, `h`, `v`
+    /// <br />
+    /// **Default**: `horizontal`
     #[serde(default)]
     orientation: ModuleOrientation,
+
+    /// Modules and widgets to add to this box.
+    ///
+    /// **Default**: `null`
+    widgets: Option<Vec<WidgetConfig>>,
 }
 
 impl CustomWidget for ButtonWidget {

src/modules/custom/image.rs

@@ -10,9 +10,27 @@ use super::{CustomWidget, CustomWidgetContext};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct ImageWidget {
+    /// Widget name.
+    ///
+    /// **Default**: `null`
     name: Option<String>,
+
+    /// Widget class name.
+    ///
+    /// **Default**: `null`
     class: Option<String>,
+
+    /// Image source.
+    ///
+    /// This is an [image](image) via [Dynamic String](dynamic-values#dynamic-string).
+    ///
+    /// **Required**
     src: String,
+
+    /// The width/height of the image.
+    /// Aspect ratio is preserved.
+    ///
+    /// **Default**: `32`
     #[serde(default = "default_size")]
     size: i32,
 }

src/modules/custom/label.rs

@@ -10,9 +10,29 @@ use super::{CustomWidget, CustomWidgetContext};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct LabelWidget {
+    /// Widget name.
+    ///
+    /// **Default**: `null`
     name: Option<String>,
+
+    /// Widget class name.
+    ///
+    /// **Default**: `null`
     class: Option<String>,
+
+    /// Widget text label. Pango markup and embedded scripts are supported.
+    ///
+    /// This is a [Dynamic String](dynamic-values#dynamic-string).
+    ///
+    /// **Required**
     label: String,
+
+    /// Orientation of the label.
+    /// Setting to vertical will rotate text 90 degrees.
+    ///
+    /// **Valid options**: `horizontal`, `vertical`, `h`, `v`
+    /// <br />
+    /// **Default**: `horizontal`
     #[serde(default)]
     orientation: ModuleOrientation,
 }
@@ -24,7 +44,6 @@ impl CustomWidget for LabelWidget {
         let label = build!(self, Self::Widget);
 
         label.set_angle(self.orientation.to_angle());
-
         label.set_use_markup(true);
 
         {

src/modules/custom/mod.rs

@@ -29,19 +29,28 @@ use tracing::{debug, error};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct CustomModule {
-    /// Widgets to add to the bar container
+    /// Modules and widgets to add to the bar container.
+    ///
+    /// **Default**: `[]`
     bar: Vec<WidgetConfig>,
-    /// Widgets to add to the popup container
+
+    /// Modules and widgets to add to the popup container.
+    ///
+    /// **Default**: `null`
     popup: Option<Vec<WidgetConfig>>,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct WidgetConfig {
+    /// One of a custom module native Ironbar module.
     #[serde(flatten)]
     widget: WidgetOrModule,
+
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     common: CommonConfig,
 }
@@ -49,18 +58,27 @@ pub struct WidgetConfig {
 #[derive(Debug, Deserialize, Clone)]
 #[serde(untagged)]
 pub enum WidgetOrModule {
+    /// A custom-module specific basic widget
     Widget(Widget),
+    /// A native Ironbar module, such as `clock` or `focused`.
+    /// All widgets are supported, including their popups.
     Module(ModuleConfig),
 }
 
 #[derive(Debug, Deserialize, Clone)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum Widget {
+    /// A container to place nested widgets inside.
     Box(BoxWidget),
+    /// A text label. Pango markup is supported.
     Label(LabelWidget),
+    /// A clickable button, which can run a command when clicked.
     Button(ButtonWidget),
+    /// An image or icon from disk or http.
     Image(ImageWidget),
+    /// A draggable slider.
     Slider(SliderWidget),
+    /// A progress bar.
     Progress(ProgressWidget),
 }
 

src/modules/custom/progress.rs

@@ -14,14 +14,49 @@ use super::{CustomWidget, CustomWidgetContext};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct ProgressWidget {
+    /// Widget name.
+    ///
+    /// **Default**: `null`
     name: Option<String>,
+
+    /// Widget class name.
+    ///
+    /// **Default**: `null`
     class: Option<String>,
+
+    /// Orientation of the progress bar.
+    ///
+    /// **Valid options**: `horizontal`, `vertical`, `h`, `v`
+    /// <br />
+    /// **Default**: `horizontal`
     #[serde(default)]
     orientation: ModuleOrientation,
+
+    /// Text label to show for the progress bar.
+    ///
+    /// This is a [Dynamic String](dynamic-values#dynamic-string).
+    ///
+    /// **Default**: `null`
     label: Option<String>,
+
+    /// Script to run to get the progress bar value.
+    /// Output must be a valid percentage.
+    ///
+    /// Note that this expects a numeric value between `0`-`max` as output.
+    ///
+    /// **Default**: `null`
     value: Option<ScriptInput>,
+
+    /// The maximum progress bar value.
+    ///
+    /// **Default**: `100`
     #[serde(default = "default_max")]
     max: f64,
+
+    /// The progress bar length, in pixels.
+    /// GTK will automatically determine the size if left blank.
+    ///
+    /// **Default**: `null`
     length: Option<i32>,
 }
 

src/modules/custom/slider.rs

@@ -17,18 +17,67 @@ use super::{CustomWidget, CustomWidgetContext, ExecEvent};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct SliderWidget {
+    /// Widget name.
+    ///
+    /// **Default**: `null`
     name: Option<String>,
+
+    /// Widget class name.
+    ///
+    /// **Default**: `null`
     class: Option<String>,
+
+    /// Orientation of the slider.
+    ///
+    /// **Valid options**: `horizontal`, `vertical`, `h`, `v`
+    /// <br />
+    /// **Default**: `horizontal`
     #[serde(default)]
     orientation: ModuleOrientation,
+
+    /// Script to run to get the slider value.
+    /// Output must be a valid number.
+    ///
+    /// **Default**: `null`
     value: Option<ScriptInput>,
+
+    /// Command to execute when the slider changes.
+    /// More on this [below](#slider).
+    ///
+    /// Note that this will provide the floating point value as an argument.
+    /// If your input program requires an integer, you will need to round it.
+    ///
+    /// **Default**: `null`
     on_change: Option<String>,
+
+    /// Minimum slider value.
+    ///
+    /// **Default**: `0`
     #[serde(default = "default_min")]
     min: f64,
+
+    /// Maximum slider value.
+    ///
+    /// **Default**: `100`
     #[serde(default = "default_max")]
     max: f64,
+
+    /// If the increment to change when scrolling with the mousewheel.
+    /// If left blank, GTK will use the default value,
+    /// determined by the current environment.
+    ///
+    /// **Default**: `null`
     step: Option<f64>,
+
+    /// The slider length.
+    /// GTK will automatically determine the size if left blank.
+    ///
+    /// **Default**: `null`
     length: Option<i32>,
+
+    /// Whether to show the value label above the slider.
+    ///
+    /// **Default**: `true`
     #[serde(default = "crate::config::default_true")]
     show_label: bool,
 }

src/modules/focused.rs

@@ -14,18 +14,29 @@ use tracing::debug;
 #[derive(Debug, Deserialize, Clone)]
 pub struct FocusedModule {
     /// Whether to show icon on the bar.
+    ///
+    /// **Default**: `true`
     #[serde(default = "crate::config::default_true")]
     show_icon: bool,
     /// Whether to show app name on the bar.
+    ///
+    /// **Default**: `true`
     #[serde(default = "crate::config::default_true")]
     show_title: bool,
 
     /// Icon size in pixels.
+    ///
+    /// **Default**: `32`
     #[serde(default = "default_icon_size")]
     icon_size: i32,
 
+    // -- common --
+    /// See [truncate options](module-level-options#truncate-mode).
+    ///
+    /// **Default**: `null`
     truncate: Option<TruncateMode>,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/label.rs

@@ -10,8 +10,13 @@ use tokio::sync::mpsc;
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct LabelModule {
+    /// The text to show on the label.
+    /// This is a [Dynamic String](dynamic-values#dynamic-string).
+    ///
+    /// **Required**
     label: String,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/launcher/mod.rs

@@ -22,20 +22,38 @@ use tracing::{debug, error, trace};
 pub struct LauncherModule {
     /// List of app IDs (or classes) to always show regardless of open state,
     /// in the order specified.
+    ///
+    /// **Default**: `null`
     favorites: Option<Vec<String>>,
+
     /// Whether to show application names on the bar.
+    ///
+    /// **Default**: `false`
     #[serde(default = "crate::config::default_false")]
     show_names: bool,
+
     /// Whether to show application icons on the bar.
+    ///
+    /// **Default**: `true`
     #[serde(default = "crate::config::default_true")]
     show_icons: bool,
 
+    /// Size in pixels to render icon at (image icons only).
+    ///
+    /// **Default**: `32`
     #[serde(default = "default_icon_size")]
     icon_size: i32,
 
+    /// Whether items should be added from right-to-left
+    /// instead of left-to-right.
+    ///
+    /// This includes favourites.
+    ///
+    /// **Default**: `false`
     #[serde(default = "crate::config::default_false")]
     reversed: bool,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/music/config.rs

@@ -6,34 +6,50 @@ use std::path::PathBuf;
 #[derive(Debug, Deserialize, Clone)]
 pub struct Icons {
     /// Icon to display when playing.
+    ///
+    /// **Default**: ``
     #[serde(default = "default_icon_play")]
     pub(crate) play: String,
 
     /// Icon to display when paused.
+    ///
+    /// **Default**: ``
     #[serde(default = "default_icon_pause")]
     pub(crate) pause: String,
 
     /// Icon to display for previous button.
+    ///
+    /// **Default**: `󰒮`
     #[serde(default = "default_icon_prev")]
     pub(crate) prev: String,
 
     /// Icon to display for next button.
+    ///
+    /// **Default**: `󰒭`
     #[serde(default = "default_icon_next")]
     pub(crate) next: String,
 
-    /// Icon to display under volume slider
+    /// Icon to display under volume slider.
+    ///
+    /// **Default**: `󰕾`
     #[serde(default = "default_icon_volume")]
     pub(crate) volume: String,
 
-    /// Icon to display nex to track title
+    /// Icon to display nex to track title.
+    ///
+    /// **Default**: `󰎈`
     #[serde(default = "default_icon_track")]
     pub(crate) track: String,
 
-    /// Icon to display nex to album name
+    /// Icon to display nex to album name.
+    ///
+    /// **Default**: `󰀥`
     #[serde(default = "default_icon_album")]
     pub(crate) album: String,
 
-    /// Icon to display nex to artist name
+    /// Icon to display nex to artist name.
+    ///
+    /// **Default**: `󰠃`
     #[serde(default = "default_icon_artist")]
     pub(crate) artist: String,
 }
@@ -73,33 +89,62 @@ pub struct MusicModule {
     pub(crate) player_type: PlayerType,
 
     /// Format of current song info to display on the bar.
+    ///
+    /// Info on formatting tokens [below](#formatting-tokens).
+    ///
+    /// **Default**: `{title} / {artist}`
     #[serde(default = "default_format")]
     pub(crate) format: String,
 
-    /// Player state icons
+    /// Player state icons.
+    ///
+    /// See [icons](#icons).
     #[serde(default)]
     pub(crate) icons: Icons,
 
-    // -- MPD --
-    /// TCP or Unix socket address.
-    #[serde(default = "default_socket")]
-    pub(crate) host: String,
-    /// Path to root of music directory.
-    #[serde(default = "default_music_dir")]
-    pub(crate) music_dir: PathBuf,
-
+    /// Whether to show the play/pause status icon
+    /// on the bar.
+    ///
+    /// **Default**: `true`
     #[serde(default = "crate::config::default_true")]
     pub(crate) show_status_icon: bool,
 
+    /// Size to render the icons at, in pixels (image icons only).
+    ///
+    /// **Default** `32`
     #[serde(default = "default_icon_size")]
     pub(crate) icon_size: i32,
 
+    /// Size to render the album art image at inside the popup, in pixels.
+    ///
+    /// **Default**: `128`
     #[serde(default = "default_cover_image_size")]
     pub(crate) cover_image_size: i32,
 
+    // -- MPD --
+    /// *[MPD Only]*
+    /// TCP or Unix socket address of the MPD server.
+    /// For TCP, this should include the port number.
+    ///
+    /// **Default**: `localhost:6600`
+    #[serde(default = "default_socket")]
+    pub(crate) host: String,
+
+    /// *[MPD Only]*
+    /// Path to root of the MPD server's music directory.
+    /// This is required for displaying album art.
+    ///
+    /// **Default**: `$HOME/Music`
+    #[serde(default = "default_music_dir")]
+    pub(crate) music_dir: PathBuf,
+
     // -- Common --
+    /// See [truncate options](module-level-options#truncate-mode).
+    ///
+    /// **Default**: `null`
     pub(crate) truncate: Option<TruncateMode>,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/notifications.rs

@@ -11,28 +11,60 @@ use tracing::error;
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct NotificationsModule {
+    /// Whether to show the current notification count.
+    ///
+    /// **Default**: `true`
     #[serde(default = "crate::config::default_true")]
     show_count: bool,
 
+    /// SwayNC state icons.
+    ///
+    /// See [icons](#icons).
     #[serde(default)]
     icons: Icons,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }
 
 #[derive(Debug, Deserialize, Clone)]
 struct Icons {
+    /// Icon to show when the panel is closed, with no notifications.
+    ///
+    /// **Default**: `󰍥`
     #[serde(default = "default_icon_closed_none")]
     closed_none: String,
+
+    /// Icon to show when the panel is closed, with notifications.
+    ///
+    /// **Default**: `󱥂`
     #[serde(default = "default_icon_closed_some")]
     closed_some: String,
+
+    /// Icon to show when the panel is closed, with DnD enabled.
+    /// Takes higher priority than count-based icons.
+    ///
+    /// **Default**: `󱅯`
     #[serde(default = "default_icon_closed_dnd")]
     closed_dnd: String,
+
+    /// Icon to show when the panel is open, with no notifications.
+    ///
+    /// **Default**: `󰍡`
     #[serde(default = "default_icon_open_none")]
     open_none: String,
+
+    /// Icon to show when the panel is open, with notifications.
+    ///
+    /// **Default**: `󱥁`
     #[serde(default = "default_icon_open_some")]
     open_some: String,
+
+    /// Icon to show when the panel is open, with DnD enabled.
+    /// Takes higher priority than count-based icons.
+    ///
+    /// **Default**: `󱅮`
     #[serde(default = "default_icon_open_dnd")]
     open_dnd: String,
 }

src/modules/script.rs

@@ -12,14 +12,29 @@ use tracing::error;
 #[derive(Debug, Deserialize, Clone)]
 pub struct ScriptModule {
     /// Path to script to execute.
+    ///
+    /// This can be an absolute path,
+    /// or relative to the working directory.
+    ///
+    /// **Required**
     cmd: String,
-    /// Script execution mode
+
+    /// Script execution mode.
+    /// See [modes](#modes) for more info.
+    ///
+    /// **Valid options**: `poll`, `watch`
+    /// <br />
+    /// **Default**: `poll`
     #[serde(default = "default_mode")]
     mode: ScriptMode,
+
     /// Time in milliseconds between executions.
+    ///
+    /// **Default**: `5000`
     #[serde(default = "default_interval")]
     interval: u64,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/sysinfo.rs

@@ -15,33 +15,76 @@ use tokio::time::sleep;
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct SysInfoModule {
-    /// List of formatting strings.
+    /// List of strings including formatting tokens.
+    /// For available tokens, see [below](#formatting-tokens).
+    ///
+    /// **Required**
     format: Vec<String>,
-    /// Number of seconds between refresh
+
+    /// Number of seconds between refresh.
+    ///
+    /// This can be set as a global interval,
+    /// or passed as an object to customize the interval per-system.
+    ///
+    /// **Default**: `5`
     #[serde(default = "Interval::default")]
     interval: Interval,
 
+    /// The orientation of text for the labels.
+    ///
+    /// **Valid options**: `horizontal`, `vertical, `h`, `v`
+    /// <br>
+    /// **Default** : `horizontal`
     #[serde(default)]
     orientation: ModuleOrientation,
 
+    /// The orientation by which the labels are laid out.
+    ///
+    /// **Valid options**: `horizontal`, `vertical, `h`, `v`
+    /// <br>
+    /// **Default** : `horizontal`
     direction: Option<ModuleOrientation>,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }
 
 #[derive(Debug, Deserialize, Copy, Clone)]
 pub struct Intervals {
+    /// The number of seconds between refreshing memory data.
+    ///
+    /// **Default**: `5`
     #[serde(default = "default_interval")]
     memory: u64,
+
+    /// The number of seconds between refreshing CPU data.
+    ///
+    /// **Default**: `5`
     #[serde(default = "default_interval")]
     cpu: u64,
+
+    /// The number of seconds between refreshing temperature data.
+    ///
+    /// **Default**: `5`
     #[serde(default = "default_interval")]
     temps: u64,
+
+    /// The number of seconds between refreshing disk data.
+    ///
+    /// **Default**: `5`
     #[serde(default = "default_interval")]
     disks: u64,
+
+    /// The number of seconds between refreshing network data.
+    ///
+    /// **Default**: `5`
     #[serde(default = "default_interval")]
     networks: u64,
+
+    /// The number of seconds between refreshing system data.
+    ///
+    /// **Default**: `5`
     #[serde(default = "default_interval")]
     system: u64,
 }

src/modules/tray/mod.rs

@@ -20,15 +20,28 @@ use tracing::{debug, error, warn};
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct TrayModule {
+    /// Requests that icons from the theme be used over the item-provided item.
+    /// Most items only provide one or the other so this will have no effect in most circumstances.
+    ///
+    /// **Default**: `true`
     #[serde(default = "crate::config::default_true")]
     prefer_theme_icons: bool,
 
+    /// Size in pixels to display the tray icons as.
+    ///
+    /// **Default**: `16`
     #[serde(default = "default_icon_size")]
     icon_size: u32,
 
+    /// Direction to display the tray items.
+    ///
+    /// **Valid options**: `top_to_bottom`, `bottom_to_top`, `left_to_right`, `right_to_left`
+    /// <br>
+    /// **Default**: `left_to_right` if bar is horizontal, `top_to_bottom` if bar is vertical
     #[serde(default, deserialize_with = "deserialize_orientation")]
     direction: Option<PackDirection>,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/upower.rs

@@ -23,12 +23,20 @@ const MINUTE: i64 = 60;
 
 #[derive(Debug, Deserialize, Clone)]
 pub struct UpowerModule {
+    /// The format string to use for the widget button label.
+    /// For available tokens, see [below](#formatting-tokens).
+    ///
+    /// **Default**: `{percentage}%`
     #[serde(default = "default_format")]
     format: String,
 
+    /// The size to render the icon at, in pixels.
+    ///
+    /// **Default**: `24`
     #[serde(default = "default_icon_size")]
     icon_size: i32,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }

src/modules/volume.rs

@@ -15,15 +15,27 @@ use tokio::sync::mpsc;
 
 #[derive(Debug, Clone, Deserialize)]
 pub struct VolumeModule {
+    /// The format string to use for the widget button label.
+    /// For available tokens, see [below](#formatting-tokens).
+    ///
+    /// **Default**: `{icon} {percentage}%`
     #[serde(default = "default_format")]
     format: String,
 
+    /// Maximum value to allow volume sliders to reach.
+    /// Pulse supports values > 100 but this may result in distortion.
+    ///
+    /// **Default**: `100`
     #[serde(default = "default_max_volume")]
     max_volume: f64,
 
+    /// Volume state icons.
+    ///
+    /// See [icons](#icons).
     #[serde(default)]
     icons: Icons,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }
@@ -34,12 +46,27 @@ fn default_format() -> String {
 
 #[derive(Debug, Clone, Deserialize)]
 pub struct Icons {
+    /// Icon to show for high volume levels.
+    ///
+    /// **Default**: `󰕾`
     #[serde(default = "default_icon_volume_high")]
     volume_high: String,
+
+    /// Icon to show for medium volume levels.
+    ///
+    /// **Default**: `󰖀`
     #[serde(default = "default_icon_volume_medium")]
     volume_medium: String,
+
+    /// Icon to show for low volume levels.
+    ///
+    /// **Default**: `󰕿`
     #[serde(default = "default_icon_volume_low")]
     volume_low: String,
+
+    /// Icon to show for muted outputs.
+    ///
+    /// **Default**: `󰝟`
     #[serde(default = "default_icon_muted")]
     muted: String,
 }

src/modules/workspaces.rs

@@ -45,26 +45,69 @@ impl Default for Favorites {
 #[derive(Debug, Deserialize, Clone)]
 pub struct WorkspacesModule {
     /// Map of actual workspace names to custom names.
+    ///
+    /// Custom names can be [images](images).
+    ///
+    /// If a workspace is not present in the map,
+    /// it will fall back to using its actual name.
     name_map: Option<HashMap<String, String>>,
 
-    /// Array of always shown workspaces, and what monitor to show on
+    /// Workspaces which should always be shown.
+    /// This can either be an array of workspace names,
+    /// or a map of monitor names to arrays of workspace names.
+    ///
+    /// **Default**: `{}`
+    ///
+    /// # Example
+    ///
+    /// ```corn
+    /// // array format
+    /// {
+    ///   type = "workspaces"
+    ///   favorites = ["1", "2", "3"]
+    /// }
+    ///
+    /// // map format
+    /// {
+    ///   type = "workspaces"
+    ///   favorites.DP-1 = ["1", "2", "3"]
+    ///   favorites.DP-2 = ["4", "5", "6"]
+    /// }
+    /// ```
     #[serde(default)]
     favorites: Favorites,
 
-    /// List of workspace names to never show
+    /// A list of workspace names to never show.
+    ///
+    /// This may be useful for scratchpad/special workspaces, for example.
+    ///
+    /// **Default**: `[]`
     #[serde(default)]
     hidden: Vec<String>,
 
-    /// Whether to display buttons for all monitors.
+    /// Whether to display workspaces from all monitors.
+    /// When false, only shows workspaces on the current monitor.
+    ///
+    /// **Default**: `false`
     #[serde(default = "crate::config::default_false")]
     all_monitors: bool,
 
+    /// The method used for sorting workspaces.
+    /// `added` always appends to the end, `alphanumeric` sorts by number/name.
+    ///
+    /// **Valid options**: `added`, `alphanumeric`
+    /// <br>
+    /// **Default**: `alphanumeric`
     #[serde(default)]
     sort: SortOrder,
 
+    /// The size to render icons at (image icons only).
+    ///
+    /// **Default**: `32`
     #[serde(default = "default_icon_size")]
     icon_size: i32,
 
+    /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }