#118 graphics cleanup

graphics/core.lua

@@ -16,6 +16,7 @@ local events = {}
 ---@field y integer
 
 -- create a new touch event definition
+---@nodiscard
 ---@param monitor string
 ---@param x integer
 ---@param y integer
@@ -32,7 +33,7 @@ core.events = events
 
 local graphics = {}
 
----@alias TEXT_ALIGN integer
+---@enum TEXT_ALIGN
 graphics.TEXT_ALIGN = {
     LEFT = 1,
     CENTER = 2,
@@ -47,6 +48,7 @@ graphics.TEXT_ALIGN = {
 ---@alias element_id string|integer
 
 -- create a new border definition
+---@nodiscard
 ---@param width integer border width
 ---@param color color border color
 ---@param even? boolean whether to pad width extra to account for rectangular pixels, defaults to false
@@ -66,6 +68,7 @@ end
 ---@field h integer
 
 -- create a new graphics frame definition
+---@nodiscard
 ---@param x integer
 ---@param y integer
 ---@param w integer
@@ -91,6 +94,7 @@ end
 ---@field blit_bkg string
 
 -- create a new color pair definition
+---@nodiscard
 ---@param a color
 ---@param b color
 ---@return cpair
@@ -120,9 +124,9 @@ end
 ---@field thin boolean true for 1 subpixel, false (default) for 2
 ---@field align_tr boolean false to align bottom left (default), true to align top right
 
--- create a new pipe
+-- create a new pipe<br>
---
 -- note: pipe coordinate origin is (0, 0)
+---@nodiscard
 ---@param x1 integer starting x, origin is 0
 ---@param y1 integer starting y, origin is 0
 ---@param x2 integer ending x, origin is 0

graphics/element.lua

@@ -47,6 +47,7 @@ local element = {}
 ---|tiling_args
 
 -- a base graphics element, should not be created on its own
+---@nodiscard
 ---@param args graphics_args arguments
 function element.new(args)
     local self = {
@@ -172,6 +173,7 @@ function element.new(args)
     end
 
     -- get value
+    ---@nodiscard
     function protected.get_value()
         return protected.value
     end
@@ -218,6 +220,7 @@ function element.new(args)
     end
 
     -- get public interface
+    ---@nodiscard
     ---@return graphics_element element, element_id id
     function protected.get() return public, self.id end
 
@@ -246,11 +249,13 @@ function element.new(args)
     ----------------------
 
     -- get the window object
+    ---@nodiscard
     function public.window() return protected.window end
 
     -- CHILD ELEMENTS --
 
     -- add a child element
+    ---@nodiscard
     ---@param key string|nil id
     ---@param child graphics_template
     ---@return integer|string key
@@ -271,6 +276,7 @@ function element.new(args)
     end
 
     -- get a child element
+    ---@nodiscard
     ---@return graphics_element
     function public.get_child(key) return self.children[key] end
 
@@ -279,6 +285,7 @@ function element.new(args)
     function public.remove(key) self.children[key] = nil end
 
     -- attempt to get a child element by ID (does not include this element itself)
+    ---@nodiscard
     ---@param id element_id
     ---@return graphics_element|nil element
     function public.get_element_by_id(id)
@@ -297,39 +304,49 @@ function element.new(args)
     -- AUTO-PLACEMENT --
 
     -- skip a line for automatically placed elements
-    function public.line_break() self.next_y = self.next_y + 1 end
+    function public.line_break()
+        self.next_y = self.next_y + 1
+    end
 
     -- PROPERTIES --
 
     -- get the foreground/background colors
+    ---@nodiscard
     ---@return cpair fg_bg
-    function public.get_fg_bg() return protected.fg_bg end
+    function public.get_fg_bg()
+        return protected.fg_bg
+    end
 
     -- get element x
+    ---@nodiscard
     ---@return integer x
     function public.get_x()
         return protected.frame.x
     end
 
     -- get element y
+    ---@nodiscard
     ---@return integer y
     function public.get_y()
         return protected.frame.y
     end
 
     -- get element width
+    ---@nodiscard
     ---@return integer width
     function public.width()
         return protected.frame.w
     end
 
     -- get element height
+    ---@nodiscard
     ---@return integer height
     function public.height()
         return protected.frame.h
     end
 
     -- get the element value
+    ---@nodiscard
     ---@return any value
     function public.get_value()
         return protected.get_value()

graphics/elements/displaybox.lua

@@ -12,6 +12,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new root display box
+---@nodiscard
 ---@param args displaybox_args
 local function displaybox(args)
     -- create new graphics element base object

graphics/elements/div.lua

@@ -13,6 +13,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new div element
+---@nodiscard
 ---@param args div_args
 ---@return graphics_element element, element_id id
 local function div(args)

graphics/elements/indicators/alight.lua

@@ -20,6 +20,7 @@ local flasher = require("graphics.flasher")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new alarm indicator light
+---@nodiscard
 ---@param args alarm_indicator_light
 ---@return graphics_element element, element_id id
 local function alarm_indicator_light(args)

graphics/elements/indicators/coremap.lua

@@ -14,6 +14,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 
 -- new core map box
+---@nodiscard
 ---@param args core_map_args
 ---@return graphics_element element, element_id id
 local function core_map(args)

graphics/elements/indicators/data.lua

@@ -19,6 +19,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new data indicator
+---@nodiscard
 ---@param args data_indicator_args
 ---@return graphics_element element, element_id id
 local function data(args)

graphics/elements/indicators/hbar.lua

@@ -17,6 +17,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new horizontal bar
+---@nodiscard
 ---@param args hbar_args
 ---@return graphics_element element, element_id id
 local function hbar(args)

graphics/elements/indicators/icon.lua

@@ -20,6 +20,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new icon indicator
+---@nodiscard
 ---@param args icon_indicator_args
 ---@return graphics_element element, element_id id
 local function icon(args)

graphics/elements/indicators/light.lua

@@ -18,6 +18,7 @@ local flasher = require("graphics.flasher")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new indicator light
+---@nodiscard
 ---@param args indicator_light_args
 ---@return graphics_element element, element_id id
 local function indicator_light(args)

graphics/elements/indicators/power.lua

@@ -18,6 +18,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new power indicator
+---@nodiscard
 ---@param args power_indicator_args
 ---@return graphics_element element, element_id id
 local function power(args)

graphics/elements/indicators/rad.lua

@@ -19,6 +19,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new radiation indicator
+---@nodiscard
 ---@param args rad_indicator_args
 ---@return graphics_element element, element_id id
 local function rad(args)

graphics/elements/indicators/state.lua

@@ -20,6 +20,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new state indicator
+---@nodiscard
 ---@param args state_indicator_args
 ---@return graphics_element element, element_id id
 local function state_indicator(args)

graphics/elements/indicators/trilight.lua

@@ -20,6 +20,7 @@ local flasher = require("graphics.flasher")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new tri-state indicator light
+---@nodiscard
 ---@param args tristate_indicator_light_args
 ---@return graphics_element element, element_id id
 local function tristate_indicator_light(args)

graphics/elements/indicators/vbar.lua

@@ -15,6 +15,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 
 -- new vertical bar
+---@nodiscard
 ---@param args vbar_args
 ---@return graphics_element element, element_id id
 local function vbar(args)

graphics/elements/rectangle.lua

@@ -144,7 +144,7 @@ local function rectangle(args)
                     e.window.blit(spaces, blit_fg, blit_bg_top_bot)
                 end
             else
-                if (args.thin == true) then
+                if args.thin == true then
                     e.window.blit(p_s, blit_fg_sides, blit_bg_sides)
                 else
                     e.window.blit(p_s, blit_fg, blit_bg_sides)

graphics/elements/tiling.lua

@@ -60,7 +60,7 @@ local function tiling(args)
     -- create pattern
     for y = start_y, inner_height + (start_y - 1) do
         e.window.setCursorPos(start_x, y)
-        for x = 1, inner_width do
+        for _ = 1, inner_width do
             if alternator then
                 if even then
                     e.window.blit("  ", "00", fill_a .. fill_a)

graphics/flasher.lua

@@ -21,8 +21,7 @@ local active = false
 local registry = { {}, {}, {} } -- one registry table per period
 local callback_counter = 0
 
--- blink registered indicators
+-- blink registered indicators<br>
---
 -- this assumes it is called every 250ms, it does no checking of time on its own
 local function callback_250ms()
     if active then
@@ -55,8 +54,7 @@ function flasher.clear()
     registry = { {}, {}, {} }
 end
 
--- register a function to be called on the selected blink period
+-- register a function to be called on the selected blink period<br>
---
 -- times are not strictly enforced, but all with a given period will be set at the same time
 ---@param f function function to call each period
 ---@param period PERIOD time period option (1, 2, or 3)