docs: tidy and improve config comments and schema gen

JakeStanger · JakeStanger · commit 8683efe3419d · 2026-01-07T20:53:19.000Z
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -199,5 +199,5 @@ rustix = { version = "1.1.3", default-features = false, features = ["std", "fs",
 serde_json = { version = "1.0.148", optional = true } # ipc, niri
 
 # extras
-schemars = { version = "1.2.0", optional = true, features = ["indexmap2"] }
+schemars = { version = "1.2.0", optional = true, features = ["preserve_order", "indexmap2"] }
 clap_complete = {  version = "4.5.62", optional = true }
diff --git a/src/config/layout.rs b/src/config/layout.rs
@@ -6,7 +6,6 @@ use serde::Deserialize;
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 pub struct LayoutConfig {
     /// The orientation to display the widget contents.
-    /// Setting to vertical will rotate text 90 degrees.
     ///
     /// **Valid options**: `horizontal`, `vertical`
     /// <br>
diff --git a/src/config/mod.rs b/src/config/mod.rs
@@ -505,7 +505,7 @@ pub struct Config {
 
     // force type to be included in schema
     #[cfg(feature = "extras")]
-    __common: CommonConfig
+    __common: CommonConfig,
 }
 
 /// Double-click time configuration
diff --git a/src/config/truncate.rs b/src/config/truncate.rs
@@ -34,6 +34,7 @@ impl From<EllipsizeMode> for GtkEllipsizeMode {
 #[derive(Debug, Deserialize, Clone, Copy)]
 #[serde(untagged)]
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
+#[cfg_attr(feature = "extras", schemars(_unstable_ref_variants))] // fix unit variant showing as null
 pub enum TruncateMode {
     /// Do not truncate content.
     ///
diff --git a/src/dynamic_value/mod.rs b/src/dynamic_value/mod.rs
@@ -1,4 +1,4 @@
-#![doc = include_str!("../../docs/Dynamic values.md")]
+#![doc = include_str!("../../docs/dynamic content/Dynamic values.md")]
 
 mod dynamic_bool;
 mod dynamic_string;
diff --git a/src/ironvar.rs b/src/ironvar.rs
@@ -1,4 +1,4 @@
-#![doc = include_str!("../docs/Ironvars.md")]
+#![doc = include_str!("../docs/dynamic content/Ironvars.md")]
 
 use crate::channels::SyncSenderExt;
 use crate::{arc_rw, read_lock, write_lock};
diff --git a/src/modules/battery.rs b/src/modules/battery.rs
@@ -29,7 +29,15 @@ const MINUTE: i64 = 60;
 #[serde(default)]
 pub struct BatteryModule {
     /// The format string to use for the widget button label.
-    /// For available tokens, see [below](#formatting-tokens).
+    ///
+    /// The following tokens can be used
+    /// and will be replaced with values from the battery state:
+    ///
+    /// | Token               | Description                              |
+    /// |---------------------|------------------------------------------|
+    /// | `{percentage}`      | The battery charge percentage.           |
+    /// | `{state}`           | The current battery (dis)charging state. |
+    /// | `{time_remaining}`  | The ETA to battery empty or full.        |
     ///
     /// **Default**: `{percentage}%`
     format: String,
diff --git a/src/modules/bluetooth/config.rs b/src/modules/bluetooth/config.rs
@@ -44,6 +44,18 @@ impl Default for BluetoothModule {
     }
 }
 
+/// Format strings for each of the bluetooth adapter states.
+///
+/// The following tokens can be used:
+///
+/// | Token                      | Description                                                                                                             |
+/// |----------------------------|-------------------------------------------------------------------------------------------------------------------------|
+/// | `{adapter_status}`         | The current adapter status. The mapping of a status to a string could be defined using `adapter_status` config section. |
+/// | `{device_alias}`           | The device name or address if name is not available.                                                                    |
+/// | `{device_status}`          | The current device status. The mapping of a status to a string could be defined using `device_status` config section.   |
+/// | `{device_battery_percent}` | The device battery percentage.                                                                                          |
+/// | `{device_address}`         | The device address, e.g `00:11:22:33:FF:EE`.                                                                            |
+
 #[derive(Debug, Deserialize, Clone)]
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 #[serde(default)]
@@ -90,7 +102,9 @@ impl Default for FormatConfig {
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 #[serde(rename_all = "lowercase")]
 pub enum SizeLimit {
+    /// The maximum number of devices the window can reach before scrolling.
     Devices(i32),
+    /// The maximum number of pixels the window can reach before scrolling.
     Pixels(i32),
 }
 
diff --git a/src/modules/cairo.rs b/src/modules/cairo.rs
@@ -19,14 +19,13 @@ use tracing::{debug, error};
 
 #[derive(Debug, Clone, Deserialize)]
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
+#[cfg_attr(feature = "extras", schemars(extend("required" = ["path"])))]
 #[serde(default)]
 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.
@@ -45,6 +44,7 @@ pub struct CairoModule {
     height: u32,
 
     /// See [common options](module-level-options#common-options).
+    #[serde(flatten)]
     pub common: Option<CommonConfig>,
 }
 
diff --git a/src/modules/inhibit/config.rs b/src/modules/inhibit/config.rs
@@ -11,23 +11,21 @@ use std::time::Duration;
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 #[serde(rename_all = "lowercase")]
 pub enum InhibitCommand {
-    /// Toggle inhibit on/off
+    /// Toggle inhibit on/off.
     Toggle,
-    /// Cycle to next duration
+    /// Cycle to next duration.
     Cycle,
 }
 
 #[derive(Debug, Deserialize, Clone)]
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 #[serde(default)]
 pub struct InhibitModule {
-    /// Duration configuration: list of durations to cycle through and default.
-    /// Use `0` for infinite inhibit. Format: `HH:MM:SS` (e.g., `01:30:00`)
-    ///
-    /// If `default_duration` is not specified, the first item in `durations` is used.
-    ///
-    /// **Default**: `durations = ["00:30:00", "01:00:00", "01:30:00", "02:00:00", "0"]`
-    /// **Default**: `default_duration = "00:30:00"`
+    /// See [common options](module-level-options#common-options).
+    #[serde(flatten)]
+    pub common: Option<CommonConfig>,
+
+    /// See [DurationSpec]
     #[serde(flatten)]
     pub(super) duration_spec: DurationSpec,
 
@@ -36,13 +34,15 @@ pub struct InhibitModule {
     /// **Valid options**: `toggle`, `cycle`
     /// <br>
     /// **Default**: `toggle`
+    #[cfg_attr(feature = "extras", schemars(extend("default" = "'toggle'")))]
     pub(super) on_click_left: Option<InhibitCommand>,
 
     /// Command to execute on right click.
     ///
     /// **Valid options**: `toggle`, `cycle`
     /// <br>
     /// **Default**: `cycle`
+    #[cfg_attr(feature = "extras", schemars(extend("default" = "'cycle'")))]
     pub(super) on_click_right: Option<InhibitCommand>,
 
     /// Command to execute on middle click.
@@ -55,22 +55,26 @@ pub struct InhibitModule {
     /// Format string when inhibit is active.
     /// `{duration}` token shows remaining/selected time.
     ///
+    /// Available tokens:
+    ///
+    /// | Token        | Description       |
+    /// |--------------|-------------------|
+    /// | `{duration}` | Current duration. |
+    ///
     /// **Default**: `"☕ {duration}"`
     pub(super) format_on: String,
 
     /// Format string when inhibit is inactive.
     /// `{duration}` token shows selected duration.
     ///
+    /// See [format_on](#format_on) for available tokens.
+    ///
     /// **Default**: `"💤 {duration}"`
     pub(super) format_off: String,
 
     /// See [layout options](module-level-options#layout).
     #[serde(flatten)]
     pub(super) layout: LayoutConfig,
-
-    /// See [common options](module-level-options#common-options).
-    #[serde(flatten)]
-    pub common: Option<CommonConfig>,
 }
 
 impl Default for InhibitModule {
@@ -100,9 +104,17 @@ fn parse_duration(s: &str) -> Result<Duration, String> {
 #[derive(Debug, Clone)]
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 pub(super) struct DurationSpec {
+    /// List of durations to cycle through.
+    /// Use `0` for infinite inhibit. Format: `HH:MM:SS` (e.g., `01:30:00`).
+    ///
+    /// If `default_duration` is not specified, the first item in `durations` is used.
     #[cfg_attr(feature = "extras", schemars(with = "Vec<String>"))]
+    #[cfg_attr(feature = "extras", schemars(extend("default" = ["00:30:00", "01:00:00", "01:30:00", "02:00:00", "inf"])))]
     pub(super) durations: Vec<Duration>,
+
+    /// Starting duration. See [durations](#durations) above for information.
     #[cfg_attr(feature = "extras", schemars(with = "String"))]
+    #[cfg_attr(feature = "extras", schemars(extend("default" = "00:30:00")))]
     pub(super) default_duration: Duration,
 }
 
diff --git a/src/modules/label.rs b/src/modules/label.rs
@@ -14,8 +14,6 @@ use tokio::sync::mpsc;
 pub struct LabelModule {
     /// The text to show on the label.
     /// This is a [Dynamic String](dynamic-values#dynamic-string).
-    ///
-    /// **Required**
     label: String,
 
     // -- Common --
diff --git a/src/modules/launcher/mod.rs b/src/modules/launcher/mod.rs
@@ -87,6 +87,11 @@ pub struct LauncherModule {
     /// **Default**: `16`
     pagination_icon_size: i32,
 
+    /// Command used to launch applications.
+    ///
+    /// **Default**: `gtk-launch`
+    launch_command: String,
+
     // -- common --
     /// Truncate application names on the bar if they get too long.
     /// See [truncate options](module-level-options#truncate-mode).
@@ -104,11 +109,6 @@ pub struct LauncherModule {
     #[serde(default, flatten)]
     layout: LayoutConfig,
 
-    /// Command used to launch applications.
-    ///
-    /// **Default**: `gtk-launch`
-    launch_command: String,
-
     /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
diff --git a/src/modules/menu/config.rs b/src/modules/menu/config.rs
@@ -89,7 +89,7 @@ pub struct MenuModule {
     /// Can be used with `truncate` options
     /// to customise how item labels are truncated.
     ///
-    /// **Default**: `null`
+    /// Setting `height` will cause this to default to `400`.
     pub(super) width: Option<i32>,
 
     /// Label to show on the menu button on the bar.
@@ -105,6 +105,11 @@ pub struct MenuModule {
     /// Size of the `label_icon` image.
     pub(super) label_icon_size: i32,
 
+    /// Command used to launch applications.
+    ///
+    /// **Default**: `gtk-launch`
+    pub launch_command: String,
+
     // -- common --
     /// Truncate options to apply to (sub)menu item labels.
     ///
@@ -116,11 +121,6 @@ pub struct MenuModule {
     /// See [common options](module-level-options#common-options).
     #[serde(flatten)]
     pub common: Option<CommonConfig>,
-
-    /// Command used to launch applications.
-    ///
-    /// **Default**: `gtk-launch`
-    pub launch_command: String,
 }
 
 impl Default for MenuModule {
diff --git a/src/modules/music/config.rs b/src/modules/music/config.rs
@@ -32,13 +32,25 @@ impl Default for PlayerType {
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 #[serde(default)]
 pub struct MusicModule {
-    /// Type of player to connect to
+    /// Type of player to connect to.
     #[serde(default)]
+    #[cfg_attr(feature = "extras", schemars(extend("default" = "'mpris'")))]
     pub(crate) player_type: PlayerType,
 
     /// Format of current song info to display on the bar.
     ///
-    /// Info on formatting tokens [below](#formatting-tokens).
+    /// The following tokens can be used and will be replaced
+    /// with values from the currently playing track:
+    ///
+    /// | Token        | Description                          |
+    /// |--------------|--------------------------------------|
+    /// | `{title}`    | Title                                |
+    /// | `{album}`    | Album name                           |
+    /// | `{artist}`   | Artist name                          |
+    /// | `{date}`     | Release date                         |
+    /// | `{track}`    | Track number                         |
+    /// | `{disc}`     | Disc number                          |
+    /// | `{genre}`    | Genre                                |
     ///
     /// **Default**: `{title} / {artist}`
     pub(crate) format: String,
@@ -65,14 +77,20 @@ pub struct MusicModule {
     pub(crate) cover_image_size: i32,
 
     // -- MPD --
-    /// *[MPD Only]*
+    /// :::note
+    /// MPD only
+    /// :::
+    ///
     /// TCP or Unix socket address of the MPD server.
     /// For TCP, this should include the port number.
     ///
     /// **Default**: `localhost:6600`
     pub(crate) host: String,
 
-    /// *[MPD Only]*
+    /// :::note
+    /// MPD only
+    /// :::
+    ///
     /// Path to root of the MPD server's music directory.
     /// This is required for displaying album art.
     ///
diff --git a/src/modules/networkmanager.rs b/src/modules/networkmanager.rs
@@ -15,6 +15,7 @@ use tokio::sync::mpsc::Receiver;
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 #[serde(default)]
 pub struct NetworkManagerModule {
+    /// Size in pixels to render the icon at.
     icon_size: i32,
 
     #[serde(flatten)]
diff --git a/src/modules/script.rs b/src/modules/script.rs
@@ -12,22 +12,21 @@ use tracing::error;
 
 #[derive(Debug, Deserialize, Clone)]
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
+#[cfg_attr(feature = "extras", schemars(extend("required" = ["cmd"])))]
 #[serde(default)]
 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.
-    /// See [modes](#modes) for more info.
     ///
-    /// **Valid options**: `poll`, `watch`
-    /// <br />
-    /// **Default**: `poll`
+    /// - Use `poll` to run the script wait for it to exit. On exit, the label is updated to show everything the script wrote to `stdout`.
+    /// - Use `watch` to start a long-running script. Every time the script writes to `stdout`, the label is updated to show the latest line.
+    ///   Note this does not work for all programs as they may use block-buffering instead of line-buffering when they detect output being piped.
+    #[cfg_attr(feature = "extras", schemars(extend("default" = "'poll'")))]
     mode: ScriptMode,
 
     /// Time in milliseconds between executions.
diff --git a/src/modules/sysinfo/mod.rs b/src/modules/sysinfo/mod.rs
@@ -22,9 +22,9 @@ use tokio::time::sleep;
 #[serde(default)]
 pub struct SysInfoModule {
     /// List of strings including formatting tokens.
-    /// For available tokens, see [below](#formatting-tokens).
     ///
-    /// **Required**
+    /// See [formatting tokens](#formatting tokens) for detailed information
+    /// on how the formatting system works.
     format: Vec<String>,
 
     /// Number of seconds between refresh.
@@ -116,7 +116,9 @@ impl Default for Intervals {
 #[serde(untagged)]
 #[cfg_attr(feature = "extras", derive(schemars::JsonSchema))]
 pub enum Interval {
+    /// Shared between all systems.
     All(u64),
+    /// Per-system overrides.
     Individual(Intervals),
 }
 
diff --git a/src/modules/tray/mod.rs b/src/modules/tray/mod.rs
diff --git a/src/modules/volume.rs b/src/modules/volume.rs
diff --git a/src/modules/workspaces/mod.rs b/src/modules/workspaces/mod.rs
diff --git a/src/script.rs b/src/script.rs

Original file line number	Diff line number	Diff line change
`@@ -505,7 +505,7 @@ pub struct Config {`
`505`	`505`
`506`	`506`	`// force type to be included in schema`
`507`	`507`	`#[cfg(feature = "extras")]`
`508`		`- __common: CommonConfig`
	`508`	`+ __common: CommonConfig,`
`509`	`509`	`}`
`510`	`510`
`511`	`511`	`/// Double-click time configuration`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-#![doc = include_str!("../../docs/Dynamic values.md")]`
	`1`	`+#![doc = include_str!("../../docs/dynamic content/Dynamic values.md")]`
`2`	`2`
`3`	`3`	`mod dynamic_bool;`
`4`	`4`	`mod dynamic_string;`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-#![doc = include_str!("../docs/Ironvars.md")]`
	`1`	`+#![doc = include_str!("../docs/dynamic content/Ironvars.md")]`
`2`	`2`
`3`	`3`	`use crate::channels::SyncSenderExt;`
`4`	`4`	`use crate::{arc_rw, read_lock, write_lock};`