📝 Add docstrings to aro/windows-dev

Docstrings generation was requested by @arozx.

* #18 (comment)

The following files were modified:

* `sandbox/src/SandboxApp.cpp`
* `src/Application.cpp`
* `src/Debug/Profiler.h`
* `src/EntryPoint.h`
* `src/Input/InputSystem.cpp`
* `src/UI/ImGuiOverlay.cpp`
* `src/UI/ImGuiOverlay.h`
* `src/Window/OpenGLWindow.cpp`

sandbox/src/SandboxApp.cpp

@@ -181,15 +181,14 @@ void SandboxApp::ExecuteCommand(const std::string& command) {
 
 namespace Engine {
 /**
- * @brief Creates and returns a new SandboxApp instance.
- * 
- * This function is responsible for instantiating the primary application 
- * for the sandbox environment. It allocates a new SandboxApp object 
- * which provides a Lua scripting console and other sandbox-specific 
- * application features.
- * 
- * @return Application* A pointer to a newly created SandboxApp instance.
- * @note The caller is responsible for managing the memory of the returned Application pointer.
+ * @brief Instantiates and returns a new SandboxApp.
+ *
+ * Creates a new SandboxApp, which powers the sandbox environment with a Lua scripting console and related features.
+ * Any exceptions thrown during instantiation are caught; in such cases, an error is logged to standard error and a 
+ * nullptr is returned.
+ *
+ * @return Application* Pointer to the new SandboxApp instance, or nullptr if instantiation fails.
+ * @note The caller is responsible for managing the memory of the returned pointer.
  */
 
 Application* CreateApplication() {

src/Application.cpp

@@ -57,7 +57,18 @@ namespace Engine {
     Application* Application::s_Instance = nullptr;
 
     /**
-     * @brief Initialize the application and all subsystems
+     * @brief Constructs the Application instance and initializes core engine subsystems.
+     *
+     * This constructor sets up the runtime environment for the voxel engine by:
+     * - Assigning the global instance pointer.
+     * - Beginning a runtime profiling session.
+     * - Creating the application window.
+     * - Initializing the renderer and input system.
+     * - Configuring the ImGui layer and overlay for UI rendering.
+     * - Initializing the Lua script system and executing initial scripts from designated asset directories.
+     * - Preloading frequently used assets and setting up default key toggle states.
+     *
+     * Critical initialization failures are logged to aid in troubleshooting startup issues.
      */
     Application::Application() 
     {

src/Debug/Profiler.h

@@ -423,6 +423,13 @@ class Profiler {
         }
     }
 
+    /**
+     * @brief Ensures the thread-local batched measurements container has sufficient capacity.
+     *
+     * This function checks whether the current capacity of the batched measurements vector is 
+     * less than the predefined BATCH_RESERVE_SIZE. If it is, additional capacity is reserved to 
+     * minimize the need for reallocations during batch profiling.
+     */
     bool m_Enabled{true};
     std::unordered_set<std::string> m_StringPool;
     OutputFormat m_OutputFormat{OutputFormat::JSON};

src/EntryPoint.h

@@ -12,7 +12,20 @@
 
 extern Engine::Application* Engine::CreateApplication();
 
-int main(int argc, char** argv) {
+/**
+     * @brief Application entry point.
+     *
+     * This function initializes the application by obtaining an instance via Engine::CreateApplication(). 
+     * If the application instance is not created (i.e., returns a null pointer), it throws a runtime error. 
+     * On a successful creation, it runs the application and cleans up the allocated resources before returning 0.
+     *
+     * @param argc The number of command-line arguments.
+     * @param argv The array of command-line argument strings.
+     * @return int Returns 0 on success, or -1 if an error is encountered.
+     *
+     * @throws std::runtime_error if Engine::CreateApplication() returns a null pointer.
+     */
+    int main(int argc, char** argv) {
     try {
         // Create application instance
         auto app = Engine::CreateApplication();

src/Input/InputSystem.cpp

@@ -14,6 +14,16 @@
 #include <GLFW/glfw3.h>
 
 namespace Engine {
+    /**
+     * @brief Constructs the InputSystem instance.
+     *
+     * Initializes the input system with the provided window and renderer. The constructor locks
+     * the cursor by default and updates its state. It also performs a null check on the window pointer,
+     * throwing a std::invalid_argument exception if the pointer is null.
+     *
+     * @param window Pointer to the application window. Must not be null.
+     * @param renderer Reference to the renderer utilized by the input system.
+     */
     InputSystem::InputSystem(Window* window, Renderer& renderer)
         : m_Window(window), m_Renderer(renderer) {
 
@@ -75,6 +85,13 @@ namespace Engine {
         HandleSensitivityAdjustment();
     }
 
+    /**
+     * @brief Adjusts the mouse sensitivity based on key input.
+     *
+     * Increases the mouse sensitivity by 0.01 when the right bracket key is pressed,
+     * and decreases it by 0.01 when the left bracket key is pressed, ensuring a minimum
+     * sensitivity of 0.01.
+     */
     void InputSystem::HandleSensitivityAdjustment() {
         if (IsKeyPressed(GLFW_KEY_RIGHT_BRACKET)) {
             m_MouseSensitivity += 0.01f;
@@ -84,6 +101,14 @@ namespace Engine {
         }
     }
 
+    /**
+     * @brief Adjusts the movement speed based on modifier key inputs.
+     *
+     * Modifies the provided speed value by reference: if the left control key is pressed, the speed is reduced
+     * by the slow multiplier; if the left shift key is pressed, the speed is increased by the sprint multiplier.
+     *
+     * @param speed Movement speed factor to be adjusted.
+     */
     void InputSystem::HandleSpeedModifiers(float& speed) const {
         if (IsKeyPressed(GLFW_KEY_LEFT_CONTROL)) {
             speed *= m_SlowMultiplier;
@@ -92,6 +117,19 @@ namespace Engine {
         }
     }
 
+    /**
+     * @brief Updates the perspective camera's position based on keyboard input.
+     *
+     * Processes movement keys (W, A, S, D, SPACE, and LEFT SHIFT) to compute a directional
+     * vector relative to the camera's orientation. The movement speed is adjusted by custom modifiers,
+     * and the displacement is scaled by the elapsed time. When smooth camera movement is enabled, a damping
+     * algorithm interpolates the camera's position toward a target to ensure smooth transitions.
+     *
+     * No movement is applied if camera control is disabled, movement is locked, or if the active or
+     * perspective camera is invalid.
+     *
+     * @param deltaTime The elapsed time since the last update, used to scale the movement.
+     */
     void InputSystem::HandleCameraMovement(float deltaTime) {
         if (!m_CameraEnabled || m_MovementLocked) return;
 
@@ -155,6 +193,15 @@ namespace Engine {
         }
     }
 
+    /**
+     * @brief Updates the perspective camera's rotation based on mouse movement.
+     *
+     * Processes a mouse movement event by calculating the offset from the previous cursor position,
+     * then applies this offset to the perspective camera if camera controls are enabled and movement is not locked.
+     * On the first mouse event, it initializes the last known mouse coordinates to prevent sudden jumps.
+     *
+     * @param e The mouse movement event containing the current cursor coordinates.
+     */
     void InputSystem::HandleMouseMovement(const MouseMovedEvent& e) {
         if (!m_CameraEnabled || m_MovementLocked) return;
 

src/UI/ImGuiOverlay.cpp

@@ -151,17 +151,16 @@ namespace Engine {
     }
 
     /**
-     * @brief Renders a comprehensive profiler window for performance metrics and analysis
-     * 
-     * This method displays a window that allows users to control and view profiling information.
-     * Features include:
-     * - Enabling/disabling profiling
-     * - Clearing existing profiling data
-     * - Configuring number of frames to profile
-     * - Displaying detailed performance statistics for each profiled function
-     * 
-     * @note The window is only rendered if m_ShowProfiler is true
-     * @note Profiling data includes average, minimum, maximum execution times, and number of calls
+     * @brief Renders a profiler window displaying performance metrics.
+     *
+     * This method displays an interactive profiling window that allows users to enable or disable
+     * performance profiling, clear existing profiling data, and set the number of frames to profile
+     * (clamped between 1 and 1000). It also shows detailed timing statistics for each profiled function,
+     * including average, minimum, and maximum execution times, as well as the call count.
+     *
+     * If a frame profiling session is active, the window displays the current profiling progress.
+     *
+     * @note The profiler window is rendered only when profiling display (m_ShowProfiler) is enabled.
      */
     void ImGuiOverlay::RenderProfiler() const {
         if (!m_ShowProfiler) return;

src/UI/ImGuiOverlay.h

@@ -10,6 +10,110 @@
 #include "../Core/FPSCounter.h"
 #include "ImGuiFlameGraph.h"
 
+/**
+ * @brief ImGui-based overlay for engine debugging and control interfaces.
+ *
+ * Provides a collection of ImGui windows and panels to display performance metrics,
+ * manipulate object transforms, adjust renderer settings, debug events, and control terrain generation.
+ */
+
+/**
+ * @brief Initializes the ImGui overlay.
+ *
+ * Sets up the ImGui overlay using the specified application window, which serves as the rendering context for ImGui elements.
+ *
+ * @param window Pointer to the application window.
+ */
+
+/**
+ * @brief Default destructor.
+ */
+
+/**
+ * @brief Renders the performance statistics overlay.
+ *
+ * Displays real-time performance metrics including current FPS, average FPS, frame time,
+ * and the 1% low/high FPS values. Optionally shows the FPS counter based on the provided flag.
+ *
+ * @param renderObject Current render object context.
+ * @param showFPSCounter Whether the FPS counter should be displayed.
+ * @param currentFPS Current frames per second.
+ * @param averageFPS Average frames per second.
+ * @param frameTime Time taken to render the last frame.
+ * @param fps1PercentLow 1% low FPS value.
+ * @param fps1PercentHigh 1% high FPS value.
+ */
+
+/**
+ * @brief Renders the transform manipulation controls.
+ *
+ * Displays interactive controls for adjusting the transform properties of a render object,
+ * such as translation, rotation, and scale.
+ *
+ * @param renderObject The render object whose transform is being controlled.
+ */
+
+/**
+ * @brief Displays the profiler information window.
+ *
+ * Renders a window with detailed profiling metrics for performance analysis.
+ * This method is const and does not modify the overlay state.
+ */
+
+/**
+ * @brief Displays the renderer settings panel.
+ *
+ * Provides a UI panel to adjust various renderer options and optimize visual performance.
+ */
+
+/**
+ * @brief Displays the event debugging interface.
+ *
+ * Renders a window that allows in-depth inspection and debugging of engine events.
+ */
+
+/**
+ * @brief Displays the terrain generation controls.
+ *
+ * Renders interactive UI elements for adjusting terrain generation parameters,
+ * enabling real-time debugging and refinement.
+ */
+
+/**
+ * @brief Sets the visibility of transform manipulation controls.
+ *
+ * @param show Flag indicating whether the transform controls should be displayed.
+ */
+
+/**
+ * @brief Sets the visibility of the profiler window.
+ *
+ * @param show Flag indicating whether the profiler should be displayed.
+ */
+
+/**
+ * @brief Sets the visibility of the renderer settings panel.
+ *
+ * @param show Flag indicating whether the renderer settings should be displayed.
+ */
+
+/**
+ * @brief Sets the visibility of the event debugger interface.
+ *
+ * @param show Flag indicating whether the event debugger should be displayed.
+ */
+
+/**
+ * @brief Sets the visibility of the terrain controls.
+ *
+ * @param show Flag indicating whether the terrain controls should be displayed.
+ */
+
+/**
+ * @brief Sets the visibility of the FPS counter overlay.
+ *
+ * @param show Flag indicating whether the FPS counter should be displayed.
+ */
 namespace Engine {
     /**
      * @brief ImGui-based overlay for debug and control interfaces

src/Window/OpenGLWindow.cpp

@@ -165,13 +165,16 @@ namespace Engine {
     }
 
     /**
-     * @brief Clean up window resources
-     * @details Destroys GLFW window and terminates GLFW
+     * @brief Shuts down the OpenGL window system.
+     *
+     * This function destroys the GLFW window if it exists and then terminates the GLFW library.
+     * Note that the internal window pointer is not reset after destruction, so it may become a dangling pointer
+     * if accessed subsequently.
      */
     void OpenGLWindow::Shutdown() {
         if (m_Window) {
             glfwDestroyWindow(m_Window);
-            m_Window = nullptr;
+            // m_Window = nullptr;
         }
         glfwTerminate();
     }