From 5cdf5aa7d7eaf57cd4c30d2b1e2e4640c1612976 Mon Sep 17 00:00:00 2001
From: Alan Griffiths <alan@octopull.co.uk>
Date: Tue, 7 Jan 2025 17:00:59 +0000
Subject: [PATCH] Document decoration interfaces a bit

---
 .../shell/decoration/decoration_strategy.h    | 26 +++++++++++--------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/src/server/shell/decoration/decoration_strategy.h b/src/server/shell/decoration/decoration_strategy.h
index f6be32d54b..df2ba81768 100644
--- a/src/server/shell/decoration/decoration_strategy.h
+++ b/src/server/shell/decoration/decoration_strategy.h
@@ -42,24 +42,24 @@ enum class BorderType
 
 auto border_type_for(MirWindowType type, MirWindowState state) -> BorderType;
 
+/// Minimize, maximize, and close buttons
 struct Button
 {
-    enum class State
-    {
-        Up,         ///< The user is not interacting with this button
-        Hovered,    ///< The user is hovering over this button
-        Down,       ///< The user is currently pressing this button
-    };
-
     enum class Function
     {
         Close,
         Maximize,
         Minimize,
     };
+    using enum Function;
 
+    enum class State
+    {
+        Up,         ///< The user is not interacting with this button
+        Hovered,    ///< The user is hovering over this button
+        Down,       ///< The user is currently pressing this button
+    };
     using enum State;
-    using enum Function;
 
     Function function;
     State state;
@@ -141,6 +141,7 @@ class WindowState
     float const scale_;
 };
 
+/// Customization point for rendering
 class RendererStrategy
 {
 public:
@@ -163,6 +164,7 @@ class RendererStrategy
     virtual auto render_bottom_border() -> std::optional<RenderedPixels> = 0;
 };
 
+/// Customization point for decorations
 class DecorationStrategy
 {
 public:
@@ -177,14 +179,16 @@ class DecorationStrategy
         std::shared_ptr<scene::Surface> const& window_surface, float scale) const -> std::unique_ptr<WindowState> = 0;
     virtual auto buffer_format() const -> MirPixelFormat = 0;
     virtual auto resize_corner_input_size() const -> geometry::Size = 0;
-    virtual auto titlebar_height() const -> geometry::Height = 0;
-    virtual auto side_border_width() const -> geometry::Width = 0;
-    virtual auto bottom_border_height() const -> geometry::Height = 0;
 
     DecorationStrategy() = default;
     virtual ~DecorationStrategy() = default;
 
 private:
+    virtual auto titlebar_height() const -> geometry::Height = 0;
+    virtual auto side_border_width() const -> geometry::Width = 0;
+    virtual auto bottom_border_height() const -> geometry::Height = 0;
+    friend class WindowState;
+
     DecorationStrategy(DecorationStrategy const&) = delete;
     DecorationStrategy& operator=(DecorationStrategy const&) = delete;
 };