From 69855af86117ae462b76ad499fef3510d71383c8 Mon Sep 17 00:00:00 2001 From: Mikayla Date: Thu, 26 Sep 2024 21:00:57 +0000 Subject: [PATCH] updated type hints and comments --- graphics/element.lua | 59 ++++++++++++++++-------- graphics/elements/controls/App.lua | 2 +- graphics/elements/controls/Radio2D.lua | 2 +- graphics/elements/indicators/CoreMap.lua | 2 +- reactor-plc/config/system.lua | 2 +- scada-common/log.lua | 6 +-- supervisor/facility.lua | 6 +-- supervisor/session/svsessions.lua | 4 +- 8 files changed, 52 insertions(+), 31 deletions(-) diff --git a/graphics/element.lua b/graphics/element.lua index ff93414..0d6800a 100644 --- a/graphics/element.lua +++ b/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 diff --git a/graphics/elements/controls/App.lua b/graphics/elements/controls/App.lua index fb8ac49..2d6ca01 100644 --- a/graphics/elements/controls/App.lua +++ b/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) diff --git a/graphics/elements/controls/Radio2D.lua b/graphics/elements/controls/Radio2D.lua index 9d60ec9..cf2da34 100644 --- a/graphics/elements/controls/Radio2D.lua +++ b/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) diff --git a/graphics/elements/indicators/CoreMap.lua b/graphics/elements/indicators/CoreMap.lua index fcc22de..071fdc0 100644 --- a/graphics/elements/indicators/CoreMap.lua +++ b/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 diff --git a/reactor-plc/config/system.lua b/reactor-plc/config/system.lua index d2e5023..74e2e88 100644 --- a/reactor-plc/config/system.lua +++ b/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) diff --git a/scada-common/log.lua b/scada-common/log.lua index c416d9c..1b36385 100644 --- a/scada-common/log.lua +++ b/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 diff --git a/supervisor/facility.lua b/supervisor/facility.lua index f61e280..3ec2b82 100644 --- a/supervisor/facility.lua +++ b/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 diff --git a/supervisor/session/svsessions.lua b/supervisor/session/svsessions.lua index df480c4..6090eff 100644 --- a/supervisor/session/svsessions.lua +++ b/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[] } } }