From be14666b4a8525657b22239c4906af69934027cc Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Fri, 29 Nov 2019 00:33:44 -0500
Subject: [PATCH] doc: Modernize the widget doc.

This hass the following tags:

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

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

Also add some signals to standardize everything.
---
 lib/wibox/widget/checkbox.lua    | 60 ++++++++++++++++----
 lib/wibox/widget/graph.lua       | 57 ++++++++++++++-----
 lib/wibox/widget/imagebox.lua    |  6 ++
 lib/wibox/widget/piechart.lua    | 26 ++++++++-
 lib/wibox/widget/progressbar.lua | 97 ++++++++++++++++++++++++++------
 lib/wibox/widget/separator.lua   | 26 +++++++--
 lib/wibox/widget/slider.lua      | 74 +++++++++++++++++++-----
 lib/wibox/widget/systray.lua     | 18 ++++++
 lib/wibox/widget/textbox.lua     | 87 +++++++++++++++++++++++-----
 lib/wibox/widget/textclock.lua   |  8 ++-
 10 files changed, 379 insertions(+), 80 deletions(-)

diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua
index 53571ca4c..65783ca8e 100644
--- a/lib/wibox/widget/checkbox.lua
+++ b/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)
diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua
index 3747a2a90..18e91ace1 100644
--- a/lib/wibox/widget/graph.lua
+++ b/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
--- @param group The stack color group index.
+-- @tparam number value The value to be added to the graph
+-- @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 {}
diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua
index 18e0aaf50..009c921c0 100644
--- a/lib/wibox/widget/imagebox.lua
+++ b/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.
diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua
index 2e57e9522..6eb0dae7f 100644
--- a/lib/wibox/widget/piechart.lua
+++ b/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.
 
diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua
index 0eb2bc62a..afdc4c783 100644
--- a/lib/wibox/widget/progressbar.lua
+++ b/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.
--- @return A progressbar widget.
+--
+-- @tparam table args Standard widget() arguments. You should add width and
+--  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 {}
diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua
index e56f9ba78..9e8215b3f 100644
--- a/lib/wibox/widget/separator.lua
+++ b/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)
diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua
index 63a10f746..13bf84e53 100644
--- a/lib/wibox/widget/slider.lua
+++ b/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
diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua
index 59b715d3e..669da8f52 100644
--- a/lib/wibox/widget/systray.lua
+++ b/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
diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua
index 2bb9998d6..b683e8b7f 100644
--- a/lib/wibox/widget/textbox.lua
+++ b/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
diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua
index 7d44f2e4f..fcabe7df4 100644
--- a/lib/wibox/widget/textclock.lua
+++ b/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")