section and within annotations for ldoc

inc/init/init.config.lua

@@ -1,5 +1,7 @@
 Config = {}
 
+--- Return initial data for Config
+--- @within Config
 function Config.initial_data()
   return {
     screen = {
@@ -24,6 +26,7 @@ function Config.initial_data()
 end
 
 --- Restores default configuration settings.
+--- @within Config
 function Config.reset()
   local initial = Config.initial_data()
   Config.screen = initial.screen
@@ -37,12 +40,14 @@ local CONFIG_SPLASH_DURATION_ADDRESS = 3
 local CONFIG_MAGIC_VALUE = 0xDE
 
 --- Saves the current configuration.
+--- @within Config
 function Config.save()
   mset(CONFIG_MAGIC_VALUE, CONFIG_MAGIC_VALUE_ADDRESS, CONFIG_SAVE_BANK)
   mset(Config.timing.splash_duration, CONFIG_SPLASH_DURATION_ADDRESS, CONFIG_SAVE_BANK)
 end
 
 --- Loads saved configuration.
+--- @within Config
 function Config.load()
   if mget(CONFIG_MAGIC_VALUE_ADDRESS, CONFIG_SAVE_BANK) == CONFIG_MAGIC_VALUE then
     Config.timing.splash_duration = mget(CONFIG_SPLASH_DURATION_ADDRESS, CONFIG_SAVE_BANK)

inc/init/init.context.lua

@@ -3,9 +3,11 @@ local SAVE_GAME_MAGIC_VALUE_ADDRESS = 0
 local SAVE_GAME_MAGIC_VALUE = 0xCA
 
 --- Global game context.
+--- @section Context
 Context = {}
 
 --- Gets initial data for Context.
+--- @within Context
 -- @return table Initial context data.
 function Context.initial_data()
   return {
@@ -28,6 +30,7 @@ function Context.initial_data()
 end
 
 --- Resets game context to initial state.
+--- @within Context
 function Context.reset()
   local initial_data = Context.initial_data()
   for k in pairs(Context) do
@@ -42,6 +45,7 @@ function Context.reset()
 end
 
 --- Starts a new game.
+--- @within Context
 function Context.new_game()
   Context.reset()
   Context.game_in_progress = true
@@ -50,12 +54,14 @@ function Context.new_game()
 end
 
 --- Saves the current game state.
+--- @within Context
 function Context.save_game()
   if not Context.game_in_progress then return end
   mset(SAVE_GAME_MAGIC_VALUE, SAVE_GAME_MAGIC_VALUE_ADDRESS, SAVE_GAME_BANK)
 end
 
 --- Loads a saved game state.
+--- @within Context
 function Context.load_game()
   if mget(SAVE_GAME_MAGIC_VALUE_ADDRESS, SAVE_GAME_BANK) ~= SAVE_GAME_MAGIC_VALUE then
     Context.new_game()

inc/init/init.meter.lua

@@ -1,3 +1,4 @@
+--- @section Meter
 local METER_MAX = 1000
 local METER_DEFAULT = 500
 local METER_DECAY_PER_FRAME = 0.02
@@ -13,6 +14,7 @@ Meter.COLOR_BM = Config.colors.black
 Meter.COLOR_BG = Config.colors.meter_bg
 
 --- Gets initial meter values.
+--- @within Meter
 -- @return table A table of initial meter values.
 function Meter.get_initial()
   return {
@@ -26,22 +28,26 @@ function Meter.get_initial()
 end
 
 --- Hides meters.
+--- @within Meter
 function Meter.hide()
   if Context and Context.meters then Context.meters.hidden = true end
 end
 
 --- Shows meters.
+--- @within Meter
 function Meter.show()
   if Context and Context.meters then Context.meters.hidden = false end
 end
 
 --- Gets max meter value.
+--- @within Meter
 -- @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.
 function Meter.get_combo_multiplier()
   if not Context or not Context.meters then return 1 end
@@ -51,6 +57,7 @@ function Meter.get_combo_multiplier()
 end
 
 --- Updates all meters.
+--- @within Meter
 function Meter.update()
   if not Context or not Context.game_in_progress or not Context.meters then return end
   local m = Context.meters
@@ -67,6 +74,7 @@ function Meter.update()
 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.
 function Meter.add(key, amount)
@@ -78,6 +86,7 @@ function Meter.add(key, amount)
 end
 
 --- Called on minigame completion.
+--- @within Meter
 function Meter.on_minigame_complete()
   local m = Context.meters
   local gain = math.floor(METER_GAIN_PER_CHORE * Meter.get_combo_multiplier())

inc/init/init.minigame.lua

@@ -1,6 +1,8 @@
 -- Manages minigame configurations and initial states.
+--- @section Minigame
 
---- Applies parameters to defaults.
+--- 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.
@@ -13,6 +15,7 @@ local function apply_params(defaults, params)
 end
 
 --- Gets default DDR minigame configuration.
+--- @within Minigame
 -- @return table The default DDR minigame configuration.
 function Minigame.get_default_ddr()
   local arrow_size = 12
@@ -54,6 +57,7 @@ function Minigame.get_default_ddr()
 end
 
 --- Gets default button mash minigame configuration.
+--- @within Minigame
 -- @return table The default button mash minigame configuration.
 function Minigame.get_default_button_mash()
   return {
@@ -76,6 +80,7 @@ function Minigame.get_default_button_mash()
 end
 
 --- Gets default rhythm minigame configuration.
+--- @within Minigame
 -- @return table The default rhythm minigame configuration.
 function Minigame.get_default_rhythm()
   return {
@@ -105,6 +110,7 @@ function Minigame.get_default_rhythm()
 end
 
 --- Configures DDR minigame.
+--- @within Minigame
 -- @param params table Optional parameters to override defaults.
 -- @return table The configured DDR minigame state.
 function Minigame.configure_ddr(params)
@@ -112,6 +118,7 @@ function Minigame.configure_ddr(params)
 end
 
 --- Configures button mash minigame.
+--- @within Minigame
 -- @param params table Optional parameters to override defaults.
 -- @return table The configured button mash minigame state.
 function Minigame.configure_button_mash(params)
@@ -119,6 +126,7 @@ function Minigame.configure_button_mash(params)
 end
 
 --- Configures rhythm minigame.
+--- @within Minigame
 -- @param params table Optional parameters to override defaults.
 -- @return table The configured rhythm minigame state.
 function Minigame.configure_rhythm(params)