docs(schema): add deprecations and improve formatting

komorebi-bar/src/widgets/komorebi.rs

@@ -103,7 +103,8 @@ pub struct KomorebiWorkspaceLayerConfig {
 pub struct KomorebiFocusedContainerConfig {
     /// Enable the Komorebi Focused Container widget
     pub enable: bool,
-    /// DEPRECATED: use 'display' instead (Show the icon of the currently focused container)
+    /// DEPRECATED: use `display` instead (Show the icon of the currently focused container)
+    #[deprecated(note = "Use `display` instead")]
     pub show_icon: Option<bool>,
     /// Display format of the currently focused container
     pub display: Option<DisplayFormat>,
@@ -506,7 +507,9 @@ impl FocusedContainerBar {
         if !value.enable {
             return None;
         }
+
         // Handle legacy setting - convert show_icon to display format
+        #[allow(deprecated)]
         let format = value
             .display
             .unwrap_or(if value.show_icon.unwrap_or(false) {

komorebi/src/core/mod.rs

@@ -1,5 +1,6 @@
 #![warn(clippy::all)]
 #![allow(clippy::missing_errors_doc, clippy::use_self, clippy::doc_markdown)]
+#![allow(deprecated)] // allow deprecated variants like HidingBehaviour::Hide to be used in derive macros
 
 use std::num::NonZeroUsize;
 use std::path::PathBuf;
@@ -397,7 +398,7 @@ pub struct WindowManagementBehaviour {
     pub floating_layer_placement: Placement,
     /// The `Placement` to be used when spawning a window with float override active
     pub float_override_placement: Placement,
-    /// The `Placement` to be used when spawning a window that matches a 'floating_applications' rule
+    /// The `Placement` to be used when spawning a window that matches a `floating_applications` rule
     pub float_rule_placement: Placement,
 }
 
@@ -493,9 +494,10 @@ pub enum CrossBoundaryBehaviour {
 #[derive(Copy, Clone, Debug, Serialize, Deserialize, Display, EnumString, ValueEnum, PartialEq)]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub enum HidingBehaviour {
-    /// END OF LIFE FEATURE: Use the SW_HIDE flag to hide windows when switching workspaces (has issues with Electron apps)
+    /// END OF LIFE FEATURE: Use the `SW_HIDE` flag to hide windows when switching workspaces (has issues with Electron apps)
+    #[deprecated(note = "End of life feature")]
     Hide,
-    /// Use the SW_MINIMIZE flag to hide windows when switching workspaces (has issues with frequent workspace switching)
+    /// Use the `SW_MINIMIZE` flag to hide windows when switching workspaces (has issues with frequent workspace switching)
     Minimize,
     /// Use the undocumented SetCloak Win32 function to hide windows when switching workspaces
     Cloak,

komorebi/src/main.rs

@@ -176,7 +176,7 @@ struct Opts {
     /// Allow the use of komorebi's custom focus-follows-mouse implementation
     #[clap(short, long = "ffm")]
     focus_follows_mouse: bool,
-    /// Wait for 'komorebic complete-configuration' to be sent before processing events
+    /// Wait for `komorebic complete-configuration` to be sent before processing events
     #[clap(short, long)]
     await_configuration: bool,
     /// Start a TCP server on the given port to allow the direct sending of SocketMessages

komorebi/src/reaper.rs

@@ -183,6 +183,7 @@ fn find_orphans() -> color_eyre::Result<()> {
         for (hwnd, (m_idx, w_idx)) in cache.iter() {
             let window = Window::from(*hwnd);
 
+            #[allow(deprecated)]
             if !window.is_window()
                 || (
                     // This one is a hack because WINWORD.EXE is an absolute trainwreck of an app

komorebi/src/static_config.rs

@@ -196,6 +196,7 @@ pub struct WorkspaceConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub layout_options: Option<LayoutOptions>,
     /// END OF LIFE FEATURE: Custom Layout (default: None)
+    #[deprecated(note = "End of life feature")]
     #[serde(skip_serializing_if = "Option::is_none")]
     #[serde_as(as = "Option<ResolvedPathBuf>")]
     pub custom_layout: Option<PathBuf>,
@@ -203,6 +204,7 @@ pub struct WorkspaceConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub layout_rules: Option<HashMap<usize, DefaultLayout>>,
     /// END OF LIFE FEATURE: Custom layout rules (default: None)
+    #[deprecated(note = "End of life feature")]
     #[serde(skip_serializing_if = "Option::is_none")]
     #[serde(deserialize_with = "resolve_option_hashmap_usize_path", default)]
     pub custom_layout_rules: Option<HashMap<usize, PathBuf>>,
@@ -299,11 +301,13 @@ impl From<&Workspace> for WorkspaceConfig {
                 })
                 .flatten(),
             layout_options: value.layout_options,
+            #[allow(deprecated)]
             custom_layout: value
                 .workspace_config
                 .as_ref()
                 .and_then(|c| c.custom_layout.clone()),
             layout_rules,
+            #[allow(deprecated)]
             custom_layout_rules: value
                 .workspace_config
                 .as_ref()
@@ -403,9 +407,9 @@ impl From<&Monitor> for MonitorConfig {
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[serde(untagged)]
 pub enum AppSpecificConfigurationPath {
-    /// A single applications.json file
+    /// A single `applications.json` file
     Single(#[serde_as(as = "ResolvedPathBuf")] PathBuf),
-    /// Multiple applications.json files
+    /// Multiple `applications.json` files
     Multiple(#[serde_as(as = "Vec<ResolvedPathBuf>")] Vec<PathBuf>),
 }
 
@@ -415,6 +419,7 @@ pub enum AppSpecificConfigurationPath {
 /// The `komorebi.json` static configuration file reference for `v0.1.40`
 pub struct StaticConfig {
     /// DEPRECATED from v0.1.22: no longer required
+    #[deprecated(note = "No longer required")]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub invisible_borders: Option<Rect>,
     /// DISCOURAGED: Minimum width for a window to be eligible for tiling
@@ -449,7 +454,7 @@ pub struct StaticConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub float_override_placement: Option<Placement>,
     /// Determines the `Placement` to be used when spawning a window that matches a
-    /// 'floating_applications' rule (default: None)
+    /// `floating_applications` rule (default: None)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub float_rule_placement: Option<Placement>,
     /// Determine what happens when a window is moved across a monitor boundary (default: Swap)
@@ -462,6 +467,9 @@ pub struct StaticConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub unmanaged_window_operation_behaviour: Option<OperationBehaviour>,
     /// END OF LIFE FEATURE: Use https://github.com/LGUG2Z/masir instead
+    #[deprecated(
+        note = "End of life feature, use [masir](https://github.com/LGUG2Z/masir) instead"
+    )]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub focus_follows_mouse: Option<FocusFollowsMouseImplementation>,
     /// Enable or disable mouse follows focus (default: true)
@@ -491,6 +499,7 @@ pub struct StaticConfig {
     #[serde(alias = "active_window_border_style")]
     pub border_style: Option<BorderStyle>,
     /// DEPRECATED from v0.1.31: no longer required
+    #[deprecated(note = "No longer required")]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub border_z_order: Option<ZOrder>,
     /// Window border implementation (default: Komorebi)
@@ -536,13 +545,13 @@ pub struct StaticConfig {
     /// Identify tray and multi-window applications
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tray_and_multi_window_applications: Option<Vec<MatchingRule>>,
-    /// Identify applications that have the WS_EX_LAYERED extended window style
+    /// Identify applications that have the `WS_EX_LAYERED` extended window style
     #[serde(skip_serializing_if = "Option::is_none")]
     pub layered_applications: Option<Vec<MatchingRule>>,
-    /// Identify applications that send EVENT_OBJECT_NAMECHANGE on launch (very rare)
+    /// Identify applications that send `EVENT_OBJECT_NAMECHANGE` on launch (very rare)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub object_name_change_applications: Option<Vec<MatchingRule>>,
-    /// Do not process EVENT_OBJECT_NAMECHANGE events as Show events for identified applications matching these title regexes
+    /// Do not process `EVENT_OBJECT_NAMECHANGE` events as Show events for identified applications matching these title regexes
     #[serde(skip_serializing_if = "Option::is_none")]
     pub object_name_change_title_ignore_list: Option<Vec<String>>,
     /// Set monitor index preferences
@@ -862,6 +871,7 @@ impl From<&WindowManager> for StaticConfig {
         };
 
         Self {
+            #[allow(deprecated)]
             invisible_borders: None,
             resize_delta: Option::from(value.resize_delta),
             window_container_behaviour: Option::from(
@@ -890,6 +900,7 @@ impl From<&WindowManager> for StaticConfig {
             ),
             minimum_window_height: Some(window::MINIMUM_HEIGHT.load(Ordering::SeqCst)),
             minimum_window_width: Some(window::MINIMUM_WIDTH.load(Ordering::SeqCst)),
+            #[allow(deprecated)]
             focus_follows_mouse: value.focus_follows_mouse,
             mouse_follows_focus: Option::from(value.mouse_follows_focus),
             app_specific_configuration_path: None,
@@ -905,6 +916,7 @@ impl From<&WindowManager> for StaticConfig {
             ),
             transparency_ignore_rules: None,
             border_style: Option::from(STYLE.load()),
+            #[allow(deprecated)]
             border_z_order: None,
             border_implementation: Option::from(IMPLEMENTATION.load()),
             default_workspace_padding: Option::from(
@@ -1312,6 +1324,7 @@ impl StaticConfig {
                 .unmanaged_window_operation_behaviour
                 .unwrap_or(OperationBehaviour::Op),
             resize_delta: value.resize_delta.unwrap_or(50),
+            #[allow(deprecated)]
             focus_follows_mouse: value.focus_follows_mouse,
             mouse_follows_focus: value.mouse_follows_focus.unwrap_or(true),
             hotwatch: Hotwatch::new()?,
@@ -1322,6 +1335,7 @@ impl StaticConfig {
             known_hwnds: HashMap::new(),
         };
 
+        #[allow(deprecated)]
         match value.focus_follows_mouse {
             None => WindowsApi::disable_focus_follows_mouse()?,
             Some(FocusFollowsMouseImplementation::Windows) => {
@@ -1702,7 +1716,10 @@ impl StaticConfig {
         wm.resize_delta = value.resize_delta.unwrap_or(50);
         wm.mouse_follows_focus = value.mouse_follows_focus.unwrap_or(true);
         wm.work_area_offset = value.global_work_area_offset;
-        wm.focus_follows_mouse = value.focus_follows_mouse;
+        #[allow(deprecated)]
+        {
+            wm.focus_follows_mouse = value.focus_follows_mouse;
+        }
 
         match wm.focus_follows_mouse {
             None => WindowsApi::disable_focus_follows_mouse()?,
@@ -1969,6 +1986,7 @@ mod tests {
         "#;
         let config = serde_json::from_str::<WorkspaceConfig>(config).unwrap();
 
+        #[allow(deprecated)]
         let custom_layout_rules = config.custom_layout_rules.unwrap();
 
         assert_eq!(
@@ -1985,7 +2003,10 @@ mod tests {
             "name": "Test",
         }
         "#;
+
         let config = serde_json::from_str::<WorkspaceConfig>(config).unwrap();
-        assert_eq!(config.custom_layout_rules, None);
+        #[allow(deprecated)]
+        let custom_layout_rules = config.custom_layout_rules;
+        assert_eq!(custom_layout_rules, None);
     }
 }

komorebi/src/window.rs

@@ -491,6 +491,8 @@ impl Window {
         }
 
         let hiding_behaviour = HIDING_BEHAVIOUR.lock();
+
+        #[allow(deprecated)]
         match *hiding_behaviour {
             HidingBehaviour::Hide => WindowsApi::hide_window(self.hwnd),
             HidingBehaviour::Minimize => WindowsApi::minimize_window(self.hwnd),
@@ -515,6 +517,8 @@ impl Window {
         }
 
         let hiding_behaviour = HIDING_BEHAVIOUR.lock();
+
+        #[allow(deprecated)]
         match *hiding_behaviour {
             HidingBehaviour::Hide | HidingBehaviour::Minimize => {
                 WindowsApi::restore_window(self.hwnd);

komorebi/src/workspace.rs

@@ -176,14 +176,19 @@ impl Workspace {
             self.layout = Layout::Default(*layout);
         }
 
+        #[allow(deprecated)]
         if let Some(pathbuf) = &config.custom_layout {
             let layout = CustomLayout::from_path(pathbuf)?;
             self.layout = Layout::Custom(layout);
         }
 
-        self.tile =
-            !(config.custom_layout.is_none() && config.layout.is_none() && config.tile.is_none()
+        #[allow(deprecated)]
+        {
+            self.tile = !(config.custom_layout.is_none()
+                && config.layout.is_none()
+                && config.tile.is_none()
                 || config.tile.is_some_and(|tile| !tile));
+        }
 
         let mut all_layout_rules = vec![];
         if let Some(layout_rules) = &config.layout_rules {
@@ -197,6 +202,7 @@ impl Workspace {
 
         self.layout_rules = all_layout_rules.clone();
 
+        #[allow(deprecated)]
         if let Some(layout_rules) = &config.custom_layout_rules {
             for (count, pathbuf) in layout_rules {
                 let rule = CustomLayout::from_path(pathbuf)?;

komorebic/src/main.rs

@@ -796,7 +796,7 @@ struct Start {
     #[clap(short, long)]
     #[clap(value_parser = replace_env_in_path)]
     config: Option<PathBuf>,
-    /// Wait for 'komorebic complete-configuration' to be sent before processing events
+    /// Wait for `komorebic complete-configuration` to be sent before processing events
     #[clap(short, long)]
     await_configuration: bool,
     /// Start a TCP server on the given port to allow the direct sending of SocketMessages
@@ -1387,6 +1387,7 @@ enum SubCommand {
     /// For legacy komorebi.ahk or komorebi.ps1 configurations, signal that the final configuration option has been sent
     CompleteConfiguration,
     /// DEPRECATED since v0.1.22
+    #[deprecated(note = "No longer required")]
     #[clap(arg_required_else_help = true)]
     #[clap(hide = true)]
     AltFocusHack(AltFocusHack),
@@ -1524,7 +1525,7 @@ enum SubCommand {
     #[clap(arg_required_else_help = true)]
     #[clap(alias = "convert-asc")]
     ConvertAppSpecificConfiguration(ConvertAppSpecificConfiguration),
-    /// Format a YAML file for use with the 'app-specific-configuration' command
+    /// Format a YAML file for use with the `app-specific-configuration` command
     #[clap(arg_required_else_help = true)]
     #[clap(alias = "fmt-asc")]
     #[clap(hide = true)]
@@ -3352,6 +3353,7 @@ if (Get-Command Get-CimInstance -ErrorAction SilentlyContinue) {
             print_query(&SocketMessage::GenerateStaticConfig);
         }
         // Deprecated
+        #[allow(deprecated)]
         SubCommand::AltFocusHack(_) | SubCommand::IdentifyBorderOverflowApplication(_) => {
             println!("Command deprecated - this is now automatically handled by komorebi! 🎉");
         }

schema.bar.json

@@ -1300,7 +1300,8 @@
         {
           "description": "END OF LIFE FEATURE: Use the SW_HIDE flag to hide windows when switching workspaces (has issues with Electron apps)",
           "type": "string",
-          "const": "Hide"
+          "const": "Hide",
+          "deprecated": true
         },
         {
           "description": "Use the SW_MINIMIZE flag to hide windows when switching workspaces (has issues with frequent workspace switching)",
@@ -1631,11 +1632,12 @@
           "type": "boolean"
         },
         "show_icon": {
-          "description": "DEPRECATED: use 'display' instead (Show the icon of the currently focused container)",
+          "description": "DEPRECATED: use `display` instead (Show the icon of the currently focused container)",
           "type": [
             "boolean",
             "null"
-          ]
+          ],
+          "deprecated": true
         }
       },
       "required": [

schema.json

@@ -111,7 +111,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "deprecated": true
     },
     "cross_boundary_behaviour": {
       "description": "Determine what happens when an action is called on a window at a monitor boundary (default: Monitor)",
@@ -245,7 +246,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "deprecated": true
     },
     "global_work_area_offset": {
       "description": "Global work area (space used for tiling) offset (default: None)",
@@ -277,7 +279,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "deprecated": true
     },
     "layered_applications": {
       "description": "Identify applications that have the WS_EX_LAYERED extended window style",
@@ -1289,7 +1292,8 @@
         {
           "description": "END OF LIFE FEATURE: Use the SW_HIDE flag to hide windows when switching workspaces (has issues with Electron apps)",
           "type": "string",
-          "const": "Hide"
+          "const": "Hide",
+          "deprecated": true
         },
         {
           "description": "Use the SW_MINIMIZE flag to hide windows when switching workspaces (has issues with frequent workspace switching)",
@@ -2384,7 +2388,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "deprecated": true
         },
         "custom_layout_rules": {
           "description": "END OF LIFE FEATURE: Custom layout rules (default: None)",
@@ -2393,6 +2398,7 @@
             "null"
           ],
           "additionalProperties": false,
+          "deprecated": true,
           "patternProperties": {
             "^\\d+$": {
               "type": "string"