Changes

Author: NoryiE

src/elements/BarChart.lua

@@ -3,13 +3,17 @@ local VisualElement = elementManager.getElement("VisualElement")
 local BaseGraph = elementManager.getElement("Graph")
 local tHex = require("libraries/colorHex")
 --- @configDescription A bar chart element based on the graph element.
----@configDefault false
+--- @configDefault false
 
---- The Bar Chart element is designed for visualizing data series as vertical bars. It displays multiple values as side-by-side bars where each bar's height represents its value.
+--- A data visualization element that represents numeric data through vertical bars. Each bar's height corresponds to its value, making it ideal for comparing quantities across categories or showing data changes over time. Supports multiple data series with customizable colors and styles.
+--- @usage -- Create a bar chart
 --- @usage local chart = main:addBarChart()
---- @usage :addSeries("input", " ", colors.green, colors.green, 5)
---- @usage :addSeries("output", " ", colors.red, colors.red, 5)
 --- @usage 
+--- @usage -- Add two data series with different colors
+--- @usage chart:addSeries("input", " ", colors.green, colors.green, 5)
+--- @usage chart:addSeries("output", " ", colors.red, colors.red, 5)
+--- @usage 
+--- @usage -- Continuously update the chart with random data
 --- @usage basalt.schedule(function()
 --- @usage     while true do
 --- @usage         chart:addPoint("input", math.random(1,100))
@@ -42,7 +46,8 @@ function BarChart:init(props, basalt)
     return self
 end
 
---- @shortDescription Renders the BarChart
+--- Renders the bar chart by calculating bar positions and heights based on data values
+--- @shortDescription Draws bars for each data point in visible series
 --- @protected
 function BarChart:render()
     VisualElement.render(self)

src/elements/BaseElement.lua

@@ -3,12 +3,12 @@ local uuid = require("libraries/utils").uuid
 local errorManager = require("errorManager")
 ---@configDescription The base class for all UI elements in Basalt.
 
---- The base class for all UI elements in Basalt. This class provides basic properties and event handling functionality.
+--- The fundamental base class for all UI elements in Basalt. It implements core functionality like event handling, property management, lifecycle hooks, and the observer pattern. Every UI component inherits from this class to ensure consistent behavior and interface.
 --- @class BaseElement : PropertySystem
 local BaseElement = setmetatable({}, PropertySystem)
 BaseElement.__index = BaseElement
 
---- @property type string BaseElement The type identifier of the element
+--- @property type string BaseElement A hierarchical identifier of the element's type chain
 BaseElement.defineProperty(BaseElement, "type", {default = {"BaseElement"}, type = "string", setter=function(self, value)
     if type(value) == "string" then
         table.insert(self._values.type, 1, value)
@@ -22,19 +22,19 @@ end, getter = function(self, _, index)
     return self._values.type[index or 1]
 end})
 
---- @property id string BaseElement The unique identifier for the element
+--- @property id string BaseElement Auto-generated unique identifier for element lookup
 BaseElement.defineProperty(BaseElement, "id", {default = "", type = "string", readonly = true})
 
---- @property name string BaseElement The name of the element
+--- @property name string BaseElement User-defined name for the element
 BaseElement.defineProperty(BaseElement, "name", {default = "", type = "string"})
 
---- @property eventCallbacks table BaseElement The event callbacks for the element
+--- @property eventCallbacks table BaseElement Collection of registered event handler functions
 BaseElement.defineProperty(BaseElement, "eventCallbacks", {default = {}, type = "table"})
 
---- @property enabled boolean BaseElement Whether the element is enabled or not
+--- @property enabled boolean BaseElement Controls event processing for this element
 BaseElement.defineProperty(BaseElement, "enabled", {default = true, type = "boolean" })
 
---- Registers a new event listener for the element (on class level)
+--- Registers a class-level event listener with optional dependency
 --- @shortDescription Registers a new event listener for the element (on class level)
 --- @param class table The class to register
 --- @param eventName string The name of the event to register
@@ -49,8 +49,8 @@ function BaseElement.defineEvent(class, eventName, requiredEvent)
     }
 end
 
---- Registers a new event callback for the element (on class level)
---- @shortDescription Registers a new event callback for the element (on class level)
+--- Defines a class-level event callback method with automatic event registration
+--- @shortDescription Registers a new event callback method with auto-registration
 --- @param class table The class to register
 --- @param callbackName string The name of the callback to register
 --- @param ... string The names of the events to register the callback for
@@ -143,8 +143,8 @@ function BaseElement:postInit()
     return self
 end
 
---- Checks if the element is a specific type
---- @shortDescription Checks if the element is a specific type
+--- Checks if the element matches or inherits from the specified type
+--- @shortDescription Tests if element is of or inherits given type
 --- @param type string The type to check for
 --- @return boolean isType Whether the element is of the specified type
 function BaseElement:isType(type)
@@ -156,8 +156,8 @@ function BaseElement:isType(type)
     return false
 end
 
---- Enables or disables event listening for a specific event
---- @shortDescription Enables or disables event listening for a specific event
+--- Configures event listening behavior with automatic parent notification
+--- @shortDescription Enables/disables event handling for this element
 --- @param eventName string The name of the event to listen for
 --- @param enable? boolean Whether to enable or disable the event (default: true)
 --- @return table self The BaseElement instance
@@ -179,8 +179,8 @@ function BaseElement:listenEvent(eventName, enable)
     return self
 end
 
---- Registers a callback function for an event
---- @shortDescription Registers a callback function
+--- Adds an event handler function with automatic event registration
+--- @shortDescription Registers a function to handle specific events
 --- @param event string The event to register the callback for
 --- @param callback function The callback function to register
 --- @return table self The BaseElement instance
@@ -197,8 +197,8 @@ function BaseElement:registerCallback(event, callback)
     return self
 end
 
---- Triggers an event and calls all registered callbacks
---- @shortDescription Triggers an event and calls all registered callbacks
+--- Executes all registered callbacks for the specified event
+--- @shortDescription Triggers event callbacks with provided arguments
 --- @param event string The event to fire
 --- @param ... any Additional arguments to pass to the callbacks
 --- @return table self The BaseElement instance
@@ -236,8 +236,8 @@ function BaseElement:handleEvent(event, ...)
     return false
 end
 
---- Observes a property and calls a callback when it changes
---- @shortDescription Observes a property and calls a callback when it changes
+--- Sets up a property change observer with immediate callback registration
+--- @shortDescription Watches property changes with callback notification
 --- @param property string The property to observe
 --- @param callback function The callback to call when the property changes
 --- @return table self The BaseElement instance
@@ -246,8 +246,8 @@ function BaseElement:onChange(property, callback)
     return self
 end
 
---- Returns the base frame of the element
---- @shortDescription Returns the base frame of the element
+--- Traverses parent chain to locate the root frame element
+--- @shortDescription Retrieves the root frame of this element's tree
 --- @return BaseFrame BaseFrame The base frame of the element
 function BaseElement:getBaseFrame()
     if self.parent then
@@ -256,8 +256,8 @@ function BaseElement:getBaseFrame()
     return self
 end
 
---- Destroys the element and cleans up all references
---- @shortDescription Destroys the element and cleans up all references
+--- Removes the element from UI tree and cleans up resources
+--- @shortDescription Removes element and performs cleanup
 function BaseElement:destroy()
     if(self.parent) then
         self.parent:removeChild(self)
@@ -267,8 +267,8 @@ function BaseElement:destroy()
     self:setFocused(false)
 end
 
---- Requests a render update for this element
---- @shortDescription Requests a render update for this element
+--- Propagates render request up the element tree
+--- @shortDescription Requests UI update for this element
 --- @return table self The BaseElement instance
 function BaseElement:updateRender()
     if(self.parent) then

src/elements/BaseFrame.lua

@@ -5,7 +5,7 @@ local Render = require("render")
 ---@configDescription This is the base frame class. It is the root element of all elements and the only element without a parent.
 
 
---- This is the base frame class. It is the root element of all elements and the only element without a parent.
+--- This is the root frame class that serves as the foundation for the UI hierarchy. It manages the rendering context and acts as the top-level container for all other elements. Unlike other elements, it renders directly to a terminal or monitor and does not require a parent element.
 ---@class BaseFrame : Container
 ---@field _render Render The render object
 ---@field _renderUpdate boolean Whether the render object needs to be updated
@@ -110,22 +110,31 @@ function BaseFrame:textBg(x, y, text, bg)
     self._render:textBg(x, y, text, bg)
 end
 
---- @shortDescription Renders a text with a background color to the render Object
+--- @shortDescription Draws plain text to the render Object
 --- @param x number The x position to render to
 --- @param y number The y position to render to
 --- @param text string The text to render
---- @param bg colors The background color
 --- @protected
 function BaseFrame:drawText(x, y, text)
     if x < 1 then text = string.sub(text, 1 - x); x = 1 end
     self._render:text(x, y, text)
 end
 
+--- @shortDescription Draws a foreground color to the render Object
+--- @param x number The x position to render to
+--- @param y number The y position to render to
+--- @param fg colors The foreground color
+--- @protected
 function BaseFrame:drawFg(x, y, fg)
     if x < 1 then fg = string.sub(fg, 1 - x); x = 1 end
     self._render:fg(x, y, fg)
 end
 
+--- @shortDescription Draws a background color to the render Object
+--- @param x number The x position to render to
+--- @param y number The y position to render to
+--- @param bg colors The background color
+--- @protected
 function BaseFrame:drawBg(x, y, bg)
     if x < 1 then bg = string.sub(bg, 1 - x); x = 1 end
     self._render:bg(x, y, bg)

src/elements/BigFont.lua

@@ -145,22 +145,34 @@ local VisualElement = elementManager.getElement("VisualElement")
 ---@cofnigDescription The BigFont is a text element that displays large text.
 ---@configDefault false
 
---- The BigFont element is a text element that displays larger text. It uses Wojbie's BigFont API to render the text in a larger font size. Credits to Wojbie for the original API.
---- @run local basalt = require("basalt")
---- @run local main = basalt.getMainFrame()
---- @run local font = main:addBigFont()
---- @run font:setText("Hello World!")
---- @run basalt.run()
+--- A specialized text element that renders characters in larger sizes using Wojbie's BigFont API. Supports multiple font sizes and custom colors while maintaining the pixel-art style of ComputerCraft. Ideal for headers, titles, and emphasis text.
+--- @usage -- Create a large welcome message
+--- @usage local main = basalt.getMainFrame()
+--- @usage local title = main:addBigFont()
+--- @usage     :setPosition(3, 3)
+--- @usage     :setFontSize(2)  -- Makes text twice as large
+--- @usage     :setText("Welcome!")
+--- @usage     :setForeground(colors.yellow)  -- Make text yellow
+--- @usage
+--- @usage -- For animated text
+--- @usage basalt.schedule(function()
+--- @usage     while true do
+--- @usage         title:setForeground(colors.yellow)
+--- @usage         sleep(0.5)
+--- @usage         title:setForeground(colors.orange)
+--- @usage         sleep(0.5)
+--- @usage     end
+--- @usage end)
 ---@class BigFont : VisualElement
 local BigFont = setmetatable({}, VisualElement)
 BigFont.__index = BigFont
 
----@property text string BigFont BigFont text
+---@property text string BigFont The text string to display in enlarged format
 BigFont.defineProperty(BigFont, "text", {default = "BigFont", type = "string", canTriggerRender = true, setter=function(self, value)
     self.bigfontText = makeText(self.get("fontSize"), value, self.get("foreground"), self.get("background"))
     return value
 end})
----@property fontSize number 1 The font size of the BigFont
+---@property fontSize number 1 Scale factor for text size (1-3, where 1 is 3x3 pixels per character)
 BigFont.defineProperty(BigFont, "fontSize", {default = 1, type = "number", canTriggerRender = true, setter=function(self, value)
     self.bigfontText = makeText(value, self.get("text"), self.get("foreground"), self.get("background"))
     return value

src/elements/Button.lua

@@ -1,14 +1,34 @@
 local elementManager = require("elementManager")
 local VisualElement = elementManager.getElement("VisualElement")
 local getCenteredPosition = require("libraries/utils").getCenteredPosition
----@cofnigDescription The Button is a standard button element with click handling and state management.
+---@configDescription The Button is a standard button element with click handling and state management.
 
---- The Button is a standard button element with click handling and state management.
+--- A clickable interface element that triggers actions when pressed. Supports text labels, custom styling, and automatic text centering. Commonly used for user interactions and form submissions.
+--- @usage -- Create a simple action button
+--- @usage local button = parent:addButton()
+--- @usage     :setPosition(5, 5)
+--- @usage     :setText("Click me!")
+--- @usage     :setBackground(colors.blue)
+--- @usage     :setForeground(colors.white)
+--- @usage
+--- @usage -- Add click handling
+--- @usage button:onClick(function(self, button, x, y)
+--- @usage     -- Change appearance when clicked
+--- @usage     self:setBackground(colors.green)
+--- @usage     self:setText("Success!")
+--- @usage     
+--- @usage     -- Revert after delay
+--- @usage     basalt.schedule(function()
+--- @usage         sleep(1)
+--- @usage         self:setBackground(colors.blue)
+--- @usage         self:setText("Click me!")
+--- @usage     end)
+--- @usage end)
 ---@class Button : VisualElement
 local Button = setmetatable({}, VisualElement)
 Button.__index = Button
 
----@property text string Button Button text
+---@property text string Button Label text displayed centered within the button
 Button.defineProperty(Button, "text", {default = "Button", type = "string", canTriggerRender = true})
 
 Button.defineEvent(Button, "mouse_click")

src/elements/CheckBox.lua

@@ -1,14 +1,26 @@
 local VisualElement = require("elements/VisualElement")
----@cofnigDescription This is a checkbox. It is a visual element that can be checked.
+---@configDescription This is a checkbox. It is a visual element that can be checked.
 
---- The CheckBox is a visual element that can be checked.
----@class CheckBox : VisualElement
+--- A toggleable UI element that can be checked or unchecked. Displays different text based on its state and supports automatic sizing. Commonly used in forms and settings interfaces for boolean options.
+--- @usage -- Create a checkbox for a setting
+--- @usage local checkbox = parent:addCheckBox()
+--- @usage     :setText("Enable Feature")
+--- @usage     :setCheckedText("✓")
+--- @usage     :onChange("checked", function(self, checked)
+--- @usage         -- React to checkbox state changes
+--- @usage         if checked then
+--- @usage             -- Handle enabled state
+--- @usage         else
+--- @usage             -- Handle disabled state
+--- @usage         end
+--- @usage     end)
+--- @class CheckBox : VisualElement
 local CheckBox = setmetatable({}, VisualElement)
 CheckBox.__index = CheckBox
 
----@property checked boolean Whether checkbox is checked
+---@property checked boolean false The current state of the checkbox (true=checked, false=unchecked)
 CheckBox.defineProperty(CheckBox, "checked", {default = false, type = "boolean", canTriggerRender = true})
----@property text string empty Text to display
+---@property text string empty Text shown when the checkbox is unchecked
 CheckBox.defineProperty(CheckBox, "text", {default = " ", type = "string", canTriggerRender = true, setter=function(self, value)
     local checkedText = self.get("checkedText")
     local width = math.max(#value, #checkedText)
@@ -17,7 +29,7 @@ CheckBox.defineProperty(CheckBox, "text", {default = " ", type = "string", canTr
     end
     return value
 end})
----@property checkedText string Text when checked
+---@property checkedText string x Text shown when the checkbox is checked
 CheckBox.defineProperty(CheckBox, "checkedText", {default = "x", type = "string", canTriggerRender = true, setter=function(self, value)
     local text = self.get("text")
     local width = math.max(#value, #text)
@@ -26,7 +38,7 @@ CheckBox.defineProperty(CheckBox, "checkedText", {default = "x", type = "string"
     end
     return value
 end})
----@property autoSize boolean true Whether to automatically size the checkbox
+---@property autoSize boolean true Automatically adjusts width based on text length
 CheckBox.defineProperty(CheckBox, "autoSize", {default = true, type = "boolean"})
 
 CheckBox.defineEvent(CheckBox, "mouse_click")
@@ -51,7 +63,8 @@ function CheckBox:init(props, basalt)
     self.set("type", "CheckBox")
 end
 
---- @shortDescription Handles mouse click events
+--- Handles mouse interactions to toggle the checkbox state
+--- @shortDescription Toggles checked state on mouse click
 --- @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