more comments

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

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
 }