doc: Modernize the container documentation.

This hass the following tags:

 * @interface
 * @tparam
 * @propbeautiful
 * @propemits
 * @renamedin

Beside tags, it adds some comments, fix formatting and add
new lines and dots where they belong.

Also add some signals to standardize everything.

lib/wibox/container/arcchart.lua

@@ -191,6 +191,7 @@ end
 --- The widget to wrap in a radial proggressbar.
 -- @property widget
 -- @tparam widget widget The widget
+-- @interface container
 
 arcchart.set_widget = base.set_widget_common
 
@@ -205,6 +206,7 @@ end
 
 --- Reset this layout. The widget will be removed and the rotation reset.
 -- @method reset
+-- @interface container
 function arcchart:reset()
     self:set_widget(nil)
 end
@@ -226,41 +228,59 @@ end
 -- @tparam[opt=0] number paddings.bottom
 -- @tparam[opt=0] number paddings.left
 -- @tparam[opt=0] number paddings.right
+-- @emits [opt=bob] property::paddings When the `paddings` changes.
+-- @emitstparam property::paddings widget self The object being modified.
+-- @emitstparam property::paddings table paddings The new paddings.
+-- @usebeautiful beautiful.arcchart_paddings Fallback value when the object
+--  `paddings` isn't specified.
 
 --- The border background color.
 --@DOC_wibox_container_arcchart_border_color_EXAMPLE@
 -- @property border_color
--- @param color
+-- @tparam color border_color
+-- @propemits true false
+-- @propbeautiful
 
 --- The arcchart values foreground colors.
 --@DOC_wibox_container_arcchart_color_EXAMPLE@
 -- @property colors
 -- @tparam table values An ordered set of colors for each value in arcchart.
+-- @propemits true false
+-- @propbeautiful
 
 --- The border width.
+--
 --@DOC_wibox_container_arcchart_border_width_EXAMPLE@
+--
 -- @property border_width
 -- @tparam[opt=3] number border_width
+-- @propemits true false
+-- @propbeautiful
 
 --- The minimum value.
 -- @property min_value
--- @param number
+-- @tparam number min_value
+-- @propemits true false
 
 --- The maximum value.
 -- @property max_value
--- @param number
+-- @tparam number max_value
+-- @propemits true false
 
 --- The radial background.
 --@DOC_wibox_container_arcchart_bg_EXAMPLE@
 -- @property bg
--- @param color
+-- @tparam color bg
 -- @see gears.color
+-- @propemits true false
+-- @propbeautiful
 
 --- The value.
 --@DOC_wibox_container_arcchart_value_EXAMPLE@
 -- @property value
 -- @tparam number value Between min_value and max_value
 -- @see values
+-- @propemits true false
 
 --- The values.
 -- The arcchart is designed to display multiple values at once. Each will be
@@ -268,29 +288,33 @@ end
 --@DOC_wibox_container_arcchart_values_EXAMPLE@
 -- @property values
 -- @tparam table values An ordered set of values.
+-- @propemits true false
 -- @see value
 
 --- If the chart has rounded edges.
 --@DOC_wibox_container_arcchart_rounded_edge_EXAMPLE@
 -- @property rounded_edge
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean rounded_edge
+-- @propemits true false
 
 --- The arc thickness.
 --@DOC_wibox_container_arcchart_thickness_EXAMPLE@
 -- @property thickness
--- @param number
+-- @propemits true false
+-- @tparam number thickness
 
 --- The (radiant) angle where the first value start.
 --@DOC_wibox_container_arcchart_start_angle_EXAMPLE@
 -- @property start_angle
--- @param[opt=math.pi] number A number between 0 and 2*math.pi
+-- @tparam[opt=math.pi] number start_angle A number between 0 and 2*math.pi
+-- @propemits true false
 
 for _, prop in ipairs {"border_width", "border_color", "paddings", "colors",
     "rounded_edge", "bg", "thickness", "values", "min_value", "max_value",
     "start_angle" } do
     arcchart["set_"..prop] = function(self, value)
         self._private[prop] = value
-        self:emit_signal("property::"..prop)
+        self:emit_signal("property::"..prop, value)
         self:emit_signal("widget::redraw_needed")
     end
     arcchart["get_"..prop] = function(self)
@@ -315,7 +339,7 @@ function arcchart:set_value(value)
 end
 
 --- Returns a new arcchart layout.
--- @param[opt] widget The widget to display.
+-- @tparam[opt] wibox.widget widget The widget to display.
 -- @constructorfct wibox.container.arcchart
 local function new(widget)
     local ret = base.make_widget(nil, nil, {

lib/wibox/container/constraint.lua

@@ -1,4 +1,5 @@
 ---------------------------------------------------------------------------
+-- Restrict a widget size using one of multiple available strategies.
 --
 --@DOC_wibox_container_defaults_constraint_EXAMPLE@
 -- @author Lukáš Hrázký
@@ -39,8 +40,10 @@ function constraint:fit(context, width, height)
 end
 
 --- The widget to be constrained.
+--
 -- @property widget
 -- @tparam widget widget The widget
+-- @interface container
 
 constraint.set_widget = base.set_widget_common
 
@@ -56,10 +59,16 @@ function constraint:set_children(children)
     self:set_widget(children[1])
 end
 
---- Set the strategy to use for the constraining. Valid values are 'max',
+--- Set the strategy to use for the constraining.
--- 'min' or 'exact'. Throws an error on invalid values.
+-- Valid values are:
+--
+-- * **max**: Never allow the size to be larger than the limit.
+-- * **min**: Never allow the size to tbe below the limit.
+-- * **exact**: Force the widget size.
+--
 -- @property strategy
--- @tparam string strategy Either 'max', 'min' or 'exact'
+-- @tparam string strategy Either 'max', 'min' or 'exact'.
+-- @propemits true false
 
 function constraint:set_strategy(val)
     local func = {
@@ -80,6 +89,7 @@ function constraint:set_strategy(val)
 
     self._private.strategy = func[val]
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::strategy", val)
 end
 
 function constraint:get_strategy()
@@ -87,12 +97,15 @@ function constraint:get_strategy()
 end
 
 --- Set the maximum width to val. nil for no width limit.
+--
 -- @property height
--- @param number
+-- @tparam number height
+-- @propemits true false
 
 function constraint:set_width(val)
     self._private.width = val
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::width", val)
 end
 
 function constraint:get_width()
@@ -100,21 +113,28 @@ function constraint:get_width()
 end
 
 --- Set the maximum height to val. nil for no height limit.
+--
 -- @property width
--- @param number
+-- @tparam number width
+-- @propemits true false
 
 function constraint:set_height(val)
     self._private.height = val
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::height", val)
 end
 
 function constraint:get_height()
     return self._private.height
 end
 
---- Reset this layout. The widget will be unreferenced, strategy set to "max"
+--- Reset this layout.
+--
+--The widget will be unreferenced, strategy set to "max"
 -- and the constraints set to nil.
+--
 -- @method reset
+-- @interface container
 function constraint:reset()
     self._private.width = nil
     self._private.height = nil
@@ -123,6 +143,7 @@ function constraint:reset()
 end
 
 --- Returns a new constraint container.
+--
 -- This container will constraint the size of a
 -- widget according to the strategy. Note that this will only work for layouts
 -- that respect the widget's size, eg. fixed layout. In layouts that don't

lib/wibox/container/margin.lua

@@ -1,4 +1,5 @@
 ---------------------------------------------------------------------------
+-- Add a margin around a widget.
 --
 --@DOC_wibox_container_defaults_margin_EXAMPLE@
 -- @author Uli Schlachter
@@ -70,8 +71,10 @@ function margin:fit(context, width, height)
 end
 
 --- The widget to be wrapped the the margins.
+--
 -- @property widget
 -- @tparam widget widget The widget
+-- @interface container
 
 margin.set_widget = base.set_widget_common
 
@@ -88,9 +91,11 @@ function margin:set_children(children)
 end
 
 --- Set all the margins to val.
+--
 -- @property margins
 -- @tparam number|table val The margin value. It can be a number or a table with
 --  the *left*/*right*/*top*/*bottom* keys.
+-- @propemits false false
 
 function margin:set_margins(val)
 
@@ -114,28 +119,36 @@ function margin:set_margins(val)
     end
 
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::margins")
 end
 
 --- Set the margins color to create a border.
+--
 -- @property color
 -- @param color A color used to fill the margin.
+-- @propemits true false
 
 function margin:set_color(color)
     self._private.color = color and gcolor(color)
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::color", color)
 end
 
 function margin:get_color()
     return self._private.color
 end
 
---- Draw the margin even if the content size is 0x0 (default: true)
+--- Draw the margin even if the content size is 0x0.
--- @method draw_empty
+--
--- @tparam boolean draw_empty Draw nothing is content is 0x0 or draw the margin anyway
+-- @property draw_empty
+-- @tparam[opt=true] boolean draw_empty Draw nothing is content is 0x0 or draw
+--  the margin anyway.
+-- @propemits true false
 
 function margin:set_draw_empty(draw_empty)
     self._private.draw_empty = draw_empty
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::draw_empty", draw_empty)
 end
 
 function margin:get_draw_empty()
@@ -145,6 +158,7 @@ end
 --- Reset this layout. The widget will be unreferenced, the margins set to 0
 -- and the color erased
 -- @method reset
+-- @interface container
 function margin:reset()
     self:set_widget(nil)
     self:set_margins(0)
@@ -152,20 +166,28 @@ function margin:reset()
 end
 
 --- Set the left margin that this layout adds to its widget.
--- @param margin The new margin to use.
+--
 -- @property left
+-- @tparam number left The new margin to use.
+-- @propemits true false
 
 --- Set the right margin that this layout adds to its widget.
--- @param margin The new margin to use.
+--
 -- @property right
+-- @tparam number right The new margin to use.
+-- @propemits true false
 
 --- Set the top margin that this layout adds to its widget.
--- @param margin The new margin to use.
+--
 -- @property top
+-- @tparam number top The new margin to use.
+-- @propemits true false
 
 --- Set the bottom margin that this layout adds to its widget.
--- @param margin The new margin to use.
+--
 -- @property bottom
+-- @tparam number bottom The new margin to use.
+-- @propemits true false
 
 -- Create setters for each direction
 for _, v in pairs({ "left", "right", "top", "bottom" }) do
@@ -173,6 +195,7 @@ for _, v in pairs({ "left", "right", "top", "bottom" }) do
         if layout._private[v] == val then return end
         layout._private[v] = val
         layout:emit_signal("widget::layout_changed")
+        layout:emit_signal("property::".. v, val)
     end
 
     margin["get_" .. v] = function(layout)
@@ -181,6 +204,7 @@ for _, v in pairs({ "left", "right", "top", "bottom" }) do
 end
 
 --- Returns a new margin container.
+--
 -- @param[opt] widget A widget to use.
 -- @param[opt] left A margin to use on the left side of the widget.
 -- @param[opt] right A margin to use on the right side of the widget.

lib/wibox/container/mirror.lua

@@ -1,4 +1,5 @@
 ---------------------------------------------------------------------------
+-- Reflect a widget along one or both axis.
 --
 --@DOC_wibox_container_defaults_mirror_EXAMPLE@
 -- @author dodo
@@ -37,7 +38,7 @@ function mirror:layout(_, width, height)
     return { base.place_widget_via_matrix(self._private.widget, m, width, height) }
 end
 
--- Fit this layout into the given area
+-- Fit this layout into the given area.
 function mirror:fit(context, ...)
     if not self._private.widget then
         return 0, 0
@@ -46,8 +47,10 @@ function mirror:fit(context, ...)
 end
 
 --- The widget to be reflected.
+--
 -- @property widget
--- @tparam widget widget The widget
+-- @tparam widget widget The widget.
+-- @interface container
 
 mirror.set_widget = base.set_widget_common
 
@@ -64,7 +67,9 @@ function mirror:set_children(children)
 end
 
 --- Reset this layout. The widget will be removed and the axes reset.
+--
 -- @method reset
+-- @interface container
 function mirror:reset()
     self._private.horizontal = false
     self._private.vertical = false
@@ -82,25 +87,29 @@ function mirror:set_reflection(reflection)
         end
     end
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::reflection", reflection)
 end
 
 --- Get the reflection of this mirror layout.
+--
 -- @property reflection
 -- @tparam table reflection A table of booleans with the keys "horizontal", "vertical".
 -- @tparam boolean reflection.horizontal
 -- @tparam boolean reflection.vertical
+-- @propemits true false
 
 function mirror:get_reflection()
     return { horizontal = self._private.horizontal, vertical = self._private.vertical }
 end
 
 --- Returns a new mirror container.
--- A mirror container mirrors a given widget. Use
+--
--- `:set_widget()` to set the widget and
+-- A mirror container mirrors a given widget. Use the `widget` property to set
--- `:set_horizontal()` and `:set_vertical()` for the direction.
+-- the widget and `reflection` property to set the direction.
 -- horizontal and vertical are by default false which doesn't change anything.
--- @param[opt] widget The widget to display.
+--
--- @param[opt] reflection A table describing the reflection to apply.
+-- @tparam[opt] widget widget The widget to display.
+-- @tparam[opt] table reflection A table describing the reflection to apply.
 -- @treturn table A new mirror container
 -- @constructorfct wibox.container.mirror
 local function new(widget, reflection)

lib/wibox/container/place.lua

@@ -62,8 +62,10 @@ function place:fit(context, width, height)
 end
 
 --- The widget to be placed.
+--
 -- @property widget
 -- @tparam widget widget The widget
+-- @interface container
 
 place.set_widget = base.set_widget_common
 
@@ -71,10 +73,6 @@ function place:get_widget()
     return self._private.widget
 end
 
---- Get or set the children elements.
--- @property children
--- @tparam table children The children.
-
 function place:get_children()
     return {self._private.widget}
 end
@@ -85,6 +83,7 @@ end
 
 --- Reset this layout. The widget will be removed and the rotation reset.
 -- @method reset
+-- @interface container
 function place:reset()
     self:set_widget(nil)
 end
@@ -98,7 +97,8 @@ end
 -- * *bottom*
 --
 -- @property valign
--- @param[opt="center"] string
+-- @tparam[opt="center"] string valign
+-- @propemits true false
 
 --- The horizontal alignment.
 --
@@ -109,7 +109,8 @@ end
 -- * *right*
 --
 -- @property halign
--- @param[opt="center"] string
+-- @tparam[opt="center"] string halign
+-- @propemits true false
 
 function place:set_valign(value)
     if value ~= "center" and value ~= "top" and value ~= "bottom" then
@@ -118,6 +119,7 @@ function place:set_valign(value)
 
     self._private.valign = value
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::valign", value)
 end
 
 function place:set_halign(value)
@@ -127,46 +129,60 @@ function place:set_halign(value)
 
     self._private.halign = value
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::halign", value)
 end
 
 --- Fill the vertical space.
+--
 -- @property fill_vertical
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean fill_vertical
+-- @propemits true false
 
 function place:set_fill_vertical(value)
     self._private.fill_vertical = value
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::fill_vertical", value)
 end
 
 --- Fill the horizontal space.
+--
 -- @property fill_horizontal
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean fill_horizontal
+-- @propemits true false
 
 function place:set_fill_horizontal(value)
     self._private.fill_horizontal = value
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::fill_horizontal", value)
 end
 
 --- Stretch the contained widget so it takes all the vertical space.
+--
 -- @property content_fill_vertical
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean content_fill_vertical
+-- @propemits true false
 
 function place:set_content_fill_vertical(value)
     self._private.content_fill_vertical = value
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::content_fill_vertical", value)
 end
 
 --- Stretch the contained widget so it takes all the horizontal space.
+--
 -- @property content_fill_horizontal
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean content_fill_horizontal
+-- @propemits true false
 
 function place:set_content_fill_horizontal(value)
     self._private.content_fill_horizontal = value
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::content_fill_horizontal", value)
 end
 
 --- Returns a new place container.
--- @param[opt] widget The widget to display.
+--
+-- @tparam[opt] widget widget The widget to display.
 -- @tparam[opt="center"] string halign The horizontal alignment
 -- @tparam[opt="center"] string valign The vertical alignment
 -- @treturn table A new place container.

lib/wibox/container/radialprogressbar.lua

@@ -1,5 +1,4 @@
 ---------------------------------------------------------------------------
---
 -- A circular progressbar wrapper.
 --
 -- If no child `widget` is set, then the radialprogressbar will take all the
@@ -23,14 +22,17 @@ local default_outline_width  = 2
 local radialprogressbar = { mt = {} }
 
 --- The progressbar border background color.
+--
 -- @beautiful beautiful.radialprogressbar_border_color
 -- @param color
 
 --- The progressbar foreground color.
+--
 -- @beautiful beautiful.radialprogressbar_color
 -- @param color
 
 --- The progressbar border width.
+--
 -- @beautiful beautiful.radialprogressbar_border_width
 -- @param number
 
@@ -126,8 +128,10 @@ function radialprogressbar:fit(context, width, height)
 end
 
 --- The widget to wrap in a radial proggressbar.
+--
 -- @property widget
 -- @tparam widget widget The widget
+-- @interface container
 
 radialprogressbar.set_widget = base.set_widget_common
 
@@ -141,7 +145,9 @@ function radialprogressbar:set_children(children)
 end
 
 --- Reset this container.
+--
 -- @method reset
+-- @interface container
 function radialprogressbar:reset()
     self:set_widget(nil)
 end
@@ -156,6 +162,7 @@ for _,v in ipairs {"left", "right", "top", "bottom"} do
 end
 
 --- The padding between the outline and the progressbar.
+--
 --@DOC_wibox_container_radialprogressbar_padding_EXAMPLE@
 -- @property paddings
 -- @tparam[opt=0] table|number paddings A number or a table
@@ -163,11 +170,15 @@ end
 -- @tparam[opt=0] number paddings.bottom
 -- @tparam[opt=0] number paddings.left
 -- @tparam[opt=0] number paddings.right
+-- @propbeautiful
+-- @propemits false false
 
 --- The progressbar value.
+--
 --@DOC_wibox_container_radialprogressbar_value_EXAMPLE@
 -- @property value
--- @tparam number value Between min_value and max_value
+-- @tparam number value Between min_value and max_value.
+-- @propemits true false
 
 function radialprogressbar:set_value(val)
     if not val then self._percent = 0; return end
@@ -182,36 +193,50 @@ function radialprogressbar:set_value(val)
 
     self._percent = val/delta
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::value", val)
 end
 
 --- The border background color.
+--
 --@DOC_wibox_container_radialprogressbar_border_color_EXAMPLE@
 -- @property border_color
--- @param color
+-- @tparam color border_color
+-- @propbeautiful
+-- @propemits true false
 
 --- The border foreground color.
+--
 --@DOC_wibox_container_radialprogressbar_color_EXAMPLE@
 -- @property color
--- @param color
+-- @tparam color color
+-- @propbeautiful
+-- @propemits true false
 
 --- The border width.
+--
 --@DOC_wibox_container_radialprogressbar_border_width_EXAMPLE@
 -- @property border_width
 -- @tparam[opt=3] number border_width
+-- @propbeautiful
+-- @propemits true false
 
 --- The minimum value.
+--
 -- @property min_value
--- @param number
+-- @tparam number min_value
+-- @propemits true false
 
 --- The maximum value.
+--
 -- @property max_value
--- @param number
+-- @tparam number max_value
+-- @propemits true false
 
 for _, prop in ipairs {"max_value", "min_value", "border_color", "color",
     "border_width", "paddings"} do
     radialprogressbar["set_"..prop] = function(self, value)
         self._private[prop] = value
-        self:emit_signal("property::"..prop)
+        self:emit_signal("property::"..prop, value)
         self:emit_signal("widget::redraw_needed")
     end
     radialprogressbar["get_"..prop] = function(self)
@@ -231,9 +256,12 @@ function radialprogressbar:set_paddings(val)
     self:emit_signal("widget::layout_changed")
 end
 
---- Returns a new radialprogressbar layout. A radialprogressbar layout
+--- Returns a new radialprogressbar layout.
--- radialprogressbars a given widget. Use `.widget` to set the widget.
+--
--- @param[opt] widget The widget to display.
+-- A radialprogressbar layout  radialprogressbars a given widget. Use `.widget`
+-- to set the widget.
+--
+-- @tparam[opt] widget widget The widget to display.
 -- @constructorfct wibox.container.radialprogressbar
 local function new(widget)
     local ret = base.make_widget(nil, nil, {

lib/wibox/container/rotate.lua

@@ -59,8 +59,10 @@ function rotate:fit(context, width, height)
 end
 
 --- The widget to be rotated.
+--
 -- @property widget
--- @tparam widget widget The widget
+-- @tparam widget widget The widget.
+-- @interface container
 
 rotate.set_widget = base.set_widget_common
 
@@ -76,18 +78,19 @@ function rotate:set_children(children)
     self:set_widget(children[1])
 end
 
---- Reset this layout. The widget will be removed and the rotation reset.
+--- Reset this layout.
+--
+-- The widget will be removed and the rotation reset.
+--
 -- @method reset
+-- @interface container
 function rotate:reset()
     self._private.direction = nil
     self:set_widget(nil)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 --- The direction of this rotating container.
+--
 -- Valid values are:
 --
 -- * *north*
@@ -97,7 +100,8 @@ end
 --
 --@DOC_wibox_container_rotate_angle_EXAMPLE@
 -- @property direction
--- @tparam string dir The direction
+-- @tparam string dir The direction.
+-- @propemits true false
 
 function rotate:set_direction(dir)
     local allowed = {
@@ -113,6 +117,7 @@ function rotate:set_direction(dir)
 
     self._private.direction = dir
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::direction")
 end
 
 -- Get the direction of this rotating layout
@@ -121,11 +126,12 @@ function rotate:get_direction()
 end
 
 --- Returns a new rotate container.
--- A rotate container rotates a given widget. Use
+--
--- :set_widget() to set the widget and :set_direction() for the direction.
+-- A rotate container rotates a given widget. Use the `widget` property
+-- to set the widget and `direction` property for the direction.
 -- The default direction is "north" which doesn't change anything.
--- @param[opt] widget The widget to display.
+-- @tparam[opt] widget widget The widget to display.
--- @param[opt] dir The direction to rotate to.
+-- @tparam[opt] string dir The direction to rotate to.
 -- @treturn table A new rotate container.
 -- @constructorfct wibox.container.rotate
 local function new(widget, dir)
@@ -143,6 +149,10 @@ function rotate.mt:__call(...)
     return new(...)
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(rotate, rotate.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80