Merge pull request #2929 from Elv13/doc_fix_modules_summaries

Doc fix modules summaries

docs/common/fixed.ldoc

@@ -1,42 +1,65 @@
 --- Set a widget at a specific index, replace the current one.
--- **Signal:** widget::replaced The argument is the new widget and the old one
+--
--- and the index.
 -- @tparam number index A widget or a widget index
--- @param widget2 The widget to take the place of the first one
+-- @tparam widget widget2 The widget to take the place of the first one
 -- @treturn boolean If the operation is successful
 -- @method set
+-- @emits widget::replaced
+-- @emitstparam widget::replaced widget self The layout.
+-- @emitstparam widget::replaced widget widget index The inserted widget.
+-- @emitstparam widget::replaced widget previous The previous widget.
+-- @emitstparam widget::replaced number index The replaced index.
+-- @interface layout
 
 --- Replace the first instance of `widget` in the layout with `widget2`.
+--
 -- **Signal:** widget::replaced The argument is the new widget and the old one
 -- and the index.
--- @param widget The widget to replace
+-- @tparam widget widget The widget to replace
--- @param widget2 The widget to replace `widget` with
+-- @tparam widget widget2 The widget to replace `widget` with
 -- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
 -- @treturn boolean If the operation is successful
 -- @method replace_widget
+-- @emits widget::replaced
+-- @emitstparam widget::replaced widget self The layout.
+-- @emitstparam widget::replaced widget widget index The inserted widget.
+-- @emitstparam widget::replaced widget previous The previous widget.
+-- @emitstparam widget::replaced number index The replaced index.
+-- @interface layout
 
 --- Swap 2 widgets in a layout.
--- **Signal:** widget::swapped The arguments are both widgets and both (new) indexes.
+--
 -- @tparam number index1 The first widget index
 -- @tparam number index2 The second widget index
 -- @treturn boolean If the operation is successful
 -- @method swap
+-- @emits widget::swapped
+-- @emitstparam widget::swapped widget self The layout.
+-- @emitstparam widget::swapped widget widget1 index The first widget.
+-- @emitstparam widget::swapped widget widget2 index The second widget.
+-- @emitstparam widget::swapped number index1 The first index.
+-- @emitstparam widget::swapped number index1 The second index.
+-- @interface layout
 
 --- Swap 2 widgets in a layout.
 -- If widget1 is present multiple time, only the first instance is swapped
 -- **Signal:** widget::swapped The arguments are both widgets and both (new) indexes.
 -- if the layouts not the same, then only `widget::replaced` will be emitted.
--- @param widget1 The first widget
+-- @tparam widget widget1 The first widget
--- @param widget2 The second widget
+-- @tparam widget widget2 The second widget
 -- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
 -- @treturn boolean If the operation is successful
 -- @method swap_widgets
-
+-- @emits widget::swapped
---- Get all direct children of this layout.
+-- @emitstparam widget::swapped widget self The layout.
--- @param layout The layout you are modifying.
+-- @emitstparam widget::swapped widget widget1 index The first widget.
--- @property children
+-- @emitstparam widget::swapped widget widget2 index The second widget.
+-- @emitstparam widget::swapped number index1 The first index.
+-- @emitstparam widget::swapped number index1 The second index.
+-- @interface layout
 
 --- Reset a ratio layout. This removes all widgets from the layout.
--- **Signal:** widget::reset
--- @param layout The layout you are modifying.
 -- @method reset
+-- @emits widget::reset
+-- @emitstparam widget::reset widget self The layout.
+-- @interface layout

docs/common/widget.ldoc

@@ -59,7 +59,7 @@
 
 --- Add a new `awful.button` to this widget.
 -- @tparam awful.button button The button to add.
--- @function add_button
+-- @method add_button
 -- @baseclass wibox.widget
 
 --- Emit a signal and ensure all parent widgets in the hierarchies also
@@ -67,8 +67,8 @@
 -- set of containers and layouts wrapping the widget.
 -- @tparam string signal_name
 -- @param ... Other arguments
--- @method emit_signal_recursive
 -- @baseclass wibox.widget
+-- @method emit_signal_recursive
 
 --- When the layout (size) change.
 -- This signal is emitted when the previous results of `:layout()` and `:fit()`

docs/config.ld

@@ -344,6 +344,56 @@ add_custom_tag {
     hidden = true
 }
 
+-- Define which interface a method or property implements.
+-- @interface container
+add_custom_tag {
+    name   = "interface",
+    hidden = true
+}
+
+-- Specify when this an item was deprecated.
+-- @deprecatedin 4.4 Optional message.
+add_custom_tag {
+    name   = "deprecatedin",
+    hidden = true,
+    params = {
+        { name = "api_level" },
+    },
+}
+
+-- Specify when this an item was deprecated because it was renamed.
+-- @renamedin 4.4 new_name Optional message.
+add_custom_tag {
+    name   = "renamedin",
+    hidden = true,
+    params = {
+        { name = "api_level" },
+        { name = "new_name"  },
+    },
+}
+
+-- Specify when this an item was deprecated because it was moved.
+-- @movedin 4.4 new_class new_name Optional message.
+add_custom_tag {
+    name   = "movedin",
+    hidden = true,
+    params = {
+        { name = "api_level" },
+        { name = "new_class" },
+        { name = "new_name"  },
+    },
+}
+
+-- Specify when an item was added.
+-- @introducedin 4.4
+add_custom_tag {
+    name   = "introducedin",
+    hidden = true,
+    params = {
+        { name = "api_level" },
+    },
+}
+
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries', script='Sample files'}
 
@@ -444,10 +494,10 @@ local named_args = {
 
 -- Sections which are hidden by default, but visible when clicked.
 local summarize = {
-    emits         = {index = 1, title = "Signals"        },
+    emits         = {index = 1, title = "signals"        },
-    propemits     = {index = 2, title = "Signals"        },
+    propemits     = {index = 2, title = "signals"        },
-    usebeautiful  = {index = 3, title = "Theme variables"},
+    usebeautiful  = {index = 3, title = "theme variables"},
-    propbeautiful = {index = 4, title = "Theme variables"}
+    propbeautiful = {index = 4, title = "theme variables"}
 }
 
 local delimiter_for_tag = {
@@ -591,7 +641,6 @@ local function wrap_args(item)
     return "<span class='function_args'> <b>(</b>"..new_args.."<b>)</b></span>"
 end
 
-
 -- Mimics the ldoc built-in method style, but better.
 --
 -- This custom renderer exists because using ldoc built-in method detection
@@ -638,7 +687,9 @@ local function sanitize_type(item, ldoc)
     item.display_type = "<span class='summary_type'>N/A</span>"
 end
 local no_prefix = {
-    property = true, signal = true, clientruleproperty = true,
+    property           = true,
+    signal             = true,
+    clientruleproperty = true,
     deprecatedproperty = true,
 }
 
@@ -733,7 +784,6 @@ custom_display_name_handler = function(item, default_handler)
         ret = render_methods(item)
     end
 
-
     -- Get rid of the "module:" in front of method names. It is either wrong or
     -- just redundant.
     ret = ret:gsub("([^:]*)(:[^:])","%2")

docs/ldoc.css

@@ -282,6 +282,7 @@ table.module_list td, table.function_list td {
 table.module_list td.name, table.function_list td.name {
     background-color: white;
     min-width: 200px;
+    border-left-width: 0px;
     border-right-width: 0px;
 }
 table.module_list td.summary, table.function_list td.summary {
@@ -293,14 +294,28 @@ table.module_list td.summary, table.function_list td.summary {
 
 table.function_list td.shortname {
     background-color: white;
+    border-left-width: 0px;
     border-right-width: 0px;
 }
 
+table.function_list td.inheritance {
+    background-color: white;
+    border-right-width: 0px;
+    border-left-width: 0px;
+    color: #a4c7ff;
+    min-width: 200px;
+}
+
 .proptype {
     padding-right: 20px;
     float: right;
 }
 
+span.inheritance {
+    color: #9db9f3;
+    font-weight: normal;
+}
+
 td.summarytype {
     background-color: white;
     color: #a4c7ff;
@@ -402,6 +417,11 @@ ul.nowrap {
     font-weight: normal;
 }
 
+/*.inheritedmethodparent {
+    color: #9db9f3;
+    font-weight: normal;
+}*/
+
 /* stop sublists from having initial vertical space */
 ul ul { margin-top: 0px; }
 ol ul { margin-top: 0px; }
@@ -451,3 +471,14 @@ pre .url { color: #272fc2; text-decoration: underline; }
 .show_more {
     display: default
 }
+.show_more_button {
+    display:block;
+    position: relative;
+    padding-top: 5px;
+    padding-bottom: 5px;
+    padding-right: 15px;
+    padding-left: 15px;
+    border: 1px solid rgb(210, 210, 220);
+    color: rgb(128, 128, 128);
+    border-radius: 7px;
+}

docs/ldoc.ltp

@@ -11,12 +11,12 @@
 # end
    <script>
      function show_extra(id) {
-        var cur = document.getElementById(id).className
+        var cur = document.getElementById("item"+id).className
 
-        if (cur == "hide_extra")
+        if (cur == "hide_extra") {
-            document.getElementById(id).className = "show_more"
+            document.getElementById("item"+id).className = "show_more"
-        else
+            document.getElementById("button"+id).className = "hide_extra"
-            document.getElementById(id).className = "hide_extra"
+        }
      }
    </script>
 
@@ -161,12 +161,12 @@
 #   else
       <td class="name" $(nowrap)><a href="#$(item.name)">$(dn)</a></td>
 #   end
-      <td class="summary">$(M(item.summary,item))</td>
+      <td colspan="$(item.inherited and 1 or 2)" class="summary">$(M(item.summary,item))</td>
-      <td class="baseclass" $(nowrap)>
 #   if item.inherited then
+      <td class="baseclass" $(nowrap)>
         Inherited from $(item.baseclass)
-#   end
       </td>
+#   end
     </tr>
 #  end -- for items
 # last_kind = kind
@@ -210,12 +210,25 @@
     <dt>
     <a name = "$(item.name)"></a>
     <strong>$(display_name(item))</strong>
+#   if item.display_inheritance then
+    <span class="inheritance">
+      &middot Inherited from
+      <a href="$(item.display_inheritance)">$(item.display_inheritance)</a>
+    </span>
+#   end -- display_inheritance
 #   if item.display_type then
     <span class="proptype">($(item.display_type))</span>
 #   end
+    <span class="baseclass" $(nowrap)>
 #   if item.inherited then
-    <span class="baseclass" $(nowrap)>&nbsp;&middot;&nbsp;Inherited from $(item.baseclass)</span>
+    &middot;&nbsp;Inherited from $(item.baseclass)
 #   end
+#   if item.extra_summary then
+#       for _, col in ldoc.ipairs(item.extra_summary) do
+         &middot $(col.count.." "..col.title)
+#       end -- summary col
+#   end -- summary
+    </span>
 #   if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
     <a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
 #  end
@@ -311,10 +324,14 @@
     </ul>
 #   end -- if usage
 
-    <br />
+#   if item.extra_summary then
-    <a class="deprecated_h2" onclick="show_extra('$("item"..item.uid)')">
+     <br />
-     Click to display more
+     <center id=button$(item.uid)>
-    </a>
+     <a class="show_more_button" onclick="show_extra('$(item.uid)')">
+      Click to display more
+     </a>
+     </center>
+#   end
 
     <span id=item$(item.uid) class="hide_extra">
 #    if ldoc.custom_tags then

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/background.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- A container capable of changing the background color, foreground color
+-- A container capable of changing the background color, foreground color and
 -- widget shape.
 --
 --@DOC_wibox_container_defaults_background_EXAMPLE@
@@ -216,7 +216,8 @@ end
 --- The widget displayed in the background widget.
 -- @property widget
 -- @tparam widget widget The widget to be disaplayed inside of the background
---  area
+--  area.
+-- @interface container
 
 background.set_widget = base.set_widget_common
 
@@ -233,10 +234,13 @@ function background:set_children(children)
 end
 
 --- The background color/pattern/gradient to use.
+--
 --@DOC_wibox_container_background_bg_EXAMPLE@
+--
 -- @property bg
--- @param bg A color string, pattern or gradient
+-- @tparam color bg A color string, pattern or gradient
 -- @see gears.color
+-- @propemits true false
 
 function background:set_bg(bg)
     if bg then
@@ -245,6 +249,7 @@ function background:set_bg(bg)
         self._private.background = nil
     end
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::bg", bg)
 end
 
 function background:get_bg()
@@ -252,9 +257,12 @@ function background:get_bg()
 end
 
 --- The foreground (text) color/pattern/gradient to use.
+--
 --@DOC_wibox_container_background_fg_EXAMPLE@
+--
 -- @property fg
--- @param fg A color string, pattern or gradient
+-- @tparam color fg A color string, pattern or gradient
+-- @propemits true false
 -- @see gears.color
 
 function background:set_fg(fg)
@@ -264,6 +272,7 @@ function background:set_fg(fg)
         self._private.foreground = nil
     end
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::fg", fg)
 end
 
 function background:get_fg()
@@ -275,16 +284,19 @@ end
 -- Use `set_shape` to set additional shape paramaters.
 --
 --@DOC_wibox_container_background_shape_EXAMPLE@
+--
 -- @property shape
--- @param shape A function taking a context, width and height as arguments
+-- @tparam gears.shape|function shape A function taking a context, width and height as arguments
 -- @see gears.shape
 -- @see set_shape
 
 --- Set the background shape.
 --
--- Any other arguments will be passed to the shape function
+-- Any other arguments will be passed to the shape function.
+--
 -- @method set_shape
--- @param shape A function taking a context, width and height as arguments
+-- @tparam gears.shape|function shape A function taking a context, width and height as arguments
+-- @propemits true false
 -- @see gears.shape
 -- @see shape
 function background:set_shape(shape, ...)
@@ -295,6 +307,7 @@ function background:set_shape(shape, ...)
     self._private.shape = shape
     self._private.shape_args = {...}
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::shape", shape)
 end
 
 function background:get_shape()
@@ -304,8 +317,10 @@ end
 --- When a `shape` is set, also draw a border.
 --
 -- See `wibox.container.background.shape` for an usage example.
+--
 -- @deprecatedproperty shape_border_width
 -- @tparam number width The border width
+-- @renamedin 4.4 border_width
 -- @see border_width
 
 --- Add a border of a specific width.
@@ -315,6 +330,8 @@ end
 -- See `wibox.container.background.shape` for an usage example.
 -- @property border_width
 -- @tparam[opt=0] number width The border width.
+-- @propemits true false
+-- @introducedin 4.4
 -- @see border_color
 
 function background:set_border_width(width)
@@ -322,6 +339,7 @@ function background:set_border_width(width)
 
     self._private.shape_border_width = width
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::border_width", width)
 end
 
 function background:get_border_width()
@@ -345,8 +363,11 @@ end
 --- When a `shape` is set, also draw a border.
 --
 -- See `wibox.container.background.shape` for an usage example.
+--
 -- @deprecatedproperty shape_border_color
--- @param[opt=self._private.foreground] fg The border color, pattern or gradient
+-- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set.
+-- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient
+-- @renamedin 4.4 border_color
 -- @see gears.color
 -- @see border_color
 
@@ -354,7 +375,10 @@ end
 --
 -- See `wibox.container.background.shape` for an usage example.
 -- @property border_color
--- @param[opt=self._private.foreground] fg The border color, pattern or gradient
+-- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient
+-- @propemits true false
+-- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set.
+-- @introducedin 4.4
 -- @see gears.color
 -- @see border_width
 
@@ -363,6 +387,7 @@ function background:set_border_color(fg)
 
     self._private.shape_border_color = fg
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::border_color", fg)
 end
 
 function background:get_border_color()
@@ -403,24 +428,28 @@ end
 -- * *inner*: Squeeze the size of the content by the border width.
 --
 -- @property border_strategy
--- @param[opt="none"] string
+-- @tparam[opt="none"] string border_strategy
 
 function background:set_border_strategy(value)
     self._private.border_strategy = value
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::border_strategy", value)
 end
 
---- The background image to use
+--- The background image to use.
+--
 -- If `image` is a function, it will be called with `(context, cr, width, height)`
 -- as arguments. Any other arguments passed to this method will be appended.
+--
 -- @property bgimage
--- @param image A background image or a function
+-- @tparam string|surface|function image A background image or a function
 -- @see gears.surface
 
 function background:set_bgimage(image, ...)
     self._private.bgimage = type(image) == "function" and image or surface.load(image)
     self._private.bgimage_args = {...}
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::bgimage", image)
 end
 
 function background:get_bgimage()
@@ -431,9 +460,10 @@ end
 --
 -- A background container applies a background and foreground color
 -- to another widget.
--- @param[opt] widget The widget to display.
+--
--- @param[opt] bg The background to use for that widget.
+-- @tparam[opt] widget widget The widget to display.
--- @param[opt] shape A `gears.shape` compatible shape function
+-- @tparam[opt] color bg The background to use for that widget.
+-- @tparam[opt] gears.shape|function shape A `gears.shape` compatible shape function
 -- @constructorfct wibox.container.background
 local function new(widget, bg, shape)
     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

lib/wibox/layout/align.lua

@@ -142,7 +142,8 @@ end
 --- Set the layout's first widget.
 -- This is the widget that is at the left/top
 -- @property first
--- @param widget
+-- @tparam widget first
+-- @propemits true false
 
 function align:set_first(widget)
     if self._private.first == widget then
@@ -150,11 +151,13 @@ function align:set_first(widget)
     end
     self._private.first = widget
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::first", widget)
 end
 
 --- Set the layout's second widget. This is the centered one.
 -- @property second
--- @param widget
+-- @tparam widget second
+-- @propemits true false
 
 function align:set_second(widget)
     if self._private.second == widget then
@@ -162,12 +165,14 @@ function align:set_second(widget)
     end
     self._private.second = widget
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::second", widget)
 end
 
 --- Set the layout's third widget.
 -- This is the widget that is at the right/bottom
 -- @property third
--- @param widget
+-- @tparam widget third
+-- @propemits true false
 
 function align:set_third(widget)
     if self._private.third == widget then
@@ -175,6 +180,7 @@ function align:set_third(widget)
     end
     self._private.third = widget
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::third", widget)
 end
 
 for _, prop in ipairs {"first", "second", "third", "expand" } do
@@ -183,12 +189,6 @@ for _, prop in ipairs {"first", "second", "third", "expand" } do
     end
 end
 
---- All direct children of this layout.
--- This can be used to replace all 3 widgets at once.
--- @treturn table a list of all widgets
--- @property children
--- @param table
-
 function align:get_children()
     return gtable.from_sparse {self._private.first, self._private.second, self._private.third}
 end
@@ -229,7 +229,7 @@ end
 --- Set the expand mode which determines how sub widgets expand to take up
 -- unused space.
 --
--- @tparam[opt=inside] string mode How to use unused space.
+-- The following values are valid:
 --
 -- * "inside" - Default option. Size of outside widgets is determined using
 --   their fit function. Second, middle, or center widget expands to fill
@@ -240,7 +240,9 @@ end
 -- * "none" - All widgets are sized using their fit function, drawn to only the
 --   returned space, or remaining space, whichever is smaller. Center widget
 --   gets priority.
+--
 -- @property expand
+-- @tparam[opt=inside] string mode How to use unused space.
 
 function align:set_expand(mode)
     if mode == "none" or mode == "outside" then
@@ -249,6 +251,7 @@ function align:set_expand(mode)
         self._private.expand = "inside"
     end
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::expand", mode)
 end
 
 function align:reset()

lib/wibox/layout/fixed.lua

@@ -62,9 +62,11 @@ function fixed:layout(context, width, height)
     return result
 end
 
---- Add some widgets to the given layout
+--- Add some widgets to the given layout.
+--
 -- @method add
--- @param ... Widgets that should be added (must at least be one)
+-- @tparam widget ... Widgets that should be added (must at least be one).
+-- @interface layout
 function fixed:add(...)
     -- No table.pack in Lua 5.1 :-(
     local args = { n=select('#', ...), ... }
@@ -78,10 +80,12 @@ function fixed:add(...)
 end
 
 
---- Remove a widget from the layout
+--- Remove a widget from the layout.
+--
 -- @method remove
 -- @tparam number index The widget index to remove
 -- @treturn boolean index If the operation is successful
+-- @interface layout
 function fixed:remove(index)
     if not index or index < 1 or index > #self._private.widgets then return false end
 
@@ -92,12 +96,14 @@ function fixed:remove(index)
     return true
 end
 
---- Remove one or more widgets from the layout
+--- Remove one or more widgets from the layout.
+--
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
 -- @method remove_widgets
--- @param widget ... Widgets that should be removed (must at least be one)
+-- @tparam widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
+-- @interface layout
 function fixed:remove_widgets(...)
     local args = { ... }
 
@@ -131,12 +137,13 @@ function fixed:set_children(children)
     end
 end
 
---- Replace the first instance of `widget` in the layout with `widget2`
+--- Replace the first instance of `widget` in the layout with `widget2`.
 -- @method replace_widget
--- @param widget The widget to replace
+-- @tparam widget widget The widget to replace
--- @param widget2 The widget to replace `widget` with
+-- @tparam widget widget2 The widget to replace `widget` with
 -- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
 -- @treturn boolean If the operation is successful
+-- @interface layout
 function fixed:replace_widget(widget, widget2, recursive)
     local idx, l = self:index(widget, recursive)
 
@@ -217,19 +224,27 @@ end
 --@DOC_wibox_layout_fixed_spacing_widget_EXAMPLE@
 --
 -- @property spacing_widget
--- @param widget
+-- @tparam widget spacing_widget
+-- @propemits true false
+-- @interface layout
 
 function fixed:set_spacing_widget(wdg)
     self._private.spacing_widget = base.make_widget_from_value(wdg)
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::spacing_widget", wdg)
 end
 
 --- Insert a new widget in the layout at position `index`.
--- **Signal:** widget::inserted The arguments are the widget and the index
+--
 -- @method insert
--- @tparam number index The position
+-- @tparam number index The position.
--- @param widget The widget
+-- @tparam widget widget The widget.
--- @treturn boolean If the operation is successful
+-- @treturn boolean If the operation is successful.
+-- @emits widget::inserted
+-- @emitstparam widget::inserted widget self The fixed layout.
+-- @emitstparam widget::inserted widget widget index The inserted widget.
+-- @emitstparam widget::inserted number count The widget count.
+-- @interface layout
 function fixed:insert(index, widget)
     if not index or index < 1 or index > #self._private.widgets + 1 then return false end
 
@@ -286,18 +301,21 @@ function fixed:reset()
     self._private.widgets = {}
     self:emit_signal("widget::layout_changed")
     self:emit_signal("widget::reseted")
+    self:emit_signal("widget::reset")
 end
 
 --- Set the layout's fill_space property. If this property is true, the last
 -- widget will get all the space that is left. If this is false, the last widget
 -- won't be handled specially and there can be space left unused.
 -- @property fill_space
--- @param boolean
+-- @tparam boolean fill_space
+-- @propemits true false
 
 function fixed:fill_space(val)
     if self._private.fill_space ~= val then
         self._private.fill_space = not not val
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::fill_space", val)
     end
 end
 
@@ -346,11 +364,14 @@ end
 --
 -- @property spacing
 -- @tparam number spacing Spacing between widgets.
+-- @propemits true false
+-- @interface layout
 
 function fixed:set_spacing(spacing)
     if self._private.spacing ~= spacing then
         self._private.spacing = spacing
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::spacing", spacing)
     end
 end
 

lib/wibox/layout/flex.lua

@@ -15,30 +15,40 @@ local gtable = require("gears.table")
 
 local flex = {}
 
---@DOC_fixed_COMMON@
+--- Add some widgets to the given fixed layout.
-
+--
---- Add some widgets to the given fixed layout
+-- @tparam widget ... Widgets that should be added (must at least be one).
--- @param layout The layout you are modifying.
--- @tparam widget ... Widgets that should be added (must at least be one)
 -- @method add
+-- @interface layout
 
---- Remove a widget from the layout
+--- Remove a widget from the layout.
--- @tparam index The widget index to remove
+--
--- @treturn boolean index If the operation is successful
+-- @tparam index The widget index to remove.
+-- @treturn boolean index If the operation is successful.
 -- @method remove
+-- @interface layout
 
---- Remove one or more widgets from the layout
+--- Remove one or more widgets from the layout.
+--
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
--- @param widget ... Widgets that should be removed (must at least be one)
+--
--- @treturn boolean If the operation is successful
+-- @tparam widget ... Widgets that should be removed (must at least be one).
+-- @treturn boolean If the operation is successful.
 -- @method remove_widgets
+-- @interface layout
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
+--
 -- @tparam number index The position
--- @param widget The widget
+-- @tparam widget widget The widget
 -- @treturn boolean If the operation is successful
 -- @method insert
+-- @emits widget::inserted
+-- @emitstparam widget::inserted widget self The fixed layout.
+-- @emitstparam widget::inserted widget widget index The inserted widget.
+-- @emitstparam widget::inserted number count The widget count.
+-- @interface layout
 
 --- The widget used to fill the spacing between the layout elements.
 --
@@ -47,7 +57,9 @@ local flex = {}
 --@DOC_wibox_layout_flex_spacing_widget_EXAMPLE@
 --
 -- @property spacing_widget
--- @param widget
+-- @tparam widget spacing_widget
+-- @propemits true false
+-- @interface layout
 
 --- Add spacing between each layout widgets.
 --
@@ -55,6 +67,7 @@ local flex = {}
 --
 -- @property spacing
 -- @tparam number spacing Spacing between widgets.
+-- @propemits true false
 
 function flex:layout(_, width, height)
     local result = {}
@@ -146,14 +159,18 @@ function flex:fit(context, orig_width, orig_height)
 end
 
 --- Set the maximum size the widgets in this layout will take.
+--
 --That is, maximum width for horizontal and maximum height for vertical.
+--
 -- @property max_widget_size
--- @param number
+-- @tparam number max_widget_size
+-- @propemits true false
 
 function flex:set_max_widget_size(val)
     if self._private.max_widget_size ~= val then
         self._private.max_widget_size = val
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::max_widget_size", val)
     end
 end
 
@@ -167,22 +184,30 @@ local function get_layout(dir, widget1, ...)
     return ret
 end
 
---- Returns a new horizontal flex layout. A flex layout shares the available space
+--- Returns a new horizontal flex layout.
--- equally among all widgets. Widgets can be added via :add(widget).
+--
+-- A flex layout shares the available space.
+-- equally among all widgets. Widgets can be added via `:add(widget)`.
+--
 -- @tparam widget ... Widgets that should be added to the layout.
 -- @constructorfct wibox.layout.flex.horizontal
 function flex.horizontal(...)
     return get_layout("horizontal", ...)
 end
 
---- Returns a new vertical flex layout. A flex layout shares the available space
+--- Returns a new vertical flex layout.
--- equally among all widgets. Widgets can be added via :add(widget).
+--
+-- A flex layout shares the available space
+-- equally among all widgets. Widgets can be added via `:add(widget)`.
+--
 -- @tparam widget ... Widgets that should be added to the layout.
 -- @constructorfct wibox.layout.flex.vertical
 function flex.vertical(...)
     return get_layout("vertical", ...)
 end
 
+--@DOC_fixed_COMMON@
+
 --@DOC_widget_COMMON@
 
 --@DOC_object_COMMON@

lib/wibox/layout/grid.lua

@@ -959,6 +959,8 @@ function grid.mt:__call(...)
     return new(...)
 end
 
+--@DOC_fixed_COMMON@
+
 --@DOC_widget_COMMON@
 
 --@DOC_object_COMMON@

lib/wibox/layout/manual.lua

@@ -18,21 +18,26 @@ local manual_layout = {}
 --- Add some widgets to the given stack layout.
 --
 -- @method add
--- @param layout The layout you are modifying.
 -- @tparam widget ... Widgets that should be added
 
 --- Remove a widget from the layout.
 --
 -- @method remove
--- @tparam index The widget index to remove
+-- @tparam number index The widget index to remove
 -- @treturn boolean index If the operation is successful
+-- @interface layout
 
 --- Insert a new widget in the layout at position `index`.
 --
 -- @method insert
 -- @tparam number index The position
--- @param widget The widget
+-- @tparam widget widget The widget
--- @treturn boolean If the operation is successful
+-- @treturn boolean If the operation is successful.
+-- @emits widget::inserted
+-- @emitstparam widget::inserted widget self The fixed layout.
+-- @emitstparam widget::inserted widget widget index The inserted widget.
+-- @emitstparam widget::inserted number count The widget count.
+-- @interface layout
 function manual_layout:insert(index, widget)
     table.insert(self._private.widgets, index, widget)
 
@@ -41,6 +46,8 @@ function manual_layout:insert(index, widget)
         table.insert(self._private.pos, index, widget.point)
     end
 
+    self:emit_signal("widget::inserted", widget, #self._private.widgets)
+
     self:emit_signal("widget::layout_changed")
 end
 
@@ -50,7 +57,7 @@ end
 -- widget(s) to remove.
 --
 -- @method remove_widgets
--- @param widget ... Widgets that should be removed (must at least be one)
+-- @tparam widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
 
 
@@ -177,6 +184,7 @@ function manual_layout:add_at(widget, point)
 end
 
 --- Move a widget (by index).
+--
 -- @method move
 -- @tparam number index The widget index.
 -- @tparam table|function point A new point value.
@@ -219,6 +227,7 @@ function manual_layout:reset()
 end
 
 --- Create a manual layout.
+--
 -- @constructorfct wibox.layout.manual
 -- @tparam table ... Widgets to add to the layout.
 
@@ -234,6 +243,7 @@ local function new_manual(...)
     return ret
 end
 
+--@DOC_fixed_COMMON@
 
 --@DOC_widget_COMMON@
 

lib/wibox/layout/ratio.lua

@@ -20,8 +20,6 @@ local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility
 
 local ratio = {}
 
---@DOC_fixed_COMMON@
-
 --- The widget used to fill the spacing between the layout elements.
 --
 -- By default, no widget is used.
@@ -29,7 +27,9 @@ local ratio = {}
 --@DOC_wibox_layout_ratio_spacing_widget_EXAMPLE@
 --
 -- @property spacing_widget
--- @param widget
+-- @tparam widget spacing_widget
+-- @propemits true false
+-- @interface layout
 
 --- Add spacing between each layout widgets.
 --
@@ -37,6 +37,8 @@ local ratio = {}
 --
 -- @property spacing
 -- @tparam number spacing Spacing between widgets.
+-- @propemits true false
+-- @interface layout
 
 -- Compute the sum of all ratio (ideally, it should be 1).
 local function gen_sum(self, i_s, i_e)
@@ -227,7 +229,7 @@ end
 -- do nothing.
 --
 -- @method inc_widget_ratio
--- @param widget The widget to ajust
+-- @tparam widget widget The widget to ajust
 -- @tparam number increment An floating point value between -1 and 1 where the
 --   end result is within 0 and 1
 function ratio:inc_widget_ratio(widget, increment)
@@ -336,7 +338,7 @@ end
 --- Update all widgets to match a set of a ratio.
 --
 -- @method ajust_widget_ratio
--- @param widget The widget to ajust
+-- @tparam widget widget The widget to ajust
 -- @tparam number before The sum of the ratio before the widget
 -- @tparam number itself The ratio for "widget"
 -- @tparam number after The sum of the ratio after the widget
@@ -347,9 +349,10 @@ end
 
 --- Add some widgets to the given fixed layout.
 --
--- **Signal:** widget::added The argument are the widgets
 -- @method add
 -- @tparam widget ... Widgets that should be added (must at least be one)
+-- @emits widget::added All new widgets are passed in the parameters.
+-- @emitstparam widget::added widget self The layout.
 function ratio:add(...)
     -- No table.pack in Lua 5.1 :-(
     local args = { n=select('#', ...), ... }
@@ -367,10 +370,13 @@ end
 
 --- Remove a widget from the layout.
 --
--- **Signal:** widget::removed The arguments are the widget and the index
 -- @method remove
 -- @tparam number index The widget index to remove
 -- @treturn boolean index If the operation is successful
+-- @emits widget::removed
+-- @emitstparam widget::removed widget self The fixed layout.
+-- @emitstparam widget::removed widget widget index The removed widget.
+-- @emitstparam widget::removed number index The removed index.
 function ratio:remove(index)
     if not index or not self._private.widgets[index] then return false end
 
@@ -388,11 +394,14 @@ function ratio:remove(index)
 end
 
 --- Insert a new widget in the layout at position `index`.
--- **Signal:** widget::inserted The arguments are the widget and the index
 --
 -- @method insert
--- @tparam number index The position
+-- @tparam number index The position.
--- @param widget The widget
+-- @tparam widget widget The widget.
+-- @emits widget::inserted
+-- @emitstparam widget::inserted widget self The ratio layout.
+-- @emitstparam widget::inserted widget widget index The inserted widget.
+-- @emitstparam widget::inserted number count The widget count.
 function ratio:insert(index, widget)
     if not index or index < 1 or index > #self._private.widgets + 1 then return false end
 
@@ -422,6 +431,7 @@ end
 --
 -- @property inner_fill_strategy
 -- @tparam string inner_fill_strategy One of the value listed above.
+-- @propemits true false
 
 function ratio:get_inner_fill_strategy()
     return self._private.inner_fill_strategy or "default"
@@ -442,6 +452,7 @@ function ratio:set_inner_fill_strategy(strategy)
 
     self._private.inner_fill_strategy = strategy
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::inner_fill_strategy", strategy)
 end
 
 local function get_layout(dir, widget1, ...)
@@ -472,6 +483,8 @@ function ratio.vertical(...)
     return get_layout("vertical", ...)
 end
 
+--@DOC_fixed_COMMON@
+
 --@DOC_widget_COMMON@
 
 --@DOC_object_COMMON@

lib/wibox/layout/stack.lua

@@ -22,35 +22,48 @@ local gtable  = require("gears.table")
 
 local stack = {mt={}}
 
---@DOC_fixed_COMMON@
-
 --- Add some widgets to the given stack layout.
--- @param layout The layout you are modifying.
+--
 -- @tparam widget ... Widgets that should be added (must at least be one)
 -- @method add
+-- @interface layout
 
---- Remove a widget from the layout
+--- Remove a widget from the layout.
+--
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
 -- @method remove
+-- @interface layout
 
 --- Insert a new widget in the layout at position `index`.
+--
 -- @tparam number index The position
--- @param widget The widget
+-- @tparam widget widget The widget
 -- @treturn boolean If the operation is successful
 -- @method insert
+-- @emits widget::inserted
+-- @emitstparam widget::inserted widget self The fixed layout.
+-- @emitstparam widget::inserted widget widget index The inserted widget.
+-- @emitstparam widget::inserted number count The widget count.
+-- @interface layout
 
 --- Remove one or more widgets from the layout.
+--
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
--- @param widget ... Widgets that should be removed (must at least be one)
+--
+-- @tparam widget widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
 -- @method remove_widgets
+-- @interface layout
 
 --- Add spacing around the widget, similar to the margin container.
+--
 --@DOC_wibox_layout_stack_spacing_EXAMPLE@
 -- @property spacing
 -- @tparam number spacing Spacing between widgets.
+-- @propemits true false
+-- @interface layout
 
 function stack:layout(_, width, height)
     local result = {}
@@ -83,7 +96,10 @@ function stack:fit(context, orig_width, orig_height)
 end
 
 --- If only the first stack widget is drawn.
+--
 -- @property top_only
+-- @tparam boolean top_only
+-- @propemits true false
 
 function stack:get_top_only()
     return self._private.top_only
@@ -91,9 +107,12 @@ end
 
 function stack:set_top_only(top_only)
     self._private.top_only = top_only
+    self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::top_only", top_only)
 end
 
 --- Raise a widget at `index` to the top of the stack.
+--
 -- @method raise
 -- @tparam number index the widget index to raise
 function stack:raise(index)
@@ -107,8 +126,9 @@ function stack:raise(index)
 end
 
 --- Raise the first instance of `widget`.
+--
 -- @method raise_widget
--- @param widget The widget to raise
+-- @tparam widget widget The widget to raise
 -- @tparam[opt=false] boolean recursive Also look deeper in the hierarchy to
 --   find the widget
 function stack:raise_widget(widget, recursive)
@@ -134,7 +154,9 @@ end
 --@DOC_wibox_layout_stack_offset_EXAMPLE@
 --
 -- @property horizontal_offset
--- @param number
+-- @tparam number horizontal_offset
+-- @propemits true false
+-- @see vertial_offset
 
 --- Add an vertical offset to each layers.
 --
@@ -142,20 +164,24 @@ end
 -- layers offsets.
 --
 -- @property vertial_offset
--- @param number
+-- @tparam number vertial_offset
+-- @propemits true false
 -- @see horizontal_offset
 
 function stack:set_horizontal_offset(value)
     self._private.h_offset = value
-    self:emit_signal("widget::layout_changed")
+    self:emit_signal("widget::horizontal_offset")
+    self:emit_signal("property::top_only", value)
 end
 
 function stack:set_vertical_offset(value)
     self._private.v_offset = value
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::vertical_offset", value)
 end
 
 --- Create a new stack layout.
+--
 -- @constructorfct wibox.layout.stack
 -- @treturn widget A new stack layout
 
@@ -174,6 +200,8 @@ function stack.mt:__call(_, ...)
     return new(...)
 end
 
+--@DOC_fixed_COMMON@
+
 --@DOC_widget_COMMON@
 
 --@DOC_object_COMMON@

lib/wibox/widget/checkbox.lua

@@ -20,41 +20,50 @@ local gtable    = require( "gears.table"       )
 local checkbox = {}
 
 --- The outer (unchecked area) border width.
+--
 -- @beautiful beautiful.checkbox_border_width
 -- @param number
 
 --- The outer (unchecked area) background color, pattern or gradient.
+--
 -- @beautiful beautiful.checkbox_bg
 -- @param color
 
 --- The outer (unchecked area) border color.
+--
 -- @beautiful beautiful.checkbox_border_color
 -- @param color
 
 --- The checked part border color.
+--
 -- @beautiful beautiful.checkbox_check_border_color
 -- @param color
 
 --- The checked part border width.
+--
 -- @beautiful beautiful.checkbox_check_border_width
 -- @param number
 
 --- The checked part filling color.
+--
 -- @beautiful beautiful.checkbox_check_color
 -- @param number
 
 --- The outer (unchecked area) shape.
+--
 -- @beautiful beautiful.checkbox_shape
--- @tparam gears.shape shape
+-- @tparam gears.shape|function shape
 -- @see gears.shape
 
 --- The checked part shape.
+--
 -- If none is set, then the `shape` property will be used.
 -- @beautiful beautiful.checkbox_check_shape
--- @tparam gears.shape shape
+-- @tparam gears.shape|function shape
 -- @see gears.shape
 
 --- The padding between the outline and the progressbar.
+--
 -- @beautiful beautiful.checkbox_paddings
 -- @tparam[opt=0] table|number paddings A number or a table
 -- @tparam[opt=0] number paddings.top
@@ -63,6 +72,7 @@ local checkbox = {}
 -- @tparam[opt=0] number paddings.right
 
 --- The checkbox color.
+--
 -- This will be used for the unchecked part border color and the checked part
 -- filling color. Note that `check_color` and `border_color` have priority
 -- over this property.
@@ -70,57 +80,87 @@ local checkbox = {}
 -- @param color
 
 --- The outer (unchecked area) border width.
+--
 -- @property border_width
--- @param number
+-- @tparam number border_width
+-- @propbeautiful
+-- @propemits true false
 
 --- The outer (unchecked area) background color, pattern or gradient.
+--
 --@DOC_wibox_widget_checkbox_bg_EXAMPLE@
 -- @property bg
--- @param color
+-- @tparam color bg
+-- @propbeautiful
+-- @propemits true false
 
 --- The outer (unchecked area) border color.
+--
 -- @property border_color
--- @param color
+-- @tparam color border_color
+-- @propbeautiful
+-- @propemits true false
 
 --- The checked part border color.
+--
 -- @property check_border_color
--- @param color
+-- @tparam color check_border_color
+-- @propbeautiful
+-- @propemits true false
 
 --- The checked part border width.
+--
 -- @property check_border_width
--- @param number
+-- @tparam number check_border_width
+-- @propbeautiful
+-- @propemits true false
 
 --- The checked part filling color.
+--
 -- @property check_color
--- @param color
+-- @tparam color check_color
+-- @propbeautiful
+-- @propemits true false
 
 --- The outer (unchecked area) shape.
+--
 --@DOC_wibox_widget_checkbox_shape_EXAMPLE@
 -- @property shape
 -- @tparam gears.shape shape
+-- @propbeautiful
+-- @propemits true false
 -- @see gears.shape
 
 --- The checked part shape.
+--
 -- If none is set, then the `shape` property will be used.
 --@DOC_wibox_widget_checkbox_check_shape_EXAMPLE@
 -- @property check_shape
 -- @tparam gears.shape shape
+-- @propbeautiful
+-- @propemits true false
 -- @see gears.shape
 
 --- The padding between the outline and the progressbar.
+--
 -- @property paddings
 -- @tparam[opt=0] table|number paddings A number or a table
 -- @tparam[opt=0] number paddings.top
 -- @tparam[opt=0] number paddings.bottom
 -- @tparam[opt=0] number paddings.left
 -- @tparam[opt=0] number paddings.right
+-- @propbeautiful
+-- @propemits false false
 
 --- The checkbox color.
+--
 -- This will be used for the unchecked part border color and the checked part
 -- filling color. Note that `check_color` and `border_color` have priority
 -- over this property.
 -- @property color
--- @param color
+-- @tparam color color
+-- @propbeautiful
+-- @propemits true false
 
 local function outline_workarea(self, width, height)
     local offset = (self._private.border_width or
@@ -220,7 +260,7 @@ for _, prop in ipairs {"border_width", "bg", "border_color", "check_border_color
     "checked", "color" } do
     checkbox["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
     checkbox["get_"..prop] = function(self)

lib/wibox/widget/graph.lua

@@ -28,41 +28,53 @@ local beautiful = require("beautiful")
 local graph = { mt = {} }
 
 --- Set the graph border color.
+--
 -- If the value is nil, no border will be drawn.
 --
 -- @property border_color
 -- @tparam gears.color border_color The border color to set.
+-- @propbeautiful
+-- @propemits true false
 -- @see gears.color
 
 --- Set the graph foreground color.
 --
 -- @property color
 -- @tparam color color The graph color.
+-- @usebeautiful beautiful.graph_fg
+-- @propemits true false
 -- @see gears.color
 
 --- Set the graph background color.
 --
 -- @property background_color
 -- @tparam gears.color background_color The graph background color.
+-- @usebeautiful beautiful.graph_bg
+-- @propemits true false
 -- @see gears.color
 
 --- Set the maximum value the graph should handle.
+--
 -- If "scale" is also set, the graph never scales up below this value, but it
 -- automatically scales down to make all data fit.
 --
 -- @property max_value
--- @param number
+-- @tparam number max_value
+-- @propemits true false
 
 --- The minimum value.
+--
 -- Note that the min_value is not supported when used along with the stack
 -- property.
 -- @property min_value
--- @param number
+-- @tparam number min_value
+-- @propemits true false
 
 --- Set the graph to automatically scale its values. Default is false.
 --
 -- @property scale
--- @param boolean
+-- @tparam boolean scale
+-- @propemits true false
 
 --- Set the width or the individual steps.
 --
@@ -71,39 +83,47 @@ local graph = { mt = {} }
 --@DOC_wibox_widget_graph_step_EXAMPLE@
 --
 -- @property step_width
--- @param[opt=1] number
+-- @tparam[opt=1] number step_width
+-- @propemits true false
 
 --- Set the spacing between the steps.
 --
 -- Note that it isn't supported when used along with stacked graphs.
 --
 -- @property step_spacing
--- @param[opt=0] number
+-- @tparam[opt=0] number step_spacing
+-- @propemits true false
 
 --- The step shape.
+--
 -- @property step_shape
--- @param[opt=rectangle] shape
+-- @tparam[opt=rectangle] gears.shape|function step_shape
+-- @propemits true false
 -- @see gears.shape
 
 --- Set the graph to draw stacks. Default is false.
 --
 -- @property stack
--- @param boolean
+-- @tparam boolean stack
+-- @propemits true false
 
 --- Set the graph stacking colors. Order matters.
 --
 -- @property stack_colors
--- @param stack_colors A table with stacking colors.
+-- @tparam table stack_colors A table with stacking colors.
 
 --- The graph background color.
+--
 -- @beautiful beautiful.graph_bg
 -- @param color
 
 --- The graph foreground color.
+--
 -- @beautiful beautiful.graph_fg
 -- @param color
 
 --- The graph border color.
+--
 -- @beautiful beautiful.graph_border_color
 -- @param color
 
@@ -235,8 +255,8 @@ end
 --- Add a value to the graph
 --
 -- @method add_value
--- @param value The value to be added to the graph
+-- @tparam number value The value to be added to the graph
--- @param group The stack color group index.
+-- @tparam[opt] number group The stack color group index.
 function graph:add_value(value, group)
     value = value or 0
     local values = self._private.values
@@ -269,6 +289,7 @@ function graph:add_value(value, group)
 end
 
 --- Clear the graph.
+--
 -- @method clear
 function graph:clear()
     self._private.values = {}
@@ -277,25 +298,31 @@ function graph:clear()
 end
 
 --- Set the graph height.
+--
 -- @property height
--- @param number The height to set.
+-- @tparam number height The height to set.
+-- @propemits true false
 
 function graph:set_height(height)
     if height >= 5 then
         self._private.height = height
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::height", height)
     end
     return self
 end
 
 --- Set the graph width.
+--
 -- @property width
--- @param number The width to set.
+-- @param number width The width to set.
+-- @propemits true false
 
 function graph:set_width(width)
     if width >= 5 then
         self._private.width = width
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::width", width)
     end
     return self
 end
@@ -307,6 +334,7 @@ for _, prop in ipairs(properties) do
             if _graph._private[prop] ~= value then
                 _graph._private[prop] = value
                 _graph:emit_signal("widget::redraw_needed")
+                _graph:emit_signal("property::"..prop, value)
             end
             return _graph
         end
@@ -319,9 +347,10 @@ for _, prop in ipairs(properties) do
 end
 
 --- Create a graph widget.
--- @param args Standard widget() arguments. You should add width and height
+--
+-- @tparam table args Standard widget() arguments. You should add width and height
 -- key to set graph geometry.
--- @return A new graph widget.
+-- @treturn wibox.widget.graph A new graph widget.
 -- @constructorfct wibox.widget.graph
 function graph.new(args)
     args = args or {}

lib/wibox/widget/imagebox.lua

@@ -153,6 +153,7 @@ end
 --
 -- @property image
 -- @tparam image image The image to render.
+-- @propemits false false
 -- @see set_image
 
 --- Set the `imagebox` image.
@@ -201,6 +202,7 @@ function imagebox:set_image(image)
 
     self:emit_signal("widget::redraw_needed")
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::image")
     return true
 end
 
@@ -210,6 +212,7 @@ end
 --
 -- @property clip_shape
 -- @tparam function|gears.shape clip_shape A `gears.shape` compatible shape function.
+-- @propemits true false
 -- @see gears.shape
 -- @see set_clip_shape
 
@@ -227,11 +230,13 @@ function imagebox:set_clip_shape(clip_shape, ...)
     self._private.clip_shape = clip_shape
     self._private.clip_args = {...}
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::clip_shape", clip_shape)
 end
 
 --- Should the image be resized to fit into the available space?
 -- @DOC_wibox_widget_imagebox_resize_EXAMPLE@
 -- @property resize
+-- @propemits true false
 -- @tparam boolean resize
 
 --- Should the image be resized to fit into the available space?
@@ -242,6 +247,7 @@ function imagebox:set_resize(allowed)
     self._private.resize_forbidden = not allowed
     self:emit_signal("widget::redraw_needed")
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::resize", allowed)
 end
 
 --- Returns a new `wibox.widget.imagebox` instance.

lib/wibox/widget/piechart.lua

@@ -137,49 +137,68 @@ local function fit(_, _, width, height)
 end
 
 --- The pie chart data list.
+--
 -- @property data_list
 -- @tparam table data_list Sorted table where each entry has a label as its
 -- first value and a number as its second value.
+-- @propemits false false
 
 --- The pie chart data.
+--
 -- @property data
 -- @tparam table data Labels as keys and number as value.
+-- @propemits false false
 
 --- The border color.
+--
 -- If none is set, it will use current foreground (text) color.
+--
 --@DOC_wibox_widget_piechart_border_color_EXAMPLE@
 -- @property border_color
--- @param color
+-- @tparam color border_color
+-- @propemits true false
+-- @propbeautiful
 -- @see gears.color
 
 --- The pie elements border width.
+--
 --@DOC_wibox_widget_piechart_border_width_EXAMPLE@
 -- @property border_width
 -- @tparam[opt=1] number border_width
+-- @propemits true false
+-- @propbeautiful
 
 --- The pie chart colors.
+--
 -- If no color is set, only the border will be drawn. If less colors than
 -- required are set, colors will be re-used in order.
+--
 -- @property colors
--- @tparam table colors A table of colors, one for each elements
+-- @tparam table colors A table of colors, one for each elements.
+-- @propemits true false
+-- @propbeautiful
 -- @see gears.color
 
 --- The border color.
+--
 -- If none is set, it will use current foreground (text) color.
 -- @beautiful beautiful.piechart_border_color
 -- @param color
 -- @see gears.color
 
 --- If the pie chart has labels.
+--
 --@DOC_wibox_widget_piechart_label_EXAMPLE@
 -- @property display_labels
 -- @param[opt=true] boolean
 
 --- The pie elements border width.
+--
 -- @beautiful beautiful.piechart_border_width
 -- @tparam[opt=1] number border_width
 
 --- The pie chart colors.
+--
 -- If no color is set, only the border will be drawn. If less colors than
 -- required are set, colors will be re-used in order.
 -- @beautiful beautiful.piechart_colors
@@ -194,6 +213,8 @@ for _, prop in ipairs {"data_list", "border_color", "border_width", "colors",
         self:emit_signal("property::"..prop)
         if prop == "data_list" then
             self:emit_signal("property::data")
+        else
+            self:emit_signal("property::"..prop, value)
         end
         self:emit_signal("widget::redraw_needed")
     end
@@ -219,6 +240,7 @@ function piechart:get_data()
 end
 
 --- Create a new piechart.
+--
 -- @constructorfct wibox.widget.piechart
 -- @tparam table data_list The data.
 

lib/wibox/widget/progressbar.lua

@@ -33,37 +33,53 @@ local gtable = require("gears.table")
 local progressbar = { mt = {} }
 
 --- The progressbar border color.
+--
 -- If the value is nil, no border will be drawn.
 --
 -- @property border_color
--- @tparam gears.color color The border color to set.
+-- @tparam color color The border color to set.
+-- @propemits true false
+-- @propbeautiful
 -- @see gears.color
 
 --- The progressbar border width.
+--
 -- @property border_width
--- @param number
+-- @tparam number border_width
+-- @propemits true false
+-- @propbeautiful
 
 --- The progressbar inner border color.
+--
 -- If the value is nil, no border will be drawn.
 --
 -- @property bar_border_color
--- @tparam gears.color color The border color to set.
+-- @tparam color color The border color to set.
+-- @propemits true false
+-- @propbeautiful
 -- @see gears.color
 
 --- The progressbar inner border width.
+--
 -- @property bar_border_width
--- @param number
+-- @tparam number bar_border_width
+-- @propbeautiful
+-- @propemits true false
 
 --- The progressbar foreground color.
 --
 -- @property color
--- @tparam gears.color color The progressbar color.
+-- @tparam color color The progressbar color.
+-- @propemits true false
+-- @usebeautiful beautiful.progressbar_fg
 -- @see gears.color
 
 --- The progressbar background color.
 --
 -- @property background_color
--- @tparam gears.color color The progressbar background color.
+-- @tparam color color The progressbar background color.
+-- @propemits true false
+-- @usebeautiful beautiful.progressbar_bg
 -- @see gears.color
 
 --- The progressbar inner shape.
@@ -72,6 +88,8 @@ local progressbar = { mt = {} }
 --
 -- @property bar_shape
 -- @tparam[opt=gears.shape.rectangle] gears.shape shape
+-- @propemits true false
+-- @propbeautiful
 -- @see gears.shape
 
 --- The progressbar shape.
@@ -80,12 +98,17 @@ local progressbar = { mt = {} }
 --
 -- @property shape
 -- @tparam[opt=gears.shape.rectangle] gears.shape shape
+-- @propemits true false
+-- @propbeautiful
 -- @see gears.shape
 
 --- Set the progressbar to draw vertically.
+--
 -- This doesn't do anything anymore, use a `wibox.container.rotate` widget.
+--
 -- @deprecated set_vertical
 -- @tparam boolean vertical
+-- @deprecatedin 4.0
 
 --- Force the inner part (the bar) to fit in the background shape.
 --
@@ -93,90 +116,110 @@ local progressbar = { mt = {} }
 --
 -- @property clip
 -- @tparam[opt=true] boolean clip
+-- @propemits true false
 
 --- The progressbar to draw ticks. Default is false.
 --
 -- @property ticks
--- @param boolean
+-- @tparam boolean ticks
+-- @propemits true false
 
 --- The progressbar ticks gap.
 --
 -- @property ticks_gap
--- @param number
+-- @tparam number ticks_gap
+-- @propemits true false
 
 --- The progressbar ticks size.
 --
 -- @property ticks_size
--- @param number
+-- @tparam number ticks_size
+-- @propemits true false
 
 --- The maximum value the progressbar should handle.
 --
 -- @property max_value
--- @param number
+-- @tparam number max_value
+-- @propemits true false
 
 --- The progressbar background color.
+--
 -- @beautiful beautiful.progressbar_bg
 -- @param color
 
 --- The progressbar foreground color.
+--
 -- @beautiful beautiful.progressbar_fg
 -- @param color
 
 --- The progressbar shape.
+--
 -- @beautiful beautiful.progressbar_shape
 -- @tparam gears.shape shape
 -- @see gears.shape
 
 --- The progressbar border color.
+--
 -- @beautiful beautiful.progressbar_border_color
 -- @param color
 
 --- The progressbar outer border width.
+--
 -- @beautiful beautiful.progressbar_border_width
 -- @param number
 
 --- The progressbar inner shape.
+--
 -- @beautiful beautiful.progressbar_bar_shape
 -- @tparam gears.shape shape
 -- @see gears.shape
 
 --- The progressbar bar border width.
+--
 -- @beautiful beautiful.progressbar_bar_border_width
 -- @param number
 
 --- The progressbar bar border color.
+--
 -- @beautiful beautiful.progressbar_bar_border_color
 -- @param color
 
 --- The progressbar margins.
+--
 -- Note that if the `clip` is disabled, this allows the background to be smaller
 -- than the bar.
 --
 -- See the `clip` example.
 --
+-- @property margins
 -- @tparam[opt=0] (table|number|nil) margins A table for each side or a number
 -- @tparam[opt=0] number margins.top
 -- @tparam[opt=0] number margins.bottom
 -- @tparam[opt=0] number margins.left
 -- @tparam[opt=0] number margins.right
--- @property margins
+-- @propemits false false
+-- @propbeautiful
 -- @see clip
 
 --- The progressbar padding.
+--
 -- Note that if the `clip` is disabled, this allows the bar to be taller
 -- than the background.
 --
 -- See the `clip` example.
 --
+-- @property paddings
 -- @tparam[opt=0] (table|number|nil) padding A table for each side or a number
 -- @tparam[opt=0] number padding.top
 -- @tparam[opt=0] number padding.bottom
 -- @tparam[opt=0] number padding.left
 -- @tparam[opt=0] number padding.right
--- @property paddings
+-- @propemits false false
+-- @propbeautiful
 -- @see clip
 
 --- The progressbar margins.
+--
 -- Note that if the `clip` is disabled, this allows the background to be smaller
 -- than the bar.
 -- @tparam[opt=0] (table|number|nil) margins A table for each side or a number
@@ -188,6 +231,7 @@ local progressbar = { mt = {} }
 -- @see clip
 
 --- The progressbar padding.
+--
 -- Note that if the `clip` is disabled, this allows the bar to be taller
 -- than the background.
 -- @tparam[opt=0] (table|number|nil) padding A table for each side or a number
@@ -378,8 +422,10 @@ function progressbar:fit(_, width, height)
 end
 
 --- Set the progressbar value.
+--
 -- @property value
--- @param number The progress bar value between 0 and 1.
+-- @tparam number value The progress bar value between 0 and 1.
+-- @propemits true false
 
 function progressbar:set_value(value)
     value = value or 0
@@ -398,20 +444,26 @@ function progressbar:set_max_value(max_value)
 end
 
 --- Set the progressbar height.
+--
 -- This method is deprecated.  Use a `wibox.container.constraint` widget or
 -- `forced_height`.
--- @param height The height to set.
+--
+-- @tparam number height The height to set.
 -- @deprecated set_height
+-- @renamedin 4.0
 function progressbar:set_height(height)
     gdebug.deprecate("Use a `wibox.container.constraint` widget or `forced_height`", {deprecated_in=4})
     self:set_forced_height(height)
 end
 
 --- Set the progressbar width.
+--
 -- This method is deprecated.  Use a `wibox.container.constraint` widget or
 -- `forced_width`.
--- @param width The width to set.
+--
+-- @tparam number width The width to set.
 -- @deprecated set_width
+-- @renamedin 4.0
 function progressbar:set_width(width)
     gdebug.deprecate("Use a `wibox.container.constraint` widget or `forced_width`", {deprecated_in=4})
     self:set_forced_width(width)
@@ -423,9 +475,15 @@ for _, prop in ipairs(properties) do
         progressbar["set_" .. prop] = function(pbar, value)
             pbar._private[prop] = value
             pbar:emit_signal("widget::redraw_needed")
+            pbar:emit_signal("property::"..prop, value)
             return pbar
         end
     end
+    if not progressbar["get_"..prop] then
+        progressbar["set_" .. prop] = function(pbar)
+            return pbar._private[prop]
+        end
+    end
 end
 
 function progressbar:set_vertical(value) --luacheck: no unused_args
@@ -434,9 +492,12 @@ end
 
 
 --- Create a progressbar widget.
--- @param args Standard widget() arguments. You should add width and height
+--
--- key to set progressbar geometry.
+-- @tparam table args Standard widget() arguments. You should add width and
--- @return A progressbar widget.
+--  height constructor parameters to set progressbar geometry.
+-- @tparam number args.width The width.
+-- @tparam number args.height The height.
+-- @treturn wibox.widget.progressbar A progressbar widget.
 -- @constructorfct wibox.widget.progressbar
 function progressbar.new(args)
     args = args or {}

lib/wibox/widget/separator.lua

@@ -42,14 +42,17 @@ local separator = {}
 --@DOC_wibox_widget_separator_orientation_EXAMPLE@
 --
 -- @property orientation
--- @param string
+-- @tparam string orientation
+-- @propemits true false
 
 --- The separator's thickness.
 --
 -- This is used by the default line separator, but ignored when a shape is used.
 --
 -- @property thickness
--- @param number
+-- @tparam number thickness
+-- @propbeautiful
+-- @propemits true false
 
 --- The separator's shape.
 --
@@ -57,15 +60,22 @@ local separator = {}
 --
 -- @property shape
 -- @tparam function shape A valid shape function
+-- @propbeautiful
+-- @propemits true false
 -- @see gears.shape
 
 --- The relative percentage covered by the bar.
+--
 -- @property span_ratio
 -- @tparam[opt=1] number A number between 0 and 1.
+-- @propbeautiful
+-- @propemits true false
 
 --- The separator's color.
 -- @property color
--- @param string
+-- @tparam color color
+-- @propbeautiful
+-- @propemits true false
 -- @see gears.color
 
 --- The separator's border color.
@@ -73,12 +83,16 @@ local separator = {}
 --@DOC_wibox_widget_separator_border_color_EXAMPLE@
 --
 -- @property border_color
--- @param string
+-- @tparam color border_color
+-- @propbeautiful
+-- @propemits true false
 -- @see gears.color
 
 --- The separator's border width.
 -- @property border_width
--- @param number
+-- @tparam number border_width
+-- @propbeautiful
+-- @propemits true false
 
 --- The separator thickness.
 -- @beautiful beautiful.separator_thickness
@@ -177,7 +191,7 @@ for _, prop in ipairs {"orientation", "color", "thickness", "span_ratio",
                        "border_width", "border_color", "shape" } do
     separator["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
     separator["get_"..prop] = function(self)

lib/wibox/widget/slider.lua

@@ -30,6 +30,8 @@ local slider = {mt={}}
 --
 -- @property handle_shape
 -- @tparam[opt=gears shape rectangle] gears.shape shape
+-- @propemits true false
+-- @propbeautiful
 -- @see gears.shape
 
 --- The slider handle color.
@@ -37,7 +39,9 @@ local slider = {mt={}}
 --@DOC_wibox_widget_slider_handle_color_EXAMPLE@
 --
 -- @property handle_color
--- @param color
+-- @propbeautiful
+-- @tparam color handle_color
+-- @propemits true false
 
 --- The slider handle margins.
 --
@@ -49,24 +53,32 @@ local slider = {mt={}}
 -- @tparam[opt=0] number margins.right
 -- @tparam[opt=0] number margins.top
 -- @tparam[opt=0] number margins.bottom
+-- @propemits true false
+-- @propbeautiful
 
 --- The slider handle width.
 --
 --@DOC_wibox_widget_slider_handle_width_EXAMPLE@
 --
 -- @property handle_width
--- @param number
+-- @tparam number handle_width
+-- @propemits true false
+-- @propbeautiful
 
 --- The handle border_color.
 --
 --@DOC_wibox_widget_slider_handle_border_EXAMPLE@
 --
 -- @property handle_border_color
--- @param color
+-- @tparam color handle_border_color
+-- @propemits true false
+-- @propbeautiful
 
 --- The handle border width.
 -- @property handle_border_width
--- @param[opt=0]  number
+-- @tparam[opt=0] number handle_border_width
+-- @propemits true false
+-- @propbeautiful
 
 --- The bar (background) shape.
 --
@@ -74,6 +86,8 @@ local slider = {mt={}}
 --
 -- @property bar_shape
 -- @tparam[opt=gears shape rectangle] gears.shape shape
+-- @propemits true false
+-- @propbeautiful
 -- @see gears.shape
 
 --- The bar (background) height.
@@ -81,14 +95,18 @@ local slider = {mt={}}
 --@DOC_wibox_widget_slider_bar_height_EXAMPLE@
 --
 -- @property bar_height
--- @param number
+-- @tparam number bar_height
+-- @propbeautiful
+-- @propemits true false
 
 --- The bar (background) color.
 --
 --@DOC_wibox_widget_slider_bar_color_EXAMPLE@
 --
 -- @property bar_color
--- @param color
+-- @tparam color bar_color
+-- @propbeautiful
+-- @propemits true false
 
 --- The bar (active) color.
 --
@@ -96,7 +114,9 @@ local slider = {mt={}}
 --
 -- Only works when both `bar_active_color` and `bar_color` are passed as hex color string
 -- @property bar_active_color
--- @param color
+-- @tparam color bar_active_color
+-- @propbeautiful
+-- @propemits true false
 
 --- The bar (background) margins.
 --
@@ -108,17 +128,22 @@ local slider = {mt={}}
 -- @tparam[opt=0] number margins.right
 -- @tparam[opt=0] number margins.top
 -- @tparam[opt=0] number margins.bottom
+-- @propbeautiful
+-- @propemits true false
 
 --- The bar (background) border width.
 -- @property bar_border_width
--- @param[opt=0] numbergb
+-- @tparam[opt=0] number bar_border_width
+-- @propemits true false
 
 --- The bar (background) border_color.
 --
 --@DOC_wibox_widget_slider_bar_border_EXAMPLE@
 --
 -- @property bar_border_color
--- @param color
+-- @tparam color bar_border_color
+-- @propbeautiful
+-- @propemits true false
 
 --- The slider value.
 --
@@ -127,54 +152,70 @@ local slider = {mt={}}
 --@DOC_wibox_widget_slider_value_EXAMPLE@
 --
 -- @property value
--- @param[opt=0] number
+-- @tparam[opt=0] number value
+-- @propemits true false
 
 --- The slider minimum value.
+--
 -- @property minimum
--- @param[opt=0] number
+-- @tparam[opt=0] number minimum
+-- @propemits true false
 
 --- The slider maximum value.
+--
 -- @property maximum
--- @param[opt=100] number
+-- @tparam[opt=100] number maximum
+-- @propemits true false
 
 --- The bar (background) border width.
+--
 -- @beautiful beautiful.slider_bar_border_width
 -- @param number
 
 --- The bar (background) border color.
+--
 -- @beautiful beautiful.slider_bar_border_color
 -- @param color
 
 --- The handle border_color.
+--
 -- @beautiful beautiful.slider_handle_border_color
 -- @param color
 
 --- The handle border width.
+--
 -- @beautiful beautiful.slider_handle_border_width
 -- @param number
 
---- The handle .
+--- The handle width.
+--
 -- @beautiful beautiful.slider_handle_width
 -- @param number
 
+--- The handle color.
+--
 -- @beautiful beautiful.slider_handle_color
 -- @param color
 
 --- The handle shape.
+--
 -- @beautiful beautiful.slider_handle_shape
 -- @tparam[opt=gears shape rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The bar (background) shape.
+--
 -- @beautiful beautiful.slider_bar_shape
 -- @tparam[opt=gears shape rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The bar (background) height.
+--
 -- @beautiful beautiful.slider_bar_height
 -- @param number
 
 --- The bar (background) margins.
+--
 -- @beautiful beautiful.slider_bar_margins
 -- @tparam[opt={}] table margins
 -- @tparam[opt=0] number margins.left
@@ -183,6 +224,7 @@ local slider = {mt={}}
 -- @tparam[opt=0] number margins.bottom
 
 --- The slider handle margins.
+--
 -- @beautiful beautiful.slider_handle_margins
 -- @tparam[opt={}] table margins
 -- @tparam[opt=0] number margins.left
@@ -191,10 +233,12 @@ local slider = {mt={}}
 -- @tparam[opt=0] number margins.bottom
 
 --- The bar (background) color.
+--
 -- @beautiful beautiful.slider_bar_color
 -- @param color
 
 --- The bar (active) color.
+--
 -- Only works when both `beautiful.slider_bar_color` and `beautiful.slider_bar_active_color` are hex color strings
 -- @beautiful beautiful.slider_bar_active_color
 -- @param color
@@ -231,7 +275,7 @@ for prop in pairs(properties) do
         self._private[prop] = value
 
         if changed then
-            self:emit_signal("property::"..prop)
+            self:emit_signal("property::"..prop, value)
             self:emit_signal("widget::redraw_needed")
         end
     end
@@ -253,7 +297,7 @@ function slider:set_value(value)
     self._private.value = value
 
     if changed then
-        self:emit_signal( "property::value"       )
+        self:emit_signal( "property::value", value)
         self:emit_signal( "widget::redraw_needed" )
     end
 end

lib/wibox/widget/systray.lua

@@ -25,10 +25,12 @@ local reverse = false
 local display_on_screen = "primary"
 
 --- The systray background color.
+--
 -- @beautiful beautiful.bg_systray
 -- @param string The color (string like "#ff0000" only)
 
 --- The systray icon spacing.
+--
 -- @beautiful beautiful.systray_icon_spacing
 -- @tparam[opt=0] integer The icon spacing
 
@@ -114,56 +116,72 @@ local function get_args(self, ...)
 end
 
 --- Set the size of a single icon.
+--
 -- If this is set to nil, then the size is picked dynamically based on the
 -- available space. Otherwise, any single icon has a size of `size`x`size`.
+--
 -- @property base_size
 -- @tparam integer|nil size The base size
+-- @propemits true false
 
 function systray:set_base_size(size)
     base_size = get_args(self, size)
     if instance then
         instance:emit_signal("widget::layout_changed")
+        instance:emit_signal("property::base_size", size)
     end
 end
 
 --- Decide between horizontal or vertical display.
+--
 -- @property horizontal
 -- @tparam boolean horiz Use horizontal mode?
+-- @propemits true false
 
 function systray:set_horizontal(horiz)
     horizontal = get_args(self, horiz)
     if instance then
         instance:emit_signal("widget::layout_changed")
+        instance:emit_signal("property::horizontal", horiz)
     end
 end
 
 --- Should the systray icons be displayed in reverse order?
+--
 -- @property reverse
 -- @tparam boolean rev Display in reverse order.
+-- @propemits true false
 
 function systray:set_reverse(rev)
     reverse = get_args(self, rev)
     if instance then
         instance:emit_signal("widget::redraw_needed")
+        instance:emit_signal("property::reverse", rev)
     end
 end
 
 --- Set the screen that the systray should be displayed on.
+--
 -- This can either be a screen, in which case the systray will be displayed on
 -- exactly that screen, or the string `"primary"`, in which case it will be
 -- visible on the primary screen. The default value is "primary".
+--
 -- @property screen
 -- @tparam screen|"primary" s The screen to display on.
+-- @propemits true false
 
 function systray:set_screen(s)
     display_on_screen = get_args(self, s)
     if instance then
         instance:emit_signal("widget::layout_changed")
+        instance:emit_signal("property::screen", s)
     end
 end
 
 --- Create the systray widget.
+--
 -- Note that this widget can only exist once.
+--
 -- @tparam boolean revers Show in the opposite direction
 -- @treturn table The new `systray` widget
 -- @constructorfct wibox.widget.systray

lib/wibox/widget/textbox.lua

@@ -19,6 +19,7 @@ local setmetatable = setmetatable
 local textbox = { mt = {} }
 
 --- The textbox font.
+--
 -- @beautiful beautiful.font
 -- @param string
 
@@ -69,8 +70,10 @@ function textbox:fit(context, width, height)
 end
 
 --- Get the preferred size of a textbox.
+--
 -- This returns the size that the textbox would use if infinite space were
 -- available.
+--
 -- @method get_preferred_size
 -- @tparam integer|screen s The screen on which the textbox will be displayed.
 -- @treturn number The preferred width.
@@ -88,8 +91,10 @@ function textbox:get_preferred_size(s)
 end
 
 --- Get the preferred height of a textbox at a given width.
+--
 -- This returns the height that the textbox would use when it is limited to the
 -- given width.
+--
 -- @method get_height_for_width
 -- @tparam number width The available width.
 -- @tparam integer|screen s The screen on which the textbox will be displayed.
@@ -106,8 +111,10 @@ function textbox:get_height_for_width(width, s)
 end
 
 --- Get the preferred size of a textbox.
+--
 -- This returns the size that the textbox would use if infinite space were
 -- available.
+--
 -- @method get_preferred_size_at_dpi
 -- @tparam number dpi The DPI value to render at.
 -- @treturn number The preferred width.
@@ -121,8 +128,10 @@ function textbox:get_preferred_size_at_dpi(dpi)
 end
 
 --- Get the preferred height of a textbox at a given width.
+--
 -- This returns the height that the textbox would use when it is limited to the
 -- given width.
+--
 -- @method get_height_for_width_at_dpi
 -- @tparam number width The available width.
 -- @tparam number dpi The DPI value to render at.
@@ -136,8 +145,9 @@ function textbox:get_height_for_width_at_dpi(width, dpi)
     return h
 end
 
---- Set the text of the textbox (with
+--- Set the text of the textbox.(with
 -- [Pango markup](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html)).
+--
 -- @tparam string text The text to set. This can contain pango markup (e.g.
 --   `<b>bold</b>`). You can use `gears.string.escape` to escape
 --   parts of it.
@@ -161,15 +171,18 @@ function textbox:set_markup_silently(text)
     self._private.layout.attributes = attr
     self:emit_signal("widget::redraw_needed")
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::markup", text)
     return true
 end
 
 --- Set the text of the textbox (with
 -- [Pango markup](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html)).
+--
 -- @property markup
 -- @tparam string text The text to set. This can contain pango markup (e.g.
 --   `<b>bold</b>`). You can use `gears.string.escape` to escape
 --   parts of it.
+-- @propemits true false
 -- @see text
 
 function textbox:set_markup(text)
@@ -183,9 +196,12 @@ function textbox:get_markup()
     return self._private.markup
 end
 
---- Set a textbox' text.
+--- Set a textbox text.
+--
 -- @property text
--- @param text The text to display. Pango markup is ignored and shown as-is.
+-- @tparam string text The text to display. Pango markup is ignored and shown
+--  as-is.
+-- @propemits true false
 -- @see markup
 
 function textbox:set_text(text)
@@ -197,15 +213,25 @@ function textbox:set_text(text)
     self._private.layout.attributes = nil
     self:emit_signal("widget::redraw_needed")
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::text", text)
 end
 
 function textbox:get_text()
     return self._private.layout.text
 end
 
---- Set a textbox' ellipsize mode.
+--- Set a textbox ellipsize mode.
+--
+-- Valid values are:
+--
+-- * **start**
+-- * **middle**
+-- * **end**
+--
 -- @property ellipsize
--- @param mode Where should long lines be shortened? "start", "middle" or "end"
+-- @tparam string mode Where should long lines be shortened? "start", "middle"
+--  or "end".
+-- @propemits true false
 
 function textbox:set_ellipsize(mode)
     local allowed = { none = "NONE", start = "START", middle = "MIDDLE", ["end"] = "END" }
@@ -216,12 +242,21 @@ function textbox:set_ellipsize(mode)
         self._private.layout:set_ellipsize(allowed[mode])
         self:emit_signal("widget::redraw_needed")
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::ellipsize", mode)
     end
 end
 
---- Set a textbox' wrap mode.
+--- Set a textbox wrap mode.
+--
+-- Valid values are:
+--
+-- * **word**
+-- * **char**
+-- * **word_char**
+--
 -- @property wrap
--- @param mode Where to wrap? After "word", "char" or "word_char"
+-- @tparam string mode Where to wrap? After "word", "char" or "word_char".
+-- @propemits true false
 
 function textbox:set_wrap(mode)
     local allowed = { word = "WORD", char = "CHAR", word_char = "WORD_CHAR" }
@@ -232,12 +267,22 @@ function textbox:set_wrap(mode)
         self._private.layout:set_wrap(allowed[mode])
         self:emit_signal("widget::redraw_needed")
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::wrap", mode)
     end
 end
 
---- The textbox' vertical alignment
+--- The textbox' vertical alignment.
+--
+-- Valid values are:
+--
+-- * **top**
+-- * **center**
+-- * **bottom**
+--
 -- @property valign
--- @param mode Where should the textbox be drawn? "top", "center" or "bottom"
+-- @tparam string mode Where should the textbox be drawn? "top", "center" or
+--  "bottom".
+-- @propemits true false
 
 function textbox:set_valign(mode)
     local allowed = { top = true, center = true, bottom = true }
@@ -248,12 +293,22 @@ function textbox:set_valign(mode)
         self._private.valign = mode
         self:emit_signal("widget::redraw_needed")
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::valign", mode)
     end
 end
 
---- Set a textbox' horizontal alignment.
+--- Set a textbox horizontal alignment.
+--
+-- Valid values are:
+--
+-- * **left**
+-- * **center**
+-- * **right**
+--
 -- @property align
--- @param mode Where should the textbox be drawn? "left", "center" or "right"
+-- @tparam string mode Where should the textbox be drawn? "left", "center" or
+--  "right".
+-- @propemits true false
 
 function textbox:set_align(mode)
     local allowed = { left = "LEFT", center = "CENTER", right = "RIGHT" }
@@ -264,20 +319,26 @@ function textbox:set_align(mode)
         self._private.layout:set_alignment(allowed[mode])
         self:emit_signal("widget::redraw_needed")
         self:emit_signal("widget::layout_changed")
+        self:emit_signal("property::align", mode)
     end
 end
 
---- Set a textbox' font
+--- Set a textbox font.
+--
 -- @property font
--- @param font The font description as string
+-- @tparam string font The font description as string.
+-- @propemits true false
+-- @propbeautiful
 
 function textbox:set_font(font)
     self._private.layout:set_font_description(beautiful.get_font(font))
     self:emit_signal("widget::redraw_needed")
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::font", font)
 end
 
 --- Create a new textbox.
+--
 -- @tparam[opt=""] string text The textbox content
 -- @tparam[opt=false] boolean ignore_markup Ignore the pango/HTML markup
 -- @treturn table A new textbox widget

lib/wibox/widget/textclock.lua

@@ -29,6 +29,7 @@ if source_date_epoch and os.getenv("SOURCE_DIRECTORY") then
 end
 
 --- Set the clock's format.
+--
 -- For information about the format specifiers, see
 -- [the GLib docs](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format).
 -- @property format
@@ -43,7 +44,8 @@ function textclock:get_format()
     return self._private.format
 end
 
---- Set the clock's timezone
+--- Set the clock's timezone.
+--
 -- e.g. "Z" for UTC, "±hh:mm" or "Europe/Amsterdam". See
 -- [GTimeZone](https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new).
 -- @property timezone
@@ -59,7 +61,8 @@ function textclock:get_timezone()
     return self._private.tzid
 end
 
---- Set the clock's refresh rate
+--- Set the clock's refresh rate.
+--
 -- @property refresh
 -- @tparam number refresh How often the clock is updated, in seconds
 
@@ -73,6 +76,7 @@ function textclock:get_refresh()
 end
 
 --- Force a textclock to update now.
+--
 -- @method force_update
 function textclock:force_update()
     self._timer:emit_signal("timeout")