From 15b84dda07e4840c56f420a52e230dc186c44597 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Benno=20F=C3=BCnfst=C3=BCck?= <benno.fuenfstueck@gmail.com>
Date: Mon, 13 Aug 2018 18:38:36 +0200
Subject: [PATCH] docs(background_manager): add comments

---
 include/x11/background_manager.hpp | 42 +++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/include/x11/background_manager.hpp b/include/x11/background_manager.hpp
index 33d5a36f..85f72ab0 100644
--- a/include/x11/background_manager.hpp
+++ b/include/x11/background_manager.hpp
@@ -16,6 +16,13 @@ namespace cairo {
   class xcb_surface;
 }
 
+/**
+ * \brief Class to keep track of the desktop background used to support pseudo-transparency
+ *
+ * For pseudo-transparency that bar needs access to the desktop background.
+ * We only need to store the slice of the background image which is covered by the bar window,
+ * so this class takes a rectangle that limits what part of the background is stored.
+ */
 class background_manager : public signal_receiver<SIGN_PRIORITY_SCREEN, signals::ui::update_geometry>,
                            public xpp::event::sink<evt::property_notify>
 {
@@ -23,29 +30,62 @@ class background_manager : public signal_receiver<SIGN_PRIORITY_SCREEN, signals:
   using make_type = background_manager&;
   static make_type make();
 
+  /**
+   * Initializes a new background_manager that by default does not observe anything.
+   *
+   * To observe a slice of the background you need to call background_manager::activate.
+   */
   explicit background_manager(connection& conn, signal_emitter& sig, const logger& log);
   ~background_manager();
 
+  /**
+   * Starts observing a rectangular slice of the desktop background.
+   *
+   * After calling this function, you can obtain the current slice of the desktop background
+   * with background_manager::get_surface. Whenever the background slice changes (for example,
+   * due to bar position changes or because the user changed the desktop background) the class
+   * emits a signals::ui::update_background event.
+   *
+   * \param window This should be set to the bar window.
+   * \param rect Slice of the background to observe (coordinates relative to window).
+   *             Typically set to the outer area of the bar.
+   */
   void activate(xcb_window_t window, xcb_rectangle_t rect);
+
+
+  /**
+   * Stops observing the desktop background and frees all resources.
+   */
   void deactivate();
 
+  /**
+   * Retrieve the current desktop background slice.
+   *
+   * This function returns a slice of the desktop background that has the size of the rectangle
+   * given to background_manager::activate. As the slice is cached by the manager, this function
+   * is fast.
+   */
   cairo::surface* get_surface() const;
 
   void handle(const evt::property_notify& evt);
   bool on(const signals::ui::update_geometry&);
  private:
+  // references to standard components
   connection& m_connection;
   signal_emitter& m_sig;
   const logger& m_log;
-  xcb_window_t m_window;
 
+  // these are set by activate
+  xcb_window_t m_window;
   xcb_rectangle_t m_rect{0, 0, 0U, 0U};
 
+  // required values for fetching the root window's background
   xcb_visualtype_t* m_visual{nullptr};
   xcb_gcontext_t m_gcontext{XCB_NONE};
   xcb_pixmap_t m_pixmap{XCB_NONE};
   unique_ptr<cairo::xcb_surface> m_surface;
 
+  // true if we are currently attached as a listener for desktop background changes
   bool m_attached{false};
 
   void allocate_resources();