From 42c57064a8613d5b21fe190e70ad60f8dd9ab2f6 Mon Sep 17 00:00:00 2001 From: Ricardo Antunes Date: Fri, 25 Aug 2023 12:48:18 +0100 Subject: [PATCH] docs(core): misc improvements --- core/include/cubos/core/al/audio_device.hpp | 6 +++--- core/include/cubos/core/data/fs/file.hpp | 2 +- core/include/cubos/core/log.hpp | 2 +- engine/include/cubos/engine/input/action.hpp | 2 +- engine/include/cubos/engine/input/input.hpp | 4 ++-- .../cubos/engine/renderer/deferred_renderer.hpp | 4 ++-- engine/include/cubos/engine/renderer/frame.hpp | 2 +- engine/include/cubos/engine/renderer/pps/manager.hpp | 10 +++++----- engine/include/cubos/engine/renderer/pps/pass.hpp | 4 ++-- engine/include/cubos/engine/renderer/renderer.hpp | 5 +++-- engine/include/cubos/engine/scene/scene.hpp | 2 +- 11 files changed, 22 insertions(+), 21 deletions(-) diff --git a/core/include/cubos/core/al/audio_device.hpp b/core/include/cubos/core/al/audio_device.hpp index 4bfadd57a..9bfbeb9b5 100644 --- a/core/include/cubos/core/al/audio_device.hpp +++ b/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 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& 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; }; diff --git a/core/include/cubos/core/data/fs/file.hpp b/core/include/cubos/core/data/fs/file.hpp index 05adaf4ee..7a4d1947d 100644 --- a/core/include/cubos/core/data/fs/file.hpp +++ b/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); diff --git a/core/include/cubos/core/log.hpp b/core/include/cubos/core/log.hpp index 2c08e5438..eff6e611f 100644 --- a/core/include/cubos/core/log.hpp +++ b/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. /// diff --git a/engine/include/cubos/engine/input/action.hpp b/engine/include/cubos/engine/input/action.hpp index fbc875539..5d842abdd 100644 --- a/engine/include/cubos/engine/input/action.hpp +++ b/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: diff --git a/engine/include/cubos/engine/input/input.hpp b/engine/include/cubos/engine/input/input.hpp index d5e5542fa..b6c20de30 100644 --- a/engine/include/cubos/engine/input/input.hpp +++ b/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. }; diff --git a/engine/include/cubos/engine/renderer/deferred_renderer.hpp b/engine/include/cubos/engine/renderer/deferred_renderer.hpp index de47cb153..e2f734b4f 100644 --- a/engine/include/cubos/engine/renderer/deferred_renderer.hpp +++ b/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 diff --git a/engine/include/cubos/engine/renderer/frame.hpp b/engine/include/cubos/engine/renderer/frame.hpp index 5cbd043d8..13e570502 100644 --- a/engine/include/cubos/engine/renderer/frame.hpp +++ b/engine/include/cubos/engine/renderer/frame.hpp @@ -80,7 +80,7 @@ namespace cubos::engine const std::vector& directionalLights() const; /// @brief Gets the point lights of the frame. - /// @return The point lights. + /// @return Point lights. const std::vector& pointLights() const; private: diff --git a/engine/include/cubos/engine/renderer/pps/manager.hpp b/engine/include/cubos/engine/renderer/pps/manager.hpp index e0a089f9c..4e99bda64 100644 --- a/engine/include/cubos/engine/renderer/pps/manager.hpp +++ b/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 mInputs; ///< The inputs provided to the passes. - std::map 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 mInputs; ///< Inputs provided to the passes. + std::map 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. }; diff --git a/engine/include/cubos/engine/renderer/pps/pass.hpp b/engine/include/cubos/engine/renderer/pps/pass.hpp index c48832945..7508b362c 100644 --- a/engine/include/cubos/engine/renderer/pps/pass.hpp +++ b/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 diff --git a/engine/include/cubos/engine/renderer/renderer.hpp b/engine/include/cubos/engine/renderer/renderer.hpp index 8e9b4a56d..b3319245e 100644 --- a/engine/include/cubos/engine/renderer/renderer.hpp +++ b/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. diff --git a/engine/include/cubos/engine/scene/scene.hpp b/engine/include/cubos/engine/scene/scene.hpp index 4d12cf88e..c6b7b4c51 100644 --- a/engine/include/cubos/engine/scene/scene.hpp +++ b/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",