improve widget docs

luigi/widget/radio.lua

@@ -1,11 +1,9 @@
 --[[--
-A radio button.
+A radio widget.
 
-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`.
+When pressed, a radio widget's @{attribute.value|value} changes to
+`true`, and the values of other radio widgets in the same `group`
+change 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}
@@ -44,7 +42,27 @@ local function setGroup (self, value)
 end
 
 return function (self)
+--[[--
+Special Attributes
+
+@section special
+--]]--
+
+--[[--
+Widget group.
+
+Should contain a string identifying the widget's group.
+If not defined, defaults to the string `'default'`.
+
+When a radio widget is pressed, the values of other radio widgets
+in the same group change to `false`.
+
+@attrib group
+--]]--
     self:defineAttribute('group', { set = setGroup })
+--[[--
+@section end
+--]]--
 
     self:onPress(function ()
         for _, widget in ipairs(groups[self.group]) do

luigi/widget/text.lua

@@ -186,6 +186,25 @@ return function (self)
 
     self.text = ''
 
+--[[--
+Special Attributes
+
+@section special
+--]]--
+
+--[[--
+Highlight color.
+
+Should contain an array with 3 or 4 values (RGB or RGBA) from 0 to 255.
+
+This color is used to indicate the selected range of text.
+
+@attrib highlight
+--]]--
+    self:defineAttribute('highlight')
+--[[--
+@section end
+--]]--
     if not self.highlight then
         self.highlight = { 0x80, 0x80, 0x80 }
     end
@@ -266,14 +285,19 @@ return function (self)
         Backend.setScissor(x, y, w, h)
         Backend.setFont(font)
 
-        -- draw highlight
         if self.focused then
+            -- draw highlighted selection
             Backend.setColor(self.highlight)
             Backend.drawRectangle('fill', startX, y, width, height)
+            -- draw cursor selection
             if Backend.getTime() % 2 < 1.75 then
                 Backend.setColor(color)
                 Backend.drawRectangle('fill', endX, y, 1, height)
             end
+        else
+            Backend.setColor { color[1], color[2], color[3],
+                (color[4] or 256) / 8 }
+            Backend.drawRectangle('fill', startX, y, width, height)
         end
 
         -- draw text