From 7099b5c548462bfb633a52925f348a727d58798e Mon Sep 17 00:00:00 2001
From: Robert Jelic <36573031+NoryiE@users.noreply.github.com>
Date: Wed, 29 Oct 2025 18:41:32 +0100
Subject: [PATCH] Docs fixes

---
 src/elements/BarChart.lua    | 32 ++++++++++++++------------
 src/elements/BigFont.lua     | 36 +++++++++++++++--------------
 src/elements/Button.lua      | 42 ++++++++++++++++++----------------
 src/elements/CheckBox.lua    | 26 +++++++++++----------
 src/elements/ComboBox.lua    | 38 ++++++++++++++++---------------
 src/elements/Display.lua     | 44 +++++++++++++++++++-----------------
 src/elements/DropDown.lua    |  5 ++++
 src/elements/FlexBox.lua     | 16 +++++++------
 src/elements/Graph.lua       | 24 +++++++++++---------
 src/elements/LineChart.lua   | 24 +++++++++++---------
 src/elements/ProgressBar.lua |  8 ++++---
 src/elements/Table.lua       |  8 ++++---
 12 files changed, 165 insertions(+), 138 deletions(-)

diff --git a/src/elements/BarChart.lua b/src/elements/BarChart.lua
index 9bad022..b4f31d8 100644
--- a/src/elements/BarChart.lua
+++ b/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
diff --git a/src/elements/BigFont.lua b/src/elements/BigFont.lua
index f4b3b63..d57c9f2 100644
--- a/src/elements/BigFont.lua
+++ b/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
diff --git a/src/elements/Button.lua b/src/elements/Button.lua
index d41102b..b4aefaf 100644
--- a/src/elements/Button.lua
+++ b/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
diff --git a/src/elements/CheckBox.lua b/src/elements/CheckBox.lua
index 9cc3e08..b783e4f 100644
--- a/src/elements/CheckBox.lua
+++ b/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
diff --git a/src/elements/ComboBox.lua b/src/elements/ComboBox.lua
index 1fd6239..af23958 100644
--- a/src/elements/ComboBox.lua
+++ b/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
diff --git a/src/elements/Display.lua b/src/elements/Display.lua
index 93b1341..dd92d5a 100644
--- a/src/elements/Display.lua
+++ b/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
diff --git a/src/elements/DropDown.lua b/src/elements/DropDown.lua
index 5967bc7..04d362d 100644
--- a/src/elements/DropDown.lua
+++ b/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)
diff --git a/src/elements/FlexBox.lua b/src/elements/FlexBox.lua
index 1df2cd1..2cdc317 100644
--- a/src/elements/FlexBox.lua
+++ b/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
diff --git a/src/elements/Graph.lua b/src/elements/Graph.lua
index ab762c3..1e06a38 100644
--- a/src/elements/Graph.lua
+++ b/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
diff --git a/src/elements/LineChart.lua b/src/elements/LineChart.lua
index 03e5c93..0e6fc91 100644
--- a/src/elements/LineChart.lua
+++ b/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
diff --git a/src/elements/ProgressBar.lua b/src/elements/ProgressBar.lua
index abffea8..4f85f2c 100644
--- a/src/elements/ProgressBar.lua
+++ b/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
diff --git a/src/elements/Table.lua b/src/elements/Table.lua
index 55688f2..156e4a5 100644
--- a/src/elements/Table.lua
+++ b/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