#545 pocket type annotation updates

graphics/elements/controls/sidebar.lua

@@ -129,8 +129,14 @@ local function sidebar(args)
     end
 
     -- update the sidebar navigation options
-    ---@param items table sidebar entries
+    ---@param items sidebar_entry[] sidebar entries
     function e.on_update(items)
+        ---@class sidebar_entry
+        ---@field label string
+        ---@field tall boolean
+        ---@field color cpair
+        ---@field callback function|nil
+
         local next_y = 1
 
         tabs = {}

pocket/iocontrol.lua

@@ -39,15 +39,6 @@ local io = {
     ps = psil.create()
 }
 
--- luacheck: no unused args
-
--- placeholder acknowledge function for type hinting
----@param success boolean
----@diagnostic disable-next-line: unused-local
-local function __generic_ack(success) end
-
--- luacheck: unused args
-
 local config = nil  ---@type pkt_config
 local comms  = nil  ---@type pocket_comms
 
@@ -93,9 +84,9 @@ function iocontrol.init_core(pkt_comms, nav, cfg)
         get_tone_states = function () comms.diag__get_alarm_tones() end,
 
         ready_warn = nil,       ---@type graphics_element
-        tone_buttons = {},
+        tone_buttons = {},      ---@type graphics_element[]
-        alarm_buttons = {},
+        alarm_buttons = {},     ---@type graphics_element[]
-        tone_indicators = {}    -- indicators to update from supervisor tone states
+        tone_indicators = {}    ---@type graphics_element[] indicators to update from supervisor tone states
     }
 
     -- API access
@@ -166,24 +157,21 @@ function iocontrol.init_fac(conf)
 
         radiation = types.new_zero_radiation_reading(),
 
-        start_ack = __generic_ack,
+        start_ack = nil,         ---@type fun(success: boolean)
-        stop_ack = __generic_ack,
+        stop_ack = nil,          ---@type fun(success: boolean)
-        scram_ack = __generic_ack,
+        scram_ack = nil,         ---@type fun(success: boolean)
-        ack_alarms_ack = __generic_ack,
+        ack_alarms_ack = nil,    ---@type fun(success: boolean)
 
         ps = psil.create(),
 
-        induction_ps_tbl = {},
+        induction_ps_tbl = {},   ---@type psil[]
-        induction_data_tbl = {},
+        induction_data_tbl = {}, ---@type imatrix_session_db[]
 
-        sps_ps_tbl = {},
+        sps_ps_tbl = {},         ---@type psil[]
-        sps_data_tbl = {},
+        sps_data_tbl = {},       ---@type sps_session_db[]
 
-        tank_ps_tbl = {},
+        tank_ps_tbl = {},        ---@type psil[]
-        tank_data_tbl = {},
+        tank_data_tbl = {}       ---@type dynamicv_session_db[]
-
-        env_d_ps = psil.create(),
-        env_d_data = {}
     }
 
     -- create induction and SPS tables (currently only 1 of each is supported)
@@ -192,107 +180,14 @@ function iocontrol.init_fac(conf)
     table.insert(io.facility.sps_ps_tbl, psil.create())
     table.insert(io.facility.sps_data_tbl, {})
 
-    -- determine tank information
-    if io.facility.tank_mode == 0 then
-        io.facility.tank_defs = {}
-        -- on facility tank mode 0, setup tank defs to match unit tank option
-        for i = 1, conf.num_units do
-            io.facility.tank_defs[i] = util.trinary(conf.cooling.r_cool[i].TankConnection, 1, 0)
-        end
-
-        io.facility.tank_list = { table.unpack(io.facility.tank_defs) }
-    else
-        -- decode the layout of tanks from the connections definitions
-        local tank_mode = io.facility.tank_mode
-        local tank_defs = io.facility.tank_defs
-        local tank_list = { table.unpack(tank_defs) }
-
-        local function calc_fdef(start_idx, end_idx)
-            local first = 4
-            for i = start_idx, end_idx do
-                if io.facility.tank_defs[i] == 2 then
-                    if i < first then first = i end
-                end
-            end
-            return first
-        end
-
-        if tank_mode == 1 then
-            -- (1) 1 total facility tank (A A A A)
-            local first_fdef = calc_fdef(1, #tank_defs)
-            for i = 1, #tank_defs do
-                if i > first_fdef and tank_defs[i] == 2 then
-                    tank_list[i] = 0
-                end
-            end
-        elseif tank_mode == 2 then
-            -- (2) 2 total facility tanks (A A A B)
-            local first_fdef = calc_fdef(1, math.min(3, #tank_defs))
-            for i = 1, #tank_defs do
-                if (i ~= 4) and (i > first_fdef) and (tank_defs[i] == 2) then
-                    tank_list[i] = 0
-                end
-            end
-        elseif tank_mode == 3 then
-            -- (3) 2 total facility tanks (A A B B)
-            for _, a in pairs({ 1, 3 }) do
-                local b = a + 1
-                if (tank_defs[a] == 2) and (tank_defs[b] == 2) then
-                    tank_list[b] = 0
-                end
-            end
-        elseif tank_mode == 4 then
-            -- (4) 2 total facility tanks (A B B B)
-            local first_fdef = calc_fdef(2, #tank_defs)
-            for i = 1, #tank_defs do
-                if (i ~= 1) and (i > first_fdef) and (tank_defs[i] == 2) then
-                    tank_list[i] = 0
-                end
-            end
-        elseif tank_mode == 5 then
-            -- (5) 3 total facility tanks (A A B C)
-            local first_fdef = calc_fdef(1, math.min(2, #tank_defs))
-            for i = 1, #tank_defs do
-                if (not (i == 3 or i == 4)) and (i > first_fdef) and (tank_defs[i] == 2) then
-                    tank_list[i] = 0
-                end
-            end
-        elseif tank_mode == 6 then
-            -- (6) 3 total facility tanks (A B B C)
-            local first_fdef = calc_fdef(2, math.min(3, #tank_defs))
-            for i = 1, #tank_defs do
-                if (not (i == 1 or i == 4)) and (i > first_fdef) and (tank_defs[i] == 2) then
-                    tank_list[i] = 0
-                end
-            end
-        elseif tank_mode == 7 then
-            -- (7) 3 total facility tanks (A B C C)
-            local first_fdef = calc_fdef(3, #tank_defs)
-            for i = 1, #tank_defs do
-                if (not (i == 1 or i == 2)) and (i > first_fdef) and (tank_defs[i] == 2) then
-                    tank_list[i] = 0
-                end
-            end
-        end
-
-        io.facility.tank_list = tank_list
-    end
-
-    -- create facility tank tables
-    for i = 1, #io.facility.tank_list do
-        if io.facility.tank_list[i] == 2 then
-            table.insert(io.facility.tank_ps_tbl, psil.create())
-            table.insert(io.facility.tank_data_tbl, {})
-        end
-    end
-
     -- create unit data structures
-    io.units = {}
+    io.units = {}   ---@type pioctl_unit[]
     for i = 1, conf.num_units do
         ---@class pioctl_unit
         local entry = {
             unit_id = i,
             connected = false,
+            ---@type { boilers: { connected: boolean, faulted: boolean }[], turbines: { connected: boolean, faulted: boolean }[] }
             rtu_hw = {},
 
             num_boilers = 0,
@@ -323,27 +218,27 @@ function iocontrol.init_fac(conf)
             ack_alarms = function () process.ack_all_alarms(i) end,
             set_burn = function (rate) process.set_rate(i, rate) end,   ---@param rate number burn rate
 
-            start_ack = __generic_ack,
+            start_ack = nil,        ---@type fun(success: boolean)
-            scram_ack = __generic_ack,
+            scram_ack = nil,        ---@type fun(success: boolean)
-            reset_rps_ack = __generic_ack,
+            reset_rps_ack = nil,    ---@type fun(success: boolean)
-            ack_alarms_ack = __generic_ack,
+            ack_alarms_ack = nil,   ---@type fun(success: boolean)
 
             ---@type alarms
             alarms = { ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE, ALARM_STATE.INACTIVE },
 
-            annunciator = {},   ---@type annunciator
+            annunciator = {},       ---@type annunciator
 
             unit_ps = psil.create(),
-            reactor_data = {},  ---@type reactor_db
+            reactor_data = {},      ---@type reactor_db
 
-            boiler_ps_tbl = {},
+            boiler_ps_tbl = {},     ---@type psil[]
-            boiler_data_tbl = {},
+            boiler_data_tbl = {},   ---@type boilerv_session_db[]
 
-            turbine_ps_tbl = {},
+            turbine_ps_tbl = {},    ---@type psil[]
-            turbine_data_tbl = {},
+            turbine_data_tbl = {},  ---@type turbinev_session_db[]
 
-            tank_ps_tbl = {},
+            tank_ps_tbl = {},       ---@type psil[]
-            tank_data_tbl = {}
+            tank_data_tbl = {}      ---@type dynamicv_session_db[]
         }
 
         -- on other facility modes, overwrite unit TANK option with facility tank defs
@@ -485,7 +380,7 @@ end
 -- update unit status data from API_GET_UNIT
 ---@param data table
 function iocontrol.record_unit_data(data)
-    local unit = io.units[data[1]]  ---@type pioctl_unit
+    local unit = io.units[data[1]]
 
     unit.connected = data[2]
     unit.rtu_hw = data[3]
@@ -650,8 +545,8 @@ function iocontrol.record_unit_data(data)
     unit.boiler_data_tbl = data[8]
 
     for id = 1, #unit.boiler_data_tbl do
-        local boiler = unit.boiler_data_tbl[id] ---@type boilerv_session_db
+        local boiler = unit.boiler_data_tbl[id]
-        local ps     = unit.boiler_ps_tbl[id]   ---@type psil
+        local ps     = unit.boiler_ps_tbl[id]
 
         local boiler_status = 1
         local computed_status = 1
@@ -683,8 +578,8 @@ function iocontrol.record_unit_data(data)
     unit.turbine_data_tbl = data[9]
 
     for id = 1, #unit.turbine_data_tbl do
-        local turbine = unit.turbine_data_tbl[id] ---@type turbinev_session_db
+        local turbine = unit.turbine_data_tbl[id]
-        local ps      = unit.turbine_ps_tbl[id]   ---@type psil
+        local ps      = unit.turbine_ps_tbl[id]
 
         local turbine_status = 1
         local computed_status = 1

pocket/pocket.lua

@@ -100,22 +100,22 @@ pocket.APP_ID = APP_ID
 
 ---@class nav_tree_page
 ---@field _p nav_tree_page|nil page's parent
----@field _c table page's children
+---@field _c nav_tree_page[] page's children
 ---@field nav_to function function to navigate to this page
 ---@field switcher function|nil function to switch between children
----@field tasks table tasks to run while viewing this page
+---@field tasks function[] tasks to run while viewing this page
 
 -- initialize the page navigation system
 ---@param smem pkt_shared_memory
 function pocket.init_nav(smem)
     local self = {
-        pane = nil,    ---@type graphics_element
+        pane = nil,          ---@type graphics_element
-        sidebar = nil, ---@type graphics_element
+        sidebar = nil,       ---@type graphics_element
-        apps = {},
+        apps = {},           ---@type pocket_app[]
-        containers = {},
+        containers = {},     ---@type graphics_element[]
-        help_map = {},
+        help_map = {},       ---@type { [string]: function }
-        help_return = nil,
+        help_return = nil,   ---@type POCKET_APP_ID|nil
-        loader_return = nil,
+        loader_return = nil, ---@type POCKET_APP_ID|nil
         cur_app = APP_ID.ROOT
     }
 
@@ -142,10 +142,10 @@ function pocket.init_nav(smem)
         ---@class pocket_app
         local app = {
             loaded = false,
-            cur_page = nil, ---@type nav_tree_page
+            cur_page = nil,    ---@type nav_tree_page
             pane = pane,
-            paned_pages = {},
+            paned_pages = {},  ---@type nav_tree_page[]
-            sidebar_items = {}
+            sidebar_items = {} ---@type sidebar_entry[]
         }
 
         app.load = function () app.loaded = true end
@@ -165,7 +165,7 @@ function pocket.init_nav(smem)
         end
 
         -- configure the sidebar
-        ---@param items table
+        ---@param items sidebar_entry[]
         function app.set_sidebar(items)
             app.sidebar_items = items
             if self.sidebar then self.sidebar.update(items) end
@@ -263,7 +263,7 @@ function pocket.init_nav(smem)
         -- reset help return on navigating out of an app
         if app_id == APP_ID.ROOT then self.help_return = nil end
 
-        local app = self.apps[app_id] ---@type pocket_app
+        local app = self.apps[app_id]
         if app then
             if app.requires_conn() and not smem.pkt_sys.pocket_comms.is_linked() then
                 -- bring up the app loader
@@ -339,7 +339,7 @@ function pocket.init_nav(smem)
             return
         end
 
-        local app = self.apps[self.cur_app] ---@type pocket_app
+        local app = self.apps[self.cur_app]
         log.debug("attempting app nav up for app " .. self.cur_app)
 
         if not app.nav_up() then
@@ -359,6 +359,7 @@ function pocket.init_nav(smem)
     end
 
     -- link the help map from the guide app
+    ---@param map { [string]: function }
     function nav.link_help(map) self.help_map = map end
 
     return nav

pocket/startup.lua

@@ -20,7 +20,7 @@ local pocket    = require("pocket.pocket")
 local renderer  = require("pocket.renderer")
 local threads   = require("pocket.threads")
 
-local POCKET_VERSION = "v0.12.1-alpha"
+local POCKET_VERSION = "v0.12.2-alpha"
 
 local println = util.println
 local println_ts = util.println_ts

pocket/ui/apps/control.lua

@@ -108,7 +108,7 @@ local function new_view(root)
         for i = 1, db.facility.num_units do
             local u_pane = panes[i]
             local u_div = Div{parent=u_pane,x=2,width=main.get_width()-2}
-            local unit = db.units[i] ---@type pioctl_unit
+            local unit = db.units[i]
             local u_ps = unit.unit_ps
 
             -- refresh data callback, every 500ms it will re-send the query

pocket/ui/apps/guide.lua

@@ -90,10 +90,9 @@ local function new_view(root)
         local lnk = Div{parent=page_div,x=2,width=p_width}
         local panes = { home, search, use, uis, fps, gls, lnk }
 
-        local doc_map = {}
+        local doc_map = {}   ---@type { [string]: function }
-        local search_db = {}
+        local search_db = {} ---@type [ string, string, string, function ][]
 
-        ---@class _guide_section_constructor_data
         local sect_construct_data = { app, page_div, panes, doc_map, search_db, btn_fg_bg, btn_active }
 
         TextBox{parent=home,y=1,text="cc-mek-scada Guide",alignment=ALIGN.CENTER}
@@ -117,7 +116,7 @@ local function new_view(root)
 
         function func_ref.run_search()
             local query = string.lower(query_field.get_value())
-            local s_results = { {}, {}, {}, {} }
+            local s_results = { {}, {}, {}, {} } ---@type [ string, string, string, function ][][]
 
             search_results.remove_all()
 

pocket/ui/apps/unit.lua

@@ -73,7 +73,7 @@ local function new_view(root)
 
     -- set sidebar to display unit-specific fields based on a specified unit
     local function set_sidebar(id)
-        local unit = db.units[id] ---@type pioctl_unit
+        local unit = db.units[id]
 
         local list = {
             { label = " # ", tall = true, color = core.cpair(colors.black, colors.green), callback = function () db.nav.open_app(APP_ID.ROOT) end },
@@ -127,7 +127,7 @@ local function new_view(root)
         for i = 1, db.facility.num_units do
             local u_pane = panes[i]
             local u_div = Div{parent=u_pane,x=2,width=main.get_width()-2}
-            local unit = db.units[i] ---@type pioctl_unit
+            local unit = db.units[i]
             local u_ps = unit.unit_ps
 
             -- refresh data callback, every 500ms it will re-send the query

pocket/ui/pages/guide_section.lua

@@ -21,14 +21,14 @@ local DOC_TYPE = docs.DOC_ITEM_TYPE
 local LIST_TYPE = docs.DOC_LIST_TYPE
 
 -- new guide documentation section
----@param data _guide_section_constructor_data
+---@param data { [1]: pocket_app, [2]: graphics_element, [3]: graphics_element[], [4]: { [string]: function }, [5]: [ string, string, string, function ][], [6]: cpair, [7]: cpair }
 ---@param base_page nav_tree_page
 ---@param title string
 ---@param items table
 ---@param scroll_height integer
 ---@return nav_tree_page
 return function (data, base_page, title, items, scroll_height)
-    local app, page_div, panes, doc_map, search_db, btn_fg_bg, btn_active = table.unpack(data)
+    local app, page_div, panes, doc_map, search_db, btn_fg_bg, btn_active = data[1], data[2], data[3], data[4], data[5], data[6], data[7]
 
     local section_page = app.new_page(base_page, #panes + 1)
     local section_div = Div{parent=page_div,x=2}

pocket/ui/pages/unit_boiler.lua

@@ -29,7 +29,7 @@ local yel_ind_s = style.icon_states.yel_ind_s
 -- create a boiler view in the unit app
 ---@param app pocket_app
 ---@param u_page nav_tree_page
----@param panes table
+---@param panes graphics_element[]
 ---@param blr_pane graphics_element
 ---@param b_id integer boiler ID
 ---@param ps psil

pocket/ui/pages/unit_reactor.lua

@@ -29,7 +29,7 @@ local yel_ind_s = style.icon_states.yel_ind_s
 -- create a reactor view in the unit app
 ---@param app pocket_app
 ---@param u_page nav_tree_page
----@param panes table
+---@param panes graphics_element[]
 ---@param page_div graphics_element
 ---@param u_ps psil
 ---@param update function

pocket/ui/pages/unit_turbine.lua

@@ -30,7 +30,7 @@ local yel_ind_s = style.icon_states.yel_ind_s
 -- create a turbine view in the unit app
 ---@param app pocket_app
 ---@param u_page nav_tree_page
----@param panes table
+---@param panes graphics_element[]
 ---@param tbn_pane graphics_element
 ---@param u_id integer unit ID
 ---@param t_id integer turbine ID