section and within annotations for ldoc

inc/window/window.audiotest.lua

@@ -1,3 +1,4 @@
+--- @section AudioTestWindow
 AudioTestWindow = {
     index_menu = 1,
     index_func = 1,
@@ -7,6 +8,7 @@ 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.
@@ -39,6 +41,7 @@ function AudioTestWindow.generate_menuitems(list_func, index_func)
 end
 
 --- Generates list of audio functions.
+--- @within AudioTestWindow
 -- @return table A sorted list of audio function names.
 function AudioTestWindow.generate_listfunc()
     local result = {}
@@ -55,12 +58,14 @@ function AudioTestWindow.generate_listfunc()
 end
 
 --- Navigates back from audio test window.
+--- @within AudioTestWindow
 function AudioTestWindow.back()
     Audio.sfx_deselect()
     GameWindow.set_state("menu")
 end
 
 --- Initializes audio test window.
+--- @within AudioTestWindow
 function AudioTestWindow.init()
     AudioTestWindow.last_pressed = false
     AudioTestWindow.index_menu = 1
@@ -72,12 +77,14 @@ function AudioTestWindow.init()
 end
 
 --- Draws audio test window.
+--- @within AudioTestWindow
 function AudioTestWindow.draw()
     UI.draw_top_bar("Audio test")
     UI.draw_menu(AudioTestWindow.menuitems, AudioTestWindow.index_menu, 20, 50)
 end
 
 --- Updates audio test window logic.
+--- @within AudioTestWindow
 function AudioTestWindow.update()
     if Input.up() then
         AudioTestWindow.index_menu = Util.safeindex(AudioTestWindow.menuitems, AudioTestWindow.index_menu - 1)

inc/window/window.configuration.lua

@@ -1,9 +1,11 @@
+--- @section ConfigurationWindow
 ConfigurationWindow = {
   controls = {},
   selected_control = 1,
 }
 
 --- Initializes configuration window.
+--- @within ConfigurationWindow
 function ConfigurationWindow.init()
   ConfigurationWindow.controls = {
     UI.create_action_item(
@@ -18,6 +20,7 @@ function ConfigurationWindow.init()
 end
 
 --- Draws configuration window.
+--- @within ConfigurationWindow
 function ConfigurationWindow.draw()
   UI.draw_top_bar("Configuration")
 
@@ -60,6 +63,7 @@ function ConfigurationWindow.draw()
 end
 
 --- Updates configuration window logic.
+--- @within ConfigurationWindow
 function ConfigurationWindow.update()
   if Input.menu_back() then
     GameWindow.set_state("menu")

inc/window/window.game.lua

@@ -1,7 +1,9 @@
+--- @section GameWindow
 local _available_decisions = {}
 local _selected_decision_index = 1
 
 --- Draws the game window.
+--- @within GameWindow
 function GameWindow.draw()
   local screen = Screen.get_by_id(Context.game.current_screen)
   if screen.background then Map.draw(screen.background) end
@@ -13,6 +15,7 @@ function GameWindow.draw()
 end
 
 --- Updates the game window logic.
+--- @within GameWindow
 function GameWindow.update()
   if Input.menu_back() then
     Window.set_current("menu")
@@ -60,6 +63,7 @@ function GameWindow.update()
 end
 
 --- Sets the active window.
+--- @within GameWindow
 -- @param new_state string The ID of the new active window.
 function GameWindow.set_state(new_state)
   Window.set_current(new_state)

inc/window/window.intro.lua

@@ -1,3 +1,4 @@
+--- @section IntroWindow
 IntroWindow.y = Config.screen.height
 IntroWindow.speed = 0.5
 IntroWindow.text = [[
@@ -14,12 +15,14 @@ on than meets the eye.
 ]]
 
 --- Draws the intro window.
+--- @within IntroWindow
 function IntroWindow.draw()
   local x = (Config.screen.width - 132) / 2
   Print.text(IntroWindow.text, x, IntroWindow.y, Config.colors.green)
 end
 
 --- Updates the intro window logic.
+--- @within IntroWindow
 function IntroWindow.update()
   IntroWindow.y = IntroWindow.y - IntroWindow.speed
 

inc/window/window.manager.lua

@@ -1,6 +1,8 @@
+--- @section Window
 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).
 function Window.register(id, window_table)
@@ -8,6 +10,7 @@ function Window.register(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.
 function Window.get(id)
@@ -15,12 +18,14 @@ function Window.get(id)
 end
 
 --- Sets the currently active window.
+--- @within Window
 -- @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.
 function Window.get_current_id()
   return Context.current_window
@@ -28,6 +33,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.
 function Window.get_current_handler()
   local window_table = Window.get(Context.current_window)

inc/window/window.menu.lua

@@ -1,12 +1,15 @@
+--- @section MenuWindow
 local _menu_items = {}
 
 --- Draws the menu window.
+--- @within MenuWindow
 function MenuWindow.draw()
   UI.draw_top_bar("Main Menu")
   UI.draw_menu(_menu_items, Context.current_menu_item, 108, 70)
 end
 
 --- Updates the menu window logic.
+--- @within MenuWindow
 function MenuWindow.update()
   Context.current_menu_item = UI.update_menu(_menu_items, Context.current_menu_item)
 
@@ -20,45 +23,53 @@ function MenuWindow.update()
 end
 
 --- Starts a new game from the menu.
+--- @within MenuWindow
 function MenuWindow.new_game()
   Context.new_game()
   GameWindow.set_state("game")
 end
 
 --- Loads a game from the menu.
+--- @within MenuWindow
 function MenuWindow.load_game()
   Context.load_game()
   GameWindow.set_state("game")
 end
 
 --- Saves the current game from the menu.
+--- @within MenuWindow
 function MenuWindow.save_game()
   Context.save_game()
 end
 
 --- Resumes the game from the menu.
+--- @within MenuWindow
 function MenuWindow.resume_game()
   GameWindow.set_state("game")
 end
 
 --- Exits the game.
+--- @within MenuWindow
 function MenuWindow.exit()
   exit()
 end
 
 --- Opens the configuration menu.
+--- @within MenuWindow
 function MenuWindow.configuration()
   ConfigurationWindow.init()
   GameWindow.set_state("configuration")
 end
 
 --- Opens the audio test menu.
+--- @within MenuWindow
 function MenuWindow.audio_test()
   AudioTestWindow.init()
   GameWindow.set_state("audiotest")
 end
 
 --- Refreshes menu items.
+--- @within MenuWindow
 function MenuWindow.refresh_menu_items()
   _menu_items = {}
   if Context.game_in_progress then

inc/window/window.minigame.ddr.lua

@@ -1,10 +1,14 @@
+--- @section MinigameDDRWindow
+
 --- Initializes DDR minigame state.
+--- @within MinigameDDRWindow
 -- @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.
@@ -29,6 +33,7 @@ function MinigameDDRWindow.start(return_window, song_key, params)
 end
 
 --- Spawns a random arrow.
+--- @within MinigameDDRWindow
 local function spawn_arrow()
   local mg = Context.minigame_ddr
   local target = mg.target_arrows[math.random(1, 4)]
@@ -40,6 +45,7 @@ local function spawn_arrow()
 end
 
 --- Spawns an arrow in a specific direction.
+--- @within MinigameDDRWindow
 -- @param direction string The direction of the arrow ("left", "down", "up", "right").
 local function spawn_arrow_dir(direction)
   local mg = Context.minigame_ddr
@@ -56,6 +62,7 @@ local function spawn_arrow_dir(direction)
 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.
 local function check_hit(arrow)
@@ -65,6 +72,7 @@ local function check_hit(arrow)
 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.
 local function check_miss(arrow)
@@ -73,6 +81,7 @@ local function check_miss(arrow)
 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.
@@ -96,6 +105,7 @@ local function draw_arrow(x, y, direction, color)
 end
 
 --- Updates DDR minigame logic.
+--- @within MinigameDDRWindow
 function MinigameDDRWindow.update()
   local mg = Context.minigame_ddr
   if mg.bar_fill >= mg.max_fill then
@@ -189,6 +199,7 @@ function MinigameDDRWindow.update()
 end
 
 --- Draws DDR minigame.
+--- @within MinigameDDRWindow
 function MinigameDDRWindow.draw()
   local mg = Context.minigame_ddr
   if not mg then

inc/window/window.minigame.mash.lua

@@ -1,10 +1,14 @@
+--- @section MinigameButtonMashWindow
+
 --- Initializes button mash minigame state.
+--- @within MinigameButtonMashWindow
 -- @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.
 function MinigameButtonMashWindow.start(return_window, params)
@@ -14,6 +18,7 @@ function MinigameButtonMashWindow.start(return_window, params)
 end
 
 --- Updates button mash minigame logic.
+--- @within MinigameButtonMashWindow
 function MinigameButtonMashWindow.update()
   local mg = Context.minigame_button_mash
   if Input.select() then
@@ -40,6 +45,7 @@ function MinigameButtonMashWindow.update()
 end
 
 --- Draws button mash minigame.
+--- @within MinigameButtonMashWindow
 function MinigameButtonMashWindow.draw()
   local mg = Context.minigame_button_mash
   if mg.return_window == "game" then

inc/window/window.minigame.rhythm.lua

@@ -1,10 +1,14 @@
+--- @section MinigameRhythmWindow
+
 --- Initializes rhythm minigame state.
+--- @within MinigameRhythmWindow
 -- @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.
 function MinigameRhythmWindow.start(return_window, params)
@@ -14,6 +18,7 @@ function MinigameRhythmWindow.start(return_window, params)
 end
 
 --- Updates rhythm minigame logic.
+--- @within MinigameRhythmWindow
 function MinigameRhythmWindow.update()
   local mg = Context.minigame_rhythm
   mg.line_position = mg.line_position + (mg.line_speed * mg.line_direction)
@@ -57,6 +62,7 @@ function MinigameRhythmWindow.update()
 end
 
 --- Draws rhythm minigame.
+--- @within MinigameRhythmWindow
 function MinigameRhythmWindow.draw()
   local mg = Context.minigame_rhythm
   if mg.return_window == "game" then

inc/window/window.popup.lua

@@ -1,3 +1,4 @@
+--- @section PopupWindow
 local POPUP_X = 40
 local POPUP_Y = 40
 local POPUP_WIDTH = 160
@@ -7,6 +8,7 @@ local TEXT_MARGIN_Y = POPUP_Y + 10
 local LINE_HEIGHT = 8
 
 --- Displays a popup window.
+--- @within PopupWindow
 -- @param content_strings table A table of strings to display in the popup.
 function PopupWindow.show(content_strings)
   Context.popup.show = true
@@ -15,6 +17,7 @@ function PopupWindow.show(content_strings)
 end
 
 --- Hides the popup window.
+--- @within PopupWindow
 function PopupWindow.hide()
   Context.popup.show = false
   Context.popup.content = {}
@@ -22,6 +25,7 @@ function PopupWindow.hide()
 end
 
 --- Updates popup window logic.
+--- @within PopupWindow
 function PopupWindow.update()
   if Context.popup.show then
     if Input.menu_confirm() or Input.menu_back() then
@@ -31,6 +35,7 @@ function PopupWindow.update()
 end
 
 --- Draws the popup window.
+--- @within PopupWindow
 function PopupWindow.draw()
   if Context.popup.show then
     rect(POPUP_X, POPUP_Y, POPUP_WIDTH, POPUP_HEIGHT, Config.colors.black)

inc/window/window.splash.lua

@@ -1,4 +1,7 @@
+--- @section SplashWindow
+
 --- Draws the splash window.
+--- @within SplashWindow
 function SplashWindow.draw()
   local txt = "Definitely not an Impostor"
   local y = (Config.screen.height - 6) / 2
@@ -6,6 +9,7 @@ function SplashWindow.draw()
 end
 
 --- Updates the splash window logic.
+--- @within SplashWindow
 function SplashWindow.update()
   Context.splash_timer = Context.splash_timer - 1
   if Context.splash_timer <= 0 or Input.menu_confirm() then