diff --git a/.clang-format b/.clang-format new file mode 100644 index 00000000..682be41f --- /dev/null +++ b/.clang-format @@ -0,0 +1,66 @@ +# FlingEngine clang-format configuration +# +# Apply to first-party sources only (FlingEngine/, Sandbox/, FlingTests/). +# Do not run clang-format on external/ submodules. +# +# Note: clang-format can reflow and align comments, but it cannot enforce +# documentation *content* (e.g. forbidding @brief). Use +# scripts/check_comment_style.py for that — see docs/CodingStyle.md. + +BasedOnStyle: LLVM +Language: Cpp +Standard: c++17 + +# Indentation — the tree historically mixes tabs and spaces; prefer spaces +# for new/edited code so formatting stays consistent going forward. +UseTab: Never +IndentWidth: 4 +TabWidth: 4 +AccessModifierOffset: -4 +NamespaceIndentation: All +IndentCaseLabels: false +IndentPPDirectives: None + +# Pointers / references +PointerAlignment: Left +ReferenceAlignment: Left +DerivePointerAlignment: false + +# Line wrapping +ColumnLimit: 120 +AllowShortFunctionsOnASingleLine: InlineOnly +AllowShortIfStatementsOnASingleLine: Never +AllowShortLoopsOnASingleLine: false +AllowShortBlocksOnASingleLine: Never +AllowShortLambdasOnASingleLine: Inline +AlwaysBreakTemplateDeclarations: Yes +BreakConstructorInitializers: BeforeColon +ConstructorInitializerAllOnOneLineOrOnePerLine: true +BinPackArguments: false +BinPackParameters: false + +# Includes +SortIncludes: false +IncludeBlocks: Preserve + +# Spacing +SpaceAfterCStyleCast: false +SpaceAfterTemplateKeyword: true +SpaceBeforeCpp11BracedList: false +SpaceBeforeCtorInitializerColon: true +SpaceBeforeInheritanceColon: true +SpaceBeforeParens: ControlStatements +SpaceInEmptyParentheses: false +SpacesInAngles: false +SpacesInParentheses: false +SpacesInSquareBrackets: false + +# Comments — reflow long lines, but keep doc-comment semantics alone +ReflowComments: true +AlignTrailingComments: true + +# Misc +FixNamespaceComments: true +KeepEmptyLinesAtTheStartOfBlocks: false +MaxEmptyLinesToKeep: 1 +Cpp11BracedListStyle: true diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 52f7ecb9..ebb1221f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -163,3 +163,13 @@ jobs: run: | mkdir -p Logs ./build/FlingTests/bin/FlingTests.exe + + # Doc-comment conventions for first-party sources (see docs/CodingStyle.md / issue #166). + # clang-format cannot enforce comment *content*; this script does. + comment-style: + name: Comment style + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + - name: Check documentation comment style + run: python3 scripts/check_comment_style.py diff --git a/FlingEngine/Core/inc/Engine.h b/FlingEngine/Core/inc/Engine.h index 582810f1..84fdd889 100644 --- a/FlingEngine/Core/inc/Engine.h +++ b/FlingEngine/Core/inc/Engine.h @@ -41,7 +41,7 @@ namespace Fling { /** - * @brief Core engine class of Fling. This is where the core update loop lives + * Core engine class of Fling. This is where the core update loop lives * along with all startup/shutdown ordering. */ class Engine : public NonCopyable @@ -53,7 +53,7 @@ namespace Fling FLING_API ~Engine() = default; /** - * @brief Run the engine (Startup, Tick until should stop, and shutdown) + * Run the engine (Startup, Tick until should stop, and shutdown) * * @return uint64 0 for success, otherwise an error has occured */ diff --git a/FlingEngine/Core/inc/Input/Input.h b/FlingEngine/Core/inc/Input/Input.h index 1a0ac6eb..4720b222 100644 --- a/FlingEngine/Core/inc/Input/Input.h +++ b/FlingEngine/Core/inc/Input/Input.h @@ -8,7 +8,7 @@ namespace Fling { /** - * @brief represents the current mouse position in screen space + * represents the current mouse position in screen space */ struct MousePos { @@ -27,7 +27,7 @@ namespace Fling static void Init() { m_Instance->InitImpl(); } /** - * @brief PreUpdate is called before polling of input, and after Init. Useful for + * PreUpdate is called before polling of input, and after Init. Useful for * anything that needs to happen after Window creation. */ static void PreUpdate() { m_Instance->PreUpdateImpl(); }; @@ -43,7 +43,7 @@ namespace Fling } /** - * @brief Update any input polling that needs to happen on this platform. + * Update any input polling that needs to happen on this platform. */ static void Poll() { m_Instance->PollImpl(); } @@ -59,7 +59,7 @@ namespace Fling static MousePos GetMousePos() { return m_Instance->GetMousePosImpl(); } /** - * @brief Bind a callback function to when a key is pressed + * Bind a callback function to when a key is pressed * * @tparam Candidate The function that you would like to bind * @param t_KeyName Key name to bind to @@ -89,7 +89,7 @@ namespace Fling static Input* m_Instance; /** - * @brief Add a key mapping to this platform. + * Add a key mapping to this platform. * * @param t_Name The name of this key * @param t_KeyCode The KeyCode that maps this key to the current platform diff --git a/FlingEngine/Core/inc/Input/LinuxInput.h b/FlingEngine/Core/inc/Input/LinuxInput.h index 3534967e..2ce873a6 100644 --- a/FlingEngine/Core/inc/Input/LinuxInput.h +++ b/FlingEngine/Core/inc/Input/LinuxInput.h @@ -26,7 +26,7 @@ namespace Fling virtual bool IsMouseDownImpl(const std::string& t_KeyName) override; /** - * @brief Get the mouse position in screen space + * Get the mouse position in screen space * * @return MousePos */ diff --git a/FlingEngine/Core/inc/Input/WindowsInput.h b/FlingEngine/Core/inc/Input/WindowsInput.h index 8ccca83f..36f89eb1 100644 --- a/FlingEngine/Core/inc/Input/WindowsInput.h +++ b/FlingEngine/Core/inc/Input/WindowsInput.h @@ -27,7 +27,7 @@ namespace Fling virtual bool IsMouseDownImpl(const std::string& t_KeyName) override; /** - * @brief Get the mouse position in screen space + * Get the mouse position in screen space * * @return MousePos */ diff --git a/FlingEngine/Editor/inc/BaseEditor.h b/FlingEngine/Editor/inc/BaseEditor.h index 6b9c8d7d..e83fbaf3 100644 --- a/FlingEngine/Editor/inc/BaseEditor.h +++ b/FlingEngine/Editor/inc/BaseEditor.h @@ -7,7 +7,7 @@ namespace Fling { /** - * @brief The BaseEditor of the Fling Engine. Draw and add any game specifc Editor UI tools here + * The BaseEditor of the Fling Engine. Draw and add any game specifc Editor UI tools here */ class BaseEditor { @@ -21,7 +21,7 @@ namespace Fling virtual void RegisterComponents(entt::registry& t_Reg); /** - * @brief Draws the editor via IMGUI. Does NOT need to do any addition renderering pipeline things + * Draws the editor via IMGUI. Does NOT need to do any addition renderering pipeline things */ virtual void Draw(entt::registry& t_Reg, float DeltaTime); diff --git a/FlingEngine/Gameplay/inc/Camera.h b/FlingEngine/Gameplay/inc/Camera.h index a6c8f622..e64df9e8 100644 --- a/FlingEngine/Gameplay/inc/Camera.h +++ b/FlingEngine/Gameplay/inc/Camera.h @@ -4,8 +4,7 @@ namespace Fling { /** - * @brief Base class for camera, meant to be overridden - * + * Base class for camera, meant to be overridden */ class Camera { @@ -22,25 +21,19 @@ namespace Fling virtual void Update(float dt) = 0; /** - * @brief Gets the near plane of the view frustrum - * - * @return const float& m_nearPlane + * Gets the near plane of the view frustrum */ const float GetNearPlane() const { return m_nearPlane; } void SetNearPlane(const float& nearPlane) { m_nearPlane = nearPlane; } /** - * @brief Gets the far plane of the view frustrum - * - * @return const float& m_farPlane + * Gets the far plane of the view frustrum */ const float GetFarPlane() const { return m_farPlane; } void SetFarPlane(const float& farPlane) { m_farPlane = farPlane; } /** - * @brief Gets the field of view angle from the view frustrum - * - * @return const float& m_fieldOfView + * Gets the field of view angle from the view frustrum */ const float GetFieldOfView() const { return m_fieldOfView; } void SetFieldOfView(const float& fieldOfView) { m_fieldOfView = fieldOfView; } @@ -51,16 +44,12 @@ namespace Fling const float GetAspectRatio() const { return m_aspectRatio; } /** - * @brief Gets the view matrix created by the current camera position and rotation - * - * @return const glm::mat4& viewMatrix + * Gets the view matrix created by the current camera position and rotation */ const glm::mat4& GetViewMatrix() const {return m_viewMatrix; } /** - * @brief Gets the projection matrix used by camera - * - * @return const glm::mat4& projectionMatrix + * Gets the projection matrix used by camera */ const glm::mat4& GetProjectionMatrix() const { return m_projectionMatrix; } diff --git a/FlingEngine/Gameplay/inc/Game.h b/FlingEngine/Gameplay/inc/Game.h index cb41513c..91f79136 100644 --- a/FlingEngine/Gameplay/inc/Game.h +++ b/FlingEngine/Gameplay/inc/Game.h @@ -10,7 +10,7 @@ namespace Fling class World; /** - * @brief The game class is mean to be overridden on a per-game instance. + * The game class is mean to be overridden on a per-game instance. * It provides an interface for users to add their own System calls * in the update, read, write, etc * @see World @@ -50,17 +50,13 @@ namespace Fling virtual void Shutdown(entt::registry& t_Reg) = 0; /** - * @brief Gets the owning world of this game. You can use the world to add entities to + * Gets the owning world of this game. You can use the world to add entities to * the world. Asserts that world exists first - * - * @return FORCEINLINE* GetWorld */ FORCEINLINE World* GetWorld() const { assert(m_OwningWorld); return m_OwningWorld; } /** - * @brief If true then this game wants to texit the application entirely. - * - * @return FORCEINLINE WantsToQuit + * If true then this game wants to texit the application entirely. */ FORCEINLINE bool WantsToQuit() const { return m_WantsToQuit; } diff --git a/FlingEngine/Gameplay/inc/Level.h b/FlingEngine/Gameplay/inc/Level.h index 61595db0..3f9be78b 100644 --- a/FlingEngine/Gameplay/inc/Level.h +++ b/FlingEngine/Gameplay/inc/Level.h @@ -9,7 +9,7 @@ namespace Fling class World; /** - * @brief A level contains active objects and provides the environment + * A level contains active objects and provides the environment * for the player. You should only load a level through the world. */ class Level : public NonCopyable @@ -23,7 +23,7 @@ namespace Fling ~Level(); /** - * @brief Update the BSP of actors and tick every active actor. + * Update the BSP of actors and tick every active actor. * @see World::Update * * @param t_DeltaTime Time between previous frame and the current one. @@ -31,12 +31,12 @@ namespace Fling void Update(float t_DeltaTime); /** - * @brief Unload the current level and all actors inside of it + * Unload the current level and all actors inside of it */ void Unload(); /** - * @brief Get the Owning World object of this level. + * Get the Owning World object of this level. * * @return World* */ @@ -51,12 +51,12 @@ namespace Fling std::string m_LevelFileName = "UNLOADED"; /** - * @brief Load the level based on the current file name! + * Load the level based on the current file name! */ void LoadLevel(); /** - * @brief Any behavior that needs to happen after the level has been fully loaded. + * Any behavior that needs to happen after the level has been fully loaded. */ void PostLoad(); diff --git a/FlingEngine/Gameplay/inc/World.h b/FlingEngine/Gameplay/inc/World.h index 007c966f..8267825c 100644 --- a/FlingEngine/Gameplay/inc/World.h +++ b/FlingEngine/Gameplay/inc/World.h @@ -25,20 +25,20 @@ namespace Fling explicit World(entt::registry& t_Reg, Fling::Game* t_Game); /** - * @brief Initializes the world. Loads the StartLevel that is specified in the config. + * Initializes the world. Loads the StartLevel that is specified in the config. * @note Keep explicit Init and Shutdown functions to make the startup order more readable */ void Init(); /** - * @brief Tick all active levels in the world and upates any Lua scripts that have Update functions + * Tick all active levels in the world and upates any Lua scripts that have Update functions * * @param t_DeltaTime Time between previous frame and the current one. */ void Update(float t_DeltaTime); /** - * @brief Called just before destruction. + * Called just before destruction. */ void Shutdown(); @@ -49,7 +49,7 @@ namespace Fling void RequestGameStop(); /** - * @brief Check if the world wants to exit the program. + * Check if the world wants to exit the program. * @see Engine::Tick * * @return True if the world has signaled for exit @@ -57,7 +57,7 @@ namespace Fling FORCEINLINE bool ShouldQuit() const { assert(m_Game); return m_ShouldQuit || m_Game->WantsToQuit(); } /** - * @brief Based on all current entities in the registry serialize that data to a JSON file + * Based on all current entities in the registry serialize that data to a JSON file * This will write out some core engine components along with the specified custom * game components. * @@ -69,7 +69,7 @@ namespace Fling bool OutputLevelFile(const std::string& t_LevelToLoad); /** - * @brief Reset the current registry and load in new entities/components from a JSON file + * Reset the current registry and load in new entities/components from a JSON file * This will read in some core engine components along with the specified custom * game components. * diff --git a/FlingEngine/Graphics/inc/Buffer.h b/FlingEngine/Graphics/inc/Buffer.h index fd83efb3..b203b421 100644 --- a/FlingEngine/Graphics/inc/Buffer.h +++ b/FlingEngine/Graphics/inc/Buffer.h @@ -13,7 +13,7 @@ namespace Fling public: /** - * @brief Default Ctor for a buffer. Buffer is initialized to 0 + * Default Ctor for a buffer. Buffer is initialized to 0 */ Buffer() : m_Size(0) @@ -24,11 +24,11 @@ namespace Fling { } - /*! @brief copy constructor. */ + /** Copy constructor. */ Buffer(const Buffer& t_Other); /** - * @brief Construct a new Buffer object + * Create a Vulkan buffer and optionally map initial data into it. * * @param t_Size Size of this buffer in bytes * @param t_Usage Vk usage flags for this buffer @@ -43,7 +43,7 @@ namespace Fling ); /** - * @brief Destroy the Buffer object, frees Vk memory and destroys buffer + * Free Vulkan memory and destroy the buffer. */ ~Buffer(); @@ -59,7 +59,7 @@ namespace Fling FORCEINLINE VkDescriptorBufferInfo& GetDescriptor() { return m_Descriptor; } /** - * @brief Copy the contents of the source buffer to the destination buffer using a single command + * Copy the contents of the source buffer to the destination buffer using a single command * * @param t_SrcBuffer Source buffer data * @param t_DstBuffer Destination buffer data @@ -68,32 +68,31 @@ namespace Fling static void CopyBuffer(Buffer* t_SrcBuffer, Buffer* t_DstBuffer, VkDeviceSize t_Size); /** - * @brief Destroy the VK buffer object, frees vk memory. - * + * Free Vulkan memory and destroy the buffer handle. */ void Release(); /** - * @brief Check if this buffer's Vulkan assets are used. + * Check if this buffer's Vulkan assets are used. * * @return true memory is not null and the size is greater than 0 */ bool IsUsed() const { return m_BufferMemory != VK_NULL_HANDLE && m_Buffer != VK_NULL_HANDLE && m_Size; } /** - * @brief Map the memory of this buffer to the given data + * Map the memory of this buffer to the given data * * @param t_Data Where to map this buffer's data to */ VkResult MapMemory(VkDeviceSize t_Size = VK_WHOLE_SIZE, VkDeviceSize t_Offset = 0); /** - * @brief Unmap this buffers memory from the Vulkan device + * Unmap this buffers memory from the Vulkan device */ void UnmapMemory(); /** - * @brief Create a Buffer object + * Create a Buffer object * * @param t_size device size * @param t_Usage buffer usage flag @@ -109,7 +108,7 @@ namespace Fling const void* t_Data = nullptr); /** - * @brief Flush memory range to device + * Flush memory range to device * * @param t_size Size of the memory range to flush to * @param t_offset offset from the beginning diff --git a/FlingEngine/Graphics/inc/CommandBuffer.h b/FlingEngine/Graphics/inc/CommandBuffer.h index 2a5101bf..77e30cd8 100644 --- a/FlingEngine/Graphics/inc/CommandBuffer.h +++ b/FlingEngine/Graphics/inc/CommandBuffer.h @@ -11,8 +11,7 @@ namespace Fling // #TODO Resource binding state class definition /** - * @brief Encapsulates functionality of a Vulkan Command buffer - * + * Encapsulates functionality of a Vulkan Command buffer */ class CommandBuffer { diff --git a/FlingEngine/Graphics/inc/Cubemap.h b/FlingEngine/Graphics/inc/Cubemap.h index 15e686a8..af1120b1 100644 --- a/FlingEngine/Graphics/inc/Cubemap.h +++ b/FlingEngine/Graphics/inc/Cubemap.h @@ -48,30 +48,28 @@ namespace Fling std::unique_ptr GetGraphicsPipeline() const { return std::unique_ptr(m_GraphicsPipeline); } /** - * @brief Get the Descriptor Sets object + * Get the Descriptor Sets object * * @return const VkDescriptorSet> */ VkDescriptorSet& GetDescriptorSet() { return m_DescriptorSet; } /** - * @brief Get the Vertex Buffer object + * Get the Vertex Buffer object * * @return const Buffer* */ Buffer* GetVertexBuffer() const { return m_Cube->GetVertexBuffer(); } /** - * @brief Get the Index Buffer object + * Get the Index Buffer object * * @return const Buffer* */ Buffer* GetIndexBuffer() const { return m_Cube->GetIndexBuffer(); } /** - * @brief Get the Index Count object - * - * @return const uint32 + * Get the Index Count object */ uint32 GetIndexCount() const { return m_Cube->GetIndexCount(); } diff --git a/FlingEngine/Graphics/inc/DepthBuffer.h b/FlingEngine/Graphics/inc/DepthBuffer.h index 7c3f9f30..8f0be894 100644 --- a/FlingEngine/Graphics/inc/DepthBuffer.h +++ b/FlingEngine/Graphics/inc/DepthBuffer.h @@ -20,14 +20,14 @@ namespace Fling /** - * @brief Creates all VK resources. Assumes that they are null. Uses swap chain extents + * Creates all VK resources. Assumes that they are null. Uses swap chain extents * Called on construction * @see Cleanup */ void Create(); /** - * @brief Cleans up all Vulkan resources of this depth buffer. + * Cleans up all Vulkan resources of this depth buffer. * Called automatically on destruction */ void Cleanup(); diff --git a/FlingEngine/Graphics/inc/DesktopWindow.h b/FlingEngine/Graphics/inc/DesktopWindow.h index d00ec62a..6d717396 100644 --- a/FlingEngine/Graphics/inc/DesktopWindow.h +++ b/FlingEngine/Graphics/inc/DesktopWindow.h @@ -47,7 +47,7 @@ namespace Fling virtual bool GetMouseVisible() override; /** - * @brief Set this window's icon. + * Set this window's icon. * @param t_ID the GUID of the window icon */ void SetWindowIcon(Guid t_ID) override; diff --git a/FlingEngine/Graphics/inc/FlingWindow.h b/FlingEngine/Graphics/inc/FlingWindow.h index 0aa869c2..83901795 100644 --- a/FlingEngine/Graphics/inc/FlingWindow.h +++ b/FlingEngine/Graphics/inc/FlingWindow.h @@ -63,7 +63,7 @@ namespace Fling virtual bool GetMouseVisible() = 0; /** - * @brief Set this window's icon. + * Set this window's icon. * @param t_ID the GUID of the window icon */ virtual void SetWindowIcon(Guid t_ID) = 0; diff --git a/FlingEngine/Graphics/inc/FrameBuffer.h b/FlingEngine/Graphics/inc/FrameBuffer.h index 790f0a51..728fb4f7 100644 --- a/FlingEngine/Graphics/inc/FrameBuffer.h +++ b/FlingEngine/Graphics/inc/FrameBuffer.h @@ -10,7 +10,7 @@ namespace Fling class LogicalDevice; /** - * @brief Describes the attributes of an attachment to be created + * Describes the attributes of an attachment to be created */ struct AttachmentCreateInfo { @@ -30,17 +30,17 @@ namespace Fling void Release(); /** - * @brief Returns true if the attachment has a depth component + * Returns true if the attachment has a depth component */ bool HasDepth(); /** - * @brief Returns true if the attachment has a stencil component + * Returns true if the attachment has a stencil component */ bool HasStencil(); /** - * @brief Returns true if the attachment is a depth and/or stencil attachment + * Returns true if the attachment is a depth and/or stencil attachment */ bool IsDepthStencil(); @@ -89,7 +89,7 @@ namespace Fling VkRenderPass GetRenderPassHandle() const { return m_RenderPass; } /** - * @brief Create the default render pass of this frame buffer + * Create the default render pass of this frame buffer * based on the given attachments it has. Should be called * AFTER adding attachments for proper uses. * @@ -98,7 +98,7 @@ namespace Fling VkResult CreateRenderPass(); /** - * @brief Create a sampler for sampling from any frame buffer attachments + * Create a sampler for sampling from any frame buffer attachments * @return VkResult for sampler creation */ VkResult CreateSampler(VkFilter magFilter, VkFilter minFilter, VkSamplerAddressMode adressMode); @@ -109,7 +109,7 @@ namespace Fling uint32 AddAttachment(AttachmentCreateInfo t_CreateInfo); /** - * @brief Get the frame buffer attachment at a given index + * Get the frame buffer attachment at a given index * @return nullptr if index is invalid */ FrameBufferAttachment* GetAttachmentAtIndex(uint32 t_Index); diff --git a/FlingEngine/Graphics/inc/GeometrySubpass.h b/FlingEngine/Graphics/inc/GeometrySubpass.h index 057cfd2b..55e68d87 100644 --- a/FlingEngine/Graphics/inc/GeometrySubpass.h +++ b/FlingEngine/Graphics/inc/GeometrySubpass.h @@ -19,7 +19,7 @@ namespace Fling class FirstPersonCamera; /** - * @brief Settings for the max directional lights and max point lights. + * Settings for the max directional lights and max point lights. * These settings are used * @todo Ideally we would load these settings in from the game config file */ @@ -53,7 +53,7 @@ namespace Fling }; /** - * @brief The geometry subpass is in charge of sending the geometry portion of + * The geometry subpass is in charge of sending the geometry portion of * the Deferred pipeline to the GPU. This includes frame buffer attachments for * albedo, normals, and depth as well some actual mesh data via a Uniform buffer * Uses the Deferred shaders diff --git a/FlingEngine/Graphics/inc/GraphicsHelpers.h b/FlingEngine/Graphics/inc/GraphicsHelpers.h index 2136ee09..38eee371 100644 --- a/FlingEngine/Graphics/inc/GraphicsHelpers.h +++ b/FlingEngine/Graphics/inc/GraphicsHelpers.h @@ -115,7 +115,7 @@ namespace Fling VkShaderModule CreateShaderModule(std::shared_ptr t_ShaderCode); /** - * @brief Create a an image view for Vulkan with the given format + * Create a an image view for Vulkan with the given format */ VkImageView CreateVkImageView(VkImage t_Image, VkFormat t_Format, VkImageAspectFlags t_AspectFalgs, uint32 t_MipLevels = 1); @@ -130,7 +130,7 @@ namespace Fling ); /** - * @brief Returns true if the given format has a stencil component + * Returns true if the given format has a stencil component */ bool HasStencilComponent(VkFormat t_format); diff --git a/FlingEngine/Graphics/inc/Instance.h b/FlingEngine/Graphics/inc/Instance.h index 2bc47e7f..bdffa61f 100644 --- a/FlingEngine/Graphics/inc/Instance.h +++ b/FlingEngine/Graphics/inc/Instance.h @@ -6,7 +6,7 @@ namespace Fling { /** - * @brief The instance is a representation of this application graphics instance in Vulkan + * The instance is a representation of this application graphics instance in Vulkan */ class Instance : NonCopyable { @@ -38,7 +38,7 @@ namespace Fling uint8 m_EnableValidationLayers : 1; /** - * @brief Create the VkInstance of this object and application information + * Create the VkInstance of this object and application information */ void CreateInstance(); diff --git a/FlingEngine/Graphics/inc/Lighting/DirectionalLight.hpp b/FlingEngine/Graphics/inc/Lighting/DirectionalLight.hpp index 8080b20e..a629c8e5 100644 --- a/FlingEngine/Graphics/inc/Lighting/DirectionalLight.hpp +++ b/FlingEngine/Graphics/inc/Lighting/DirectionalLight.hpp @@ -6,7 +6,7 @@ namespace Fling { /** - * @brief Simple representation of a directional light for Fling. Needs to be 16 bytes aligned + * Simple representation of a directional light for Fling. Needs to be 16 bytes aligned * for Vulkan */ struct alignas(16) DirectionalLight diff --git a/FlingEngine/Graphics/inc/Lighting/PointLight.hpp b/FlingEngine/Graphics/inc/Lighting/PointLight.hpp index 9e829faa..9d97517e 100644 --- a/FlingEngine/Graphics/inc/Lighting/PointLight.hpp +++ b/FlingEngine/Graphics/inc/Lighting/PointLight.hpp @@ -6,15 +6,14 @@ namespace Fling { /** - * @brief Simple representation of a point light in Light Vox. The colors and position have + * Simple representation of a point light in Light Vox. The colors and position have * to be glm::vec4's because of shader alignment things */ struct alignas(16) PointLight { public: /** - * @brief Diffuse color of this point light, RBA on a scale of 0.0 to 1.0 - * + * Diffuse color of this point light, RBA on a scale of 0.0 to 1.0 */ glm::vec4 DiffuseColor { 1.0f }; diff --git a/FlingEngine/Graphics/inc/LogicalDevice.h b/FlingEngine/Graphics/inc/LogicalDevice.h index 3ddc93b5..00ec4d5c 100644 --- a/FlingEngine/Graphics/inc/LogicalDevice.h +++ b/FlingEngine/Graphics/inc/LogicalDevice.h @@ -8,7 +8,7 @@ namespace Fling class Instance; /** - * @brief A logical device represents the application view of the device + * A logical device represents the application view of the device */ class LogicalDevice { @@ -57,12 +57,12 @@ namespace Fling uint32 m_TransferFamily = 0; /** - * @brief Get what queue Indecies/families this device should use + * Get what queue Indecies/families this device should use */ void CreateQueueIndecies(); /** - * @brief Create the Vk resoruces for this logical device + * Create the Vk resoruces for this logical device */ void CreateDevice(); }; diff --git a/FlingEngine/Graphics/inc/Material.h b/FlingEngine/Graphics/inc/Material.h index a5456947..4bf5b858 100644 --- a/FlingEngine/Graphics/inc/Material.h +++ b/FlingEngine/Graphics/inc/Material.h @@ -8,7 +8,7 @@ namespace Fling { /** - * @brief the properties of a PBR + * the properties of a PBR */ struct PBRTextures { @@ -19,7 +19,7 @@ namespace Fling }; /** - * @brief A material represents what properties should be given to a set + * A material represents what properties should be given to a set * of shaders. This is referenced by the MeshRednerer and Renderer::DrawFrame */ class Material : public JsonFile diff --git a/FlingEngine/Graphics/inc/Model.h b/FlingEngine/Graphics/inc/Model.h index dbeca4e5..74cf01d6 100644 --- a/FlingEngine/Graphics/inc/Model.h +++ b/FlingEngine/Graphics/inc/Model.h @@ -8,7 +8,7 @@ namespace Fling { /** - * @brief A model represents a 3D model (.obj files for now) with vertices + * A model represents a 3D model (.obj files for now) with vertices * and indecies. A model has a vertex and index buffer and can be * bound to a command buffer. */ @@ -22,7 +22,7 @@ namespace Fling static std::shared_ptr Quad(); /** - * @brief Construct a new model object + * Load a model from the asset path represented by t_ID. * @param t_ID The GUID that represents the file path to this model */ Model(Guid t_ID); @@ -58,7 +58,7 @@ namespace Fling Buffer* m_IndexBuffer = nullptr; /** - * @brief Load this model from Tiny Obj loader + * Load this model from Tiny Obj loader */ void LoadModel(); diff --git a/FlingEngine/Graphics/inc/MultiSampler.h b/FlingEngine/Graphics/inc/MultiSampler.h index b171da8a..39e8187c 100644 --- a/FlingEngine/Graphics/inc/MultiSampler.h +++ b/FlingEngine/Graphics/inc/MultiSampler.h @@ -8,7 +8,7 @@ namespace Fling class LogicalDevice; /** - * @brief A multi-sampler will allow us to enable MSAA. Should be recreated with the swap chain + * A multi-sampler will allow us to enable MSAA. Should be recreated with the swap chain * as it needs the most up to date extents */ class Multisampler @@ -16,12 +16,12 @@ namespace Fling public: /** - * @brief Creates a multi-sampler with the set sample count, but does not create it + * Creates a multi-sampler with the set sample count, but does not create it */ Multisampler(LogicalDevice* t_Dev, VkSampleCountFlagBits t_SampleCount = VK_SAMPLE_COUNT_1_BIT); /** - * @brief Initializes and creates this multi-sampler. + * Initializes and creates this multi-sampler. * @param t_Extents The extents of the current swap chain * @param t_Format The same image format as your swap chain */ diff --git a/FlingEngine/Graphics/inc/PhyscialDevice.h b/FlingEngine/Graphics/inc/PhyscialDevice.h index e8693941..8d8878df 100644 --- a/FlingEngine/Graphics/inc/PhyscialDevice.h +++ b/FlingEngine/Graphics/inc/PhyscialDevice.h @@ -5,7 +5,7 @@ namespace Fling { /** - * @brief A physical device represents the Vulkan physical device (the GPU) that + * A physical device represents the Vulkan physical device (the GPU) that * we are currently using */ class PhysicalDevice @@ -24,7 +24,7 @@ namespace Fling const VkPhysicalDeviceFeatures& GetDeivceFeatures() const { return m_DeviceFeatures; } /** - * @brief Get a string representing the device vendor + * Get a string representing the device vendor * * @param t_Props * @return const char* @@ -37,7 +37,7 @@ namespace Fling void LogPhysicalDeviceInfo(); /** - * @brief Checks hte given format properties that are supported on this physical device + * Checks hte given format properties that are supported on this physical device */ VkFormatProperties GetFormatProperties(VkFormat t_Form) const; diff --git a/FlingEngine/Graphics/inc/RenderPipeline.h b/FlingEngine/Graphics/inc/RenderPipeline.h index e34e35e1..f262dd7c 100644 --- a/FlingEngine/Graphics/inc/RenderPipeline.h +++ b/FlingEngine/Graphics/inc/RenderPipeline.h @@ -13,8 +13,7 @@ namespace Fling struct MeshRenderer; /** - * @brief A render pipeline encapsulates the functionality of a - * + * A render pipeline encapsulates the functionality of a */ class RenderPipeline : public NonCopyable { @@ -39,7 +38,7 @@ namespace Fling private: /** - * @brief Creates the descriptor pool and the descriptor sets for each sub pass to use + * Creates the descriptor pool and the descriptor sets for each sub pass to use */ void CreateDescriptors(entt::registry& t_Reg); diff --git a/FlingEngine/Graphics/inc/Shader.h b/FlingEngine/Graphics/inc/Shader.h index d7701224..85742a12 100644 --- a/FlingEngine/Graphics/inc/Shader.h +++ b/FlingEngine/Graphics/inc/Shader.h @@ -63,7 +63,7 @@ namespace Fling class LogicalDevice; /** - * @brief Class that represents what a shader is in the Fling engine. + * Class that represents what a shader is in the Fling engine. * Performs shader reflection and provides some helper functionality * for creating the Vk resources needed(descriptor sets, bindings, and locations) */ @@ -75,7 +75,7 @@ namespace Fling static std::shared_ptr Create(Guid t_ID, LogicalDevice* t_Dev); /** - * @brief Construct a new Shader object. Loads from disk and compiles the shader + * Load a shader from disk and compile it. * * @param t_ID The GUID that represents the file path to this file. */ @@ -84,7 +84,7 @@ namespace Fling ~Shader(); /** - * @brief Create a Shader Module object + * Create a Shader Module object * * @return VkShaderModule */ @@ -107,7 +107,7 @@ namespace Fling static uint32 GatherResources(const std::vector& t_Shaders, VkDescriptorType(&t_ResourceTypes)[32]); /** - * @brief Compiles this shader with SPRIV-Cross + * Compiles this shader with SPRIV-Cross */ void ParseReflectionData(const uint32* t_Code, uint32 t_Size); @@ -115,7 +115,7 @@ namespace Fling VkResult CreateShaderModule(std::vector& t_ShaderCode); /** - * @brief Load the raw shader code in off-disk + * Load the raw shader code in off-disk */ static std::vector LoadRawBytes(const std::string& t_FilePath); diff --git a/FlingEngine/Graphics/inc/Subpass.h b/FlingEngine/Graphics/inc/Subpass.h index fee4af55..0d14f776 100644 --- a/FlingEngine/Graphics/inc/Subpass.h +++ b/FlingEngine/Graphics/inc/Subpass.h @@ -15,7 +15,7 @@ namespace Fling class GraphicsPipeline; /** - * @brief A subpass represents one part of a RenderPipeline. Each subpass should + * A subpass represents one part of a RenderPipeline. Each subpass should * can add attachments to the frame buffer, build it's own command buffers, * and create its own descriptors. When overriding this class, add any additional * uniform buffers or bindings you may need into the child class. @@ -40,20 +40,20 @@ namespace Fling virtual void CleanUp(entt::registry& t_reg) {} /** - * @brief Given the frame buffers and the registry, create any descriptor sets that we may need + * Given the frame buffers and the registry, create any descriptor sets that we may need * Assumes that the frame buffer has been prepared with it's attachments already. * @param t_FrameBuffer The swap chain frame buffer */ virtual void CreateDescriptorSets(VkDescriptorPool t_Pool, entt::registry& t_reg) {}; /** - * @brief If a subpass has a command buffer that the final swap chain presentation is dependent on, + * If a subpass has a command buffer that the final swap chain presentation is dependent on, * then add it this vector. The Deferred offscreen GBuffer is an example of this */ virtual void GatherPresentDependencies(std::vector& t_CmdBuffs, std::vector& t_Deps, uint32 t_ActiveFrameIndex, uint32 t_CurrentFrameInFlight) {} /** - * @brief If a subpass has an additional command buffer to add to the final swap chain draw submission + * If a subpass has an additional command buffer to add to the final swap chain draw submission * but it is not dependent on it, then add it here. ImGUI is an example of this */ virtual void GatherPresentBuffers(std::vector& t_CmdBuffs, uint32 t_ActiveFrameIndex) {} diff --git a/FlingEngine/Graphics/inc/SwapChain.h b/FlingEngine/Graphics/inc/SwapChain.h index 0aaf110b..b2579212 100644 --- a/FlingEngine/Graphics/inc/SwapChain.h +++ b/FlingEngine/Graphics/inc/SwapChain.h @@ -16,7 +16,7 @@ namespace Fling class LogicalDevice; /** - * @brief Represents a swap chain that can be used throughout the program + * Represents a swap chain that can be used throughout the program */ class Swapchain { @@ -31,13 +31,13 @@ namespace Fling VkResult QueuePresent(const VkQueue& t_PresentQueue, const VkSemaphore& t_WaitSemaphore); /** - * @brief Recreate this swap chain including image views, render passes, and command buffers. + * Recreate this swap chain including image views, render passes, and command buffers. * DOES NOT Clean up any resources. */ void Recreate(const VkExtent2D& t_Extent); /** - * @brief Cleanup all swapchain resources + * Cleanup all swapchain resources */ void Cleanup(); @@ -75,7 +75,7 @@ namespace Fling std::vector m_ImageViews; /** - * @brief Create any swap chain resources (present mode, KGR swap chain) + * Create any swap chain resources (present mode, KGR swap chain) */ void CreateResources(); diff --git a/FlingEngine/Graphics/inc/Vertex.h b/FlingEngine/Graphics/inc/Vertex.h index 1aab69ba..5513a902 100644 --- a/FlingEngine/Graphics/inc/Vertex.h +++ b/FlingEngine/Graphics/inc/Vertex.h @@ -21,7 +21,7 @@ namespace Fling } /** - * @brief Gets the shader binding of a vertex + * Gets the shader binding of a vertex */ static VkVertexInputBindingDescription GetBindingDescription() { diff --git a/FlingEngine/Graphics/inc/VulkanApp.h b/FlingEngine/Graphics/inc/VulkanApp.h index 2dd7ca28..6d40bb36 100644 --- a/FlingEngine/Graphics/inc/VulkanApp.h +++ b/FlingEngine/Graphics/inc/VulkanApp.h @@ -33,7 +33,7 @@ namespace Fling class BaseEditor; /** - * @brief Core rendering functionality of the Fling Engine. Controls what Render pipelines + * Core rendering functionality of the Fling Engine. Controls what Render pipelines * are available */ class VulkanApp : public Singleton @@ -51,7 +51,7 @@ namespace Fling ~VulkanApp() = default; /** - * @brief Updates all rendering buffers and sends commands to draw a frame + * Updates all rendering buffers and sends commands to draw a frame */ void Update(float DeltaTime, entt::registry& t_Reg); @@ -72,19 +72,19 @@ namespace Fling private: /** - * @brief Prepare logical, physical and swap chain devices. + * Prepare logical, physical and swap chain devices. * Prepares window based on the Fling Config */ void Prepare(); /** - * @brief Create semaphores for available swap chain images and fences + * Create semaphores for available swap chain images and fences * for the current frame in flight */ void CreateFrameSyncResources(); /** - * @brief Creates a window and preps the VkSurfaceKHR + * Creates a window and preps the VkSurfaceKHR */ void CreateGameWindow(const uint32 t_width, const uint32 t_height); @@ -97,7 +97,7 @@ namespace Fling void BuildRenderPipelines(PipelineFlags t_Conf, entt::registry& t_Reg, std::shared_ptr t_Editor); /** - * @brief Build the frame buffers for each swap chain image along with the render pass + * Build the frame buffers for each swap chain image along with the render pass * for it to use */ void BuildSwapChainResources(); diff --git a/FlingEngine/Resources/inc/File.h b/FlingEngine/Resources/inc/File.h index 152f1d5d..dee62eaf 100644 --- a/FlingEngine/Resources/inc/File.h +++ b/FlingEngine/Resources/inc/File.h @@ -8,7 +8,7 @@ namespace Fling { /** - * @brief A file is a basic text file that contains a basic text file + * A file is a basic text file that contains a basic text file */ class File : public Resource { @@ -17,35 +17,35 @@ namespace Fling static std::shared_ptr Create(Guid t_ID); /** - * @brief Construct a new File object + * Load a file from the asset path represented by t_ID. * * @param t_ID The GUID that represents the file path to this file. */ explicit File(Guid t_ID); /** - * @brief Get char* that represents the text in this file + * Get char* that represents the text in this file * * @return const char* */ const char* GetData() const { return m_Characters.data(); } /** - * @brief Get the File Length object + * Get the File Length object * * @return size_t Length of the file in characters */ size_t GetFileLength() const { return m_Characters.size(); } /** - * @brief Returns true if this file resource is loaded or not (i.e. has any characters in the file) + * Returns true if this file resource is loaded or not (i.e. has any characters in the file) */ bool IsLoaded() const { return m_Characters.size() != 0; } private: /** - * @brief Loads the file based on Guid path. + * Loads the file based on Guid path. * @note All Guid paths are relative to the assets directory. */ diff --git a/FlingEngine/Resources/inc/FlingPaths.h b/FlingEngine/Resources/inc/FlingPaths.h index b1f79a17..5e58d393 100644 --- a/FlingEngine/Resources/inc/FlingPaths.h +++ b/FlingEngine/Resources/inc/FlingPaths.h @@ -26,7 +26,7 @@ namespace Fling static const std::string& EngineSourceDir(); /** - * @brief Convert a full absolute path to one relative to the engine assets directory. + * Convert a full absolute path to one relative to the engine assets directory. */ static std::string ConvertAbsolutePathToRelative(const std::string& t_FullPath); diff --git a/FlingEngine/Resources/inc/HDRImage.h b/FlingEngine/Resources/inc/HDRImage.h index ca4bd952..bbcc4af1 100644 --- a/FlingEngine/Resources/inc/HDRImage.h +++ b/FlingEngine/Resources/inc/HDRImage.h @@ -7,7 +7,7 @@ namespace Fling { class LogicalDevice; /** - * @brief Loads image R16G16B16_SFLOAT file formats + * Loads image R16G16B16_SFLOAT file formats * exmplae file format : .hdr */ class HDRImage : public Resource @@ -30,14 +30,14 @@ namespace Fling FORCEINLINE const VkFormat& GetVkImageFormat() const { return m_Format; } /** - * @brief Get the Image Size object + * Get the Image Size object * Multiply by 2 * 3 because there are 3 channels that are 2 bytes each * Each channel is represented as a signed 16 (bit) float * @return uint64 */ uint64 GetImageSize() const { return m_Width * m_Height * 6; } /** - * @brief Get the Pixel Data as signed floats + * Get the Pixel Data as signed floats * * @return const float* */ diff --git a/FlingEngine/Resources/inc/JsonFile.h b/FlingEngine/Resources/inc/JsonFile.h index dc2be4a3..fc99466d 100644 --- a/FlingEngine/Resources/inc/JsonFile.h +++ b/FlingEngine/Resources/inc/JsonFile.h @@ -11,7 +11,7 @@ namespace Fling { /** - * @brief A JsonFile provides an interface for easily using JSON files + * A JsonFile provides an interface for easily using JSON files */ class JsonFile : public Resource { @@ -20,7 +20,7 @@ namespace Fling static std::shared_ptr Create(Guid t_ID); /** - * @brief Construct a new JsonFile object + * Load a JSON file from the asset path represented by t_ID. * * @param t_ID The GUID that represents the file path to this JsonFile. */ @@ -35,7 +35,7 @@ namespace Fling FORCEINLINE nlohmann::json& GetJsonData() { return m_JsonData; } /** - * @brief Write the contents of this JSON file out to given name + * Write the contents of this JSON file out to given name */ void Write(); @@ -44,7 +44,7 @@ namespace Fling nlohmann::json m_JsonData; /** - * @brief Loads the JsonFile based on Guid path. + * Loads the JsonFile based on Guid path. * @note All Guid paths are relative to the assets directory. */ void LoadJsonFile(); diff --git a/FlingEngine/Resources/inc/Resource.h b/FlingEngine/Resources/inc/Resource.h index 19766f54..1ecb36b2 100644 --- a/FlingEngine/Resources/inc/Resource.h +++ b/FlingEngine/Resources/inc/Resource.h @@ -22,7 +22,7 @@ namespace Fling virtual ~Resource() = default; /** - * @brief Get GUID handle (just an int) for this resources guid. Use this to pass around + * Get GUID handle (just an int) for this resources guid. Use this to pass around * to different functions instead of the whole GUID * * @return Fling::Guid_Handle @@ -30,14 +30,14 @@ namespace Fling Fling::Guid_Handle GetGuidHandle() const { return m_Guid; } /** - * @brief Get the human-readable string representation of this GUID + * Get the human-readable string representation of this GUID * * @return std::string */ const std::string& GetGuidString() const { return m_HumanReadableName; } /** - * @brief Returns the full file path that is relative to the assets path based on the GUID of this resource. + * Returns the full file path that is relative to the assets path based on the GUID of this resource. */ std::string GetFilepathReleativeToAssets() const; diff --git a/FlingEngine/Resources/inc/ResourceManager.h b/FlingEngine/Resources/inc/ResourceManager.h index cad7cf28..904c32db 100644 --- a/FlingEngine/Resources/inc/ResourceManager.h +++ b/FlingEngine/Resources/inc/ResourceManager.h @@ -11,7 +11,7 @@ namespace Fling { /** - * @brief The resource manager handles loading of files off disk. Every Resource type + * The resource manager handles loading of files off disk. Every Resource type * has a Guid. This Guid functions as both the file path (relative to the ASSETS directory) * as well as a hashed string for easy passing around of information. Each resource is only * ever loaded into memory ONCE. @@ -38,7 +38,7 @@ namespace Fling std::shared_ptr GetResourceOfType(Guid_Handle t_ID) const; /** - * @brief Get the already loaded resouce with this Guid. Returns nullptr if not loaded yet. + * Get the already loaded resouce with this Guid. Returns nullptr if not loaded yet. * * @param t_ID Guid of the resource (a hashed string handle) * @return std::shared_ptr Pointer to the resource diff --git a/FlingEngine/Resources/inc/Texture.h b/FlingEngine/Resources/inc/Texture.h index a991a858..c5530bac 100644 --- a/FlingEngine/Resources/inc/Texture.h +++ b/FlingEngine/Resources/inc/Texture.h @@ -6,7 +6,7 @@ namespace Fling { /** - * @brief An image represents a 2D file that has data about each pixel in the image + * An image represents a 2D file that has data about each pixel in the image */ class Texture : public Resource { @@ -28,33 +28,33 @@ namespace Fling FORCEINLINE VkDescriptorImageInfo* GetDescriptorInfo() { return &m_ImageInfo; } FORCEINLINE const VkFormat& GetVkImageFormat() const { return m_Format; } /** - * @brief Get the Image Size object (width * height * 4) + * Get the Image Size object (width * height * 4) * Multiply by 4 because the pixel is laid out row by row with 4 bytes per pixel * @return int32 */ uint64 GetImageSize() const { return m_Width * m_Height * 4; } /** - * @brief Get the Pixel Data object + * Get the Pixel Data object * * @return stbi_uc* */ stbi_uc* GetPixelData() const { return m_PixelData; } /** - * @brief Release the Vulkan resources of this image + * Release the Vulkan resources of this image */ void Release(); private: /** - * @brief Loads the Vulkan resources needed for this image + * Loads the Vulkan resources needed for this image */ void LoadVulkanImage(); /** - * @brief Create a Image View object that is needed to sample this image from the swap chain + * Create a Image View object that is needed to sample this image from the swap chain */ void CreateImageView(); diff --git a/FlingEngine/Utils/inc/CircularBuffer.hpp b/FlingEngine/Utils/inc/CircularBuffer.hpp index 9e0e137a..edc50899 100644 --- a/FlingEngine/Utils/inc/CircularBuffer.hpp +++ b/FlingEngine/Utils/inc/CircularBuffer.hpp @@ -6,7 +6,7 @@ namespace Fling { /** - * @brief A simple circular buffer that will allow you get the next element in a buffer + * A simple circular buffer that will allow you get the next element in a buffer * It does not ensure that the item is not in use, but simply loops around. * * @tparam T the type inside this circular buffer. Stack allocated diff --git a/FlingEngine/Utils/inc/FlingTypes.h b/FlingEngine/Utils/inc/FlingTypes.h index 9ea46334..111a85d0 100644 --- a/FlingEngine/Utils/inc/FlingTypes.h +++ b/FlingEngine/Utils/inc/FlingTypes.h @@ -29,7 +29,7 @@ namespace Fling } /** - * @brief Helper function to check size_t is correctly converted to uint32_t + * Helper function to check size_t is correctly converted to uint32_t * @param value Value of type @ref size_t to convert * @return An @ref uint32 representation of the same value */ diff --git a/FlingEngine/Utils/inc/FreeList.h b/FlingEngine/Utils/inc/FreeList.h index 9d06b749..f18161b4 100644 --- a/FlingEngine/Utils/inc/FreeList.h +++ b/FlingEngine/Utils/inc/FreeList.h @@ -9,18 +9,18 @@ namespace Fling { /** - * @brief Helpful for allocating/freeing objects of a certain - * size which have to be created/destroeyed dynamically - * - * @see https://blog.molecular-matters.com/2012/09/17/memory-allocation-strategies-a-pool-allocator/ + * Helpful for allocating/freeing objects of a certain size which have to be + * created/destroyed dynamically. + * + * @see https://blog.molecular-matters.com/2012/09/17/memory-allocation-strategies-a-pool-allocator/ */ class FLING_API FreeList { public: /** - * @brief Construct a new Free List object - * + * Create a free list over the given memory region for fixed-size elements. + * * @param t_Start Start of the memory block to use for this free list * @param t_End End of the memory block to use for this free list * @param t_ElmSize Size of an "element" that this list will be used for @@ -31,14 +31,14 @@ namespace Fling FreeList(void* t_Start, void* t_End, size_t t_ElmSize, size_t t_Alignment = 8, size_t t_Offset = 0); /** - * @brief Obtain a chunk of memory of the size and alignment that this list was created with - * - * @return void* nullptr if no memory available + * Obtain a chunk of memory of the size and alignment that this list was created with. + * + * @return Pointer to the block, or nullptr if none are available */ inline void* Obtain() noexcept; /** - * @brief Return a block of memory to the free list. Memory can be returned in any order + * Return a block of memory to the free list. Memory can be returned in any order. */ inline void Return(void* t_Ptr); diff --git a/FlingEngine/Utils/inc/Logger.h b/FlingEngine/Utils/inc/Logger.h index c8e7b2c0..2d2435c0 100644 --- a/FlingEngine/Utils/inc/Logger.h +++ b/FlingEngine/Utils/inc/Logger.h @@ -17,7 +17,7 @@ namespace Fling { /** - * @brief Singleton class that allows logging to the console as well as async to a file. + * Singleton class that allows logging to the console as well as async to a file. * Use the defines to actually log strings out. */ class Logger : public Singleton @@ -33,7 +33,7 @@ namespace Fling static std::shared_ptr GetCurrentConsole(); /** - * @brief Get the current async log file that is being written to + * Get the current async log file that is being written to */ static std::shared_ptr GetCurrentLogFile(); diff --git a/FlingEngine/Utils/inc/MovingAverage.hpp b/FlingEngine/Utils/inc/MovingAverage.hpp index 8a6b5d24..2b04547a 100644 --- a/FlingEngine/Utils/inc/MovingAverage.hpp +++ b/FlingEngine/Utils/inc/MovingAverage.hpp @@ -5,7 +5,7 @@ namespace Fling { /** - * @brief A moving average can be used to calculate things like FPS + * A moving average can be used to calculate things like FPS */ template class MovingAverage diff --git a/FlingEngine/Utils/inc/Singleton.hpp b/FlingEngine/Utils/inc/Singleton.hpp index 0394e123..9f679f5f 100644 --- a/FlingEngine/Utils/inc/Singleton.hpp +++ b/FlingEngine/Utils/inc/Singleton.hpp @@ -5,7 +5,7 @@ namespace Fling { /** - * @brief Class that can have only one instance. + * Class that can have only one instance. */ template class Singleton diff --git a/FlingEngine/Utils/inc/StackAllocator.h b/FlingEngine/Utils/inc/StackAllocator.h index 264ef344..11c4a652 100644 --- a/FlingEngine/Utils/inc/StackAllocator.h +++ b/FlingEngine/Utils/inc/StackAllocator.h @@ -9,36 +9,36 @@ namespace Fling { /** - * @brief - * + * Stack (LIFO) allocator over a fixed memory region. + * * @see https://blog.molecular-matters.com/2012/08/27/memory-allocation-strategies-a-stack-like-lifo-allocator/ */ class StackAllocator { public: /** - * @brief Construct a new Stack Allocator object - * + * Create a stack allocator over the memory between t_Start and t_End. + * * @param t_Start Start of the memory block to use for this stack allocator - * @param t_End End of the memory block to use for this stack allocator + * @param t_End End of the memory block to use for this stack allocator */ StackAllocator(void* t_Start, void* t_End); ~StackAllocator(); /** - * @brief - * - * @param t_Size Size of the block of memory + * Allocate a block from the top of the stack. + * + * @param t_Size Size of the block of memory * @param t_Alignment Alignment of the element (Default = 8) * @param t_Offset Offset of the element (Default = 0) - * @return void* Obtain a chunk of memory of the size, alignment, and offset (asserts when we exceed preallocated size) + * @return Pointer to the allocated block (asserts when we exceed the preallocated size) */ void* Allocate(size_t t_Size, size_t t_Alignment = 0, size_t t_Offset = 0); /** - * @brief Returns a block of memory to the stack in a LIFO manner - * - * @param t_Ptr + * Return a block of memory to the stack in LIFO order. + * + * @param t_Ptr Pointer previously returned by Allocate */ void Free(void* t_Ptr); @@ -47,4 +47,4 @@ namespace Fling char* m_End = nullptr; char* m_Current = nullptr; }; -} \ No newline at end of file +} diff --git a/FlingEngine/Utils/inc/Timing.h b/FlingEngine/Utils/inc/Timing.h index 5ccd1872..6916b2e2 100644 --- a/FlingEngine/Utils/inc/Timing.h +++ b/FlingEngine/Utils/inc/Timing.h @@ -30,16 +30,12 @@ namespace Fling float FLING_API GetDeltaTime(); /** - * @brief Get the current time of the application (double) - * - * @return double GetTime + * Get the current time of the application (double) */ double FLING_API GetTime() const; /** - * @brief Get the current time of the application (float) - * - * @return float GetTimef + * Get the current time of the application (float) */ float FLING_API GetTimef() const { @@ -47,37 +43,27 @@ namespace Fling } /** - * @brief Get the time that that frame has started - * - * @return float GetFrameStartTime + * Get the time that that frame has started */ float FLING_API GetFrameStartTime() const { return m_frameStartTimef; } /** - * @brief Get the time that the application has started - * - * @return double GetStartTime + * Get the time that the application has started */ double FLING_API GetStartTime() const { return m_startTime; } /** - * @brief Get the time since that application has started (i.e. time running) - * - * @return float GetTimeSinceStart + * Get the time since that application has started (i.e. time running) */ float FLING_API GetTimeSinceStart() const { return GetTimef() - static_cast(m_startTime); } /** - * @brief Get fps count - * - * @return int GetFrameCount + * Get fps count */ int FLING_API GetFrameCount() const { return m_fpsFrameCount; } /** - * @brief Get current frame time - * - * @return float GetFrameTime + * Get current frame time */ float FLING_API GetFrameTime() const { return 1000.0f / static_cast(m_fpsFrameCount); } diff --git a/README.md b/README.md index 991656cf..7e968e69 100644 --- a/README.md +++ b/README.md @@ -73,9 +73,10 @@ Notice the `-DDEFINE_SHIPPING` option is set to `ON`. This sets a definiton that If you have any contributions or fixes that you want to contribute, then feel free to open an issue or a pull request! I'm happy to talk about the project, so feel free to reach out -to me on [Twitter](https://twitter.com/BenjaFriend?lang=en) or here on GitHub. Eventually a -goal is to have some more specific PR templates/coding standards but for now that is not a -priority. +to me on [Twitter](https://twitter.com/BenjaFriend?lang=en) or here on GitHub. + +See [docs/CodingStyle.md](docs/CodingStyle.md) for documentation-comment conventions and +how to run the comment-style check / clang-format. ## Branching Strategy We use a pretty basic branching strategy. Make a feature branch off of `Main` for something like "add-support-for-x", and then that feature is done and tested create a pull request to get it into Main. diff --git a/Sandbox/Gameplay/inc/SandboxGame.h b/Sandbox/Gameplay/inc/SandboxGame.h index ce903343..d6767a5a 100644 --- a/Sandbox/Gameplay/inc/SandboxGame.h +++ b/Sandbox/Gameplay/inc/SandboxGame.h @@ -5,7 +5,7 @@ namespace Sandbox { /** - * @brief Custom game class that will have control of it's gameplay systems. + * Custom game class that will have control of it's gameplay systems. */ class Game : public Fling::Game { @@ -13,7 +13,7 @@ namespace Sandbox void Init(entt::registry& t_Reg) override final; /** - * @brief Called before the first gameplay loop tick. + * Called before the first gameplay loop tick. * Do any initalization for custom gameplay systems here. */ void OnStartGame(entt::registry& t_Reg) override final; @@ -29,7 +29,7 @@ namespace Sandbox void Shutdown(entt::registry& t_Reg) override final; /** - * @brief Callback for when the user has given input that shows they want to exit + * Callback for when the user has given input that shows they want to exit */ void OnQuitPressed(); diff --git a/Sandbox/Gameplay/inc/SandboxUI.h b/Sandbox/Gameplay/inc/SandboxUI.h index 22923f0d..f41337c0 100644 --- a/Sandbox/Gameplay/inc/SandboxUI.h +++ b/Sandbox/Gameplay/inc/SandboxUI.h @@ -5,7 +5,7 @@ namespace Sandbox { /** - * @brief Owns the drawing of any UI elements for the Sandbox game. + * Owns the drawing of any UI elements for the Sandbox game. */ class SandboxUI { @@ -14,7 +14,7 @@ namespace Sandbox ~SandboxUI() = default; /** - * @brief Draw the sandbox game ImGui UI elements + * Draw the sandbox game ImGui UI elements */ void NewFrame(entt::registry& t_Reg); }; diff --git a/docs/CodingStyle.md b/docs/CodingStyle.md new file mode 100644 index 00000000..a6ab6f47 --- /dev/null +++ b/docs/CodingStyle.md @@ -0,0 +1,52 @@ +# Coding Style + +Conventions for first-party Fling Engine C++ (`FlingEngine/`, `Sandbox/`, `FlingTests/`). +Third-party code under `external/` is left alone. + +## Documentation comments + +Prefer modern Doxygen-style blocks with a plain description. Do **not** use +Visual Studio / XML-wizard tags like `@brief`, and do not use `/*!`. + +```cpp +/** + * Holds onto the command line arguments passed to this application. + * + * @param Argc Number of arguments + * @param ArgV Argument values + * @return True if successfully initialized + */ +bool Init(const int32 Argc, const char* ArgV[]); +``` + +Guidelines: + +- Lead with a short description; skip `@brief`. +- Use `@param` / `@return` / `@see` only when they add information the signature does not already make obvious. +- Prefer `/** ... */` for API docs. One-line members can use `/** ... */` on a single line. +- Do not write auto-generated noise such as `@return float GetTimef` or empty `@brief` lines. + +Member fields and trivial accessors can use a short one-liner: + +```cpp +/** The time that the program started */ +double m_startTime = 0.0; +``` + +## Enforcement + +- **Comment content**: `python3 scripts/check_comment_style.py` + Rejects leftover `@brief` and `/*!` in first-party sources. +- **Layout**: `.clang-format` at the repo root. + clang-format does **not** validate documentation tags; it only formats code/comment layout. + +Format first-party files (example): + +```bash +find FlingEngine Sandbox FlingTests -type f \( -name '*.h' -o -name '*.hpp' -o -name '*.cpp' \) \ + | xargs clang-format -i +``` + +A one-time migration from the old `@brief`-heavy style lives in +`scripts/migrate_doxygen_comments.py` (see issue +[#166](https://github.com/flingengine/FlingEngine/issues/166)). diff --git a/scripts/check_comment_style.py b/scripts/check_comment_style.py new file mode 100755 index 00000000..4519ce60 --- /dev/null +++ b/scripts/check_comment_style.py @@ -0,0 +1,68 @@ +#!/usr/bin/env python3 +""" +Check that first-party C++ sources follow the FlingEngine doc-comment style +(see docs/CodingStyle.md and issue #166). + +Fails if any of these legacy patterns remain: + - @brief tags (prefer a plain description line) + - /*! doc comments (prefer /**) +""" + +from __future__ import annotations + +import argparse +import re +import sys +from pathlib import Path + +ROOTS = ("FlingEngine", "Sandbox", "FlingTests") +EXTENSIONS = {".h", ".hpp", ".cpp", ".cc", ".cxx"} + +PATTERNS = [ + (re.compile(r"@brief\b"), "@brief tag (use a plain description instead)"), + (re.compile(r"/\*!"), "/*! doc comment (use /** instead)"), +] + + +def find_sources(repo_root: Path) -> list[Path]: + files: list[Path] = [] + for root_name in ROOTS: + root = repo_root / root_name + if not root.is_dir(): + continue + for path in root.rglob("*"): + if path.suffix in EXTENSIONS and path.is_file(): + files.append(path) + return sorted(files) + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--repo-root", + type=Path, + default=Path(__file__).resolve().parent.parent, + ) + args = parser.parse_args() + + violations = 0 + for path in find_sources(args.repo_root): + text = path.read_text(encoding="utf-8", errors="replace") + rel = path.relative_to(args.repo_root) + for lineno, line in enumerate(text.splitlines(), start=1): + for pattern, message in PATTERNS: + if pattern.search(line): + print(f"{rel}:{lineno}: {message}") + print(f" {line.strip()}") + violations += 1 + + if violations: + print(f"\nFound {violations} comment-style violation(s).") + return 1 + + print("Comment style check passed.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/migrate_doxygen_comments.py b/scripts/migrate_doxygen_comments.py new file mode 100755 index 00000000..61f5ddc8 --- /dev/null +++ b/scripts/migrate_doxygen_comments.py @@ -0,0 +1,195 @@ +#!/usr/bin/env python3 +""" +One-time migration: convert verbose XML/Doxygen-wizard comments to the +project's preferred style (issue #166). + +Transforms (first-party sources only): + - /*! ... */ -> /** ... */ + - Remove @brief tags; keep the description text + - Drop empty @brief-only lines + - Drop useless auto-generated @return lines like "@return float GetTimef" + - Collapse runs of blank comment lines inside a doc block +""" + +from __future__ import annotations + +import argparse +import re +import sys +from pathlib import Path + +ROOTS = ("FlingEngine", "Sandbox", "FlingTests") +EXTENSIONS = {".h", ".hpp", ".cpp", ".cc", ".cxx"} + +# Match a doc-comment line that is only "@brief" (optional whitespace). +EMPTY_BRIEF = re.compile(r"^(\s*\*)\s*@brief\s*$") +# Match "@brief " and keep the text. +BRIEF_WITH_TEXT = re.compile(r"^(\s*\*)\s*@brief\s+(.*)$") +# Auto-generated "@return " with no real description +# (e.g. "@return float GetTimef", "@return const float& m_nearPlane"). +USELESS_RETURN = re.compile( + r"^(\s*\*)\s*@return\s+" + r"(?:const\s+)?" + r"(?:unsigned\s+)?" + r"(?:[\w:]+(?:\s*<*[\w:\s,]*>)?(?:\s*[*&])?)\s+" + r"([A-Za-z_][\w]*)\s*$" +) +# Blank interior comment line: " *" or " * " with only whitespace after *. +BLANK_COMMENT_LINE = re.compile(r"^\s*\*\s*$") +# Opening of a C-style doc comment (/** or /*!), possibly with content. +DOC_OPEN = re.compile(r"/\*[\*!]") + + +def find_sources(repo_root: Path) -> list[Path]: + files: list[Path] = [] + for root_name in ROOTS: + root = repo_root / root_name + if not root.is_dir(): + continue + for path in root.rglob("*"): + if path.suffix in EXTENSIONS and path.is_file(): + files.append(path) + return sorted(files) + + +# Single-line or opening-line forms: "/** @brief text */" / "/** @brief text" +OPENING_BRIEF = re.compile( + r"^(\s*/\*\*)\s*@brief\s*(.*?)(\s*\*/\s*)?$" +) + + +def _is_interior_blank(stripped: str) -> bool: + """True for a middle comment line that is only '*' / '* '.""" + if stripped.lstrip().startswith("/**") or stripped.rstrip().endswith("*/"): + return False + return bool(BLANK_COMMENT_LINE.match(stripped)) + + +def transform_doc_block(block: str) -> str: + """Transform the interior of a /** ... */ block (including delimiters).""" + # Normalize /*! to /** + if block.startswith("/*!"): + block = "/**" + block[3:] + + lines = block.splitlines(keepends=True) + out: list[str] = [] + + for line in lines: + stripped = line.rstrip("\r\n") + newline = line[len(stripped) :] + + opening = OPENING_BRIEF.match(stripped) + if opening: + prefix, text, closer = opening.group(1), opening.group(2).strip(), opening.group(3) + if closer: + body = f" {text} " if text else " " + out.append(f"{prefix}{body}*/{newline}") + else: + out.append(f"{prefix}{newline}" if not text else f"{prefix} {text}{newline}") + continue + + if EMPTY_BRIEF.match(stripped): + continue + + m = BRIEF_WITH_TEXT.match(stripped) + if m: + prefix, text = m.group(1), m.group(2).rstrip() + out.append(f"{prefix} {text}{newline}" if text else f"{prefix}{newline}") + continue + + if USELESS_RETURN.match(stripped): + continue + + out.append(line) + + if not out: + return block + + # Drop leading blank interior lines (right after /**). + while len(out) > 2 and _is_interior_blank(out[1].rstrip("\r\n")): + del out[1] + + # Drop trailing blank interior lines (right before */). + while len(out) > 2 and _is_interior_blank(out[-2].rstrip("\r\n")): + del out[-2] + + # Collapse consecutive blank interior lines. + collapsed: list[str] = [] + prev_blank = False + for line in out: + blank = _is_interior_blank(line.rstrip("\r\n")) + if blank and prev_blank: + continue + collapsed.append(line) + prev_blank = blank + + return "".join(collapsed) + + +def transform_file_text(text: str) -> str: + result: list[str] = [] + i = 0 + n = len(text) + + while i < n: + m = DOC_OPEN.search(text, i) + if not m: + result.append(text[i:]) + break + + start = m.start() + result.append(text[i:start]) + + # Find end of this comment block. + end = text.find("*/", start + 3) + if end == -1: + result.append(text[start:]) + break + end += 2 # include */ + + block = text[start:end] + result.append(transform_doc_block(block)) + i = end + + return "".join(result) + + +def process_file(path: Path, dry_run: bool) -> bool: + original = path.read_text(encoding="utf-8") + updated = transform_file_text(original) + if updated == original: + return False + if not dry_run: + path.write_text(updated, encoding="utf-8") + return True + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--dry-run", + action="store_true", + help="Report files that would change without writing", + ) + parser.add_argument( + "--repo-root", + type=Path, + default=Path(__file__).resolve().parent.parent, + help="Repository root (default: parent of scripts/)", + ) + args = parser.parse_args() + + changed = [] + for path in find_sources(args.repo_root): + if process_file(path, dry_run=args.dry_run): + changed.append(path.relative_to(args.repo_root)) + + action = "Would update" if args.dry_run else "Updated" + for rel in changed: + print(f"{action}: {rel}") + print(f"{action} {len(changed)} file(s).") + return 0 + + +if __name__ == "__main__": + sys.exit(main())