From d06b67107b3f2d1cc0d710bfb182070095e5e008 Mon Sep 17 00:00:00 2001
From: outfoxxed <outfoxxed@outfoxxed.me>
Date: Thu, 29 Feb 2024 00:54:18 -0800
Subject: [PATCH] docs(layer): improve WlrLayershell documentation

---
 src/wayland/wlr_layershell.hpp        | 26 ++++++++++++++++++++++++++
 src/wayland/wlr_layershell/window.hpp |  6 +++---
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/src/wayland/wlr_layershell.hpp b/src/wayland/wlr_layershell.hpp
index b96baf79..f86d5135 100644
--- a/src/wayland/wlr_layershell.hpp
+++ b/src/wayland/wlr_layershell.hpp
@@ -11,6 +11,32 @@
 #include "../core/proxywindow.hpp"
 #include "wlr_layershell/window.hpp"
 
+///! Wlroots layershell window
+/// Decorationless window that can be attached to the screen edges using the [zwlr_layer_shell_v1] protocol.
+///
+/// #### Attached property
+/// `WlrLayershell` works as an attached property of [PanelWindow] which you should use instead if you can,
+/// as it is platform independent.
+/// ```qml
+/// PanelWindow {
+///   // When PanelWindow is backed with WlrLayershell this will work
+///   WlrLayershell.layer: Layer.Bottom
+/// }
+/// ```
+///
+/// To maintain platform compatibility you can dynamically set layershell specific properties.
+/// ```qml
+/// PanelWindow {
+///   Component.onCompleted: {
+///     if (this.WlrLayershell != null) {
+///       this.WlrLayershell.layer = Layer.Bottom;
+///     }
+///   }
+/// }
+/// ```
+///
+/// [zwlr_layer_shell_v1]: https://wayland.app/protocols/wlr-layer-shell-unstable-v1
+/// [PanelWindow]: ../../quickshell/panelwindow
 class WlrLayershell: public ProxyWindowBase {
 	QSDOC_BASECLASS(PanelWindowInterface);
 	// clang-format off
diff --git a/src/wayland/wlr_layershell/window.hpp b/src/wayland/wlr_layershell/window.hpp
index 7e4828af..59de5c95 100644
--- a/src/wayland/wlr_layershell/window.hpp
+++ b/src/wayland/wlr_layershell/window.hpp
@@ -8,11 +8,13 @@
 
 #include "../../core/panelinterface.hpp"
 
+///! WlrLayershell layer
 namespace Layer { // NOLINT
 Q_NAMESPACE;
 QML_ELEMENT;
 
 enum Enum {
+	/// Below bottom
 	Background = 0,
 	/// Above background, usually below windows
 	Bottom = 1,
@@ -26,9 +28,7 @@ Q_ENUM_NS(Enum);
 
 } // namespace Layer
 
-/// Type of keyboard focus that will be accepted by a [ShellWindow]
-///
-/// [ShellWindow]: ../shellwindow
+///! WlrLayershell keyboard focus mode
 namespace KeyboardFocus { // NOLINT
 Q_NAMESPACE;
 QML_ELEMENT;