return table details in docs

inc/system/system.print.lua

@@ -2,12 +2,12 @@
 
 --- Prints text with shadow.
 --- @within Print
--- @param text string The text to print.
--- @param x number The x-coordinate.
--- @param y number The y-coordinate.
--- @param color number The color of the text.
--- @param[opt] fixed boolean If true, uses fixed-width font.
--- @param[opt] scale number The scaling factor.
+--- @param text string The text to print.
+--- @param x number The x-coordinate.
+--- @param y number The y-coordinate.
+--- @param color number The color of the text.
+--- @param[opt] fixed boolean If true, uses fixed-width font.
+--- @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 x number The x-coordinate for centering.
--- @param y number The y-coordinate.
--- @param color number The color of the text.
--- @param[opt] fixed boolean If true, uses fixed-width font.
--- @param[opt] scale number The scaling factor.
+--- @param text string The text to print.
+--- @param x number The x-coordinate for centering.
+--- @param y number The y-coordinate.
+--- @param color number The color of the text.
+--- @param[opt] fixed boolean If true, uses fixed-width font.
+--- @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 selected_item number The index of the currently selected item.
--- @param x number The x-coordinate for the menu.
--- @param y number The y-coordinate for the menu.
+--- @param items table A table of menu items.
+--- @param selected_item number The index of the currently selected item.
+--- @param x number The x-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 selected_item number The current index of the selected item.
--- @return number The updated index of the selected item.
+--- @param items table A table of menu items.
+--- @param selected_item number The current 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 max_chars_per_line number The maximum characters per line.
--- @return table A table of wrapped lines.
+--- @param text string The text to wrap.
+--- @param max_chars_per_line number The maximum characters per line.
+--- @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 value_getter function Function to get the current value.
--- @param value_setter function Function to set the current value.
--- @param min number The minimum value.
--- @param max number The maximum value.
--- @param step number The step increment.
--- @param[opt] format string The format string for displaying the value.
--- @return table A numeric stepper control definition.
+--- @param label string The label for the stepper.
+--- @param value_getter function Function to get the current value.
+--- @param value_setter function Function to set the current value.
+--- @param min number The minimum value.
+--- @param max number The maximum value.
+--- @param step number The step increment.
+--- @param[opt] format string The format string for displaying the value.
+--- @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 action function The function to execute when the item is selected.
--- @return table An action item control definition.
+--- @param label string The label for the action item.
+--- @param action function The function to execute when the item is selected.
+--- @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 selected_decision_index number The index of the selected decision.
+--- @param decisions table A table of decision items.
+--- @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 selected_decision_index number The current index of the selected decision.
--- @return number The updated index of the selected decision.
+--- @param decisions table A table of decision items.
+--- @param selected_decision_index number The current 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 index number The desired index (can be out of bounds).
--- @return number The wrapped index within the array's bounds.
+--- @param array table The array to index.
+--- @param index number The desired index (can be out of 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 value any The value to look for.
+--- @param t table The table to check.
+--- @param value any The value to look for.
 function Util.contains(t, value)
   for i = 1, #t do
     if t[i] == value then