From c3b8810bb0df9c5ca37d2a9768062c26e4e3a109 Mon Sep 17 00:00:00 2001
From: Jakob Bornecrantz <jakob@collabora.com>
Date: Wed, 3 Nov 2021 17:45:54 +0000
Subject: [PATCH] c/util: Documentation

---
 src/xrt/compositor/main/comp_documentation.h |  7 +++++++
 src/xrt/compositor/util/comp_swapchain.c     |  2 +-
 src/xrt/compositor/util/comp_swapchain.h     | 17 ++++++++++-------
 src/xrt/compositor/util/comp_sync.c          |  2 +-
 src/xrt/compositor/util/comp_sync.h          |  4 +++-
 5 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/src/xrt/compositor/main/comp_documentation.h b/src/xrt/compositor/main/comp_documentation.h
index bbb753a9b..f5e8f5930 100644
--- a/src/xrt/compositor/main/comp_documentation.h
+++ b/src/xrt/compositor/main/comp_documentation.h
@@ -25,6 +25,13 @@
  * @brief  Main compositor code.
  */
 
+/*!
+ * @defgroup comp_util Compositor utility code
+ * @ingroup comp
+ *
+ * @brief General compositor utility code.
+ */
+
 /*!
  * @defgroup comp_client Compositor client code
  * @ingroup comp
diff --git a/src/xrt/compositor/util/comp_swapchain.c b/src/xrt/compositor/util/comp_swapchain.c
index 8f8cbdf64..49702491b 100644
--- a/src/xrt/compositor/util/comp_swapchain.c
+++ b/src/xrt/compositor/util/comp_swapchain.c
@@ -4,7 +4,7 @@
  * @file
  * @brief  Independent swapchain implementation.
  * @author Jakob Bornecrantz <jakob@collabora.com>
- * @ingroup comp_main
+ * @ingroup comp_util
  */
 
 #include "xrt/xrt_handles.h"
diff --git a/src/xrt/compositor/util/comp_swapchain.h b/src/xrt/compositor/util/comp_swapchain.h
index de602aa4f..fca40d872 100644
--- a/src/xrt/compositor/util/comp_swapchain.h
+++ b/src/xrt/compositor/util/comp_swapchain.h
@@ -5,7 +5,7 @@
  * @brief  Independent swapchain implementation.
  * @author Jakob Bornecrantz <jakob@collabora.com>
  * @author Lubosz Sarnecki <lubosz.sarnecki@collabora.com>
- * @ingroup comp_main
+ * @ingroup comp_util
  */
 
 #pragma once
@@ -23,6 +23,8 @@ extern "C" {
 
 /*!
  * A garbage collector that collects swapchains to be safely destroyed.
+ *
+ * @ingroup comp_util
  */
 struct comp_swapchain_gc
 {
@@ -33,7 +35,7 @@ struct comp_swapchain_gc
 /*!
  * A single swapchain image, holds the needed state for tracking image usage.
  *
- * @ingroup comp_main
+ * @ingroup comp_util
  * @see comp_swapchain
  */
 struct comp_swapchain_image
@@ -60,7 +62,7 @@ struct comp_swapchain_image
  * sure that compositor lives for as long as the swapchain does and that all
  * swapchains are destroyed before the compositor is destroyed.
  *
- * @ingroup comp_main
+ * @ingroup comp_util
  * @implements xrt_swapchain_native
  * @see comp_compositor
  */
@@ -91,6 +93,7 @@ struct comp_swapchain
 /*!
  * Convenience function to convert a xrt_swapchain to a comp_swapchain.
  *
+ * @ingroup comp_util
  * @private @memberof comp_swapchain
  */
 static inline struct comp_swapchain *
@@ -110,7 +113,7 @@ comp_swapchain(struct xrt_swapchain *xsc)
  * Do garbage collection, destroying any resources that has been scheduled for
  * destruction from other threads.
  *
- * @public @memberof comp_compositor
+ * @ingroup comp_util
  */
 void
 comp_swapchain_garbage_collect(struct comp_swapchain_gc *cscgc);
@@ -118,7 +121,7 @@ comp_swapchain_garbage_collect(struct comp_swapchain_gc *cscgc);
 /*!
  * A compositor function that is implemented in the swapchain code.
  *
- * @public @memberof comp_compositor
+ * @ingroup comp_util
  */
 xrt_result_t
 comp_swapchain_create(struct vk_bundle *vk,
@@ -129,7 +132,7 @@ comp_swapchain_create(struct vk_bundle *vk,
 /*!
  * A compositor function that is implemented in the swapchain code.
  *
- * @public @memberof comp_compositor
+ * @ingroup comp_util
  */
 xrt_result_t
 comp_swapchain_import(struct vk_bundle *vk,
@@ -144,7 +147,7 @@ comp_swapchain_import(struct vk_bundle *vk,
  * does the actual destruction and is called from @ref
  * comp_swapchain_garbage_collect.
  *
- * @private @memberof comp_swapchain
+ * @ingroup comp_util
  */
 void
 comp_swapchain_really_destroy(struct comp_swapchain *sc);
diff --git a/src/xrt/compositor/util/comp_sync.c b/src/xrt/compositor/util/comp_sync.c
index d6876a6d7..525782eba 100644
--- a/src/xrt/compositor/util/comp_sync.c
+++ b/src/xrt/compositor/util/comp_sync.c
@@ -4,7 +4,7 @@
  * @file
  * @brief  Independent @ref xrt_compositor_fence implementation.
  * @author Jakob Bornecrantz <jakob@collabora.com>
- * @ingroup comp_main
+ * @ingroup comp_util
  */
 
 #include "xrt/xrt_config_os.h"
diff --git a/src/xrt/compositor/util/comp_sync.h b/src/xrt/compositor/util/comp_sync.h
index 50d0223f7..9cc461e59 100644
--- a/src/xrt/compositor/util/comp_sync.h
+++ b/src/xrt/compositor/util/comp_sync.h
@@ -4,7 +4,7 @@
  * @file
  * @brief  Independent @ref xrt_compositor_fence implementation.
  * @author Jakob Bornecrantz <jakob@collabora.com>
- * @ingroup comp_main
+ * @ingroup comp_util
  */
 
 #pragma once
@@ -25,6 +25,8 @@ extern "C" {
  * The vk_bundle is owned by the compositor, its the state trackers job to make
  * sure that compositor lives for as long as the fence does and that all fences
  * are destroyed before the compositor is destroyed.
+ *
+ * @ingroup comp_util
  */
 xrt_result_t
 comp_fence_import(struct vk_bundle *vk, xrt_graphics_sync_handle_t handle, struct xrt_compositor_fence **out_xcf);