docs(core): cleanup ui docs

core/include/cubos/core/ui/ecs.hpp

@@ -1,17 +1,25 @@
+/// @file
+/// @brief Functions @ref cubos::core::ui::showWorld and @ref cubos::core::ui::editWorld.
+/// @ingroup core-ui
+
 #pragma once
 
 #include <cubos/core/ecs/world.hpp>
 
 namespace cubos::core::ui
 {
-    /// ECS system which allows the user to inspect the entities and components in an ECS world.
+    /// @brief Adds a ImGui window which allows the user to inspect the entities and components in
+    /// a @ref ecs::World.
     /// @param world World to show.
     /// @param context Optional context for serializing the world.
+    /// @ingroup core-ui
     void showWorld(const ecs::World& world, data::Context* context = nullptr);
 
-    /// ECS system which allows the user to inspect and edit the entities and components in an ECS world.
+    /// @brief Adds a ImGui window which allows the user to edit the entities and components in a
+    /// @ref ecs::World.
     /// @param world World to edit.
     /// @param serContext Optional context for serializing the world.
     /// @param desContext Optional context for deserializing the world.
+    /// @ingroup core-ui
     void editWorld(ecs::World& world, data::Context* serContext = nullptr, data::Context* desContext = nullptr);
 } // namespace cubos::core::ui

core/include/cubos/core/ui/imgui.hpp

@@ -1,27 +1,39 @@
+/// @file
+/// @brief Functions for initializing and using ImGui.
+/// @ingroup core-ui
+
 #pragma once
 
 #include <cubos/core/gl/render_device.hpp>
 #include <cubos/core/io/window.hpp>
 
 namespace cubos::core::ui
 {
-    /// Initializes ImGui for use with the given window.
-    /// Should only be called once and no ImGui calls should be made before this is called.
+    /// @brief Initializes ImGui for use with the given window.
+    /// @note Should only be called once and no ImGui calls should be made before this is called.
     /// @param window The window to use.
+    /// @ingroup core-ui
     void initialize(io::Window window);
 
-    /// Shuts down ImGui.
-    /// Should only be called once, after @ref initialize, and no ImGui calls should be made after this is called.
+    /// @brief Shuts down ImGui.
+    /// @note Should only be called once, after @ref initialize(), and no ImGui calls should be
+    /// made after this is called.
+    /// @ingroup core-ui
     void terminate();
 
-    /// Begins a new ImGui frame.
+    /// @brief Begins a new ImGui frame.
+    /// @ingroup core-ui
     void beginFrame();
 
-    /// Ends the current ImGui frame, and renders the ImGui draw data to the window.
+    /// @brief Ends the current ImGui frame, and renders the ImGui draw data to the @p target
+    /// framebuffer, or the default framebuffer if @p target is null.
+    /// @param target Framebuffer to render to.
+    /// @ingroup core-ui
     void endFrame(const gl::Framebuffer& target = nullptr);
 
-    /// Passes a window event to ImGui.
-    /// @param event The event to pass.
-    /// @return True if the event was consumed by ImGui, false otherwise.
+    /// @brief Passes a window event to ImGui.
+    /// @param event Event to pass.
+    /// @return True if the event was handled by ImGui, false otherwise.
+    /// @ingroup core-ui
     bool handleEvent(const io::WindowEvent& event);
 } // namespace cubos::core::ui

core/include/cubos/core/ui/module.dox

@@ -0,0 +1,15 @@
+/// @dir
+/// @brief @ref core-ui module.
+
+#pragma once
+
+/// @namespace cubos::core::ui
+/// @brief @ref core-ui module.
+/// @ingroup core-ui
+
+namespace cubos::core::ui
+{
+    /// @defgroup core-ui User Interface
+    /// @ingroup core
+    /// @brief Provides `ImGui` integration and general UI utilities.
+} // namespace cubos::core::ui

core/include/cubos/core/ui/serialization.hpp

@@ -1,48 +1,64 @@
+/// @file
+/// @brief Functions for showing and editing serializable objects in the UI.
+/// @ingroup core-ui
+
 #pragma once
 
 #include <cubos/core/data/package.hpp>
 
 namespace cubos::core::ui
 {
-    /// Shows a packaged object's properties in the UI. Should be called
-    /// inside a ImGui::BeginTable(2)/ImGui::EndTable() block.
+    /// @brief Shows a packaged object's properties in the UI. Should be called inside a
+    /// `ImGui::BeginTable(2)` and `ImGui::EndTable()` block.
+    ///
+    /// The first column displays the name of the package and the second column displays the value
+    /// of the package.
     ///
-    /// The first column displays the name of the package and the second column displays the value of the package
-    /// @param pkg The packaged object to show.
-    /// @param name The name of the object.
+    /// @param pkg Packaged object to show.
+    /// @param name Name of the object.
+    /// @ingroup core-ui
     void showPackage(const data::Package& pkg, const std::string& name);
 
-    /// Shows a packaged object's properties in the UI, allowing the user to
-    /// edit the object. Should be called inside a
-    /// ImGui::BeginTable(3)/ImGui::EndTable() block.
-    ///
-    /// The first column displays the name of the package, the second column displays the value of the package, and the
-    /// third column is used for remove buttons in the case of arrays and dictionaries.
-    /// @param pkg The packaged object to edit.
-    /// @param name The name of the object.
-    /// @returns True if the object was edited, false otherwise.
+    /// @brief Shows a packaged object's properties in the UI, allowing the user to edit the
+    /// object. Should be called inside a `ImGui::BeginTable(3)` and `ImGui::EndTable()` block.
+    ///
+    /// The first column displays the name of the package, the second column displays the value
+    /// of the package and the third column is used for remove buttons in the case of arrays and
+    /// dictionaries.
+    ///
+    /// @param pkg Packaged object to edit.
+    /// @param name Name of the object.
+    /// @return True if the object was modified, false otherwise.
+    /// @ingroup core-ui
     bool editPackage(data::Package& pkg, const std::string& name);
 
-    /// Shows a serializable object's properties in the UI. Should be called
-    /// inside a ImGui::BeginTable(2)/ImGui::EndTable() block.
-    /// @tparam T The type of the serializable object.
-    /// @param object The object to show.
-    /// @param name The name of the object.
+    /// @brief Shows a serializable object's properties in the UI. Should be called inside a
+    /// `ImGui::BeginTable(2)` and `ImGui::EndTable()` block.
+    ///
+    /// Internally packages the object and calls @ref showPackage().
+    ///
+    /// @tparam T Type of the serializable object.
+    /// @param object Object to show.
+    /// @param name Name of the object.
+    /// @ingroup core-ui
     template <typename T>
     inline void show(const T& object, const std::string& name)
     {
         auto pkg = data::Package::from(object);
         showPackage(pkg, name);
     }
 
-    /// Shows a serializable and deserializable object's properties in the UI,
-    /// allowing the user to edit the object. If any of the properties is
-    /// edited, the object's deserialize() method is called. Should be called
-    /// inside a ImGui::BeginTable(3)/ImGui::EndTable() block.
-    /// @tparam T The type of the serializable object.
-    /// @param object The object to edit.
-    /// @param name The name of the object.
-    /// @returns True if the object was edited, false otherwise.
+    /// @brief Shows a serializable object's properties in the UI. Should be called inside a
+    /// `ImGui::BeginTable(3)` and `ImGui::EndTable()` block.
+    ///
+    /// Internally packages the object, calls @ref editPackage() and then unpackages the object, if
+    /// it was modified.
+    ///
+    /// @tparam T Type of the serializable object.
+    /// @param object Object to edit.
+    /// @param name Name of the object.
+    /// @return True if the object was edited, false otherwise.
+    /// @ingroup core-ui
     template <typename T>
     inline bool edit(T& object, const std::string& name)
     {