Docs fixes

src/elements/BarChart.lua

@@ -6,21 +6,23 @@ local tHex = require("libraries/colorHex")
 --- @configDefault false
 
 --- 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 
---- @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))
---- @usage         chart:addPoint("output", math.random(1,100))
---- @usage         sleep(2)
---- @usage     end
---- @usage end)
+--- @usage [[
+--- -- Create a bar chart
+--- local chart = main:addBarChart()
+--- 
+--- -- Add two data series with different colors
+--- chart:addSeries("input", " ", colors.green, colors.green, 5)
+--- chart:addSeries("output", " ", colors.red, colors.red, 5)
+--- 
+--- -- Continuously update the chart with random data
+--- basalt.schedule(function()
+---     while true do
+---         chart:addPoint("input", math.random(1,100))
+---         chart:addPoint("output", math.random(1,100))
+---         sleep(2)
+---      end
+--- end)
+--- ]]
 --- @class BarChart : Graph
 local BarChart = setmetatable({}, BaseGraph)
 BarChart.__index = BarChart

src/elements/BigFont.lua

@@ -146,23 +146,25 @@ local VisualElement = elementManager.getElement("VisualElement")
 ---@configDefault false
 
 --- 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)
+--- @usage [[
+--- -- Create a large welcome message
+--- local main = basalt.getMainFrame()
+--- local title = main:addBigFont()
+---     :setPosition(3, 3)
+---     :setFontSize(2)  -- Makes text twice as large
+---     :setText("Welcome!")
+---     :setForeground(colors.yellow)  -- Make text yellow
+---
+--- -- For animated text
+--- basalt.schedule(function()
+---     while true do
+---         title:setForeground(colors.yellow)
+---         sleep(0.5)
+---         title:setForeground(colors.orange)
+---         sleep(0.5)
+---     end
+--- end)
+--- ]]
 ---@class BigFont : VisualElement
 local BigFont = setmetatable({}, VisualElement)
 BigFont.__index = BigFont

src/elements/Button.lua

@@ -4,26 +4,28 @@ local getCenteredPosition = require("libraries/utils").getCenteredPosition
 ---@configDescription 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)
+--- @usage [[
+--- -- Create a simple action button
+--- local button = parent:addButton()
+---     :setPosition(5, 5)
+---     :setText("Click me!")
+---     :setBackground(colors.blue)
+---     :setForeground(colors.white)
+---
+--- -- Add click handling
+--- button:onClick(function(self, button, x, y)
+---     -- Change appearance when clicked
+---     self:setBackground(colors.green)
+---     self:setText("Success!")
+---     
+---     -- Revert after delay
+---     basalt.schedule(function()
+---         sleep(1)
+---         self:setBackground(colors.blue)
+---         self:setText("Click me!")
+---     end)
+--- end)
+--- ]]
 ---@class Button : VisualElement
 local Button = setmetatable({}, VisualElement)
 Button.__index = Button

src/elements/CheckBox.lua

@@ -2,18 +2,20 @@ local VisualElement = require("elements/VisualElement")
 ---@configDescription This is a checkbox. It is a visual element that can be checked.
 
 --- 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)
+--- @usage [[
+--- -- Create a checkbox for a setting
+--- local checkbox = parent:addCheckBox()
+---     :setText("Enable Feature")
+---     :setCheckedText("✓")
+---     :onChange("checked", function(self, checked)
+---         -- React to checkbox state changes
+---         if checked then
+---             -- Handle enabled state
+---         else
+---             -- Handle disabled state
+---         end
+---     end)
+--- ]]
 --- @class CheckBox : VisualElement
 local CheckBox = setmetatable({}, VisualElement)
 CheckBox.__index = CheckBox

src/elements/ComboBox.lua

@@ -7,24 +7,26 @@ local tHex = require("libraries/colorHex")
 
 --- A hybrid input element that combines a text input field with a dropdown list. Users can either type directly or select from predefined options. 
 --- Supports auto-completion, custom styling, and both single and multi-selection modes.
---- @usage -- Create a searchable country selector
---- @usage local combo = main:addComboBox()
---- @usage     :setPosition(5, 5)
---- @usage     :setSize(20, 1)  -- Height will expand when opened
---- @usage     :setItems({
---- @usage         {text = "Germany"},
---- @usage         {text = "France"},
---- @usage         {text = "Spain"},
---- @usage         {text = "Italy"}
---- @usage     })
---- @usage     :setPlaceholder("Select country...")
---- @usage     :setAutoComplete(true)  -- Enable filtering while typing
---- @usage 
---- @usage -- Handle selection changes
---- @usage combo:onChange(function(self, value)
---- @usage     -- value will be the selected country
---- @usage     basalt.debug("Selected:", value)
---- @usage end)
+--- @usage [[
+--- -- Create a searchable country selector
+--- local combo = main:addComboBox()
+---     :setPosition(5, 5)
+---     :setSize(20, 1)  -- Height will expand when opened
+---     :setItems({
+---         {text = "Germany"},
+---         {text = "France"},
+---         {text = "Spain"},
+---         {text = "Italy"}
+---     })
+---     :setPlaceholder("Select country...")
+---     :setAutoComplete(true)  -- Enable filtering while typing
+--- 
+--- -- Handle selection changes
+--- combo:onChange(function(self, value)
+---     -- value will be the selected country
+---     basalt.debug("Selected:", value)
+--- end)
+--- ]]
 ---@class ComboBox : DropDown
 local ComboBox = setmetatable({}, DropDown)
 ComboBox.__index = ComboBox

src/elements/Display.lua

@@ -13,27 +13,29 @@ local colorHex = require("libraries/colorHex")
 --- - Terminal emulation
 --- - Complex text manipulation
 --- The Display maintains its own terminal buffer and can be manipulated using familiar CC terminal methods.
---- @usage -- Create a display for a custom terminal
---- @usage local display = main:addDisplay()
---- @usage     :setSize(30, 10)
---- @usage     :setPosition(2, 2)
---- @usage
---- @usage -- Get the window object for CC API operations
---- @usage local win = display:getWindow()
---- @usage
---- @usage -- Use standard CC terminal operations
---- @usage win.setTextColor(colors.yellow)
---- @usage win.setBackgroundColor(colors.blue)
---- @usage win.clear()
---- @usage win.setCursorPos(1, 1)
---- @usage win.write("Hello World!")
---- @usage
---- @usage -- Or use the helper method
---- @usage display:write(1, 2, "Direct write", colors.red, colors.black)
---- @usage
---- @usage -- Useful for external APIs
---- @usage local paintutils = require("paintutils")
---- @usage paintutils.drawLine(1, 1, 10, 1, colors.red, win)
+--- @usage [[
+--- -- Create a display for a custom terminal
+--- local display = main:addDisplay()
+---     :setSize(30, 10)
+---     :setPosition(2, 2)
+---
+--- -- Get the window object for CC API operations
+--- local win = display:getWindow()
+---
+--- -- Use standard CC terminal operations
+--- win.setTextColor(colors.yellow)
+--- win.setBackgroundColor(colors.blue)
+--- win.clear()
+--- win.setCursorPos(1, 1)
+--- win.write("Hello World!")
+---
+--- -- Or use the helper method
+--- display:write(1, 2, "Direct write", colors.red, colors.black)
+---
+--- -- Useful for external APIs
+--- local paintutils = require("paintutils")
+--- paintutils.drawLine(1, 1, 10, 1, colors.red, win)
+--- ]]
 ---@class Display : VisualElement
 local Display = setmetatable({}, VisualElement)
 Display.__index = Display

src/elements/DropDown.lua

@@ -15,6 +15,9 @@ local tHex = require("libraries/colorHex")
 
 --- A collapsible selection menu that expands to show multiple options when clicked. Supports single and multi-selection modes, custom item styling, separators, and item callbacks.
 --- @run [[
+--- local basalt = require("basalt")
+--- local main = basalt.getMainFrame()
+--- 
 --- -- Create a styled dropdown menu
 --- local dropdown = main:addDropDown()
 ---     :setPosition(5, 5)
@@ -48,6 +51,8 @@ local tHex = require("libraries/colorHex")
 --- dropdown:onChange(function(self, value)
 ---     basalt.debug("Selected:", value)
 --- end)
+--- 
+--- basalt.run()
 --- ]]
 ---@class DropDown : List
 local DropDown = setmetatable({}, List)

src/elements/FlexBox.lua

@@ -3,15 +3,17 @@ local Container = elementManager.getElement("Container")
 ---@configDescription A flexbox container that arranges its children in a flexible layout.
 
 --- This is the FlexBox class. It is a container that arranges its children in a flexible layout.
---- @usage local flex = main:addFlexbox({background=colors.black, width=30, height=10})
---- @usage flex:addButton():setFlexGrow(1)
---- @usage flex:addButton():setFlexGrow(1)
---- @usage flex:addButton():setFlexGrow(1)
+--- @usage [[ 
+--- local flex = main:addFlexbox({background=colors.black, width=30, height=10})
+--- flex:addButton():setFlexGrow(1)
+--- flex:addButton():setFlexGrow(1)
+--- flex:addButton():setFlexGrow(1)
 --- The flexbox element adds the following properties to its children:
 --- 
---- @usage flex:addButton():setFlexGrow(1) -- The flex-grow property defines the ability for a flex item to grow if necessary.
---- @usage flex:addButton():setFlexShrink(1) -- The flex-shrink property defines the ability for a flex item to shrink if necessary.
---- @usage flex:addButton():setFlexBasis(1) -- The flex-basis property defines the default size of an element before the remaining space is distributed.
+--- flex:addButton():setFlexGrow(1) -- The flex-grow property defines the ability for a flex item to grow if necessary.
+--- flex:addButton():setFlexShrink(1) -- The flex-shrink property defines the ability for a flex item to shrink if necessary.
+--- flex:addButton():setFlexBasis(1) -- The flex-basis property defines the default size of an element before the remaining space is distributed.
+--- ]]
 ---@class FlexBox : Container
 local FlexBox = setmetatable({}, Container)
 FlexBox.__index = FlexBox

src/elements/Graph.lua

@@ -5,17 +5,19 @@ local tHex = require("libraries/colorHex")
 ---@configDefault false
 
 --- This is the base class for all graph elements. It is a point based graph.
---- @usage local graph = main:addGraph()
---- @usage :addSeries("input", " ", colors.green, colors.green, 10)
---- @usage :addSeries("output", " ", colors.red, colors.red, 10)
---- @usage 
---- @usage basalt.schedule(function()
---- @usage     while true do
---- @usage         graph:addPoint("input", math.random(1,100))
---- @usage         graph:addPoint("output", math.random(1,100))
---- @usage         sleep(2)
---- @usage     end
---- @usage end)
+--- @usage [[
+--- local graph = main:addGraph()
+--- :addSeries("input", " ", colors.green, colors.green, 10)
+--- :addSeries("output", " ", colors.red, colors.red, 10)
+--- 
+--- basalt.schedule(function()
+---     while true do
+---         graph:addPoint("input", math.random(1,100))
+---         graph:addPoint("output", math.random(1,100))
+---         sleep(2)
+---     end
+--- end)
+--- ]]
 --- @class Graph : VisualElement
 local Graph = setmetatable({}, VisualElement)
 Graph.__index = Graph

src/elements/LineChart.lua

@@ -6,17 +6,19 @@ local tHex = require("libraries/colorHex")
 ---@configDefault false
 
 --- The Line Chart element visualizes data series as connected line graphs. It plots points on a coordinate system and connects them with lines.
---- @usage local chart = main:addLineChart()
---- @usage :addSeries("input", " ", colors.green, colors.green, 10)
---- @usage :addSeries("output", " ", colors.red, colors.red, 10)
---- @usage 
---- @usage basalt.schedule(function()
---- @usage     while true do
---- @usage         chart:addPoint("input", math.random(1,100))
---- @usage         chart:addPoint("output", math.random(1,100))
---- @usage         sleep(2)
---- @usage     end
---- @usage end)
+--- @usage [[
+--- local chart = main:addLineChart()
+--- :addSeries("input", " ", colors.green, colors.green, 10)
+--- :addSeries("output", " ", colors.red, colors.red, 10)
+--- 
+--- basalt.schedule(function()
+---     while true do
+---         chart:addPoint("input", math.random(1,100))
+---         chart:addPoint("output", math.random(1,100))
+---         sleep(2)
+---     end
+--- end)
+--- ]]
 --- @class LineChart : Graph
 local LineChart = setmetatable({}, Graph)
 LineChart.__index = LineChart

src/elements/ProgressBar.lua

@@ -3,9 +3,11 @@ local tHex = require("libraries/colorHex")
 
 --- This is the progress bar class. It provides a visual representation of progress
 --- with optional percentage display and customizable colors.
---- @usage local progressBar = main:addProgressBar()
---- @usage progressBar:setDirection("up") 
---- @usage progressBar:setProgress(50)
+--- @usage [[ 
+--- local progressBar = main:addProgressBar()
+--- progressBar:setDirection("up") 
+--- progressBar:setProgress(50)
+--- ]]
 ---@class ProgressBar : VisualElement
 local ProgressBar = setmetatable({}, VisualElement)
 ProgressBar.__index = ProgressBar

src/elements/Table.lua

@@ -2,9 +2,11 @@ local Collection = require("elements/Collection")
 local tHex = require("libraries/colorHex")
 
 --- This is the table class. It provides a sortable data grid with customizable columns, row selection, and scrolling capabilities. Built on Collection for consistent item management.
---- @usage local people = container:addTable():setWidth(40)
---- @usage people:setColumns({{name="Name",width=12}, {name="Age",width=10}, {name="Country",width=15}})
---- @usage people:addRow("Alice", 30, "USA"):addRow("Bob", 25, "UK")
+--- @usage [[
+--- local people = container:addTable():setWidth(40)
+--- people:setColumns({{name="Name",width=12}, {name="Age",width=10}, {name="Country",width=15}})
+--- people:addRow("Alice", 30, "USA"):addRow("Bob", 25, "UK")
+--- ]]
 ---@class Table : Collection
 local Table = setmetatable({}, Collection)
 Table.__index = Table