return table details in docs

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 index_func number Current index of selected function.
--- @return table Generated menu items.
+--- @param list_func table List of audio functions.
+--- @param index_func number Current index of selected function.
+--- @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 window_table table The actual window module table (e.g., SplashWindow).
+--- @param id string The ID of the window (e.g., "splash", "menu").
+--- @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.
--- @return table The window module table.
+--- @param id string The ID of the window.
+--- @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[opt] song_key string The key of the song to play.
--- @param[opt] params table Optional parameters for minigame configuration.
+--- @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] 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.
--- @return boolean True if the arrow is hit, false otherwise.
+--- @param arrow table The arrow data.
+--- @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.
--- @return boolean True if the arrow is missed, false otherwise.
+--- @param arrow table The arrow data.
+--- @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 y number The y-coordinate.
--- @param direction string The direction of the arrow.
--- @param color number The color of the arrow.
+--- @param x number The x-coordinate.
+--- @param y number The y-coordinate.
+--- @param direction string The direction 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[opt] params table Optional parameters for minigame configuration.
+--- @param return_window string The window ID to return to after the minigame.
+--- @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[opt] params table Optional parameters for minigame configuration.
+--- @param return_window string The window ID to return to after the minigame.
+--- @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 {}