docs: add comments to UI components, HUD, and start screen (#65)

src/features/hud/components.rs

@@ -1,5 +1,6 @@
 use crate::{features::phase::components::TimerSettings, prelude::*};
 
+/// Markers for root UI nodes.
 #[derive(Component)]
 pub enum RootMarker {
     Status,
@@ -7,12 +8,14 @@ pub enum RootMarker {
     ShovelOverlay,
 }
 
+/// Markers for text components in the HUD.
 #[derive(Component)]
 pub enum TextType {
     Phase,
     Timer,
 }
 
+/// Markers for buttons in the HUD and settings.
 #[derive(Component)]
 pub enum ButtonType {
     SettingsOpen,
@@ -24,6 +27,7 @@ pub enum ButtonType {
     },
 }
 
+/// Types of timers available in the game.
 #[derive(Clone)]
 pub enum TimerType {
     Focus,
@@ -32,6 +36,7 @@ pub enum TimerType {
 }
 
 impl TimerSettings {
+    /// Changes the duration of a specific timer.
     pub fn change(&mut self, timer_type: &TimerType, amount: i32) {
         match timer_type {
             TimerType::Focus => {
@@ -59,6 +64,7 @@ impl TimerSettings {
     }
 }
 
+/// Input types for adjusting timer settings.
 #[derive(Component, Clone)]
 pub enum SettingsTimerInput {
     Minutes(TimerType),

src/features/hud/mod.rs

@@ -8,6 +8,7 @@ use ui::*;
 pub mod components;
 pub mod ui;
 
+/// Plugin for the Head-Up Display (HUD) containing status bars and buttons.
 pub struct HudPlugin;
 
 impl Plugin for HudPlugin {
@@ -27,6 +28,7 @@ impl Plugin for HudPlugin {
     }
 }
 
+/// Initializes the HUD UI.
 fn setup(mut commands: Commands, game_config: Res<GameConfig>, asset_server: Res<AssetServer>) {
     commands.spawn((
         RootMarker::Status,
@@ -126,6 +128,7 @@ fn setup(mut commands: Commands, game_config: Res<GameConfig>, asset_server: Res
     ));
 }
 
+/// Updates the status text (phase and timer).
 fn update_status(phase_res: Res<CurrentPhase>, mut text_query: Query<(&mut Text, &TextType)>) {
     if !phase_res.is_changed() {
         return;
@@ -140,6 +143,7 @@ fn update_status(phase_res: Res<CurrentPhase>, mut text_query: Query<(&mut Text,
     }
 }
 
+/// Handles HUD button interactions.
 fn buttons(
     mut commands: Commands,
     mut interaction_query: Query<(&Interaction, &ButtonType), (Changed<Interaction>, With<Button>)>,
@@ -181,12 +185,14 @@ fn buttons(
     }
 }
 
+/// Cleans up HUD resources.
 fn cleanup(mut commands: Commands, query: Query<Entity, With<RootMarker>>) {
     for entity in query.iter() {
         commands.entity(entity).despawn();
     }
 }
 
+/// Updates the timer settings display in the settings menu.
 fn update_timer_settings(
     timer_settings: ResMut<TimerSettings>,
     mut query: Query<(&SettingsTimerInput, &mut Text)>,
@@ -215,6 +221,7 @@ fn update_timer_settings(
     }
 }
 
+/// Updates the visibility of the shovel overlay based on inventory.
 fn update_shovel_overlay_visibility(
     inventory: Res<inventory::components::Inventory>,
     item_stacks: Query<&inventory::components::ItemStack>,

src/features/hud/ui/settings.rs

@@ -2,6 +2,7 @@ use super::super::components::*;
 use super::timer_settings::timer_settings;
 use crate::prelude::*;
 
+/// Spawns the settings popup.
 pub fn open_settings(commands: &mut Commands) {
     spawn_popup(
         commands,

src/features/hud/ui/timer_settings.rs

@@ -1,6 +1,7 @@
 use super::super::components::*;
 use crate::prelude::*;
 
+/// Creates a UI bundle for a specific timer setting.
 pub fn timer_settings(timer_type: TimerType) -> impl Bundle {
     (
         Node {

src/features/start_screen/components.rs

@@ -1,10 +1,12 @@
 use crate::prelude::*;
 
+/// Markers for main menu UI.
 #[derive(Component)]
 pub enum RootMarker {
     MainMenu,
 }
 
+/// Buttons in the main menu.
 #[derive(Component)]
 pub enum ButtonType {
     LoadGame,

src/features/start_screen/mod.rs

@@ -4,6 +4,7 @@ use components::*;
 
 pub mod components;
 
+/// Plugin for the main menu screen.
 pub struct StartScreenPlugin;
 
 impl Plugin for StartScreenPlugin {
@@ -14,6 +15,7 @@ impl Plugin for StartScreenPlugin {
     }
 }
 
+/// Spawns the main menu UI.
 fn setup(mut commands: Commands) {
     commands.spawn((
         RootMarker::MainMenu,
@@ -60,6 +62,7 @@ fn setup(mut commands: Commands) {
     ));
 }
 
+/// Handles main menu button interactions.
 fn menu(
     mut commands: Commands,
     mut next_state: ResMut<NextState<AppState>>,
@@ -84,6 +87,7 @@ fn menu(
     }
 }
 
+/// Cleans up main menu resources.
 fn cleanup(mut commands: Commands, query: Query<Entity, With<RootMarker>>) {
     for entity in query.iter() {
         commands.entity(entity).despawn();

src/features/ui/components.rs

@@ -1,5 +1,6 @@
 use crate::prelude::*;
 
+/// Event triggering a scroll action on an entity.
 #[derive(EntityEvent, Debug)]
 #[entity_event(propagate, auto_propagate)]
 pub struct Scroll {
@@ -7,6 +8,7 @@ pub struct Scroll {
     pub delta: Vec2,
 }
 
+/// Visual styles for buttons.
 #[derive(Component, Clone)]
 pub enum ButtonVariant {
     Primary,

src/features/ui/consts.rs

@@ -1,6 +1,10 @@
 use crate::prelude::*;
 
+/// Pixel height of a single scroll line.
 pub const LINE_HEIGHT: f32 = 21.0;
+/// Default background color for buttons.
 pub const NORMAL_BUTTON: Color = Color::srgb(0.15, 0.15, 0.15);
+/// Background color when hovering a button.
 pub const HOVERED_BUTTON: Color = Color::srgb(0.25, 0.25, 0.25);
+/// Background color when pressing a button.
 pub const PRESSED_BUTTON: Color = Color::srgb(0.35, 0.75, 0.35);

src/features/ui/messages.rs

@@ -1,4 +1,5 @@
 use crate::prelude::*;
 
+/// Message to close any open popup.
 #[derive(Message)]
 pub struct ClosePopupMessage;

src/features/ui/mod.rs

@@ -7,6 +7,7 @@ pub mod messages;
 pub mod ui;
 pub mod utils;
 
+/// Plugin for general UI behavior like scrolling and button states.
 pub struct UiPlugin;
 
 impl Plugin for UiPlugin {
@@ -20,6 +21,7 @@ impl Plugin for UiPlugin {
     }
 }
 
+/// Reads mouse wheel events and triggers scroll actions.
 fn scroll_events(
     mut mouse_wheel_reader: MessageReader<MouseWheel>,
     hover_map: Res<HoverMap>,
@@ -45,6 +47,7 @@ fn scroll_events(
     }
 }
 
+/// Updates scroll position based on scroll events.
 fn on_scroll_handler(
     mut scroll: On<components::Scroll>,
     mut query: Query<(&mut ScrollPosition, &Node, &ComputedNode)>,

src/features/ui/ui/button.rs

@@ -1,5 +1,6 @@
 use crate::prelude::*;
 
+/// Creates a standard button UI bundle.
 pub fn button<C, R>(
     button_type: impl Component,
     variant: ButtonVariant,
@@ -24,6 +25,7 @@ where
     )
 }
 
+/// Creates a rounded pill-shaped button UI bundle.
 pub fn pill_button<C, R>(
     button_type: impl Component,
     variant: ButtonVariant,
@@ -48,6 +50,7 @@ where
     )
 }
 
+/// Updates button colors based on interaction state.
 pub fn update_buttons(
     mut interaction_query: Query<
         (&Interaction, &ButtonVariant, &mut BackgroundColor),

src/features/ui/ui/flexbox.rs

@@ -1,5 +1,6 @@
 use crate::prelude::*;
 
+/// Trait for easy flexbox layout construction.
 pub trait Flexbox {
     fn hstack(spacing: Val) -> Self;
     fn vstack(spacing: Val) -> Self;

src/features/ui/ui/popups.rs

@@ -3,12 +3,15 @@ use bevy::ecs::relationship::RelatedSpawnerCommands;
 use super::super::messages::ClosePopupMessage;
 use crate::prelude::*;
 
+/// Marker for popup root nodes.
 #[derive(Component)]
 pub struct PopupRoot;
 
+/// Marker for the close button in a popup.
 #[derive(Component)]
 pub struct PopupCloseButton;
 
+/// Spawns a generic popup window.
 pub fn spawn_popup(
     commands: &mut Commands,
     root: impl Component,
@@ -68,6 +71,7 @@ pub fn spawn_popup(
         });
 }
 
+/// Spawns a context menu at a specific position.
 pub fn spawn_context_menu(
     commands: &mut Commands,
     root: impl Component,
@@ -93,6 +97,7 @@ pub fn spawn_context_menu(
         .with_children(child);
 }
 
+/// Handles closing popups via message or close button.
 pub fn handle_popup_close(
     mut commands: Commands,
     root_query: Query<Entity, With<PopupRoot>>,

src/features/ui/ui/texts.rs

@@ -1,5 +1,6 @@
 pub use crate::prelude::*;
 
+/// Creates a basic text bundle.
 pub fn text(content: impl Into<String>, size: f32, color: Color) -> (Text, TextFont, TextColor) {
     (
         Text::new(content),
@@ -8,6 +9,7 @@ pub fn text(content: impl Into<String>, size: f32, color: Color) -> (Text, TextF
     )
 }
 
+/// Creates a text bundle with an additional component attached.
 pub fn text_with_component(
     component: impl Component,
     content: impl Into<String>,

src/features/ui/utils.rs

@@ -1,6 +1,7 @@
 use crate::prelude::*;
 use bevy::window::PrimaryWindow;
 
+/// Checks if the cursor is hovering over any UI element.
 pub fn ui_blocks(
     window: Single<&Window, With<PrimaryWindow>>,
     cursor_pos: Vec2,