simplify style system

luigi/widget/button.lua

@@ -1,5 +1,26 @@
 --[[--
-A simple button.
+A button.
+
+Buttons have no special behavior beyond that of generic widgets,
+but themes should give buttons an appropriate appearance.
+
+@usage
+    -- create a layout containing only a button
+    local layout = Layout {
+        type = 'button',
+        id = 'exampleButton',
+        text = 'Press me',
+        width = 100,
+        height = 32,
+    }
+
+    -- handle Press events
+    layout.exampleButton:onPress(function (event)
+        print 'You pressed the button.'
+    end)
+
+    -- show the layout
+    layout:show()
 
 @widget button
 --]]--

luigi/widget/check.lua

@@ -1,6 +1,14 @@
 --[[--
 A check box.
 
+Check boxes toggle their @{attribute.value|value} attribute between
+`true` and `false` when pressed.
+
+Changing the value of a check box causes it to change its appearance to
+indicate its value. The standard themes use the @{attribute.icon|icon}
+attribute for this purpose. If a custom icon is provided when using the
+standard themes, the widget's value should be indicated in some other way.
+
 @widget check
 --]]--
 
@@ -9,10 +17,5 @@ return function (self)
         self.value = not self.value
     end)
 
-    self:onChange(function ()
-        local subtype = self.value and 'check.checked' or 'check.unchecked'
-        self.type = { 'check', subtype }
-    end)
-
     self.value = not not self.value
 end

luigi/widget/radio.lua

@@ -1,6 +1,17 @@
 --[[--
 A radio button.
 
+Radio buttons change their @{attribute.value|value} attribute to
+`true` when pressed. Radio buttons should also have a `group`
+attribute. When a radio button is pressed, other radio buttons
+in the same layout with the same `group` attribute change their values
+to `false`.
+
+Changing the value of a radio button causes it to change its appearance to
+indicate its value. The standard themes use the @{attribute.icon|icon}
+attribute for this purpose. If a custom icon is provided when using the
+standard themes, the widget's value should be indicated in some other way.
+
 @widget radio
 --]]--
 
@@ -24,10 +35,5 @@ return function (self)
         end
     end)
 
-    self:onChange(function ()
-        local subtype = self.value and 'radio.checked' or 'radio.unchecked'
-        self.type = { 'radio', subtype }
-    end)
-
     self.value = not not self.value
 end

luigi/widget/sash.lua

@@ -2,12 +2,24 @@
 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`.
+A sash should be adjacent to a widget with a specified size
+in the same direction as the parent element's @{attribute.flow|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.
+then either or both of the siblings adjacent to the sash
+should have a specified @{attribute.width|width} attribute.
+
+@usage
+    -- create a layout containing two widgets separated by a sash
+    local layout = Layout {
+        type = 'panel', flow = 'x',
+        { text = 'This is the left side', wrap = true, width = 100 },
+        { type = 'sash' },
+        { text = 'This is the right side', wrap = true },
+    }
+
+    -- show the layout
+    layout:show()
 
 @widget sash
 --]]--

luigi/widget/status.lua

@@ -1,6 +1,24 @@
 --[[--
 A status bar.
 
+This widget will display the @{attribute.status|status} attribute of the
+hovered widget. Only one status widget should exist per layout. If multiple
+status widgets exist in the same layout, only the last one created will
+display status messages.
+
+@usage
+    -- create a layout containing some buttons and a status bar
+    local layout = Layout {
+        { type = 'panel', flow = 'x',
+            { text = 'Do stuff', status = 'Press to do stuff' },
+            { text = 'Quit', status = 'Press to quit' },
+        },
+        { type = 'status', height = 24 },
+    }
+
+    -- show the layout
+    layout:show()
+
 @widget status
 --]]--