docs(core): misc improvements

core/include/cubos/core/al/audio_device.hpp

@@ -51,12 +51,12 @@ namespace cubos::core::al
 
         /// @brief Creates an audio device from a given device @p specifier.
         /// @see enumerateDevices()
-        /// @param specifier The device specifier (empty for default).
+        /// @param specifier Device specifier (empty for default).
         /// @return Audio device, or nullptr on failure.
         static std::shared_ptr<AudioDevice> create(const std::string& specifier = "");
 
         /// @brief Enumerates the available devices.
-        /// @param devices The vector to fill with the available devices.
+        /// @param[out] devices Vector to fill with the available devices.
         static void enumerateDevices(std::vector<std::string>& devices);
 
         /// @brief Creates a new audio buffer
@@ -77,7 +77,7 @@ namespace cubos::core::al
         virtual void setListenerOrientation(const glm::vec3& forward, const glm::vec3& up) = 0;
 
         /// @brief Sets the velocity of the listener. Used to implement the doppler effect.
-        /// @param velocity The velocity of the listener.
+        /// @param velocity Velocity of the listener.
         virtual void setListenerVelocity(const glm::vec3& velocity) = 0;
     };
 

core/include/cubos/core/data/fs/file.hpp

@@ -99,7 +99,7 @@ namespace cubos::core::data
         /// - a parent directory in the path already exists as a regular file.
         /// - a file of a different type already exists at the destination.
         ///
-        /// @param path The relative path to the file.
+        /// @param path Relative path to the file.
         /// @param directory Whether the new file should be a directory.
         /// @return Handle to the file, or nullptr on failure.
         Handle create(std::string_view path, bool directory = false);

core/include/cubos/core/log.hpp

@@ -10,7 +10,7 @@
 /// @{
 
 /// @def CUBOS_LOG_LEVEL
-/// @brief The log level to compile in.
+/// @brief Log level to compile in.
 ///
 /// This macro essentially controls the minimum log level that will be compiled into the binary.
 ///

engine/include/cubos/engine/input/action.hpp

@@ -43,7 +43,7 @@ namespace cubos::engine
         bool pressed() const;
 
         /// @brief Sets whether this action is pressed.
-        /// @param pressed The new pressed state.
+        /// @param pressed New pressed state.
         void pressed(bool pressed);
 
     private:

engine/include/cubos/engine/input/input.hpp

@@ -76,8 +76,8 @@ namespace cubos::engine
     private:
         struct BindingIndex
         {
-            std::string name;      ///< The name of the action or axis.
-            int player;            ///< The player index.
+            std::string name;      ///< Name of the action or axis.
+            int player;            ///< Player index.
             bool negative = false; ///< Whether the pressed key is a negative axis key.
         };
 

engine/include/cubos/engine/renderer/deferred_renderer.hpp

@@ -23,8 +23,8 @@ namespace cubos::engine
     ///
     /// Voxel grids are first triangulated, and then the triangles are uploaded to the GPU.
     /// The rendering is done in two passes:
-    /// - The first pass renders the scene to the GBuffer textures: position, normal and material.
-    /// - The second pass takes the GBuffer textures and calculates the color of the pixels with the lighting applied.
+    /// 1. Render the scene to the GBuffer textures: position, normal and material.
+    /// 2. Take the GBuffer textures and calculate the color of the pixels with the lighting applied.
     ///
     /// @ingroup renderer-plugin
     class DeferredRenderer : public BaseRenderer

engine/include/cubos/engine/renderer/frame.hpp

@@ -80,7 +80,7 @@ namespace cubos::engine
         const std::vector<core::gl::DirectionalLight>& directionalLights() const;
 
         /// @brief Gets the point lights of the frame.
-        /// @return The point lights.
+        /// @return Point lights.
         const std::vector<core::gl::PointLight>& pointLights() const;
 
     private:

engine/include/cubos/engine/renderer/pps/manager.hpp

@@ -74,11 +74,11 @@ namespace cubos::engine
         std::size_t passCount() const;
 
     private:
-        core::gl::RenderDevice& mRenderDevice;                      ///< The render device to use.
-        glm::uvec2 mSize;                                           ///< The current size of the window.
-        std::map<PostProcessingInput, core::gl::Texture2D> mInputs; ///< The inputs provided to the passes.
-        std::map<std::size_t, PostProcessingPass*> mPasses;         ///< The passes present in the manager.
-        std::size_t mNextId;                                        ///< The next ID to use for a pass.
+        core::gl::RenderDevice& mRenderDevice;                      ///< Render device to use.
+        glm::uvec2 mSize;                                           ///< Current size of the window.
+        std::map<PostProcessingInput, core::gl::Texture2D> mInputs; ///< Inputs provided to the passes.
+        std::map<std::size_t, PostProcessingPass*> mPasses;         ///< Passes present in the manager.
+        std::size_t mNextId;                                        ///< Next ID to use for a pass.
         core::gl::Texture2D mIntermediateTex[2];                    ///< Intermediate textures used for the passes.
         core::gl::Framebuffer mIntermediateFb[2];                   ///< Intermediate framebuffers used for the passes.
     };

engine/include/cubos/engine/renderer/pps/pass.hpp

@@ -28,7 +28,7 @@ namespace cubos::engine
         virtual ~PostProcessingPass() = default;
 
         /// @brief Constructs.
-        /// @param renderDevice The render device to use.
+        /// @param renderDevice Render device to use.
         PostProcessingPass(core::gl::RenderDevice& renderDevice);
 
         /// @brief Deleted copy constructor.
@@ -51,6 +51,6 @@ namespace cubos::engine
                              core::gl::Framebuffer out) const = 0;
 
     protected:
-        core::gl::RenderDevice& mRenderDevice; ///< The render device to use.
+        core::gl::RenderDevice& mRenderDevice; ///< Render device to use.
     };
 } // namespace cubos::engine

engine/include/cubos/engine/renderer/renderer.hpp

@@ -57,8 +57,9 @@ namespace cubos::engine
         virtual ~BaseRenderer() = default;
 
         /// @brief Constructs.
-        /// @param renderDevice The render device to use.
-        /// @param size The size of the window.
+        /// @warning @p renderDevice must be valid during the lifetime of the renderer.
+        /// @param renderDevice Render device to use.
+        /// @param size Size of the window.
         BaseRenderer(core::gl::RenderDevice& renderDevice, glm::uvec2 size);
 
         /// @brief Deleted copy constructor.

engine/include/cubos/engine/scene/scene.hpp

@@ -12,7 +12,7 @@
 
 namespace cubos::engine
 {
-    /// @brief The asset equivalent to ECS blueprints - a bundle of entities and their components.
+    /// @brief Asset equivalent to ECS blueprints - a bundle of entities and their components.
     ///
     /// Scene assets produce a blueprint when loaded which can be used to spawn them. Entity names
     /// in the resulting blueprint follow the format "foo", "import1.bar", "import1.import2.baz",