Modernize first-party C++ doc comments

.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

.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

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
 		 */

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

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 
 		 */

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 
 		 */

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);
 

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; }
 

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; } 
 

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,20 +23,20 @@ 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. 
          */
         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();
 

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,15 +49,15 @@ 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
 		 */
 		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.
 		 *