formalize attributes

luigi/widget/button.lua

@@ -1,3 +1,9 @@
+--[[--
+A simple button.
+
+@widget button
+--]]--
+
 return function (self)
 
 end

luigi/widget/menu.lua

@@ -1,3 +1,9 @@
+--[[--
+A menu bar.
+
+@widget menu
+--]]--
+
 return function (self)
 
     for index, child in ipairs(self) do

luigi/widget/menu/item.lua

@@ -1,3 +1,12 @@
+--[[--
+A menu item.
+
+When a `menu` is created, any sub-items not having a specified type
+are automatically given a type of `'menu.item'`. These widgets should
+not be explicitly created.
+
+@widget menu.item
+--]]--
 local ROOT = (...):gsub('[^.]*.[^.]*.[^.]*$', '')
 
 local Layout, Event
@@ -125,7 +134,7 @@ local function initialize (self)
     local textWidth = self.fontData:getAdvance(text) + pad * 2
 
     if isSubmenu then
-        local tc = self.textColor or { 0, 0, 0, 255 }
+        local tc = self.color or { 0, 0, 0, 255 }
         local keyColor = { tc[1], tc[2], tc[3], 0x90 }
         local edgeType
         if #self.items > 0 then
@@ -139,7 +148,7 @@ local function initialize (self)
         self:addChild { icon = icon, width = self.height }
         self:addChild { text = text, width = textWidth }
         self:addChild { text = key, align = 'middle right',
-            minwidth = self.height, textColor = keyColor, type = edgeType }
+            minwidth = self.height, color = keyColor, type = edgeType }
 
         self.icon = nil
         self.text = nil

luigi/widget/progress.lua

@@ -1,3 +1,12 @@
+--[[--
+A progress bar.
+
+Set the widget's `value` property to a decimal value
+between 0 and 1 (inclusive) to change the width of the bar.
+
+@widget progress
+--]]--
+
 return function (self)
     self.value = 0
     self.flow = 'x' -- TODO: support vertical progress?

luigi/widget/sash.lua

@@ -1,3 +1,17 @@
+--[[--
+A sash.
+
+Dragging this widget resizes the widgets adjacent to it.
+A sash must be adjacent to a widget with a specified size
+in the same direction as the parent element's `flow`.
+
+For example, if the parent of the sash is `flow = 'x'`
+then either or both of the siblings next to the sash
+must have a specified `width` property.
+
+@widget sash
+--]]--
+
 local function setDimension (widget, name, size)
     if not widget.parent then
         widget[name] = size

luigi/widget/slider.lua

@@ -1,3 +1,12 @@
+--[[--
+A slider.
+
+Dragging this widget changes its `value` property to a
+number between 0 and 1, inclusive.
+
+@widget slider
+--]]--
+
 return function (self)
 
     local function clamp (value)

luigi/widget/stepper.lua

@@ -1,3 +1,15 @@
+--[[--
+A stepper.
+
+This widget is composed of two buttons and a content area.
+Upon creation, this widget's children are moved into an
+`items` property. The items are displayed one at a time in
+the content area. Pressing the buttons cycles through the
+item displayed in the content area.
+
+@widget stepper
+--]]--
+
 return function (self)
     self.items = {}
     self.index = 1

luigi/widget/text.lua

@@ -1,3 +1,8 @@
+--[[--
+A text entry area.
+
+@widget text
+--]]--
 local ROOT = (...):gsub('[^.]*.[^.]*$', '')
 
 local utf8 = require(ROOT .. 'utf8')
@@ -231,7 +236,7 @@ return function (self)
         local x, y, w, h = self:getRectangle(true, true)
         local width, height = endX - startX, h
         local font = self.fontData
-        local textColor = self.textColor or { 0, 0, 0, 255 }
+        local color = self.color or { 0, 0, 0, 255 }
         local textTop = math.floor(y + (h - font:getLineHeight()) / 2)
 
         Backend.push()
@@ -242,12 +247,12 @@ return function (self)
         Backend.setColor(self.highlight)
         Backend.drawRectangle('fill', startX, y, width, height)
         if Backend.getTime() % 2 < 1.75 then
-            Backend.setColor(textColor)
+            Backend.setColor(color)
             Backend.drawRectangle('fill', endX, y, 1, height)
         end
 
         -- draw text
-        Backend.setColor(textColor)
+        Backend.setColor(color)
         Backend.print(self.value, x - self.scrollX, textTop)
         if not self.focused then
             Backend.pop()