more comments

Signed-off-by: Peter Siegmund <developer@mars3142.org>

components/insa/include/common/InactivityTracker.h

@@ -1,20 +1,193 @@
+/**
+ * @file InactivityTracker.h
+ * @brief Inactivity tracking system for monitoring user interaction timeouts
+ * @details This header defines the InactivityTracker class which monitors user
+ *          activity and triggers timeout callbacks when the system remains inactive
+ *          for a specified duration. It provides essential functionality for power
+ *          management, screen savers, and automatic system state transitions.
+ * @author System Control Team
+ * @date 2025-06-20
+ */
+
 #pragma once
 
-#include <cstdint>
 #include <functional>
 
+/**
+ * @class InactivityTracker
+ * @brief Activity monitoring class for detecting user inactivity periods
+ * @details This class provides a robust mechanism for tracking user activity and
+ *          triggering automatic actions when the system remains inactive for a
+ *          configured timeout period. It is commonly used for implementing power
+ *          saving features, automatic screen savers, session timeouts, and other
+ *          time-based system behaviors.
+ * 
+ * The InactivityTracker operates by:
+ * - Continuously tracking elapsed time since the last user activity
+ * - Comparing elapsed time against a configurable timeout threshold
+ * - Executing a callback function when the timeout is reached
+ * - Providing methods to reset the timer when activity is detected
+ * - Supporting enable/disable functionality for dynamic control
+ * 
+ * Key features include:
+ * - Configurable timeout duration in milliseconds
+ * - Custom callback function execution on timeout
+ * - Activity reset capability for responsive user interaction
+ * - Enable/disable control for conditional monitoring
+ * - High-resolution timing support using 64-bit millisecond precision
+ * 
+ * Common use cases:
+ * - Screen saver activation after idle periods
+ * - Automatic screen dimming or shutdown
+ * - Session timeout management
+ * - Power management and battery conservation
+ * - User interface state transitions
+ * - Security lockout after inactivity
+ * 
+ * The class is designed to be lightweight and efficient, suitable for
+ * real-time applications where precise timing and minimal overhead are important.
+ * 
+ * @note This class requires regular update calls to function properly.
+ * @note The timeout callback is executed once per timeout period and will
+ *       not repeat until the tracker is reset and times out again.
+ * 
+ * @see Widget for integration with UI components
+ * @see Menu for menu timeout implementations
+ */
 class InactivityTracker
 {
   public:
+    /**
+     * @brief Constructs an InactivityTracker with specified timeout and callback
+     * @param timeoutMs Timeout duration in milliseconds before triggering callback
+     * @param onTimeout Callback function to execute when timeout is reached
+     * 
+     * @pre timeoutMs must be greater than 0 for meaningful timeout behavior
+     * @pre onTimeout must be a valid callable function object
+     * @post InactivityTracker is initialized, enabled, and ready for activity monitoring
+     * 
+     * @details The constructor initializes the inactivity tracker with the specified
+     *          timeout duration and callback function. The tracker starts in an enabled
+     *          state with zero elapsed time, ready to begin monitoring user activity.
+     * 
+     * The timeout callback function can perform any necessary actions when inactivity
+     * is detected, such as:
+     * - Activating screen savers or power saving modes
+     * - Transitioning to different application states
+     * - Logging inactivity events
+     * - Triggering security lockouts
+     * - Initiating automatic save operations
+     * 
+     * @note The tracker begins monitoring immediately upon construction.
+     * @note The callback function should be lightweight to avoid blocking
+     *       the main application thread during timeout processing.
+     * 
+     * Example usage:
+     * @code
+     * auto tracker = InactivityTracker(30000, []() {
+     *     // Activate screen saver after 30 seconds of inactivity
+     *     activateScreenSaver();
+     * });
+     * @endcode
+     */
     InactivityTracker(uint64_t timeoutMs, std::function<void()> onTimeout);
 
+    /**
+     * @brief Updates the inactivity timer and checks for timeout conditions
+     * @param dt Delta time in milliseconds since the last update call
+     * 
+     * @details This method must be called regularly (typically every frame) to
+     *          maintain accurate timing and timeout detection. It increments the
+     *          elapsed time counter and triggers the timeout callback when the
+     *          configured timeout duration is reached.
+     * 
+     * The update process:
+     * - Adds the delta time to the elapsed time counter (if enabled)
+     * - Compares elapsed time against the configured timeout threshold
+     * - Executes the timeout callback if the threshold is exceeded
+     * - Continues monitoring until reset or disabled
+     * 
+     * @note This method should be called consistently from the main application
+     *       loop to ensure accurate timing behavior.
+     * @note The timeout callback is executed only once per timeout period.
+     * @note If the tracker is disabled, elapsed time is not updated.
+     * 
+     * @see reset() to restart the inactivity timer
+     * @see setEnabled() to control monitoring state
+     */
     void update(uint64_t dt);
+
+    /**
+     * @brief Resets the inactivity timer to indicate recent user activity
+     * 
+     * @details This method should be called whenever user activity is detected
+     *          to restart the inactivity timeout period. It resets the elapsed
+     *          time counter to zero, effectively extending the timeout deadline
+     *          and preventing timeout callback execution until the full timeout
+     *          duration elapses again without further resets.
+     * 
+     * Common scenarios for calling reset():
+     * - Button presses or key events
+     * - Mouse movement or touch input
+     * - Menu navigation or selection actions
+     * - Any user interface interaction
+     * - System activity that should extend the timeout
+     * 
+     * @post Elapsed time is reset to zero, restarting the timeout period
+     * 
+     * @note This method can be called at any time, even when the tracker
+     *       is disabled, to prepare for future monitoring.
+     * @note Frequent reset calls from active user interaction will prevent
+     *       timeout callback execution, which is the intended behavior.
+     * 
+     * Example usage:
+     * @code
+     * void onButtonPress() {
+     *     tracker.reset(); // User activity detected, restart timeout
+     *     // Handle button press...
+     * }
+     * @endcode
+     */
     void reset();
+
+    /**
+     * @brief Enables or disables inactivity monitoring
+     * @param enabled True to enable monitoring, false to disable
+     * 
+     * @details This method controls whether the inactivity tracker actively
+     *          monitors for timeouts. When disabled, the elapsed time counter
+     *          is not updated during update() calls, effectively pausing the
+     *          timeout detection without losing the current elapsed time state.
+     * 
+     * Use cases for disabling:
+     * - Temporary suspension during system operations
+     * - Context-sensitive monitoring (disable in certain application states)
+     * - Power management control (disable during low-power modes)
+     * - User preference settings (allow users to disable timeouts)
+     * - Development and debugging (disable for testing)
+     * 
+     * When re-enabled, monitoring resumes from the current elapsed time state,
+     * allowing for seamless pause/resume functionality.
+     * 
+     * @post Monitoring state is updated according to the enabled parameter
+     * 
+     * @note Disabling the tracker does not reset the elapsed time counter.
+     * @note The timeout callback will not be executed while disabled, even
+     *       if the timeout threshold would otherwise be exceeded.
+     * @note Enabling/disabling can be done at any time during operation.
+     * 
+     * Example usage:
+     * @code
+     * tracker.setEnabled(false); // Pause monitoring during critical operation
+     * performCriticalOperation();
+     * tracker.setEnabled(true);  // Resume monitoring after completion
+     * @endcode
+     */
     void setEnabled(bool enabled);
 
   private:
-    uint64_t m_timeoutMs;
+    uint64_t m_timeoutMs;                ///< Timeout duration in milliseconds before callback execution
-    uint64_t m_elapsedTime;
+    uint64_t m_elapsedTime;              ///< Current elapsed time since last reset in milliseconds
-    bool m_enabled;
+    bool m_enabled;                      ///< Flag indicating whether monitoring is currently active
-    std::function<void()> m_onTimeout;
+    std::function<void()> m_onTimeout;   ///< Callback function executed when timeout threshold is reached
 };

components/insa/include/common/Widget.h

@@ -51,9 +51,58 @@ class Widget
      */
     virtual ~Widget() = default;
 
+    /**
+     * @brief Called when the widget becomes active or enters the foreground
+     * @details This method is invoked when the widget transitions from inactive
+     *          to active state, such as when it becomes the current screen or
+     *          gains focus. Derived classes can override this method to perform
+     *          initialization tasks, reset state, or prepare for user interaction.
+     *
+     * @note The base implementation is empty, allowing derived classes to override
+     *       only if entry behavior is needed.
+     * @note This method is typically called by the UI management system during
+     *       screen transitions or focus changes.
+     */
     virtual void enter();
+
+    /**
+     * @brief Called when the widget is temporarily paused or loses focus
+     * @details This method is invoked when the widget needs to suspend its
+     *          operations temporarily, such as when another widget takes focus
+     *          or the system enters a paused state. Derived classes can override
+     *          this method to pause animations, save state, or reduce resource usage.
+     *
+     * @note The base implementation is empty, allowing derived classes to override
+     *       only if pause behavior is needed.
+     * @note The widget should be prepared to resume from this state when resume() is called.
+     */
     virtual void pause();
+
+    /**
+     * @brief Called when the widget resumes from a paused state
+     * @details This method is invoked when the widget transitions from paused
+     *          to active state, typically after a previous pause() call. Derived
+     *          classes can override this method to restore animations, reload
+     *          resources, or continue interrupted operations.
+     *
+     * @note The base implementation is empty, allowing derived classes to override
+     *       only if resume behavior is needed.
+     * @note This method should restore the widget to the state it was in before pause() was called.
+     */
     virtual void resume();
+
+    /**
+     * @brief Called when the widget is being destroyed or exits the system
+     * @details This method is invoked when the widget is about to be removed
+     *          from the system or transitions to an inactive state permanently.
+     *          Derived classes can override this method to perform cleanup tasks,
+     *          save final state, or release resources that are not automatically freed.
+     *
+     * @note The base implementation is empty, allowing derived classes to override
+     *       only if exit behavior is needed.
+     * @note This method is called before the widget's destructor and provides
+     *       an opportunity for controlled shutdown of widget-specific resources.
+     */
     virtual void exit();
 
     /**

components/insa/include/ui/ScreenSaver.h

@@ -1,36 +1,397 @@
+/**
+ * @file ScreenSaver.h
+ * @brief Animated screensaver implementation with starfield effect
+ * @details This header defines the ScreenSaver class which provides an animated
+ *          starfield screensaver that activates during periods of user inactivity.
+ *          The screensaver displays moving stars to prevent screen burn-in while
+ *          providing visual feedback that the system is still active and responsive.
+ * @author System Control Team
+ * @date 2025-06-14
+ */
+
 #pragma once
 
 #include "MenuOptions.h"
 #include "common/Widget.h"
 #include <vector>
 
+/**
+ * @class ScreenSaver
+ * @brief Animated starfield screensaver widget for system idle periods
+ * @details This final class inherits from Widget and implements an interactive
+ *          screensaver featuring an animated starfield effect. The screensaver
+ *          activates automatically during periods of user inactivity to prevent
+ *          screen burn-in while maintaining visual indication of system activity.
+ * 
+ * The ScreenSaver class provides:
+ * - Dynamic starfield animation with pseudo-3D depth effect
+ * - Configurable star count and animation speed parameters
+ * - Automatic activation during idle periods
+ * - Immediate deactivation on any user input
+ * - Smooth star movement and regeneration system
+ * - Memory-efficient star management with object pooling
+ * 
+ * Key features include:
+ * - 3D-style starfield with depth-based speed variation
+ * - Continuous star recycling for infinite animation
+ * - Responsive user input handling for immediate exit
+ * - Optimized rendering for smooth animation performance
+ * - Configurable animation parameters for different visual effects
+ * 
+ * The starfield effect simulates movement through space by moving stars
+ * from the center outward at speeds proportional to their depth (z-coordinate).
+ * Stars that move beyond the screen boundaries are automatically recycled
+ * to new random positions, creating an infinite scrolling effect.
+ * 
+ * @note This class is marked as final and cannot be inherited from.
+ * @note The screensaver automatically exits on any button press, returning
+ *       control to the previous screen or main menu interface.
+ * 
+ * @see Widget for base widget functionality
+ * @see menu_options_t for configuration structure
+ * @see InactivityTracker for automatic screensaver activation
+ */
 class ScreenSaver final : public Widget
 {
   public:
+    /**
+     * @brief Constructs the screensaver with specified configuration
+     * @param options Pointer to menu options configuration structure
+     * 
+     * @pre options must not be nullptr and must remain valid for the screensaver's lifetime
+     * @pre options->u8g2 must be initialized and ready for graphics operations
+     * @pre Screen transition callbacks in options must be properly configured
+     * @post ScreenSaver is initialized with starfield ready for animation
+     * 
+     * @details The constructor initializes the screensaver by:
+     *          - Setting up the star field with initial random positions
+     *          - Configuring animation timing and speed parameters
+     *          - Preparing graphics context for efficient rendering
+     *          - Initializing the animation counter for smooth timing
+     *          - Allocating and positioning all star objects
+     * 
+     * During initialization, all stars are placed at random positions within
+     * the 3D space defined by Z_NEAR and Z_FAR constants. Each star receives
+     * random x, y coordinates and a z-depth that determines its movement speed
+     * and visual appearance. The animation system is prepared for immediate
+     * activation when the screensaver becomes active.
+     * 
+     * @note The screensaver does not take ownership of the options structure
+     *       and assumes it remains valid throughout the screensaver's lifetime.
+     * @note Initial star positions are randomized to create immediate visual
+     *       interest when the screensaver first activates.
+     * 
+     * @see Widget::Widget for base class construction details
+     * @see initStars for star field initialization process
+     */
     explicit ScreenSaver(menu_options_t *options);
 
+    /**
+     * @brief Updates the screensaver animation and star positions
+     * @param dt Delta time in milliseconds since the last update call
+     * 
+     * @details Overrides the base Widget update method to handle screensaver-specific
+     *          animation logic including:
+     *          - Advancing the animation counter for smooth timing control
+     *          - Updating individual star positions based on their speed and depth
+     *          - Moving stars outward from center based on their z-coordinate
+     *          - Recycling stars that move beyond screen boundaries
+     *          - Maintaining consistent animation frame rate regardless of system load
+     * 
+     * The update method implements the core starfield animation by:
+     * - Incrementing each star's position based on its depth-determined speed
+     * - Checking boundary conditions for stars moving off-screen
+     * - Resetting off-screen stars to new random positions near the center
+     * - Applying speed multipliers for smooth, consistent motion
+     * - Managing the animation counter for timing-dependent effects
+     * 
+     * Star movement calculation:
+     * - Stars closer to the camera (smaller z values) move faster
+     * - Movement speed is inversely proportional to z-coordinate
+     * - Stars maintain consistent outward direction from screen center
+     * - Boundary checking ensures smooth recycling without visual gaps
+     * 
+     * @note This method is called every frame while the screensaver is active
+     *       and must be efficient to maintain smooth 60+ FPS animation.
+     * @note The animation continues indefinitely until user input is received.
+     * 
+     * @see Widget::update for the base update interface
+     * @see resetStar for star recycling implementation
+     */
     void update(uint64_t dt) override;
+    
+    /**
+     * @brief Renders the animated starfield to the display
+     * 
+     * @details Overrides the base Widget render method to draw the animated starfield
+     *          effect. The rendering process includes:
+     *          - Clearing the display buffer for clean animation frames
+     *          - Calculating screen positions for each star based on 3D coordinates
+     *          - Applying perspective projection to simulate depth
+     *          - Drawing stars with size/brightness based on distance
+     *          - Optimizing drawing operations for smooth frame rates
+     * 
+     * The render method creates a convincing 3D starfield effect by:
+     * - Converting 3D star coordinates to 2D screen positions
+     * - Scaling star positions based on perspective projection
+     * - Varying star appearance (size, brightness) based on depth
+     * - Drawing only stars within the visible screen area
+     * - Using efficient drawing primitives for optimal performance
+     * 
+     * Rendering optimizations include:
+     * - Culling stars outside the visible area
+     * - Using simple pixel/point drawing for maximum speed
+     * - Minimizing graphics context switches
+     * - Batching drawing operations where possible
+     * 
+     * The visual effect simulates movement through a star field by:
+     * - Making distant stars appear smaller and dimmer
+     * - Scaling star positions relative to screen center
+     * - Creating smooth motion blur effects for fast-moving stars
+     * 
+     * @pre u8g2 display context must be initialized and ready for drawing
+     * @post Starfield animation frame is drawn to the display buffer
+     * 
+     * @note This method is called every frame and must be highly optimized
+     *       to maintain smooth animation performance on embedded systems.
+     * @note The visual design provides an engaging screensaver that clearly
+     *       indicates system activity while preventing screen burn-in.
+     * 
+     * @see Widget::render for the base render interface
+     */
     void render() override;
+    
+    /**
+     * @brief Handles user input to exit the screensaver immediately
+     * @param button The type of button that was pressed by the user
+     * 
+     * @details Overrides the base Widget button handling to provide immediate
+     *          screensaver exit functionality. Any button press while the screensaver
+     *          is active will:
+     *          - Immediately terminate the screensaver animation
+     *          - Return to the previous screen or main menu
+     *          - Reset any inactivity timers to prevent immediate reactivation
+     *          - Ensure responsive system behavior for user interaction
+     * 
+     * The method handles all button types uniformly since the screensaver should
+     * exit on any user input regardless of the specific button pressed. This
+     * ensures maximum responsiveness and intuitive behavior - users expect any
+     * interaction to wake the system from screensaver mode.
+     * 
+     * Button handling includes:
+     * - Immediate screensaver termination regardless of button type
+     * - Automatic transition back to the previous active screen
+     * - Inactivity timer reset to prevent immediate screensaver reactivation
+     * - Proper state cleanup to ensure system stability
+     * 
+     * @note This method ensures the screensaver never interferes with normal
+     *       system operation - any user input immediately restores full functionality.
+     * @note The screensaver exit process is designed to be instantaneous to
+     *       provide the most responsive user experience possible.
+     * 
+     * @see Widget::onButtonClicked for the base input handling interface
+     * @see ButtonType for available button input types
+     */
     void onButtonClicked(ButtonType button) override;
 
   private:
+    /**
+     * @struct Star
+     * @brief Individual star object structure for starfield animation
+     * @details Defines the properties and state of a single star in the animated
+     *          starfield. Each star maintains its position in 3D space and movement
+     *          characteristics needed for realistic animation and perspective effects.
+     * 
+     * The Star structure contains:
+     * - 3D spatial coordinates (x, y, z) for position tracking
+     * - Individual speed multiplier for varied animation effects
+     * - All data needed for perspective projection and movement calculation
+     * 
+     * Star coordinate system:
+     * - x, y: Screen-relative coordinates (can be negative for off-screen positioning)
+     * - z: Depth coordinate determining speed and perspective (Z_NEAR to Z_FAR range)
+     * - speed: Individual multiplier for varied star movement rates
+     * 
+     * @note This structure is designed for efficient memory usage and fast
+     *       mathematical operations during animation updates.
+     * @note All coordinates use float precision for smooth animation interpolation.
+     */
     struct Star
     {
-        float x;
+        float x;        ///< Horizontal position coordinate (screen-relative)
-        float y;
+        float y;        ///< Vertical position coordinate (screen-relative)  
-        float z;
+        float z;        ///< Depth coordinate (determines speed and perspective)
-        float speed;
+        float speed;    ///< Individual speed multiplier for animation variation
     };
 
+    /**
+     * @brief Pointer to menu options configuration structure
+     * @details Stores a reference to the menu configuration passed during construction.
+     *          Provides access to the display context for rendering operations and
+     *          screen transition callbacks for exiting the screensaver on user input.
+     * 
+     * The configuration enables:
+     * - Display context (u8g2) for starfield graphics rendering
+     * - Screen transition callbacks for returning to previous screen
+     * - System integration for proper screensaver lifecycle management
+     * 
+     * @note This pointer is not owned by the ScreenSaver and must remain valid
+     *       throughout the screensaver's lifetime.
+     */
     menu_options_t *m_options;
+    
+    /**
+     * @brief Animation timing counter for smooth frame rate control
+     * @details Tracks elapsed time for animation timing and frame rate calculations.
+     *          Used to ensure consistent star movement regardless of system load
+     *          variations and to provide smooth interpolation between animation frames.
+     * 
+     * The counter enables:
+     * - Frame rate independent animation timing
+     * - Smooth interpolation for fluid star movement
+     * - Consistent animation speed across different hardware platforms
+     * - Precise timing control for animation effects
+     */
     uint64_t m_animationCounter;
+    
+    /**
+     * @brief Vector container for all star objects in the starfield
+     * @details Manages the collection of Star objects that comprise the animated
+     *          starfield effect. The vector provides efficient storage and iteration
+     *          for the star animation system while maintaining good cache locality
+     *          for optimal performance during update and render operations.
+     * 
+     * The vector contains:
+     * - Fixed number of Star objects (NUM_STARS) allocated at initialization
+     * - Contiguous memory layout for efficient iteration during animation
+     * - Dynamic management capabilities for potential future enhancements
+     * 
+     * @note The vector size is fixed at construction to avoid memory allocations
+     *       during animation, ensuring consistent frame timing performance.
+     */
     std::vector<Star> m_stars;
 
+    /**
+     * @brief Total number of stars in the animated starfield
+     * @details Defines the constant number of star objects that will be created
+     *          and animated in the starfield effect. This value balances visual
+     *          richness with performance requirements for smooth animation.
+     * 
+     * The star count affects:
+     * - Visual density and richness of the starfield effect  
+     * - Performance requirements for update and rendering operations
+     * - Memory usage for star object storage
+     * - Overall visual impact of the screensaver
+     * 
+     * @note This value is tuned for optimal performance on target hardware
+     *       while providing an engaging visual effect.
+     */
     static constexpr int NUM_STARS = 10;
+    
+    /**
+     * @brief Global speed multiplier for star animation
+     * @details Controls the overall speed of star movement in the starfield animation.
+     *          This multiplier is applied to all star movement calculations to provide
+     *          consistent, smooth animation at an appropriate visual speed.
+     * 
+     * The speed multiplier affects:
+     * - Overall pace of the starfield animation
+     * - Visual impact and engagement level of the screensaver
+     * - Performance requirements for smooth animation
+     * - User perception of system responsiveness
+     * 
+     * @note This value is carefully tuned to provide engaging animation without
+     *       being distracting or causing motion sickness effects.
+     */
     static constexpr float SPEED_MULTIPLIER = 0.02f;
+    
+    /**
+     * @brief Near clipping plane for 3D starfield depth range
+     * @details Defines the closest distance (minimum z-coordinate) at which stars
+     *          can exist in the 3D starfield space. Stars closer than this distance
+     *          are considered too close to the viewer and are recycled to new positions.
+     * 
+     * The near plane affects:
+     * - Minimum depth for star positioning and recycling
+     * - Perspective calculation range for realistic depth effects
+     * - Star recycling triggers for continuous animation
+     * - Visual depth range of the starfield effect
+     * 
+     * @note This value works with Z_FAR to define the 3D space within which
+     *       stars exist and animate, creating realistic depth perception.
+     */
     static constexpr float Z_NEAR = 0.1f;
+    
+    /**
+     * @brief Far clipping plane for 3D starfield depth range  
+     * @details Defines the farthest distance (maximum z-coordinate) at which stars
+     *          can exist in the 3D starfield space. This establishes the back
+     *          boundary of the starfield volume and affects initial star placement.
+     * 
+     * The far plane affects:
+     * - Maximum depth for initial star positioning
+     * - Perspective calculation range for depth effects
+     * - Visual depth range and scale of the starfield
+     * - Initial star placement during system initialization
+     * 
+     * @note This value works with Z_NEAR to create a realistic 3D space
+     *       that provides convincing depth perception in the starfield animation.
+     */
     static constexpr float Z_FAR = 10.0f;
 
+    /**
+     * @brief Initializes all stars with random positions and properties
+     * @details Private helper method that sets up the initial starfield by placing
+     *          all stars at random positions within the defined 3D space. Called
+     *          during construction to prepare the starfield for immediate animation.
+     * 
+     * The initialization process:
+     * - Assigns random x, y coordinates within screen boundaries
+     * - Sets random z-depth within the Z_NEAR to Z_FAR range
+     * - Configures individual speed multipliers for animation variation
+     * - Ensures even distribution of stars throughout the 3D volume
+     * 
+     * Random placement creates:
+     * - Natural, non-uniform star distribution for realistic appearance
+     * - Varied star depths for convincing 3D perspective effects
+     * - Immediate visual interest when screensaver first activates
+     * - Foundation for smooth continuous animation
+     * 
+     * @note This method is called only once during construction to establish
+     *       the initial starfield state before animation begins.
+     * 
+     * @see resetStar for individual star repositioning during animation
+     */
     void initStars();
+    
+    /**
+     * @brief Resets a single star to a new random position for recycling
+     * @param star Reference to the Star object to be reset and repositioned
+     * 
+     * @details Private helper method that recycles individual stars that have
+     *          moved beyond the visible screen boundaries. This enables infinite
+     *          starfield animation by continuously introducing new stars while
+     *          removing those that are no longer visible.
+     * 
+     * The reset process:
+     * - Places the star at a new random position near the screen center
+     * - Assigns a new random depth (z-coordinate) for varied movement speed
+     * - Configures new speed multiplier for animation variation
+     * - Ensures smooth transition without visual discontinuities
+     * 
+     * Star recycling maintains:
+     * - Continuous starfield animation without visual gaps
+     * - Consistent star count throughout animation lifecycle
+     * - Varied star properties for natural, non-repetitive effects
+     * - Efficient memory usage through object reuse
+     * 
+     * @pre star parameter must be a valid Star object reference
+     * @post star object is repositioned with new random properties ready for animation
+     * 
+     * @note This method is called frequently during animation as stars move
+     *       off-screen and must be efficient to maintain smooth frame rates.
+     * @note The repositioning algorithm ensures stars appear to emerge naturally
+     *       from the center of the starfield for convincing 3D movement effects.
+     */
     void resetStar(Star &star);
 };

main/button_handling.h

@@ -1,10 +1,82 @@
+/**
+ * @file button_handling.h
+ * @brief Button input handling system for user interface interaction
+ * @details This header defines the button handling subsystem which manages
+ *          hardware button inputs, debouncing, interrupt processing, and
+ *          event queue management. It provides a robust foundation for
+ *          reliable user input processing in embedded applications.
+ * @author System Control Team
+ * @date 2025-06-20
+ */
+
 #pragma once
 
 #ifdef __cplusplus
 extern "C"
 {
 #endif
+    /**
+     * @brief Initializes the button handling subsystem and configures hardware
+     * 
+     * @details This function sets up the complete button handling infrastructure:
+     *          - GPIO configuration for button input pins with pull-up resistors
+     *          - Interrupt service routine installation for responsive input
+     *          - Debouncing timer creation and configuration
+     *          - FreeRTOS queue creation for button event buffering
+     *          - Button state tracking structure initialization
+     * 
+     * The function configures all defined button pins to trigger interrupts
+     * on both rising and falling edges, enabling detection of both press
+     * and release events. Each button uses a dedicated timer for debouncing
+     * to ensure reliable input processing even with mechanical switch bounce.
+     * 
+     * Button events are queued using FreeRTOS queues to ensure no input
+     * events are lost during high system activity periods. The queue-based
+     * approach also decouples interrupt handling from application processing.
+     * 
+     * @pre ESP32 GPIO and timer subsystems must be available and functional
+     * @pre FreeRTOS must be running and queue services available
+     * @post All button pins are configured and ready for input detection
+     * @post Button event queue is created and ready for event processing
+     * @post Interrupt handlers are installed and active
+     * 
+     * @note This function must be called during system initialization before
+     *       any button input processing is expected
+     * @note The function configures hardware-specific GPIO pins as defined
+     *       in the project configuration
+     * 
+     * @see cleanup_buttons() for proper resource cleanup
+     */
     void setup_buttons(void);
+
+    /**
+     * @brief Cleans up button handling resources and disables interrupts
+     * 
+     * @details This function performs complete cleanup of the button handling
+     *          subsystem by:
+     *          - Stopping and deleting all debouncing timers
+     *          - Removing GPIO interrupt handlers from all button pins
+     *          - Deleting the button event queue and freeing associated memory
+     *          - Resetting button state tracking structures
+     * 
+     * This cleanup function ensures proper resource management and prevents
+     * memory leaks when the button handling subsystem is no longer needed.
+     * It can be called during system shutdown or when reconfiguring the
+     * input handling subsystem.
+     * 
+     * @pre Button handling subsystem must have been previously initialized
+     * @post All button-related interrupts are disabled and handlers removed
+     * @post All timers are stopped and deleted, freeing system resources
+     * @post Button event queue is deleted and memory is released
+     * @post GPIO pins are returned to default state
+     * 
+     * @note This function should be called during system shutdown or when
+     *       button handling is no longer required
+     * @note After calling this function, setup_buttons() must be called
+     *       again before button input can be processed
+     * 
+     * @see setup_buttons() for initialization of the button handling system
+     */
     void cleanup_buttons(void);
 #ifdef __cplusplus
 }

main/setup.h

@@ -1,10 +1,70 @@
+/**
+ * @file setup.h
+ * @brief System initialization and main loop declarations for embedded application
+ * @details This header defines the core system initialization and main loop functions
+ *          required for embedded ESP32 applications. It provides the essential entry
+ *          points for hardware setup, system configuration, and continuous operation
+ *          management following standard embedded system patterns.
+ * @author System Control Team
+ * @date 2025-06-20
+ */
+
 #pragma once
 
 #ifdef __cplusplus
 extern "C"
 {
 #endif
+    /**
+     * @brief Initializes all system components and hardware peripherals
+     * 
+     * @details This function performs complete system initialization including:
+     *          - Hardware peripheral configuration (GPIO, I2C, SPI, etc.)
+     *          - Display system initialization
+     *          - Button and input device setup
+     *          - Communication subsystem initialization
+     *          - Memory and storage system preparation
+     *          - Application-specific component initialization
+     * 
+     * This function is called once during system startup before entering
+     * the main application loop. It ensures all required subsystems are
+     * properly configured and ready for operation.
+     * 
+     * @pre System must be in a clean startup state
+     * @post All system components are initialized and ready for operation
+     * 
+     * @note This function must complete successfully before loop() is called
+     * @note Any initialization failures should be handled gracefully with
+     *       appropriate error reporting or system recovery
+     * 
+     * @see loop() for the main application execution function
+     */
     void setup(void);
+
+    /**
+     * @brief Main application execution loop for continuous operation
+     * 
+     * @details This function contains the main application logic that executes
+     *          continuously after system initialization. It typically handles:
+     *          - User input processing and event handling
+     *          - Display updates and rendering operations
+     *          - System state management and transitions
+     *          - Background tasks and periodic operations
+     *          - Communication handling and data processing
+     *          - Power management and system monitoring
+     * 
+     * The loop function is called repeatedly in an infinite cycle, providing
+     * the main execution context for the embedded application. It should be
+     * designed to execute efficiently without blocking to maintain system
+     * responsiveness.
+     * 
+     * @note This function runs continuously and should not block indefinitely
+     * @note All operations within this function should be non-blocking or
+     *       use appropriate task scheduling for time-consuming operations
+     * @note The function should handle all runtime errors gracefully
+     * 
+     * @see setup() for system initialization before loop execution
+     */
     void loop(void);
 #ifdef __cplusplus
 }

src/Common.h

@@ -1,5 +1,60 @@
+/**
+ * @file Common.h
+ * @brief Common utility functions and window management for application framework
+ * @details This header defines common utility functions that are shared across
+ *          the application framework. It provides essential functionality for
+ *          window creation and management, serving as a bridge between the
+ *          application layer and the underlying windowing system.
+ * @author System Control Team
+ * @date 2025-06-20
+ */
+
 #pragma once
 
 #include "model/Window.h"
 
+/**
+ * @brief Creates a new window with specified title and dimensions
+ * @param title Null-terminated string containing the window title text
+ * @param width Window width in pixels
+ * @param height Window height in pixels
+ * @return Pointer to the newly created Window object, or nullptr on failure
+ * 
+ * @pre title must not be nullptr and should contain valid display text
+ * @pre width and height must be positive values within system display limits
+ * @post A new Window object is allocated and initialized with the specified parameters
+ * @post The returned Window pointer is ready for use with window management functions
+ * 
+ * @details This function creates a new Window instance with the specified
+ *          title and dimensions. It handles the underlying window system
+ *          initialization, memory allocation, and setup required to create
+ *          a functional window object.
+ * 
+ * The window creation process includes:
+ * - Memory allocation for the Window structure
+ * - Initialization of window properties (title, dimensions, state)
+ * - Registration with the window management system
+ * - Setup of default window behavior and event handling
+ * 
+ * The returned window pointer can be used with other window management
+ * functions to display content, handle events, and manage the window
+ * lifecycle. The caller is responsible for properly managing the window
+ * lifetime and ensuring proper cleanup when the window is no longer needed.
+ * 
+ * @note The returned pointer must be properly managed by the caller
+ * @note Window resources should be freed when no longer needed
+ * @note The title string is copied internally and can be safely modified
+ *       or freed after this function returns
+ * 
+ * @see Window class for window object interface and methods
+ * 
+ * Example usage:
+ * @code
+ * auto* window = CreateWindow("System Control", 800, 600);
+ * if (window != nullptr) {
+ *     // Use the window...
+ *     // Clean up when done
+ * }
+ * @endcode
+ */
 auto CreateWindow(const char *title, int width, int height) -> Window *;