return table details in docs

inc/init/init.context.lua

@@ -8,7 +8,16 @@ Context = {}
 
 --- Gets initial data for Context.
 --- @within Context
--- @return table Initial context data.
+--- @return result table Initial context data.
+--- @return result.current_menu_item number Index of the currently selected menu item.
+--- @return result.splash_timer number Remaining frames for the splash screen timer.
+--- @return result.popup table Popup window state. Contains: `show` (boolean) whether popup is visible, `content` (table) array of strings to display.
+--- @return result.game_in_progress boolean Whether a game is currently active.
+--- @return result.minigame_ddr table DDR minigame state (see Minigame.get_default_ddr).
+--- @return result.minigame_button_mash table Button mash minigame state (see Minigame.get_default_button_mash).
+--- @return result.minigame_rhythm table Rhythm minigame state (see Minigame.get_default_rhythm).
+--- @return result.meters table Meter values (see Meter.get_initial).
+--- @return result.game table Current game progress state. Contains: `current_screen` (string) active screen ID, `current_situation` (string|nil) active situation ID.
 function Context.initial_data()
   return {
     current_menu_item = 1,

inc/init/init.meter.lua

@@ -15,7 +15,13 @@ Meter.COLOR_BG = Config.colors.meter_bg
 
 --- Gets initial meter values.
 --- @within Meter
--- @return table A table of initial meter values.
+--- @return result table A table of initial meter values.
+--- @return result.ism number Initial ISM meter value.
+--- @return result.wpm number Initial WPM meter value.
+--- @return result.bm number Initial BM meter value.
+--- @return result.combo number Current combo count.
+--- @return result.combo_timer number Frames since last combo action.
+--- @return result.hidden boolean Whether meters are hidden.
 function Meter.get_initial()
   return {
     ism = METER_DEFAULT,
@@ -41,14 +47,14 @@ end
 
 --- Gets max meter value.
 --- @within Meter
--- @return number The maximum meter value.
+--- @return number The maximum meter value.
 function Meter.get_max()
   return METER_MAX
 end
 
 --- Gets combo multiplier.
 --- @within Meter
--- @return number The current combo multiplier.
+--- @return number The current combo multiplier.
 function Meter.get_combo_multiplier()
   if not Context or not Context.meters then return 1 end
   local combo = Context.meters.combo
@@ -75,8 +81,8 @@ end
 
 --- Adds amount to a meter.
 --- @within Meter
--- @param key string The meter key (e.g., "wpm", "ism", "bm").
--- @param amount number The amount to add.
+--- @param key string The meter key (e.g., "wpm", "ism", "bm").
+--- @param amount number The amount to add.
 function Meter.add(key, amount)
   if not Context or not Context.meters then return end
   local m = Context.meters

inc/init/init.minigame.lua

@@ -3,9 +3,9 @@
 
 --- Applies parameters to defaults
 --- @within Minigame
--- @param defaults table The default configuration table.
--- @param params table The parameters to apply.
--- @return table The updated configuration table.
+--- @param defaults table The default configuration table.
+--- @param params table The parameters to apply.
+--- @return table The updated configuration table.
 local function apply_params(defaults, params)
   if not params then return defaults end
   for k, v in pairs(params) do
@@ -16,7 +16,32 @@ end
 
 --- Gets default DDR minigame configuration.
 --- @within Minigame
--- @return table The default DDR minigame configuration.
+--- @return result table The default DDR minigame configuration.
+--- @return result.bar_fill number Current fill level of the progress bar.
+--- @return result.max_fill number Maximum fill value to win.
+--- @return result.fill_per_hit number Fill gained per successful hit.
+--- @return result.miss_penalty number Fill lost per miss.
+--- @return result.bar_x number Progress bar X position.
+--- @return result.bar_y number Progress bar Y position.
+--- @return result.bar_width number Progress bar width.
+--- @return result.bar_height number Progress bar height.
+--- @return result.arrow_size number Size of arrow sprites.
+--- @return result.arrow_spawn_timer number Timer for arrow spawning.
+--- @return result.arrow_spawn_interval number Frames between arrow spawns.
+--- @return result.arrow_fall_speed number Speed of falling arrows.
+--- @return result.arrows table Array of active arrow objects.
+--- @return result.target_y number Y position of the target line.
+--- @return result.target_arrows table Array of target arrow positions. Each entry has: `dir` (string) arrow direction, `x` (number) X position.
+--- @return result.hit_threshold number Pixel distance for a valid hit.
+--- @return result.button_pressed_timers table Per-button press animation timers.
+--- @return result.button_press_duration number Duration of button press animation.
+--- @return result.input_cooldowns table Per-direction cooldown timers (left, down, up, right).
+--- @return result.input_cooldown_duration number Frames of input cooldown.
+--- @return result.frame_counter number Global frame counter.
+--- @return result.current_song table Currently playing song data.
+--- @return result.pattern_index number Current index in song pattern.
+--- @return result.use_pattern boolean Whether to use song pattern for spawning.
+--- @return result.return_window string Window ID to return to after minigame.
 function Minigame.get_default_ddr()
   local arrow_size = 12
   local arrow_spacing = 30
@@ -58,7 +83,22 @@ end
 
 --- Gets default button mash minigame configuration.
 --- @within Minigame
--- @return table The default button mash minigame configuration.
+--- @return result table The default button mash minigame configuration.
+--- @return result.bar_fill number Current fill level of the progress bar.
+--- @return result.max_fill number Maximum fill value to win.
+--- @return result.fill_per_press number Fill gained per button press.
+--- @return result.base_degradation number Base rate of bar degradation per frame.
+--- @return result.degradation_multiplier number Multiplier for degradation scaling.
+--- @return result.button_pressed_timer number Button press animation timer.
+--- @return result.button_press_duration number Duration of button press animation.
+--- @return result.return_window string Window ID to return to after minigame.
+--- @return result.bar_x number Progress bar X position.
+--- @return result.bar_y number Progress bar Y position.
+--- @return result.bar_width number Progress bar width.
+--- @return result.bar_height number Progress bar height.
+--- @return result.button_x number Button indicator X position.
+--- @return result.button_y number Button indicator Y position.
+--- @return result.button_size number Button indicator size.
 function Minigame.get_default_button_mash()
   return {
     bar_fill = 0,
@@ -81,7 +121,29 @@ end
 
 --- Gets default rhythm minigame configuration.
 --- @within Minigame
--- @return table The default rhythm minigame configuration.
+--- @return result table The default rhythm minigame configuration.
+--- @return result.line_position number Current position of the moving line (0-1).
+--- @return result.line_speed number Speed of the moving line per frame.
+--- @return result.line_direction number Direction of line movement (1 or -1).
+--- @return result.target_center number Center of the target zone (0-1).
+--- @return result.target_width number Current width of the target zone.
+--- @return result.initial_target_width number Starting width of the target zone.
+--- @return result.min_target_width number Minimum width the target zone can shrink to.
+--- @return result.target_shrink_rate number Multiplier applied to target width after each hit.
+--- @return result.score number Current score.
+--- @return result.max_score number Score needed to win.
+--- @return result.button_pressed_timer number Button press animation timer.
+--- @return result.button_press_duration number Duration of button press animation.
+--- @return result.return_window string Window ID to return to after minigame.
+--- @return result.bar_x number Progress bar X position.
+--- @return result.bar_y number Progress bar Y position.
+--- @return result.bar_width number Progress bar width.
+--- @return result.bar_height number Progress bar height.
+--- @return result.button_x number Button indicator X position.
+--- @return result.button_y number Button indicator Y position.
+--- @return result.button_size number Button indicator size.
+--- @return result.press_cooldown number Current cooldown timer.
+--- @return result.press_cooldown_duration number Frames of press cooldown.
 function Minigame.get_default_rhythm()
   return {
     line_position = 0,
@@ -111,86 +173,86 @@ end
 
 --- Configures DDR minigame.
 --- @within Minigame
--- @param params table Optional parameters to override defaults (see Minigame.get_default_ddr).
--- @param[opt] params.bar_fill number Current fill level of the progress bar.
--- @param[opt] params.max_fill number Maximum fill value to win.
--- @param[opt] params.fill_per_hit number Fill gained per successful hit.
--- @param[opt] params.miss_penalty number Fill lost per miss.
--- @param[opt] params.bar_x number Progress bar X position.
--- @param[opt] params.bar_y number Progress bar Y position.
--- @param[opt] params.bar_width number Progress bar width.
--- @param[opt] params.bar_height number Progress bar height.
--- @param[opt] params.arrow_size number Size of arrow sprites.
--- @param[opt] params.arrow_spawn_timer number Timer for arrow spawning.
--- @param[opt] params.arrow_spawn_interval number Frames between arrow spawns.
--- @param[opt] params.arrow_fall_speed number Speed of falling arrows.
--- @param[opt] params.arrows table Array of active arrow objects.
--- @param[opt] params.target_y number Y position of the target line.
--- @param[opt] params.target_arrows table Array of target arrow positions with dir and x fields.
--- @param[opt] params.hit_threshold number Pixel distance for a valid hit.
--- @param[opt] params.button_pressed_timers table Per-button press animation timers.
--- @param[opt] params.button_press_duration number Duration of button press animation.
--- @param[opt] params.input_cooldowns table Per-direction cooldown timers (left, down, up, right).
--- @param[opt] params.input_cooldown_duration number Frames of input cooldown.
--- @param[opt] params.frame_counter number Global frame counter.
--- @param[opt] params.current_song table Currently playing song data.
--- @param[opt] params.pattern_index number Current index in song pattern.
--- @param[opt] params.use_pattern boolean Whether to use song pattern for spawning.
--- @param[opt] params.return_window string Window ID to return to after minigame.
--- @return table The configured DDR minigame state.
+--- @param params table Optional parameters to override defaults (see Minigame.get_default_ddr).
+--- @param[opt] params.bar_fill number Current fill level of the progress bar.
+--- @param[opt] params.max_fill number Maximum fill value to win.
+--- @param[opt] params.fill_per_hit number Fill gained per successful hit.
+--- @param[opt] params.miss_penalty number Fill lost per miss.
+--- @param[opt] params.bar_x number Progress bar X position.
+--- @param[opt] params.bar_y number Progress bar Y position.
+--- @param[opt] params.bar_width number Progress bar width.
+--- @param[opt] params.bar_height number Progress bar height.
+--- @param[opt] params.arrow_size number Size of arrow sprites.
+--- @param[opt] params.arrow_spawn_timer number Timer for arrow spawning.
+--- @param[opt] params.arrow_spawn_interval number Frames between arrow spawns.
+--- @param[opt] params.arrow_fall_speed number Speed of falling arrows.
+--- @param[opt] params.arrows table Array of active arrow objects.
+--- @param[opt] params.target_y number Y position of the target line.
+--- @param[opt] params.target_arrows table Array of target arrow positions with dir and x fields.
+--- @param[opt] params.hit_threshold number Pixel distance for a valid hit.
+--- @param[opt] params.button_pressed_timers table Per-button press animation timers.
+--- @param[opt] params.button_press_duration number Duration of button press animation.
+--- @param[opt] params.input_cooldowns table Per-direction cooldown timers (left, down, up, right).
+--- @param[opt] params.input_cooldown_duration number Frames of input cooldown.
+--- @param[opt] params.frame_counter number Global frame counter.
+--- @param[opt] params.current_song table Currently playing song data.
+--- @param[opt] params.pattern_index number Current index in song pattern.
+--- @param[opt] params.use_pattern boolean Whether to use song pattern for spawning.
+--- @param[opt] params.return_window string Window ID to return to after minigame.
+--- @return result table The configured DDR minigame state (see Minigame.get_default_ddr for fields).
 function Minigame.configure_ddr(params)
   return apply_params(Minigame.get_default_ddr(), params)
 end
 
 --- Configures button mash minigame.
 --- @within Minigame
--- @param params table Optional parameters to override defaults (see Minigame.get_default_button_mash).
--- @param[opt] params.bar_fill number Current fill level of the progress bar.
--- @param[opt] params.max_fill number Maximum fill value to win.
--- @param[opt] params.fill_per_press number Fill gained per button press.
--- @param[opt] params.base_degradation number Base rate of bar degradation per frame.
--- @param[opt] params.degradation_multiplier number Multiplier for degradation scaling.
--- @param[opt] params.button_pressed_timer number Button press animation timer.
--- @param[opt] params.button_press_duration number Duration of button press animation.
--- @param[opt] params.return_window string Window ID to return to after minigame.
--- @param[opt] params.bar_x number Progress bar X position.
--- @param[opt] params.bar_y number Progress bar Y position.
--- @param[opt] params.bar_width number Progress bar width.
--- @param[opt] params.bar_height number Progress bar height.
--- @param[opt] params.button_x number Button indicator X position.
--- @param[opt] params.button_y number Button indicator Y position.
--- @param[opt] params.button_size number Button indicator size.
--- @return table The configured button mash minigame state.
+--- @param params table Optional parameters to override defaults (see Minigame.get_default_button_mash).
+--- @param[opt] params.bar_fill number Current fill level of the progress bar.
+--- @param[opt] params.max_fill number Maximum fill value to win.
+--- @param[opt] params.fill_per_press number Fill gained per button press.
+--- @param[opt] params.base_degradation number Base rate of bar degradation per frame.
+--- @param[opt] params.degradation_multiplier number Multiplier for degradation scaling.
+--- @param[opt] params.button_pressed_timer number Button press animation timer.
+--- @param[opt] params.button_press_duration number Duration of button press animation.
+--- @param[opt] params.return_window string Window ID to return to after minigame.
+--- @param[opt] params.bar_x number Progress bar X position.
+--- @param[opt] params.bar_y number Progress bar Y position.
+--- @param[opt] params.bar_width number Progress bar width.
+--- @param[opt] params.bar_height number Progress bar height.
+--- @param[opt] params.button_x number Button indicator X position.
+--- @param[opt] params.button_y number Button indicator Y position.
+--- @param[opt] params.button_size number Button indicator size.
+--- @return result table The configured button mash minigame state (see Minigame.get_default_button_mash for fields).
 function Minigame.configure_button_mash(params)
   return apply_params(Minigame.get_default_button_mash(), params)
 end
 
 --- Configures rhythm minigame.
 --- @within Minigame
--- @param params table Optional parameters to override defaults (see Minigame.get_default_rhythm).
--- @param[opt] params.line_position number Current position of the moving line (0-1).
--- @param[opt] params.line_speed number Speed of the moving line per frame.
--- @param[opt] params.line_direction number Direction of line movement (1 or -1).
--- @param[opt] params.target_center number Center of the target zone (0-1).
--- @param[opt] params.target_width number Current width of the target zone.
--- @param[opt] params.initial_target_width number Starting width of the target zone.
--- @param[opt] params.min_target_width number Minimum width the target zone can shrink to.
--- @param[opt] params.target_shrink_rate number Multiplier applied to target width after each hit.
--- @param[opt] params.score number Current score.
--- @param[opt] params.max_score number Score needed to win.
--- @param[opt] params.button_pressed_timer number Button press animation timer.
--- @param[opt] params.button_press_duration number Duration of button press animation.
--- @param[opt] params.return_window string Window ID to return to after minigame.
--- @param[opt] params.bar_x number Progress bar X position.
--- @param[opt] params.bar_y number Progress bar Y position.
--- @param[opt] params.bar_width number Progress bar width.
--- @param[opt] params.bar_height number Progress bar height.
--- @param[opt] params.button_x number Button indicator X position.
--- @param[opt] params.button_y number Button indicator Y position.
--- @param[opt] params.button_size number Button indicator size.
--- @param[opt] params.press_cooldown number Current cooldown timer.
--- @param[opt] params.press_cooldown_duration number Frames of press cooldown.
--- @return table The configured rhythm minigame state.
+--- @param params table Optional parameters to override defaults (see Minigame.get_default_rhythm).
+--- @param[opt] params.line_position number Current position of the moving line (0-1).
+--- @param[opt] params.line_speed number Speed of the moving line per frame.
+--- @param[opt] params.line_direction number Direction of line movement (1 or -1).
+--- @param[opt] params.target_center number Center of the target zone (0-1).
+--- @param[opt] params.target_width number Current width of the target zone.
+--- @param[opt] params.initial_target_width number Starting width of the target zone.
+--- @param[opt] params.min_target_width number Minimum width the target zone can shrink to.
+--- @param[opt] params.target_shrink_rate number Multiplier applied to target width after each hit.
+--- @param[opt] params.score number Current score.
+--- @param[opt] params.max_score number Score needed to win.
+--- @param[opt] params.button_pressed_timer number Button press animation timer.
+--- @param[opt] params.button_press_duration number Duration of button press animation.
+--- @param[opt] params.return_window string Window ID to return to after minigame.
+--- @param[opt] params.bar_x number Progress bar X position.
+--- @param[opt] params.bar_y number Progress bar Y position.
+--- @param[opt] params.bar_width number Progress bar width.
+--- @param[opt] params.bar_height number Progress bar height.
+--- @param[opt] params.button_x number Button indicator X position.
+--- @param[opt] params.button_y number Button indicator Y position.
+--- @param[opt] params.button_size number Button indicator size.
+--- @param[opt] params.press_cooldown number Current cooldown timer.
+--- @param[opt] params.press_cooldown_duration number Frames of press cooldown.
+--- @return result table The configured rhythm minigame state (see Minigame.get_default_rhythm for fields).
 function Minigame.configure_rhythm(params)
   return apply_params(Minigame.get_default_rhythm(), params)
 end