From c69dcafc56ec37f71cae2411d6bd2f0b3a27265d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tin=20=C5=A0vagelj?= <tin.svagelj@live.com>
Date: Sat, 20 Apr 2024 10:30:33 +0200
Subject: [PATCH] Reenabled parts of window_type which would work in Wayland
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added documentation for it.

Signed-off-by: Tin Švagelj <tin.svagelj@live.com>
---
 src/gui.h | 46 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 43 insertions(+), 3 deletions(-)

diff --git a/src/gui.h b/src/gui.h
index a2c952950..8b68fe42c 100644
--- a/src/gui.h
+++ b/src/gui.h
@@ -86,19 +86,59 @@ constexpr uint8_t operator*(alignment index) {
   return static_cast<axis_align>((static_cast<uint8_t>(of) >> 2) & 0b11);
 }
 
-#if defined(BUILD_X11) && defined(OWN_WINDOW)
+/// @brief Describes how and where a window should be mounted, as well as its
+/// behavior.
+///
+/// We assume the following order of layers:
+/// - Background - behind conky and any other windows, contains icons and
+///   desktop menus
+/// - Background widgets and docks
+/// - Windows
+/// - Panels - contains content that covers windows
+/// - Override windows - input-override windows on X11, custom overlays, lock
+///   screens, etc.
+///
+/// See also:
+/// - [X11 wm-spec `_NET_WM_WINDOW_TYPE` property](
+///   https://specifications.freedesktop.org/wm-spec/1.3/ar01s05.html#idm45684324619328)
+/// - [wlr-layer-shell layers](
+///   https://wayland.app/protocols/wlr-layer-shell-unstable-v1#zwlr_layer_shell_v1:enum:layer)
+/// - [xdg-positioner::anchor](
+///   https://wayland.app/protocols/xdg-shell#xdg_positioner:enum:anchor)
 enum class window_type : uint8_t {
+  /// @brief Acts as a normal window - has decorations, above
+  /// background, widgets and docks, below panels.
   NORMAL = 0,
+  /// @brief Screen background, no decorations, positioned at the very bottom
+  /// and behind widgets and docks.
+  DESKTOP,
+  /// @brief Normal window, always shown above parent window (group).
+  ///
+  /// See: [Popup](https://wayland.app/protocols/xdg-shell#xdg_popup) XDG shell
+  /// surface.
+  UTILITY,
+  /// @brief No decorations, between windows and background, attached to screen
+  /// edge.
   DOCK,
+  /// @brief No decorations, above windows, attached to screen edge, reserves
+  /// space.
   PANEL,
-  DESKTOP,
+#ifdef BUILD_X11
+  /// @brief On top of everything else, not controlled by WM.
   OVERRIDE,
-  UTILITY
+#endif /* BUILD_X11 */
 };
 constexpr uint8_t operator*(window_type index) {
   return static_cast<uint8_t>(index);
 }
 
+#if defined(BUILD_X11) && defined(OWN_WINDOW)
+// Only works in X11 because Wayland doesn't support
+
+/// @brief Hints are used to tell WM how it should treat a window.
+///
+/// See: [X11 wm-spec `_NET_WM_STATE` property](
+/// https://specifications.freedesktop.org/wm-spec/1.3/ar01s05.html#idm45684324611552)
 enum class window_hints : uint16_t {
   UNDECORATED = 0,
   BELOW,