updated type hints and comments

graphics/element.lua

@@ -57,7 +57,7 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         offset_x = 0,
         offset_y = 0,
         next_y = 1,                                     -- next child y coordinate
-        next_id = 0,                                    -- next child ID[
+        next_id = 0,                                    -- next child ID
         subscriptions = {},                             ---@type { ps: psil, key: string, func: function }[]
         button_down = { events.new_coord_2d(-1, -1), events.new_coord_2d(-1, -1), events.new_coord_2d(-1, -1) },
         focused = false,
@@ -87,9 +87,9 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
 
     setmetatable(public, self.mt)
 
-    -----------------------
-    -- PRIVATE FUNCTIONS --
-    -----------------------
+    ------------------------------
+    --#region PRIVATE FUNCTIONS --
+    ------------------------------
 
     -- use tab to jump to the next focusable field
     ---@param reverse boolean
@@ -150,9 +150,11 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         end
     end
 
-    -------------------------
-    -- PROTECTED FUNCTIONS --
-    -------------------------
+    --#endregion
+
+    --------------------------------
+    --#region PROTECTED FUNCTIONS --
+    --------------------------------
 
     -- prepare the template
     ---@param offset_x integer x offset for mouse events
@@ -371,7 +373,8 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
     function protected.on_update(...) end
 
     --#endregion
-    --#region Accessors and Control --
+
+    --#region Accessors and Control
 
     -- get value
     ---@nodiscard
@@ -409,9 +412,13 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
     -- stop animations
     function protected.stop_anim() end
 
-    -----------
-    -- SETUP --
-    -----------
+    --#endregion
+
+    --#endregion
+
+    ------------------
+    --#region SETUP --
+    ------------------
 
     -- get the parent window
     self.p_window = args.window
@@ -430,9 +437,11 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         self.id = args.parent.__add_child(args.id, protected)
     end
 
-    ----------------------
-    -- PUBLIC FUNCTIONS --
-    ----------------------
+    --#endregion
+
+    -----------------------------
+    --#region PUBLIC FUNCTIONS --
+    -----------------------------
 
     -- get the window object
     ---@nodiscard
@@ -474,7 +483,7 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         end
     end
 
-    -- ELEMENT TREE --
+    --#region ELEMENT TREE
 
     -- add a child element
     ---@package
@@ -590,14 +599,18 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         else return ({ protected.children[index].get() })[1] end
     end
 
-    -- AUTO-PLACEMENT --
+    --#endregion
+
+    --#region AUTO-PLACEMENT
 
     -- skip a line for automatically placed elements
     function public.line_break()
         self.next_y = self.next_y + 1
     end
 
-    -- PROPERTIES --
+    --#endregion
+
+    --#region PROPERTIES
 
     -- get element ID
     ---@nodiscard
@@ -724,7 +737,9 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         self.bounds.y2 = self.position.y + protected.frame.h - 1
     end
 
-    -- FUNCTION CALLBACKS --
+    --#endregion
+
+    --#region FUNCTION CALLBACKS
 
     -- handle a monitor touch or mouse click if this element is visible
     ---@param event mouse_interaction mouse interaction event
@@ -799,7 +814,9 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         ps.subscribe(key, func)
     end
 
-    -- VISIBILITY & ANIMATIONS --
+    --#endregion
+
+    --#region VISIBILITY & ANIMATIONS
 
     -- check if this element is visible
     function public.is_visible() return protected.window.isVisible() end
@@ -865,6 +882,10 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         end
     end
 
+    --#endregion
+
+    --#endregion
+
     return protected
 end
 

graphics/elements/controls/App.lua

@@ -20,7 +20,7 @@ local MOUSE_CLICK = core.events.MOUSE_CLICK
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- Create a new 'app' style button control element, like on a phone.
+-- Create a new app icon style button control element, like on a mobile device.
 ---@param args app_button_args
 ---@return App element, element_id id
 return function (args)

graphics/elements/controls/Radio2D.lua

@@ -23,7 +23,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- Create a new 2D radio button list control element (latch selection, exclusively one color at a time).
+-- Create a new 2-dimensional (rows and columns of options) radio button list control element (latch selection, exclusively one color at a time).
 ---@param args radio_2d_args
 ---@return Radio2D element, element_id id
 return function (args)

graphics/elements/indicators/CoreMap.lua

@@ -13,7 +13,7 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer auto incremented if omitted
 
--- Create a new core map box element.
+-- Create a new core map diagram indicator element.
 ---@nodiscard
 ---@param args core_map_args
 ---@return CoreMap element, element_id id

reactor-plc/config/system.lua

@@ -63,7 +63,7 @@ local system = {}
 ---@param tool_ctl _plc_cfg_tool_ctl
 ---@param main_pane graphics_element
 ---@param cfg_sys [ plc_config, plc_config, plc_config, table, function ]
----@param divs graphics_element[]
+---@param divs Div[]
 ---@param style { [string]: cpair }
 ---@param exit function
 function system.create(tool_ctl, main_pane, cfg_sys, divs, style, exit)

scada-common/log.lua

@@ -18,7 +18,7 @@ local logger = {
     mode = MODE.APPEND,
     debug = false,
     file = nil,         ---@type table|nil
-    dmesg_out = nil,    ---@type table|nil
+    dmesg_out = nil,    ---@type Redirect|nil
     dmesg_restore_coord = { 1, 1 },
     dmesg_scroll_count = 0
 }
@@ -80,7 +80,7 @@ end
 ---@param path string file path
 ---@param write_mode MODE file write mode
 ---@param include_debug boolean whether or not to include debug logs
----@param dmesg_redirect? table terminal/window to direct dmesg to
+---@param dmesg_redirect? Redirect terminal/window to direct dmesg to
 function log.init(path, write_mode, include_debug, dmesg_redirect)
     logger.path = path
     logger.mode = write_mode
@@ -107,7 +107,7 @@ function log.close()
 end
 
 -- direct dmesg output to a monitor/window
----@param window table window or terminal reference
+---@param window Window window or terminal reference
 function log.direct_dmesg(window) logger.dmesg_out = window end
 
 -- dmesg style logging for boot because I like linux-y things

supervisor/facility.lua

@@ -105,11 +105,11 @@ function facility.new(config)
         sps_low_power = false,
         disabled_sps = false,
         -- alarm tones
-        tone_states = {},       ---@type boolean[]
+        tone_states = {},       ---@type { [TONE]: boolean }
         test_tone_set = false,
         test_tone_reset = false,
-        test_tone_states = {},  ---@type boolean[]
-        test_alarm_states = {}, ---@type boolean[]
+        test_tone_states = {},  ---@type { [TONE]: boolean }
+        test_alarm_states = {}, ---@type { [ALARM]: boolean }
         -- statistics
         im_stat_init = false,
         avg_charge = util.mov_avg(3),  -- 3 seconds

supervisor/session/svsessions.lua

@@ -56,8 +56,8 @@ local self = {
     next_ids = { rtu = 0, plc = 0, crd = 0, pdg = 0 },
     -- rtu device tracking and invalid assignment detection
     dev_dbg = {
-        duplicate = {},     ---@type unit_session
-        out_of_range = {},  ---@type unit_session
+        duplicate = {},     ---@type unit_session[]
+        out_of_range = {},  ---@type unit_session[]
         connected = {}      ---@type { induction: boolean, sps: boolean, tanks: boolean[], units: unit_connections[] }
     }
 }