return table details in docs

inc/audio/audio.songs.lua

@@ -110,10 +110,10 @@ Songs = {
 
 --- Converts beats to frames.
 --- @within Songs
--- @param beat number The beat number.
+--- @param beat number The beat number.
--- @param bpm number Beats per minute.
+--- @param bpm number Beats per minute.
--- @param[opt] fps number Frames per second (default: 60).
+--- @param[opt] fps number Frames per second (default: 60).
--- @return number The corresponding frame number.
+--- @return number The corresponding frame number.
 function frame_from_beat(beat, bpm, fps)
   fps = fps or 60
   local seconds_per_beat = 60 / bpm
@@ -123,12 +123,14 @@ end
 
 --- Converts beat notation to frame pattern.
 --- @within Songs
--- @param beats table A table of beat data, e.g., {{1, "left"}, {2, "down"}}.
+--- @param beats table A table of beat data, e.g., {{1, "left"}, {2, "down"}}.
--- @param beats.1 number The beat number.
+--- @param beats.1 number The beat number.
--- @param beats.2 string Arrow direction ("left", "down", "up", or "right").
+--- @param beats.2 string Arrow direction ("left", "down", "up", or "right").
--- @param bpm number Beats per minute.
+--- @param bpm number Beats per minute.
--- @param[opt] fps number Frames per second (default: 60).
+--- @param[opt] fps number Frames per second (default: 60).
--- @return table The generated pattern.
+--- @return result table The generated pattern, an array of arrow spawn entries.
+--- @return result.frame number The frame number when the arrow should spawn.
+--- @return result.dir string Arrow direction ("left", "down", "up", or "right").
 function beats_to_pattern(beats, bpm, fps)
   fps = fps or 60
   local pattern = {}

inc/decision/decision.manager.lua

@@ -3,11 +3,11 @@ local _decisions = {}
 
 --- Registers a decision definition.
 --- @within Decision
--- @param decision table The decision data table.
+--- @param decision table The decision data table.
--- @param decision.id string Unique decision identifier.
+--- @param decision.id string Unique decision identifier.
--- @param decision.label string Display text for the decision.
+--- @param decision.label string Display text for the decision.
--- @param[opt] decision.condition function Returns true if decision is available. Defaults to always true.
+--- @param[opt] decision.condition function Returns true if decision is available. Defaults to always true.
--- @param[opt] decision.handle function Called when the decision is selected. Defaults to noop.
+--- @param[opt] decision.handle function Called when the decision is selected. Defaults to noop.
 function Decision.register(decision)
   if not decision or not decision.id then
     PopupWindow.show({"Error: Invalid decision object registered (missing id)!"})
@@ -32,24 +32,36 @@ end
 
 --- Gets a decision by ID.
 --- @within Decision
--- @param id string The ID of the decision.
+--- @param id string The ID of the decision.
--- @return table The decision table or nil.
+--- @return result table The decision table or nil.
+--- @return result.id string Unique decision identifier.
+--- @return result.label string Display text for the decision.
+--- @return result.condition function Returns true if decision is available.
+--- @return result.handle function Called when the decision is selected.
 function Decision.get_by_id(id)
   return _decisions[id]
 end
 
 --- Gets all registered decisions.
 --- @within Decision
--- @return table A table of all registered decisions.
+--- @return result table A table of all registered decisions, indexed by their IDs.
+--- @return result.id string Unique decision identifier.
+--- @return result.label string Display text for the decision.
+--- @return result.condition function Returns true if decision is available.
+--- @return result.handle function Called when the decision is selected.
 function Decision.get_all()
   return _decisions
 end
 
 --- Gets decision objects based on a screen's data.
 --- @within Decision
--- @param screen_data table The data for the screen.
+--- @param screen_data table The data for the screen.
--- @param screen_data.decisions table Array of decision ID strings.
+--- @param screen_data.decisions table Array of decision ID strings.
--- @return table A table containing decision objects relevant to the screen.
+--- @return result table An array of decision objects relevant to the screen.
+--- @return result.id string Unique decision identifier.
+--- @return result.label string Display text for the decision.
+--- @return result.condition function Returns true if decision is available.
+--- @return result.handle function Called when the decision is selected.
 function Decision.get_for_screen(screen_data)
   if not screen_data or not screen_data.decisions then
     return {}
@@ -67,8 +79,12 @@ end
 
 --- Filters a list of decision objects based on their condition function.
 --- @within Decision
--- @param decisions_list table A table of decision objects.
+--- @param decisions_list table A table of decision objects.
--- @return table A new table containing only the decisions for which condition() is true.
+--- @return result table An array of decisions for which condition() is true.
+--- @return result.id string Unique decision identifier.
+--- @return result.label string Display text for the decision.
+--- @return result.condition function Returns true if decision is available.
+--- @return result.handle function Called when the decision is selected.
 function Decision.filter_available(decisions_list)
   local available = {}
   for _, decision in ipairs(decisions_list) do

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 key string The meter key (e.g., "wpm", "ism", "bm").
--- @param amount number The amount to add.
+--- @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 defaults table The default configuration table.
--- @param params table The parameters to apply.
+--- @param params table The parameters to apply.
--- @return table The updated configuration table.
+--- @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 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.bar_fill number Current fill level of the progress bar.
--- @param[opt] params.max_fill number Maximum fill value to win.
+--- @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.fill_per_hit number Fill gained per successful hit.
--- @param[opt] params.miss_penalty number Fill lost per miss.
+--- @param[opt] params.miss_penalty number Fill lost per miss.
--- @param[opt] params.bar_x number Progress bar X position.
+--- @param[opt] params.bar_x number Progress bar X position.
--- @param[opt] params.bar_y number Progress bar Y position.
+--- @param[opt] params.bar_y number Progress bar Y position.
--- @param[opt] params.bar_width number Progress bar width.
+--- @param[opt] params.bar_width number Progress bar width.
--- @param[opt] params.bar_height number Progress bar height.
+--- @param[opt] params.bar_height number Progress bar height.
--- @param[opt] params.arrow_size number Size of arrow sprites.
+--- @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_timer number Timer for arrow spawning.
--- @param[opt] params.arrow_spawn_interval number Frames between arrow spawns.
+--- @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.arrow_fall_speed number Speed of falling arrows.
--- @param[opt] params.arrows table Array of active arrow objects.
+--- @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_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.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.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_pressed_timers table Per-button press animation timers.
--- @param[opt] params.button_press_duration number Duration of button press animation.
+--- @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_cooldowns table Per-direction cooldown timers (left, down, up, right).
--- @param[opt] params.input_cooldown_duration number Frames of input cooldown.
+--- @param[opt] params.input_cooldown_duration number Frames of input cooldown.
--- @param[opt] params.frame_counter number Global frame counter.
+--- @param[opt] params.frame_counter number Global frame counter.
--- @param[opt] params.current_song table Currently playing song data.
+--- @param[opt] params.current_song table Currently playing song data.
--- @param[opt] params.pattern_index number Current index in song pattern.
+--- @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.use_pattern boolean Whether to use song pattern for spawning.
--- @param[opt] params.return_window string Window ID to return to after minigame.
+--- @param[opt] params.return_window string Window ID to return to after minigame.
--- @return table The configured DDR minigame state.
+--- @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 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.bar_fill number Current fill level of the progress bar.
--- @param[opt] params.max_fill number Maximum fill value to win.
+--- @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.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.base_degradation number Base rate of bar degradation per frame.
--- @param[opt] params.degradation_multiplier number Multiplier for degradation scaling.
+--- @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_pressed_timer number Button press animation timer.
--- @param[opt] params.button_press_duration number Duration of button press animation.
+--- @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.return_window string Window ID to return to after minigame.
--- @param[opt] params.bar_x number Progress bar X position.
+--- @param[opt] params.bar_x number Progress bar X position.
--- @param[opt] params.bar_y number Progress bar Y position.
+--- @param[opt] params.bar_y number Progress bar Y position.
--- @param[opt] params.bar_width number Progress bar width.
+--- @param[opt] params.bar_width number Progress bar width.
--- @param[opt] params.bar_height number Progress bar height.
+--- @param[opt] params.bar_height number Progress bar height.
--- @param[opt] params.button_x number Button indicator X position.
+--- @param[opt] params.button_x number Button indicator X position.
--- @param[opt] params.button_y number Button indicator Y position.
+--- @param[opt] params.button_y number Button indicator Y position.
--- @param[opt] params.button_size number Button indicator size.
+--- @param[opt] params.button_size number Button indicator size.
--- @return table The configured button mash minigame state.
+--- @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 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_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_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.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_center number Center of the target zone (0-1).
--- @param[opt] params.target_width number Current width of the target zone.
+--- @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.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.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.target_shrink_rate number Multiplier applied to target width after each hit.
--- @param[opt] params.score number Current score.
+--- @param[opt] params.score number Current score.
--- @param[opt] params.max_score number Score needed to win.
+--- @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_pressed_timer number Button press animation timer.
--- @param[opt] params.button_press_duration number Duration of button press animation.
+--- @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.return_window string Window ID to return to after minigame.
--- @param[opt] params.bar_x number Progress bar X position.
+--- @param[opt] params.bar_x number Progress bar X position.
--- @param[opt] params.bar_y number Progress bar Y position.
+--- @param[opt] params.bar_y number Progress bar Y position.
--- @param[opt] params.bar_width number Progress bar width.
+--- @param[opt] params.bar_width number Progress bar width.
--- @param[opt] params.bar_height number Progress bar height.
+--- @param[opt] params.bar_height number Progress bar height.
--- @param[opt] params.button_x number Button indicator X position.
+--- @param[opt] params.button_x number Button indicator X position.
--- @param[opt] params.button_y number Button indicator Y position.
+--- @param[opt] params.button_y number Button indicator Y position.
--- @param[opt] params.button_size number Button indicator size.
+--- @param[opt] params.button_size number Button indicator size.
--- @param[opt] params.press_cooldown number Current cooldown timer.
+--- @param[opt] params.press_cooldown number Current cooldown timer.
--- @param[opt] params.press_cooldown_duration number Frames of press cooldown.
+--- @param[opt] params.press_cooldown_duration number Frames of press cooldown.
--- @return table The configured rhythm minigame state.
+--- @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

inc/map/map.manager.lua

@@ -6,7 +6,14 @@ local _maps = {}
 
 --- Gets all registered maps as an array.
 --- @within Map
--- @return table An array of registered map data.
+--- @return result table An array of registered map data.
+--- @return result.id string Unique map identifier.
+--- @return result.from_x number Source tile X coordinate in the map sheet.
+--- @return result.from_y number Source tile Y coordinate in the map sheet.
+--- @return result.width number Width in tiles.
+--- @return result.height number Height in tiles.
+--- @return result.to_x number Destination X coordinate on screen.
+--- @return result.to_y number Destination Y coordinate on screen.
 function Map.get_maps_array()
   local maps_array = {}
   for _, map_data in pairs(_maps) do
@@ -17,14 +24,14 @@ end
 
 --- Registers a map definition.
 --- @within Map
--- @param map_data table The map data table.
+--- @param map_data table The map data table.
--- @param map_data.id string Unique map identifier.
+--- @param map_data.id string Unique map identifier.
--- @param map_data.from_x number Source tile X coordinate in the map sheet.
+--- @param map_data.from_x number Source tile X coordinate in the map sheet.
--- @param map_data.from_y number Source tile Y coordinate in the map sheet.
+--- @param map_data.from_y number Source tile Y coordinate in the map sheet.
--- @param map_data.width number Width in tiles.
+--- @param map_data.width number Width in tiles.
--- @param map_data.height number Height in tiles.
+--- @param map_data.height number Height in tiles.
--- @param map_data.to_x number Destination X coordinate on screen.
+--- @param map_data.to_x number Destination X coordinate on screen.
--- @param map_data.to_y number Destination Y coordinate on screen.
+--- @param map_data.to_y number Destination Y coordinate on screen.
 function Map.register(map_data)
   if _maps[map_data.id] then
     trace("Warning: Overwriting map with id: " .. map_data.id)
@@ -34,15 +41,22 @@ end
 
 --- Gets a map by ID.
 --- @within Map
--- @param map_id string The ID of the map.
+--- @param map_id string The ID of the map.
--- @return table The map data table or nil.
+--- @return result table The map data table or nil.
+--- @return result.id string Unique map identifier.
+--- @return result.from_x number Source tile X coordinate in the map sheet.
+--- @return result.from_y number Source tile Y coordinate in the map sheet.
+--- @return result.width number Width in tiles.
+--- @return result.height number Height in tiles.
+--- @return result.to_x number Destination X coordinate on screen.
+--- @return result.to_y number Destination Y coordinate on screen.
 function Map.get_by_id(map_id)
   return _maps[map_id]
 end
 
 --- Draws a map.
 --- @within Map
--- @param map_id string The ID of the map to draw.
+--- @param map_id string The ID of the map to draw.
 function Map.draw(map_id)
   local map_data = Map.get_by_id(map_id)
   if not map_data then

inc/screen/screen.manager.lua

@@ -3,14 +3,14 @@ local _screens = {}
 
 --- Registers a screen definition.
 --- @within Screen
--- @param screen_data table The screen data table.
+--- @param screen_data table The screen data table.
--- @param screen_data.id string Unique screen identifier.
+--- @param screen_data.id string Unique screen identifier.
--- @param screen_data.name string Display name of the screen.
+--- @param screen_data.name string Display name of the screen.
--- @param screen_data.decisions table Array of decision ID strings available on this screen.
+--- @param screen_data.decisions table Array of decision ID strings available on this screen.
--- @param screen_data.background string Map ID used as background.
+--- @param screen_data.background string Map ID used as background.
--- @param[opt] screen_data.situations table Array of situation ID strings. Defaults to {}.
+--- @param[opt] screen_data.situations table Array of situation ID strings. Defaults to {}.
--- @param[opt] screen_data.init function Called when the screen is entered. Defaults to noop.
+--- @param[opt] screen_data.init function Called when the screen is entered. Defaults to noop.
--- @param[opt] screen_data.update function Called each frame while screen is active. Defaults to noop.
+--- @param[opt] screen_data.update function Called each frame while screen is active. Defaults to noop.
 function Screen.register(screen_data)
   if _screens[screen_data.id] then
     trace("Warning: Overwriting screen with id: " .. screen_data.id)
@@ -29,15 +29,29 @@ end
 
 --- Gets a screen by ID.
 --- @within Screen
--- @param screen_id string The ID of the screen.
+--- @param screen_id string The ID of the screen.
--- @return table The screen table or nil.
+--- @return result table The screen table or nil.
+--- @return result.id string Unique screen identifier.
+--- @return result.name string Display name of the screen.
+--- @return result.decisions table Array of decision ID strings available on this screen.
+--- @return result.background string Map ID used as background.
+--- @return result.situations table Array of situation ID strings.
+--- @return result.init function Called when the screen is entered.
+--- @return result.update function Called each frame while screen is active.
 function Screen.get_by_id(screen_id)
   return _screens[screen_id]
 end
 
 --- Gets all registered screens.
 --- @within Screen
--- @return table A table containing all registered screen data, indexed by their IDs.
+--- @return result table A table containing all registered screen data, indexed by their IDs.
+--- @return result.id string Unique screen identifier.
+--- @return result.name string Display name of the screen.
+--- @return result.decisions table Array of decision ID strings available on this screen.
+--- @return result.background string Map ID used as background.
+--- @return result.situations table Array of situation ID strings.
+--- @return result.init function Called when the screen is entered.
+--- @return result.update function Called each frame while screen is active.
 function Screen.get_all()
   return _screens
 end

inc/situation/situation.manager.lua

@@ -3,11 +3,11 @@ local _situations = {}
 
 --- Registers a situation definition.
 --- @within Situation
--- @param situation table The situation data table.
+--- @param situation table The situation data table.
--- @param situation.id string Unique situation identifier.
+--- @param situation.id string Unique situation identifier.
--- @param[opt] situation.screen_id string ID of the screen this situation belongs to.
+--- @param[opt] situation.screen_id string ID of the screen this situation belongs to.
--- @param[opt] situation.handle function Called when the situation is applied. Defaults to noop.
+--- @param[opt] situation.handle function Called when the situation is applied. Defaults to noop.
--- @param[opt] situation.update function Called each frame while situation is active. Defaults to noop.
+--- @param[opt] situation.update function Called each frame while situation is active. Defaults to noop.
 function Situation.register(situation)
   if not situation or not situation.id then
     PopupWindow.show({"Error: Invalid situation object registered (missing id)!"})
@@ -27,16 +27,24 @@ end
 
 --- Gets a situation by ID.
 --- @within Situation
--- @param id string The situation ID.
+--- @param id string The situation ID.
--- @return table The situation table or nil.
+--- @return result table The situation table or nil.
+--- @return result.id string Unique situation identifier.
+--- @return result.screen_id string ID of the screen this situation belongs to.
+--- @return result.handle function Called when the situation is applied.
+--- @return result.update function Called each frame while situation is active.
 function Situation.get_by_id(id)
   return _situations[id]
 end
 
 --- Gets all registered situations, optionally filtered by screen ID.
 --- @within Situation
--- @param screen_id string Optional. If provided, returns situations associated with this screen ID.
+--- @param screen_id string Optional. If provided, returns situations associated with this screen ID.
--- @return table A table containing all registered situation data, indexed by their IDs, or filtered by screen_id.
+--- @return result table A table containing all registered situation data, indexed by their IDs, or an array filtered by screen_id.
+--- @return result.id string Unique situation identifier.
+--- @return result.screen_id string ID of the screen this situation belongs to.
+--- @return result.handle function Called when the situation is applied.
+--- @return result.update function Called each frame while situation is active.
 function Situation.get_all(screen_id)
   if screen_id then
     local filtered_situations = {}
@@ -52,9 +60,9 @@ end
 
 --- Applies a situation, checking screen compatibility and returning the new situation ID if successful.
 --- @within Situation
--- @param id string The situation ID to apply.
+--- @param id string The situation ID to apply.
--- @param current_screen_id string The ID of the currently active screen.
+--- @param current_screen_id string The ID of the currently active screen.
--- @return string|nil The ID of the applied situation if successful, otherwise nil.
+--- @return string|nil The ID of the applied situation if successful, otherwise nil.
 function Situation.apply(id, current_screen_id)
   local situation = Situation.get_by_id(id)
   local screen = Screen.get_by_id(current_screen_id)

inc/sprite/sprite.manager.lua

@@ -4,15 +4,15 @@ local _active_sprites = {}
 
 --- Registers a sprite definition.
 --- @within Sprite
--- @param sprite_data table A table containing the sprite definition.
+--- @param sprite_data table A table containing the sprite definition.
--- @param sprite_data.id string Unique sprite identifier.
+--- @param sprite_data.id string Unique sprite identifier.
--- @param[opt] sprite_data.s number Sprite index for single-sprite mode.
+--- @param[opt] sprite_data.s number Sprite index for single-sprite mode.
--- @param[opt] sprite_data.colorkey number Default color index for transparency.
+--- @param[opt] sprite_data.colorkey number Default color index for transparency.
--- @param[opt] sprite_data.scale number Default scaling factor.
+--- @param[opt] sprite_data.scale number Default scaling factor.
--- @param[opt] sprite_data.flip_x number Set to 1 to flip horizontally by default.
+--- @param[opt] sprite_data.flip_x number Set to 1 to flip horizontally by default.
--- @param[opt] sprite_data.flip_y number Set to 1 to flip vertically by default.
+--- @param[opt] sprite_data.flip_y number Set to 1 to flip vertically by default.
--- @param[opt] sprite_data.rot number Default rotation in degrees.
+--- @param[opt] sprite_data.rot number Default rotation in degrees.
--- @param[opt] sprite_data.sprites table Array of sub-sprite tables for composite sprites. Each entry has: `s` (number) sprite index, `x_offset` (number) horizontal offset, `y_offset` (number) vertical offset, and optional `colorkey`, `scale`, `flip_x`, `flip_y`, `rot` overrides.
+--- @param[opt] sprite_data.sprites table Array of sub-sprite tables for composite sprites. Each entry has: `s` (number) sprite index, `x_offset` (number) horizontal offset, `y_offset` (number) vertical offset, and optional `colorkey`, `scale`, `flip_x`, `flip_y`, `rot` overrides.
 function Sprite.register(sprite_data)
   if not sprite_data or not sprite_data.id then
     trace("Error: Invalid sprite object registered (missing id)!")
@@ -26,14 +26,14 @@ end
 
 --- Schedules a sprite for drawing.
 --- @within Sprite
--- @param id string The unique identifier of the sprite.
+--- @param id string The unique identifier of the sprite.
--- @param x number The x-coordinate.
+--- @param x number The x-coordinate.
--- @param y number The y-coordinate.
+--- @param y number The y-coordinate.
--- @param[opt] colorkey number The color index for transparency.
+--- @param[opt] colorkey number The color index for transparency.
--- @param[opt] scale number The scaling factor.
+--- @param[opt] scale number The scaling factor.
--- @param[opt] flip_x number Set to 1 to flip horizontally.
+--- @param[opt] flip_x number Set to 1 to flip horizontally.
--- @param[opt] flip_y number Set to 1 to flip vertically.
+--- @param[opt] flip_y number Set to 1 to flip vertically.
--- @param[opt] rot number The rotation in degrees.
+--- @param[opt] rot number The rotation in degrees.
 function Sprite.show(id, x, y, colorkey, scale, flip_x, flip_y, rot)
   if not _sprites[id] then
     trace("Error: Attempted to show non-registered sprite with id: " .. id)
@@ -54,7 +54,7 @@ end
 
 --- Hides a displayed sprite.
 --- @within Sprite
--- @param id string The unique identifier of the sprite.
+--- @param id string The unique identifier of the sprite.
 function Sprite.hide(id)
   _active_sprites[id] = nil
 end

inc/system/system.print.lua

@@ -2,12 +2,12 @@
 
 --- Prints text with shadow.
 --- @within Print
--- @param text string The text to print.
+--- @param text string The text to print.
--- @param x number The x-coordinate.
+--- @param x number The x-coordinate.
--- @param y number The y-coordinate.
+--- @param y number The y-coordinate.
--- @param color number The color of the text.
+--- @param color number The color of the text.
--- @param[opt] fixed boolean If true, uses fixed-width font.
+--- @param[opt] fixed boolean If true, uses fixed-width font.
--- @param[opt] scale number The scaling factor.
+--- @param[opt] scale number The scaling factor.
 function Print.text(text, x, y, color, fixed, scale)
   local shadow_color = Config.colors.black
   if color == shadow_color then shadow_color = Config.colors.light_grey end
@@ -18,12 +18,12 @@ end
 
 --- Prints centered text with shadow.
 --- @within Print
--- @param text string The text to print.
+--- @param text string The text to print.
--- @param x number The x-coordinate for centering.
+--- @param x number The x-coordinate for centering.
--- @param y number The y-coordinate.
+--- @param y number The y-coordinate.
--- @param color number The color of the text.
+--- @param color number The color of the text.
--- @param[opt] fixed boolean If true, uses fixed-width font.
+--- @param[opt] fixed boolean If true, uses fixed-width font.
--- @param[opt] scale number The scaling factor.
+--- @param[opt] scale number The scaling factor.
 function Print.text_center(text, x, y, color, fixed, scale)
   scale = scale or 1
   local text_width = print(text, 0, -6, 0, fixed, scale)

inc/system/system.ui.lua

@@ -2,7 +2,7 @@
 
 --- Draws the top bar.
 --- @within UI
--- @param title string The title text to display.
+--- @param title string The title text to display.
 function UI.draw_top_bar(title)
   rect(0, 0, Config.screen.width, 10, Config.colors.dark_grey)
   Print.text(title, 3, 2, Config.colors.green)
@@ -16,10 +16,10 @@ end
 
 --- Draws a menu.
 --- @within UI
--- @param items table A table of menu items.
+--- @param items table A table of menu items.
--- @param selected_item number The index of the currently selected item.
+--- @param selected_item number The index of the currently selected item.
--- @param x number The x-coordinate for the menu.
+--- @param x number The x-coordinate for the menu.
--- @param y number The y-coordinate for the menu.
+--- @param y number The y-coordinate for the menu.
 function UI.draw_menu(items, selected_item, x, y)
   for i, item in ipairs(items) do
     local current_y = y + (i-1)*10
@@ -32,9 +32,9 @@ end
 
 --- Updates menu selection.
 --- @within UI
--- @param items table A table of menu items.
+--- @param items table A table of menu items.
--- @param selected_item number The current index of the selected item.
+--- @param selected_item number The current index of the selected item.
--- @return number The updated index of the selected item.
+--- @return number The updated index of the selected item.
 function UI.update_menu(items, selected_item)
   if Input.up() then
     Audio.sfx_beep()
@@ -54,9 +54,9 @@ end
 
 --- Wraps text.
 --- @within UI
--- @param text string The text to wrap.
+--- @param text string The text to wrap.
--- @param max_chars_per_line number The maximum characters per line.
+--- @param max_chars_per_line number The maximum characters per line.
--- @return table A table of wrapped lines.
+--- @return table A table of wrapped lines.
 function UI.word_wrap(text, max_chars_per_line)
     if text == nil then return {""} end
     local lines = {}
@@ -88,14 +88,22 @@ end
 
 --- Creates a numeric stepper.
 --- @within UI
--- @param label string The label for the stepper.
+--- @param label string The label for the stepper.
--- @param value_getter function Function to get the current value.
+--- @param value_getter function Function to get the current value.
--- @param value_setter function Function to set the current value.
+--- @param value_setter function Function to set the current value.
--- @param min number The minimum value.
+--- @param min number The minimum value.
--- @param max number The maximum value.
+--- @param max number The maximum value.
--- @param step number The step increment.
+--- @param step number The step increment.
--- @param[opt] format string The format string for displaying the value.
+--- @param[opt] format string The format string for displaying the value.
--- @return table A numeric stepper control definition.
+--- @return result table A numeric stepper control definition.
+--- @return result.label string The label for the stepper.
+--- @return result.get function Function to get the current value.
+--- @return result.set function Function to set the current value.
+--- @return result.min number The minimum value.
+--- @return result.max number The maximum value.
+--- @return result.step number The step increment.
+--- @return result.format string The format string for displaying the value.
+--- @return result.type string Control type identifier ("numeric_stepper").
 function UI.create_numeric_stepper(label, value_getter, value_setter, min, max, step, format)
   return {
     label = label,
@@ -111,9 +119,12 @@ end
 
 --- Creates an action item.
 --- @within UI
--- @param label string The label for the action item.
+--- @param label string The label for the action item.
--- @param action function The function to execute when the item is selected.
+--- @param action function The function to execute when the item is selected.
--- @return table An action item control definition.
+--- @return result table An action item control definition.
+--- @return result.label string The label for the action item.
+--- @return result.action function The function to execute when the item is selected.
+--- @return result.type string Control type identifier ("action_item").
 function UI.create_action_item(label, action)
   return {
     label = label,
@@ -124,8 +135,8 @@ end
 
 --- Draws decision selector.
 --- @within UI
--- @param decisions table A table of decision items.
+--- @param decisions table A table of decision items.
--- @param selected_decision_index number The index of the selected decision.
+--- @param selected_decision_index number The index of the selected decision.
 function UI.draw_decision_selector(decisions, selected_decision_index)
   local bar_height = 16
   local bar_y = Config.screen.height - bar_height
@@ -178,9 +189,9 @@ end
 
 --- Updates decision selector.
 --- @within UI
--- @param decisions table A table of decision items.
+--- @param decisions table A table of decision items.
--- @param selected_decision_index number The current index of the selected decision.
+--- @param selected_decision_index number The current index of the selected decision.
--- @return number The updated index of the selected decision.
+--- @return number The updated index of the selected decision.
 function UI.update_decision_selector(decisions, selected_decision_index)
   if Input.left() then
     Audio.sfx_beep()

inc/system/system.util.lua

@@ -3,16 +3,16 @@
 
 --- Safely wraps an index for an array.
 --- @within Util
--- @param array table The array to index.
+--- @param array table The array to index.
--- @param index number The desired index (can be out of bounds).
+--- @param index number The desired index (can be out of bounds).
--- @return number The wrapped index within the array's bounds.
+--- @return number The wrapped index within the array's bounds.
 function Util.safeindex(array, index)
     return ((index - 1 + #array) % #array) + 1
 end
 
 --- Navigates to a screen by its ID.
 --- @within Util
--- @param screen_id string The ID of the screen to go to.
+--- @param screen_id string The ID of the screen to go to.
 function Util.go_to_screen_by_id(screen_id)
   local screen = Screen.get_by_id(screen_id)
   if screen then
@@ -25,8 +25,8 @@ end
 
 --- Checks if a table contains a specific value.
 --- @within Util
--- @param t table The table to check.
+--- @param t table The table to check.
--- @param value any The value to look for.
+--- @param value any The value to look for.
 function Util.contains(t, value)
   for i = 1, #t do
     if t[i] == value then

inc/window/window.audiotest.lua

@@ -9,9 +9,11 @@ AudioTestWindow = {
 
 --- Generates menu items for audio test.
 --- @within AudioTestWindow
--- @param list_func table List of audio functions.
+--- @param list_func table List of audio functions.
--- @param index_func number Current index of selected function.
+--- @param index_func number Current index of selected function.
--- @return table Generated menu items.
+--- @return result table Generated menu items, an array of menu item tables.
+--- @return result.label string Display text for the menu item.
+--- @return result.decision function Called when the menu item is selected.
 function AudioTestWindow.generate_menuitems(list_func, index_func)
     return {
         {
@@ -42,7 +44,7 @@ end
 
 --- Generates list of audio functions.
 --- @within AudioTestWindow
--- @return table A sorted list of audio function names.
+--- @return table A sorted list of audio function names.
 function AudioTestWindow.generate_listfunc()
     local result = {}
 

inc/window/window.game.lua

@@ -64,7 +64,7 @@ end
 
 --- Sets the active window.
 --- @within GameWindow
--- @param new_state string The ID of the new active window.
+--- @param new_state string The ID of the new active window.
 function GameWindow.set_state(new_state)
   Window.set_current(new_state)
 end

inc/window/window.manager.lua

@@ -3,30 +3,32 @@ local _windows = {}
 
 --- Registers a window table.
 --- @within Window
--- @param id string The ID of the window (e.g., "splash", "menu").
+--- @param id string The ID of the window (e.g., "splash", "menu").
--- @param window_table table The actual window module table (e.g., SplashWindow).
+--- @param window_table table The actual window module table (e.g., SplashWindow).
 function Window.register(id, window_table)
   _windows[id] = window_table
 end
 
 --- Retrieves a registered window table by its ID.
 --- @within Window
--- @param id string The ID of the window.
+--- @param id string The ID of the window.
--- @return table The window module table.
+--- @return result table The window module table.
+--- @return result.update function Called each frame to update window logic.
+--- @return result.draw function Called each frame to draw the window.
 function Window.get(id)
   return _windows[id]
 end
 
 --- Sets the currently active window.
 --- @within Window
--- @param id string The ID of the window to activate.
+--- @param id string The ID of the window to activate.
 function Window.set_current(id)
   Context.current_window = id
 end
 
 --- Gets the ID of the currently active window.
 --- @within Window
--- @return string The ID of the active window.
+--- @return string The ID of the active window.
 function Window.get_current_id()
   return Context.current_window
 end
@@ -34,7 +36,7 @@ end
 --- Gets the handler function for the currently active window.
 -- This function is used by the main game loop to update and draw the active window.
 --- @within Window
--- @return function A function that updates and draws the current window.
+--- @return function A function that updates and draws the current window.
 function Window.get_current_handler()
   local window_table = Window.get(Context.current_window)
   if window_table and window_table.update and window_table.draw then

inc/window/window.minigame.ddr.lua

@@ -2,16 +2,16 @@
 
 --- Initializes DDR minigame state.
 --- @within MinigameDDRWindow
--- @param params table Optional parameters for configuration.
+--- @param params table Optional parameters for configuration.
 function MinigameDDRWindow.init(params)
   Context.minigame_ddr = Minigame.configure_ddr(params)
 end
 
 --- Starts the DDR minigame.
 --- @within MinigameDDRWindow
--- @param return_window string The window ID to return to after the minigame.
+--- @param return_window string The window ID to return to after the minigame.
--- @param[opt] song_key string The key of the song to play.
+--- @param[opt] song_key string The key of the song to play.
--- @param[opt] params table Optional parameters for minigame configuration.
+--- @param[opt] params table Optional parameters for minigame configuration.
 function MinigameDDRWindow.start(return_window, song_key, params)
   MinigameDDRWindow.init(params)
   Context.minigame_ddr.return_window = return_window or "game"
@@ -46,7 +46,7 @@ end
 
 --- Spawns an arrow in a specific direction.
 --- @within MinigameDDRWindow
--- @param direction string The direction of the arrow ("left", "down", "up", "right").
+--- @param direction string The direction of the arrow ("left", "down", "up", "right").
 local function spawn_arrow_dir(direction)
   local mg = Context.minigame_ddr
   for _, target in ipairs(mg.target_arrows) do
@@ -63,8 +63,8 @@ end
 
 --- Checks if an arrow is hit.
 --- @within MinigameDDRWindow
--- @param arrow table The arrow data.
+--- @param arrow table The arrow data.
--- @return boolean True if the arrow is hit, false otherwise.
+--- @return boolean True if the arrow is hit, false otherwise.
 local function check_hit(arrow)
   local mg = Context.minigame_ddr
   local distance = math.abs(arrow.y - mg.target_y)
@@ -73,8 +73,8 @@ end
 
 --- Checks if an arrow is missed.
 --- @within MinigameDDRWindow
--- @param arrow table The arrow data.
+--- @param arrow table The arrow data.
--- @return boolean True if the arrow is missed, false otherwise.
+--- @return boolean True if the arrow is missed, false otherwise.
 local function check_miss(arrow)
   local mg = Context.minigame_ddr
   return arrow.y > mg.target_y + mg.hit_threshold
@@ -82,10 +82,10 @@ end
 
 --- Draws an arrow.
 --- @within MinigameDDRWindow
--- @param x number The x-coordinate.
+--- @param x number The x-coordinate.
--- @param y number The y-coordinate.
+--- @param y number The y-coordinate.
--- @param direction string The direction of the arrow.
+--- @param direction string The direction of the arrow.
--- @param color number The color of the arrow.
+--- @param color number The color of the arrow.
 local function draw_arrow(x, y, direction, color)
   local size = 12
   local half = size / 2

inc/window/window.minigame.mash.lua

@@ -2,15 +2,15 @@
 
 --- Initializes button mash minigame state.
 --- @within MinigameButtonMashWindow
--- @param params table Optional parameters for configuration.
+--- @param params table Optional parameters for configuration.
 function MinigameButtonMashWindow.init(params)
   Context.minigame_button_mash = Minigame.configure_button_mash(params)
 end
 
 --- Starts the button mash minigame.
 --- @within MinigameButtonMashWindow
--- @param return_window string The window ID to return to after the minigame.
+--- @param return_window string The window ID to return to after the minigame.
--- @param[opt] params table Optional parameters for minigame configuration.
+--- @param[opt] params table Optional parameters for minigame configuration.
 function MinigameButtonMashWindow.start(return_window, params)
   MinigameButtonMashWindow.init(params)
   Context.minigame_button_mash.return_window = return_window or "game"

inc/window/window.minigame.rhythm.lua

@@ -2,15 +2,15 @@
 
 --- Initializes rhythm minigame state.
 --- @within MinigameRhythmWindow
--- @param params table Optional parameters for configuration.
+--- @param params table Optional parameters for configuration.
 function MinigameRhythmWindow.init(params)
   Context.minigame_rhythm = Minigame.configure_rhythm(params)
 end
 
 --- Starts the rhythm minigame.
 --- @within MinigameRhythmWindow
--- @param return_window string The window ID to return to after the minigame.
+--- @param return_window string The window ID to return to after the minigame.
--- @param[opt] params table Optional parameters for minigame configuration.
+--- @param[opt] params table Optional parameters for minigame configuration.
 function MinigameRhythmWindow.start(return_window, params)
   MinigameRhythmWindow.init(params)
   Context.minigame_rhythm.return_window = return_window or "game"

inc/window/window.popup.lua

@@ -9,7 +9,7 @@ local LINE_HEIGHT = 8
 
 --- Displays a popup window.
 --- @within PopupWindow
--- @param content_strings table A table of strings to display in the popup.
+--- @param content_strings table A table of strings to display in the popup.
 function PopupWindow.show(content_strings)
   Context.popup.show = true
   Context.popup.content = content_strings or {}