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/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,
 }