From 9b69099a65ee8a408a6d7bc866ef25669d814f8e Mon Sep 17 00:00:00 2001
From: Jakob Bornecrantz <jakob@collabora.com>
Date: Fri, 8 Dec 2023 18:27:40 +0000
Subject: [PATCH] c/multi: Even more documentation

---
 .../compositor/multi/comp_multi_interface.h   |  2 +
 src/xrt/compositor/multi/comp_multi_private.h | 37 +++++++++++++++++--
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/src/xrt/compositor/multi/comp_multi_interface.h b/src/xrt/compositor/multi/comp_multi_interface.h
index 13e3fb734..156f7d25c 100644
--- a/src/xrt/compositor/multi/comp_multi_interface.h
+++ b/src/xrt/compositor/multi/comp_multi_interface.h
@@ -30,6 +30,8 @@ struct u_pacing_app_factory;
  * @param xsci          Information to be exposed.
  * @param do_warm_start Should we always submit a frame at startup.
  * @param out_xsysc     Created @ref xrt_system_compositor.
+ *
+ * @public @memberof multi_system_compositor
  */
 xrt_result_t
 comp_multi_create_system_compositor(struct xrt_compositor_native *xcn,
diff --git a/src/xrt/compositor/multi/comp_multi_private.h b/src/xrt/compositor/multi/comp_multi_private.h
index ec38ff6a8..4c4251d08 100644
--- a/src/xrt/compositor/multi/comp_multi_private.h
+++ b/src/xrt/compositor/multi/comp_multi_private.h
@@ -23,7 +23,20 @@ extern "C" {
 #endif
 
 
+/*!
+ * Number of max active clients.
+ *
+ * @todo Move to `xrt_limits.h`, or make dynamic to remove limit.
+ * @ingroup comp_multi
+ */
 #define MULTI_MAX_CLIENTS 64
+
+/*!
+ * Number of max active layers per @ref multi_compositor.
+ *
+ * @todo Move to `xrt_limits.h` and share.
+ * @ingroup comp_multi
+ */
 #define MULTI_MAX_LAYERS 16
 
 
@@ -186,6 +199,11 @@ struct multi_compositor
 	struct u_pacing_app *upa;
 };
 
+/*!
+ * Small helper go from @ref xrt_compositor to @ref multi_compositor.
+ *
+ * @ingroup comp_multi
+ */
 static inline struct multi_compositor *
 multi_compositor(struct xrt_compositor *xc)
 {
@@ -298,23 +316,33 @@ enum multi_system_state
 };
 
 /*!
- * The multi-client system compositor multiplexes access to a single native compositor,
- * merging layers from one or more client apps/sessions.
+ * The multi-client module (aka multi compositor) is  system compositor that
+ * multiplexes access to a single @ref xrt_compositor_native, merging layers
+ * from one or more client apps/sessions. This object implements the
+ * @ref xrt_system_compositor, and gives each session a @ref multi_compositor,
+ * which implements @ref xrt_compositor_native.
  *
  * @ingroup comp_multi
  * @implements xrt_system_compositor
  */
 struct multi_system_compositor
 {
+	//! Base interface.
 	struct xrt_system_compositor base;
 
 	//! Extra functions to handle multi client.
 	struct xrt_multi_compositor_control xmcc;
 
-	//! Real native compositor.
+	/*!
+	 * Real native compositor, which this multi client module submits the
+	 * combined layers of active @ref multi_compositor objects.
+	 */
 	struct xrt_compositor_native *xcn;
 
-	//! App pacer factory.
+	/*!
+	 * App pacer factory, when a new @ref multi_compositor is created a
+	 * pacer is created from this factory.
+	 */
 	struct u_pacing_app_factory *upaf;
 
 	//! Render loop thread.
@@ -347,6 +375,7 @@ struct multi_system_compositor
 		uint64_t diff_ns;
 	} last_timings;
 
+	//! List of active clients.
 	struct multi_compositor *clients[MULTI_MAX_CLIENTS];
 };
 
-- 
2.51.2