optimized and commented code

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

components/insa/include/common/Common.h

@@ -2,6 +2,20 @@
 
 #include <functional>
 
-enum class ButtonType { NONE, UP, DOWN, LEFT, RIGHT, SELECT, BACK };
+// Enumeration defining the different types of buttons available in the system
+// NONE represents no button pressed or an invalid button state
+enum class ButtonType { 
+    NONE,     // No button or invalid state
+    UP,       // Up directional button
+    DOWN,     // Down directional button  
+    LEFT,     // Left directional button
+    RIGHT,    // Right directional button
+    SELECT,   // Select/confirm button
+    BACK      // Back/cancel button
+};
 
-typedef std::function<void(uint8_t, ButtonType)> ButtonCallback;
+// Type alias for button event callback function
+// Parameters:
+//   - uint8_t: Button identifier or additional data
+//   - ButtonType: The type of button that was pressed
+typedef std::function<void(uint8_t, ButtonType)> ButtonCallback;

components/insa/include/common/PSMenu.h

@@ -7,35 +7,131 @@
 #include "Widget.h"
 #include "data/MenuItem.h"
 
+/**
+ * PSMenu - A menu widget class
+ *
+ * This class extends the Widget base class to provide a customizable menu system
+ * with various types of interactive menu items including text buttons, selections,
+ * number inputs, and toggles.
+ */
 class PSMenu : public Widget
 {
 public:
+    /**
+     * Constructor - Creates a new PSMenu instance
+     * @param options Pointer to menu configuration options
+     */
     explicit PSMenu(menu_options_t *options);
+
+    /**
+     * Destructor - Cleans up resources when menu is destroyed
+     */
     ~PSMenu() override;
 
+    /**
+     * Adds a text-based menu item (button) to the menu
+     * @param id Unique identifier for this menu item
+     * @param text Display text shown on the menu
+     * @param callback Function to call when this item is selected
+     */
     void addText(uint8_t id, const std::string &text, const ButtonCallback &callback);
+
+    /**
+     * Adds a selection menu item (dropdown/list selection)
+     * @param id Unique identifier for this menu item
+     * @param text Display text/label for the selection
+     * @param value Reference to current selected value (will be modified)
+     * @param values Vector of all available options to choose from
+     * @param callback Function to call when selection changes
+     */
     void addSelection(uint8_t id, const std::string &text, std::string &value, const std::vector<std::string>& values,
                       const ButtonCallback &callback);
+
+    /**
+     * Adds a numeric input menu item
+     * @param id Unique identifier for this menu item
+     * @param text Display text/label for the number input
+     * @param value Reference to current numeric value as string (will be modified)
+     * @param callback Function to call when value changes
+     */
     void addNumber(uint8_t id, const std::string &text, std::string &value, const ButtonCallback &callback);
+
+    /**
+     * Adds a toggle/checkbox menu item
+     * @param id Unique identifier for this menu item
+     * @param text Display text/label for the toggle
+     * @param selected Current state of the toggle (true = on, false = off)
+     * @param callback Function to call when toggle state changes
+     */
     void addToggle(uint8_t id, const std::string &text, bool selected, const ButtonCallback &callback);
 
 private:
+    /**
+     * Renders the entire menu on screen
+     * Override from Widget base class
+     */
     void render() override;
+
+    /**
+     * Handles button press events from the controller/input system
+     * @param button The button that was pressed
+     * Override from Widget base class
+     */
     void onButtonClicked(uint8_t button) override;
 
+    // Navigation event handlers
+    /**
+     * Handles down arrow/stick input - moves selection down
+     */
     void onPressedDown();
+
+    /**
+     * Handles up arrow/stick input - moves selection up
+     */
     void onPressedUp();
+
+    /**
+     * Handles left arrow/stick input - decreases value for current item
+     */
     void onPressedLeft() const;
+
+    /**
+     * Handles right arrow/stick input - increases value for current item
+     */
     void onPressedRight() const;
+
+    /**
+     * Handles select/confirm button (X on PlayStation controller)
+     */
     void onPressedSelect() const;
+
+    /**
+     * Handles back/cancel button (Circle on PlayStation controller)
+     */
     void onPressedBack() const;
 
+    // Rendering helper methods
+    /**
+     * Draws the scroll bar indicating position in long menus
+     */
     void drawScrollBar() const;
+
+    /**
+     * Draws the selection highlight box around current menu item
+     */
     void drawSelectionBox() const;
 
+    /**
+     * Renders an individual menu item widget
+     * @param item Pointer to the menu item to render
+     * @param font Font to use for rendering text
+     * @param x X coordinate for rendering position
+     * @param y Y coordinate for rendering position
+     */
     void renderWidget(const MenuItem *item, const uint8_t *font, int x, int y) const;
 
-    size_t m_selected_item = 0;
-    std::vector<MenuItem> m_items;
-    menu_options_t *m_options;
+    // Member variables
+    size_t m_selected_item = 0;        ///< Index of currently selected menu item
+    std::vector<MenuItem> m_items;     ///< Collection of all menu items
+    menu_options_t *m_options;         ///< Pointer to menu configuration options
 };

components/insa/include/common/ScrollBar.h

@@ -3,22 +3,50 @@
 #include "MenuOptions.h"
 #include "Widget.h"
 
+/**
+ * ScrollBar class that represents a vertical scrollbar widget
+ * Inherits from Widget base class and provides scrolling functionality
+ */
 class ScrollBar final : public Widget
 {
-  public:
+public:
+    /**
+     * Constructor for ScrollBar
+     * @param options Pointer to menu options configuration
+     * @param x X coordinate position of the scrollbar
+     * @param y Y coordinate position of the scrollbar
+     * @param width Width of the scrollbar
+     * @param height Height of the scrollbar
+     */
     ScrollBar(const menu_options_t *options, size_t x, size_t y, size_t width, size_t height);
+
+    /**
+     * Renders the scrollbar to the screen
+     * Overrides the base Widget render method
+     */
     void render() override;
+
+    /**
+     * Updates the scrollbar state with new values
+     * @param value Current scroll position value
+     * @param max Maximum scroll value
+     * @param min Minimum scroll value (default: 0)
+     */
     void refresh(size_t value, size_t max, size_t min = 0);
 
-  private:
-    size_t m_x;
-    size_t m_y;
-    size_t m_width;
-    size_t m_height;
-    size_t m_value;
-    size_t m_max;
-    size_t m_min;
+private:
+    // Position and dimensions
+    size_t m_x;      // X coordinate of the scrollbar
+    size_t m_y;      // Y coordinate of the scrollbar
+    size_t m_width;  // Width of the scrollbar
+    size_t m_height; // Height of the scrollbar
 
-    size_t m_thumbHeight;
-    size_t m_thumbY;
-};
+    // Scroll state values
+    size_t m_value;  // Current scroll position
+    size_t m_max;    // Maximum scroll value
+    size_t m_min;    // Minimum scroll value
+
+    // Calculated thumb properties
+    size_t m_thumbHeight; // Height of the scroll thumb
+    size_t m_thumbY;      // Y position of the scroll thumb
+};

components/insa/include/common/Widget.h

@@ -1,22 +1,52 @@
 #pragma once
 
-#include <cstdint>
-
 #include "u8g2.h"
 
+/**
+ * Base class for UI widgets that can be rendered and interact with user input.
+ * This class provides a common interface for all widgets in the system.
+ */
 class Widget
 {
 public:
+    /**
+     * Constructs a widget with the given u8g2 display context.
+     * @param u8g2 Pointer to the u8g2 display context used for rendering
+     */
     explicit Widget(u8g2_t *u8g2);
 
+    /**
+     * Virtual destructor to ensure proper cleanup of derived classes.
+     */
     virtual ~Widget() = default;
 
+    /**
+     * Updates the widget's internal state based on elapsed time.
+     * This method is called once per frame to handle animations,
+     * timers, or other time-dependent behavior.
+     * @param dt Delta time in milliseconds since last update
+     */
     virtual void update(uint64_t dt);
 
+    /**
+     * Renders the widget to the display.
+     * This method should be overridden by derived classes to implement
+     * their specific rendering logic using the u8g2 display context.
+     */
     virtual void render();
 
+    /**
+     * Handles button click events.
+     * This method is called when a button is pressed and allows
+     * the widget to respond to user input.
+     * @param button The identifier of the button that was clicked
+     */
     virtual void onButtonClicked(uint8_t button);
 
 protected:
+    /**
+     * Pointer to the u8g2 display context used for rendering operations.
+     * This provides access to drawing functions for text, graphics, and other UI elements.
+     */
     u8g2_t *u8g2;
 };