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 [[
---- @usage local chart = main:addBarChart()
+--- -- Create a bar chart
---- @usage 
+--- local chart = main:addBarChart()
---- @usage -- Add two data series with different colors
+--- 
---- @usage chart:addSeries("input", " ", colors.green, colors.green, 5)
+--- -- Add two data series with different colors
---- @usage chart:addSeries("output", " ", colors.red, colors.red, 5)
+--- chart:addSeries("input", " ", colors.green, colors.green, 5)
---- @usage 
+--- chart:addSeries("output", " ", colors.red, colors.red, 5)
---- @usage -- Continuously update the chart with random data
+--- 
---- @usage basalt.schedule(function()
+--- -- Continuously update the chart with random data
---- @usage     while true do
+--- basalt.schedule(function()
---- @usage         chart:addPoint("input", math.random(1,100))
+---     while true do
---- @usage         chart:addPoint("output", math.random(1,100))
+---         chart:addPoint("input", math.random(1,100))
---- @usage         sleep(2)
+---         chart:addPoint("output", math.random(1,100))
---- @usage     end
+---         sleep(2)
---- @usage end)
+---      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 [[
---- @usage local main = basalt.getMainFrame()
+--- -- Create a large welcome message
---- @usage local title = main:addBigFont()
+--- local main = basalt.getMainFrame()
---- @usage     :setPosition(3, 3)
+--- local title = main:addBigFont()
---- @usage     :setFontSize(2)  -- Makes text twice as large
+---     :setPosition(3, 3)
---- @usage     :setText("Welcome!")
+---     :setFontSize(2)  -- Makes text twice as large
---- @usage     :setForeground(colors.yellow)  -- Make text yellow
+---     :setText("Welcome!")
---- @usage
+---     :setForeground(colors.yellow)  -- Make text yellow
---- @usage -- For animated text
+---
---- @usage basalt.schedule(function()
+--- -- For animated text
---- @usage     while true do
+--- basalt.schedule(function()
---- @usage         title:setForeground(colors.yellow)
+---     while true do
---- @usage         sleep(0.5)
+---         title:setForeground(colors.yellow)
---- @usage         title:setForeground(colors.orange)
+---         sleep(0.5)
---- @usage         sleep(0.5)
+---         title:setForeground(colors.orange)
---- @usage     end
+---         sleep(0.5)
---- @usage end)
+---     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 [[
---- @usage local button = parent:addButton()
+--- -- Create a simple action button
---- @usage     :setPosition(5, 5)
+--- local button = parent:addButton()
---- @usage     :setText("Click me!")
+---     :setPosition(5, 5)
---- @usage     :setBackground(colors.blue)
+---     :setText("Click me!")
---- @usage     :setForeground(colors.white)
+---     :setBackground(colors.blue)
---- @usage
+---     :setForeground(colors.white)
---- @usage -- Add click handling
+---
---- @usage button:onClick(function(self, button, x, y)
+--- -- Add click handling
---- @usage     -- Change appearance when clicked
+--- button:onClick(function(self, button, x, y)
---- @usage     self:setBackground(colors.green)
+---     -- Change appearance when clicked
---- @usage     self:setText("Success!")
+---     self:setBackground(colors.green)
---- @usage     
+---     self:setText("Success!")
---- @usage     -- Revert after delay
+---     
---- @usage     basalt.schedule(function()
+---     -- Revert after delay
---- @usage         sleep(1)
+---     basalt.schedule(function()
---- @usage         self:setBackground(colors.blue)
+---         sleep(1)
---- @usage         self:setText("Click me!")
+---         self:setBackground(colors.blue)
---- @usage     end)
+---         self:setText("Click me!")
---- @usage end)
+---     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 [[
---- @usage local checkbox = parent:addCheckBox()
+--- -- Create a checkbox for a setting
---- @usage     :setText("Enable Feature")
+--- local checkbox = parent:addCheckBox()
---- @usage     :setCheckedText("✓")
+---     :setText("Enable Feature")
---- @usage     :onChange("checked", function(self, checked)
+---     :setCheckedText("✓")
---- @usage         -- React to checkbox state changes
+---     :onChange("checked", function(self, checked)
---- @usage         if checked then
+---         -- React to checkbox state changes
---- @usage             -- Handle enabled state
+---         if checked then
---- @usage         else
+---             -- Handle enabled state
---- @usage             -- Handle disabled state
+---         else
---- @usage         end
+---             -- Handle disabled state
---- @usage     end)
+---         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 [[
---- @usage local combo = main:addComboBox()
+--- -- Create a searchable country selector
---- @usage     :setPosition(5, 5)
+--- local combo = main:addComboBox()
---- @usage     :setSize(20, 1)  -- Height will expand when opened
+---     :setPosition(5, 5)
---- @usage     :setItems({
+---     :setSize(20, 1)  -- Height will expand when opened
---- @usage         {text = "Germany"},
+---     :setItems({
---- @usage         {text = "France"},
+---         {text = "Germany"},
---- @usage         {text = "Spain"},
+---         {text = "France"},
---- @usage         {text = "Italy"}
+---         {text = "Spain"},
---- @usage     })
+---         {text = "Italy"}
---- @usage     :setPlaceholder("Select country...")
+---     })
---- @usage     :setAutoComplete(true)  -- Enable filtering while typing
+---     :setPlaceholder("Select country...")
---- @usage 
+---     :setAutoComplete(true)  -- Enable filtering while typing
---- @usage -- Handle selection changes
+--- 
---- @usage combo:onChange(function(self, value)
+--- -- Handle selection changes
---- @usage     -- value will be the selected country
+--- combo:onChange(function(self, value)
---- @usage     basalt.debug("Selected:", value)
+---     -- value will be the selected country
---- @usage end)
+---     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 [[
---- @usage local display = main:addDisplay()
+--- -- Create a display for a custom terminal
---- @usage     :setSize(30, 10)
+--- local display = main:addDisplay()
---- @usage     :setPosition(2, 2)
+---     :setSize(30, 10)
---- @usage
+---     :setPosition(2, 2)
---- @usage -- Get the window object for CC API operations
+---
---- @usage local win = display:getWindow()
+--- -- Get the window object for CC API operations
---- @usage
+--- local win = display:getWindow()
---- @usage -- Use standard CC terminal operations
+---
---- @usage win.setTextColor(colors.yellow)
+--- -- Use standard CC terminal operations
---- @usage win.setBackgroundColor(colors.blue)
+--- win.setTextColor(colors.yellow)
---- @usage win.clear()
+--- win.setBackgroundColor(colors.blue)
---- @usage win.setCursorPos(1, 1)
+--- win.clear()
---- @usage win.write("Hello World!")
+--- win.setCursorPos(1, 1)
---- @usage
+--- win.write("Hello World!")
---- @usage -- Or use the helper method
+---
---- @usage display:write(1, 2, "Direct write", colors.red, colors.black)
+--- -- Or use the helper method
---- @usage
+--- display:write(1, 2, "Direct write", colors.red, colors.black)
---- @usage -- Useful for external APIs
+---
---- @usage local paintutils = require("paintutils")
+--- -- Useful for external APIs
---- @usage paintutils.drawLine(1, 1, 10, 1, colors.red, win)
+--- 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 [[ 
---- @usage flex:addButton():setFlexGrow(1)
+--- local flex = main:addFlexbox({background=colors.black, width=30, height=10})
---- @usage flex:addButton():setFlexGrow(1)
+--- flex:addButton():setFlexGrow(1)
---- @usage 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.
+--- 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.
+--- 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():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 [[
---- @usage :addSeries("input", " ", colors.green, colors.green, 10)
+--- local graph = main:addGraph()
---- @usage :addSeries("output", " ", colors.red, colors.red, 10)
+--- :addSeries("input", " ", colors.green, colors.green, 10)
---- @usage 
+--- :addSeries("output", " ", colors.red, colors.red, 10)
---- @usage basalt.schedule(function()
+--- 
---- @usage     while true do
+--- basalt.schedule(function()
---- @usage         graph:addPoint("input", math.random(1,100))
+---     while true do
---- @usage         graph:addPoint("output", math.random(1,100))
+---         graph:addPoint("input", math.random(1,100))
---- @usage         sleep(2)
+---         graph:addPoint("output", math.random(1,100))
---- @usage     end
+---         sleep(2)
---- @usage end)
+---     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 [[
---- @usage :addSeries("input", " ", colors.green, colors.green, 10)
+--- local chart = main:addLineChart()
---- @usage :addSeries("output", " ", colors.red, colors.red, 10)
+--- :addSeries("input", " ", colors.green, colors.green, 10)
---- @usage 
+--- :addSeries("output", " ", colors.red, colors.red, 10)
---- @usage basalt.schedule(function()
+--- 
---- @usage     while true do
+--- basalt.schedule(function()
---- @usage         chart:addPoint("input", math.random(1,100))
+---     while true do
---- @usage         chart:addPoint("output", math.random(1,100))
+---         chart:addPoint("input", math.random(1,100))
---- @usage         sleep(2)
+---         chart:addPoint("output", math.random(1,100))
---- @usage     end
+---         sleep(2)
---- @usage end)
+---     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 [[ 
---- @usage progressBar:setDirection("up") 
+--- local progressBar = main:addProgressBar()
---- @usage progressBar:setProgress(50)
+--- 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 [[
---- @usage people:setColumns({{name="Name",width=12}, {name="Age",width=10}, {name="Country",width=15}})
+--- local people = container:addTable():setWidth(40)
---- @usage people:addRow("Alice", 30, "USA"):addRow("Bob", 25, "UK")
+--- 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