LuaLS Test

src/elements/BaseElement.lua

@@ -1,7 +1,7 @@
 local PropertySystem = require("propertySystem")
 
 --- The base class for all UI elements in Basalt
--- @module BaseElement
+--- @class BaseElement : PropertySystem
 local BaseElement = setmetatable({}, PropertySystem)
 BaseElement.__index = BaseElement
 BaseElement._events = {}

src/elements/BaseFrame.lua

@@ -1,6 +1,7 @@
 local Container = require("elements/Container")
 local Render = require("render")
 
+---@class BaseFrame : Container
 local BaseFrame = setmetatable({}, Container)
 BaseFrame.__index = BaseFrame
 

src/elements/Button.lua

@@ -1,10 +1,13 @@
 local VisualElement = require("elements/VisualElement")
 local getCenteredPosition = require("libraries/utils").getCenteredPosition
 
+---@class Button : VisualElement
 local Button = setmetatable({}, VisualElement)
 Button.__index = Button
 
 Button.defineProperty(Button, "text", {default = "Button", type = "string"})
+
+---@event mouse_click The event that is triggered when the button is clicked
 Button.listenTo(Button, "mouse_click")
 
 ---@diagnostic disable-next-line: duplicate-set-field

src/elements/Container.lua

@@ -4,6 +4,7 @@ local expect = require("libraries/expect")
 
 local max = math.max
 
+---@class Container : VisualElement
 local Container = setmetatable({}, VisualElement)
 Container.__index = Container
 

src/elements/Frame.lua

@@ -1,9 +1,9 @@
 local Container = require("elements/Container")
 
+---@class Frame : Container
 local Frame = setmetatable({}, Container)
 Frame.__index = Frame
 
----@diagnostic disable-next-line: duplicate-set-field
 function Frame.new(id, basalt)
     local self = setmetatable({}, Frame):__init()
     self:init(id, basalt)

src/elements/VisualElement.lua

@@ -1,10 +1,17 @@
 local BaseElement = require("elements/BaseElement")
+
+---@alias color number
+
+---@class VisualElement : BaseElement
 local VisualElement = setmetatable({}, BaseElement)
 VisualElement.__index = VisualElement
 local tHex = require("libraries/colorHex")
 
+---@property x number 1 x position of the element
 BaseElement.defineProperty(VisualElement, "x", {default = 1, type = "number", canTriggerRender = true})
+---@property y number 1 y position of the element
 BaseElement.defineProperty(VisualElement, "y", {default = 1, type = "number", canTriggerRender = true})
+---@property z number 1 z position of the element
 BaseElement.defineProperty(VisualElement, "z", {default = 1, type = "number", canTriggerRender = true, setter = function(self, value)
     self.basalt.LOGGER.debug("Setting z to " .. value)
     if self.parent then
@@ -12,13 +19,22 @@ BaseElement.defineProperty(VisualElement, "z", {default = 1, type = "number", ca
     end
     return value
 end})
+---@property width number 1 width of the element
 BaseElement.defineProperty(VisualElement, "width", {default = 1, type = "number", canTriggerRender = true})
+---@property height number 1 height of the element
 BaseElement.defineProperty(VisualElement, "height", {default = 1, type = "number", canTriggerRender = true})
+---@property background color black background color of the element
 BaseElement.defineProperty(VisualElement, "background", {default = colors.black, type = "number", canTriggerRender = true})
+---@property foreground color white foreground color of the element
 BaseElement.defineProperty(VisualElement, "foreground", {default = colors.white, type = "number", canTriggerRender = true})
+---@property clicked boolean false element is currently clicked
 BaseElement.defineProperty(VisualElement, "clicked", {default = false, type = "boolean"})
 
----@diagnostic disable-next-line: duplicate-set-field
+--- Creates a new VisualElement instance
+--- @param id string The unique identifier for this element
+--- @param basalt table The basalt instance
+--- @return VisualElement object The newly created VisualElement instance
+--- @usage local element = VisualElement.new("myId", basalt)
 function VisualElement.new(id, basalt)
     local self = setmetatable({}, VisualElement):__init()
     self:init(id, basalt)
@@ -26,18 +42,35 @@ function VisualElement.new(id, basalt)
     return self
 end
 
+--- Draws a text character/fg/bg at the specified position with a certain size, used in the rendering system
+--- @param x number The x position to draw
+--- @param y number The y position to draw
+--- @param width number The width of the element
+--- @param height number The height of the element
+--- @param text string The text char to draw
+--- @param fg color The foreground color
+--- @param bg color The background color
 function VisualElement:multiBlit(x, y, width, height, text, fg, bg)
     x = x + self.get("x") - 1
     y = y + self.get("y") - 1
     self.parent:multiBlit(x, y, width, height, text, fg, bg)
 end
 
+--- Draws a text character at the specified position, used in the rendering system
+--- @param x number The x position to draw
+--- @param y number The y position to draw
+--- @param text string The text char to draw
+--- @param fg color The foreground color
 function VisualElement:textFg(x, y, text, fg)
     x = x + self.get("x") - 1
     y = y + self.get("y") - 1
     self.parent:textFg(x, y, text, fg)
 end
 
+--- Checks if the specified coordinates are within the bounds of the element
+--- @param x number The x position to check
+--- @param y number The y position to check
+--- @return boolean isInBounds Whether the coordinates are within the bounds of the element
 function VisualElement:isInBounds(x, y)
     local xPos, yPos = self.get("x"), self.get("y")
     local width, height = self.get("width"), self.get("height")
@@ -46,6 +79,11 @@ function VisualElement:isInBounds(x, y)
            y >= yPos and y <= yPos + height - 1
 end
 
+--- Handles a mouse click event
+--- @param button number The button that was clicked
+--- @param x number The x position of the click
+--- @param y number The y position of the click
+--- @return boolean clicked Whether the element was clicked
 function VisualElement:mouse_click(button, x, y)
     if self:isInBounds(x, y) then
         self.set("clicked", true)
@@ -74,8 +112,8 @@ function VisualElement:handleEvent(event, ...)
 end
 
 --- Returns the absolute position of the element or the given coordinates.
----@param x? number -- x position
----@param y? number -- y position
+---@param x? number x position
+---@param y? number y position
 function VisualElement:getAbsolutePosition(x, y)
     if (x == nil) or (y == nil) then
         x, y = self.get("x"), self.get("y")
@@ -93,8 +131,8 @@ function VisualElement:getAbsolutePosition(x, y)
 end
 
 --- Returns the relative position of the element or the given coordinates.
----@param x? number -- x position
----@param y? number -- y position
+---@param x? number x position
+---@param y? number y position
 ---@return number, number
 function VisualElement:getRelativePosition(x, y)
     if (x == nil) or (y == nil) then

src/main.lua

@@ -133,7 +133,7 @@ function basalt.stop()
 end
 
 --- Starts the Basalt runtime
---- @param isActive boolean Whether to start active (default: true)
+--- @param isActive? boolean Whether to start active (default: true)
 --- @usage basalt.run()
 --- @usage basalt.run(false)
 function basalt.run(isActive)

src/propertySystem.lua

@@ -1,6 +1,7 @@
 local deepCopy = require("libraries/utils").deepCopy
 local expect = require("libraries/expect")
 
+--- @class PropertySystem
 local PropertySystem = {}
 PropertySystem.__index = PropertySystem