From 3c26ccc4248c84d5889cd5ac6b52bc99c7994d4b Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage-Vallee <elv1313@gmail.com>
Date: Sat, 21 Dec 2019 13:25:25 -0800
Subject: [PATCH 1/7] doc: Port the `wibox` module to the new doc format.

---
 docs/common/wibox.ldoc | 145 ++++++++++++++++++++---------------------
 lib/wibox/init.lua     |   6 ++
 2 files changed, 75 insertions(+), 76 deletions(-)

diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc
index 44329ec0..dc46c6ea 100644
--- a/docs/common/wibox.ldoc
+++ b/docs/common/wibox.ldoc
@@ -1,12 +1,9 @@
 --- Border width.
 --
--- **Signal:**
---
---  * *property::border_width*
---
 -- @baseclass wibox
 -- @property border_width
 -- @param integer
+-- @propemits false false
 
 --- Border color.
 --
@@ -26,178 +23,146 @@
 --       T‾  ‾T
 --    Green   Alpha
 --
--- **Signal:**
---
---  * *property::border_color*
---
 -- @baseclass wibox
 -- @property border_color
 -- @param string
+-- @propemits false false
 
 --- On top of other windows.
 --
--- **Signal:**
---
---  * *property::ontop*
---
 -- @baseclass wibox
 -- @property ontop
 -- @param boolean
+-- @propemits false false
 
 --- The mouse cursor.
 --
--- **Signal:**
---
---  * *property::cursor*
---
 -- @baseclass wibox
 -- @property cursor
 -- @param string
 -- @see mouse
+-- @propemits false false
 
 --- Visibility.
 --
--- **Signal:**
---
---  * *property::visible*
---
 -- @baseclass wibox
 -- @property visible
 -- @param boolean
+-- @propemits false false
 
 --- The opacity of the wibox, between 0 and 1.
 --
--- **Signal:**
---
---  * *property::opacity*
---
 -- @baseclass wibox
 -- @property opacity
 -- @tparam number opacity (between 0 and 1)
+-- @propemits false false
 
 --- The window type (desktop, normal, dock, ...).
 --
--- **Signal:**
---
---  * *property::type*
---
 -- @baseclass wibox
 -- @property type
 -- @param string
 -- @see client.type
+-- @propemits false false
 
 --- The x coordinates.
 --
--- **Signal:**
---
---  * *property::x*
---
 -- @baseclass wibox
 -- @property x
 -- @param integer
+-- @propemits false false
 
 --- The y coordinates.
 --
--- **Signal:**
---
---  * *property::y*
---
 -- @baseclass wibox
 -- @property y
 -- @param integer
+-- @propemits false false
 
 --- The width of the wibox.
 --
--- **Signal:**
---
---  * *property::width*
---
 -- @baseclass wibox
 -- @property width
 -- @param width
+-- @propemits false false
 
 --- The height of the wibox.
 --
--- **Signal:**
---
---  * *property::height*
---
 -- @baseclass wibox
 -- @property height
 -- @param height
+-- @propemits false false
 
 --- The wibox screen.
 --
 -- @baseclass wibox
 -- @property screen
 -- @param screen
+-- @propemits true false
 
 ---  The wibox's `drawable`.
 --
--- **Signal:**
---
---  * *property::drawable*
---
 -- @baseclass wibox
 -- @property drawable
 -- @tparam drawable drawable
+-- @propemits false false
 
 --- The widget that the `wibox` displays.
 -- @baseclass wibox
 -- @property widget
 -- @param widget
+-- @propemits true false
 
 --- The X window id.
 --
--- **Signal:**
---
---  * *property::window*
---
 -- @baseclass wibox
 -- @property window
 -- @param string
 -- @see client.window
+-- @propemits false false
 
 --- The wibox's bounding shape as a (native) cairo surface.
 --
--- **Signal:**
---
---  * *property::shape_bounding*
+-- If you want to set a shape, let say some rounded corners, use
+-- the `shape` property rather than this. If you want something
+-- very complex, for example, holes, then use this.
 --
 -- @baseclass wibox
 -- @property shape_bounding
 -- @param surface._native
+-- @propemits false false
+-- @see shape
 
 --- The wibox's clip shape as a (native) cairo surface.
 --
--- **Signal:**
---
---  * *property::shape_clip*
+-- The clip shape is the shape of the window *content* rather
+-- than the outer window shape.
 --
 -- @baseclass wibox
 -- @property shape_clip
 -- @param surface._native
+-- @propemits false false
+-- @see shape
 
 --- The wibox's input shape as a (native) cairo surface.
 --
--- **Signal:**
---
---  * *property::shape_input*
+-- The input shape allows to disable clicks and mouse events
+-- on part of the window. This is how `input_passthrough` is
+-- implemented.
 --
 -- @baseclass wibox
 -- @property shape_input
 -- @param surface._native
-
+-- @propemits false false
+-- @see input_passthrough
 
 --- The wibar's shape.
 --
--- **Signal:**
---
---  * *property::shape*
---
 -- @baseclass wibox
 -- @property shape
 -- @tparam gears.shape shape
+-- @propemits true false
+-- @see gears.shape
 
 --- Forward the inputs to the client below the wibox.
 --
@@ -207,20 +172,18 @@
 -- a subtle transparent wibox on top a fullscreen client to display important
 -- data such as a low battery warning.
 --
--- **Signal:**
---
---  * *property::input_passthrough*
---
 -- @baseclass wibox
 -- @property input_passthrough
 -- @param[opt=false] boolean
 -- @see shape_input
+-- @propemits true false
 
 --- Get or set mouse buttons bindings to a wibox.
 --
 -- @baseclass wibox
+-- @property buttons
 -- @param buttons_table A table of buttons objects, or nothing.
--- @method buttons
+-- @propemits false false
 
 --- Get or set wibox geometry. That's the same as accessing or setting the x,
 -- y, width or height properties of a wibox.
@@ -229,16 +192,33 @@
 -- @param A table with coordinates to modify.
 -- @return A table with wibox coordinates and geometry.
 -- @method geometry
+-- @emits property::geometry When the geometry change.
+-- @emitstparam property::geometry table geo The geometry table.
 
 --- Get or set wibox struts.
 --
+-- Struts are the area which should be reserved on each side of
+-- the screen for this wibox. This is used to make bars and
+-- docked displays. Note that `awful.wibar` implements all the
+-- required boilerplate code to make bar. Only use this if you
+-- want special type of bars (like bars not fully attached to
+-- the side of the screen).
+--
 -- @baseclass wibox
 -- @param strut A table with new strut, or nothing
 -- @return The wibox strut in a table.
 -- @method struts
 -- @see client.struts
+-- @emits property::struts
 
 --- The default background color.
+--
+-- The background color can be transparent. If there is a
+-- compositing manager such as compton, then it will be
+-- real transparency and may include blur (provided by the
+-- compositor). When there is no compositor, it will take
+-- a picture of the wallpaper and blend it.
+--
 -- @baseclass wibox
 -- @beautiful beautiful.bg_normal
 -- @param color
@@ -257,28 +237,41 @@
 -- @method setup
 
 --- The background of the wibox.
+--
+-- The background color can be transparent. If there is a
+-- compositing manager such as compton, then it will be
+-- real transparency and may include blur (provided by the
+-- compositor). When there is no compositor, it will take
+-- a picture of the wallpaper and blend it.
+--
 -- @baseclass wibox
--- @param c The background to use. This must either be a cairo pattern object,
---   nil or a string that gears.color() understands.
 -- @property bg
--- @param color
+-- @tparam c The background to use. This must either be a cairo pattern object,
+--   nil or a string that gears.color() understands.
 -- @see gears.color
+-- @propemits true false
+-- @usebeautiful beautiful.bg_normal The default (fallback) bg color.
 
 --- The background image of the drawable.
+--
 -- 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.
--- @param image A background image or a function
+--
+-- @tparam gears.suface|string|function image A background image or a function.
 -- @baseclass wibox
 -- @property bgimage
 -- @see gears.surface
+-- @propemits true false
 
 --- The foreground (text) of the wibox.
--- @param c The foreground to use. This must either be a cairo pattern object,
+-- @tparam color c The foreground to use. This must either be a cairo pattern object,
 --   nil or a string that gears.color() understands.
 -- @baseclass wibox
 -- @property fg
 -- @param color
 -- @see gears.color
+-- @propemits true false
+-- @usebeautiful beautiful.fg_normal The default (fallback) fg color.
 
 --- Find a widget by a point.
 -- The wibox must have drawn itself at least once for this to work.
diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua
index b27c8894..6bf2b85f 100644
--- a/lib/wibox/init.lua
+++ b/lib/wibox/init.lua
@@ -41,6 +41,7 @@ local force_forward = {
 function wibox:set_widget(widget)
     local w = base.make_widget_from_value(widget)
     self._drawable:set_widget(w)
+    self:emit_signal("property::widget", widget)
 end
 
 function wibox:get_widget()
@@ -51,14 +52,17 @@ wibox.setup = base.widget.setup
 
 function wibox:set_bg(c)
     self._drawable:set_bg(c)
+    self:emit_signal("property::bg", c)
 end
 
 function wibox:set_bgimage(image, ...)
     self._drawable:set_bgimage(image, ...)
+    self:emit_signal("property::bgimage", ...)
 end
 
 function wibox:set_fg(c)
     self._drawable:set_fg(c)
+    self:emit_signal("property::fg", c)
 end
 
 function wibox:find_widgets(x, y)
@@ -149,6 +153,7 @@ end
 function wibox:set_shape(shape)
     self._shape = shape
     self:_apply_shape()
+    self:emit_signal("property::shape", shape)
 end
 
 function wibox:get_shape()
@@ -199,6 +204,7 @@ function wibox:set_screen(s)
     -- (x,y) is not enough to figure out the correct screen.
     self.screen_assigned = s
     self._drawable:_force_screen(s)
+    self:emit_signal("property::screen", s)
 end
 
 function wibox:get_children_by_id(name)

From 6e4eb134b06abfa500ee31c609318c84a0f53140 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage-Vallee <elv1313@gmail.com>
Date: Sat, 21 Dec 2019 13:39:46 -0800
Subject: [PATCH 2/7] doc: Upgrade the `awful.popup` documentation to the new
 standards.

---
 lib/awful/popup.lua | 40 ++++++++++++++++++++++++++++++++++------
 1 file changed, 34 insertions(+), 6 deletions(-)

diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua
index cc6e6904..a66a157b 100644
--- a/lib/awful/popup.lua
+++ b/lib/awful/popup.lua
@@ -125,6 +125,7 @@ function main_widget:set_widget(widget)
     end
     self._private.widget = widget
     self:emit_signal("widget::layout_changed")
+    self:emit_signal("property::widget")
 end
 
 function main_widget:get_widget()
@@ -164,10 +165,12 @@ local popup = {}
 --  table of positions
 -- @see awful.placement.next_to
 -- @see awful.popup.preferred_anchors
+-- @propemits true false
 
 function popup:set_preferred_positions(pref_pos)
     self._private.preferred_directions = pref_pos
     set_position(self)
+    self:emit_signal("property::preferred_positions", pref_pos)
 end
 
 --- Set the preferred popup anchors relative to the parent.
@@ -188,12 +191,14 @@ end
 -- @property preferred_anchors
 -- @tparam table|string preferred_anchors Either a single anchor name or a table
 --  ordered by priority.
+-- @propemits true false
 -- @see awful.placement.next_to
 -- @see awful.popup.preferred_positions
 
 function popup:set_preferred_anchors(pref_anchors)
     self._private.preferred_anchors = pref_anchors
     set_position(self)
+    self:emit_signal("property::preferred_anchors", pref_anchors)
 end
 
 --- The current position relative to the parent object.
@@ -278,34 +283,49 @@ end
 --
 -- @property hide_on_right_click
 -- @tparam[opt=false] boolean hide_on_right_click
+-- @propemits true false
 
 function popup:set_hide_on_right_click(value)
     self[value and "connect_signal" or "disconnect_signal"](
         self, "button::press", self._private.hide_fct
     )
+    self:emit_signal("property::hide_on_right_click", value)
 end
 
 --- The popup minimum width.
+--
 -- @property minimum_width
--- @tparam[opt=1] number The minimum width
+-- @tparam[opt=1] number minimum_width The minimum width.
+-- @propemits true false
 
 --- The popup minimum height.
+--
 -- @property minimum_height
--- @tparam[opt=1] number The minimum height
+-- @tparam[opt=1] number minimum_height The minimum height.
+-- @propemits true false
 
 --- The popup maximum width.
+--
 -- @property maximum_width
--- @tparam[opt=1] number The maximum width
+-- @tparam[opt=1] number maximum_width The maximum width.
+-- @propemits true false
 
 --- The popup maximum height.
+--
 -- @property maximum_height
--- @tparam[opt=1] number The maximum height
+-- @tparam[opt=1] number maximum_height The maximum height.
+-- @propemits true false
 
 for _, orientation in ipairs {"_width", "_height"} do
     for _, limit in ipairs {"minimum", "maximum"} do
-        popup["set_"..limit..orientation] = function(self, value)
-            self._private[limit..orientation] = value
+        local prop = limit..orientation
+        popup["set_"..prop] = function(self, value)
+            self._private[prop] = value
             self._private.container:emit_signal("widget::layout_changed")
+            self:emit_signal("property::"..prop, value)
+        end
+        popup["get_"..prop] = function(self)
+            return self._private[prop]
         end
     end
 end
@@ -320,6 +340,7 @@ end
 -- @tparam table|number offset An integer value or a `{x=, y=}` table.
 -- @tparam[opt=offset] number offset.x The horizontal distance.
 -- @tparam[opt=offset] number offset.y The vertical distance.
+-- @propemits true false
 
 function popup:set_offset(offset)
 
@@ -339,13 +360,18 @@ function popup:set_offset(offset)
     self._private.offset = offset
 
     self:_apply_size_now(false)
+
+    self:emit_signal("property::offset", offset)
 end
 
 --- Set the placement function.
+--
 -- @tparam[opt=next_to] function|string|boolean The placement function or name
 -- (or false to disable placement)
 -- @property placement
 -- @param function
+-- @propemits true false
+-- @see awful.placement
 
 function popup:set_placement(f)
     if type(f) == "string" then
@@ -354,6 +380,7 @@ function popup:set_placement(f)
 
     self._private.placement = f
     self:_apply_size_now(false)
+    self:emit_signal("property::placement")
 end
 
 -- For the tests and the race condition when 2 popups are placed next to each
@@ -382,6 +409,7 @@ end
 function popup:set_widget(wid)
     self._private.widget = wid
     self._private.container:set_widget(wid)
+    self:emit_signal("property::widget", wid)
 end
 
 function popup:get_widget()

From 0393c93f42b0f05e6eb5ccf702ba4b9d1e5e14bb Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage-Vallee <elv1313@gmail.com>
Date: Sat, 21 Dec 2019 20:55:38 -0800
Subject: [PATCH 3/7] doc: Upgrade the wibar documentation to the new
 standards.

---
 lib/awful/wibar.lua | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua
index 4b4e9bb6..ad48a8fa 100644
--- a/lib/awful/wibar.lua
+++ b/lib/awful/wibar.lua
@@ -36,14 +36,8 @@ local wiboxes = setmetatable({}, {__mode = "v"})
 --- If the wibar needs to be stretched to fill the screen.
 -- @property stretch
 -- @tparam boolean stretch
-
---- The wibar's width.
--- @property width
--- @tparam integer width
-
---- The wibar's height.
--- @property height
--- @tparam integer height
+-- @propbeautiful
+-- @propemits true false
 
 --- If the wibar needs to be stretched to fill the screen.
 -- @beautiful beautiful.wibar_stretch
@@ -165,8 +159,17 @@ local function reattach(wb)
 end
 
 --- The wibox position.
+--
+-- The valid values are:
+--
+-- * left
+-- * right
+-- * top
+-- * bottom
+--
 -- @property position
--- @param string Either "left", right", "top" or "bottom"
+-- @tparam string position Either "left", right", "top" or "bottom"
+-- @propemits true false
 
 local function get_position(wb)
     return wb._position or "top"
@@ -215,6 +218,8 @@ local function set_position(wb, position, skip_reattach)
         -- or right wibars. To solve, this, they need to be re-attached.
         reattach(wb)
     end
+
+    wb:emit_signal("property::position", position)
 end
 
 local function get_stretch(w)
@@ -225,6 +230,8 @@ local function set_stretch(w, value)
     w._stretch = value
 
     attach(w, w.position)
+
+    w:emit_signal("property::stretch", value)
 end
 
 --- Remove a wibar.
@@ -444,6 +451,8 @@ end
 
 --@DOC_wibox_COMMON@
 
+--@DOC_object_COMMON@
+
 return setmetatable(awfulwibar, awfulwibar.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

From 3af095e4b054f0622a294471bf3ba70be710e635 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage-Vallee <elv1313@gmail.com>
Date: Sat, 21 Dec 2019 21:20:11 -0800
Subject: [PATCH 4/7] doc: Upgrade the tooltip documentation to the new
 standards.

---
 lib/awful/tooltip.lua | 54 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 41 insertions(+), 13 deletions(-)

diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua
index fc6bd52d..81674a3b 100644
--- a/lib/awful/tooltip.lua
+++ b/lib/awful/tooltip.lua
@@ -200,7 +200,7 @@ end
 
 --- The wibox containing the tooltip widgets.
 -- @property wibox
--- @param `wibox`
+-- @param wibox
 
 function tooltip:get_wibox()
     if self._private.wibox then
@@ -224,6 +224,7 @@ end
 --- Is the tooltip visible?
 -- @property visible
 -- @param boolean
+-- @propemits true false
 
 function tooltip:get_visible()
     return self._private.visible
@@ -237,6 +238,8 @@ function tooltip:set_visible(value)
     else
         hide(self)
     end
+
+    self:emit_signal("property::visible", value)
 end
 
 --- The horizontal alignment.
@@ -261,9 +264,10 @@ end
 --
 -- @property align
 -- @param string
--- @see beautiful.tooltip_align
 -- @see mode
 -- @see preferred_positions
+-- @propemits true false
+-- @propbeautiful
 
 --- The default tooltip alignment.
 -- @beautiful beautiful.tooltip_align
@@ -282,7 +286,7 @@ function tooltip:set_align(value)
     self._private.align = value
 
     set_geometry(self)
-    self:emit_signal("property::align")
+    self:emit_signal("property::align", value)
 end
 
 --- The shape of the tooltip window.
@@ -292,10 +296,13 @@ end
 -- @property shape
 -- @tparam gears.shape shape
 -- @see gears.shape
--- @see beautiful.tooltip_shape
+-- @propemits true false
+-- @propbeautiful
 
 function tooltip:set_shape(s)
     self.backgroundbox:set_shape(s)
+
+    self:emit_signal("property::shape", s)
 end
 
 --- Set the tooltip positioning mode.
@@ -318,12 +325,13 @@ end
 --
 -- @property mode
 -- @param string
+-- @propemits true false
 
 function tooltip:set_mode(mode)
     self._private.mode = mode
 
     set_geometry(self)
-    self:emit_signal("property::mode")
+    self:emit_signal("property::mode", mode)
 end
 
 function tooltip:get_mode()
@@ -350,6 +358,7 @@ end
 --
 -- @property preferred_positions
 -- @tparam table preferred_positions The position, ordered by priorities
+-- @propemits true false
 -- @see align
 -- @see mode
 -- @see preferred_alignments
@@ -363,6 +372,8 @@ function tooltip:set_preferred_positions(value)
     self._private.preferred_positions = value
 
     set_geometry(self)
+
+    self:emit_signal("property::preferred_positions", value)
 end
 
 --- The preferred alignment when using the `outside` mode.
@@ -394,6 +405,7 @@ end
 --
 -- @property preferred_alignments
 -- @param string
+-- @propemits true false
 -- @see preferred_positions
 
 function tooltip:get_preferred_alignments()
@@ -405,14 +417,16 @@ function tooltip:set_preferred_alignments(value)
     self._private.preferred_alignments = value
 
     set_geometry(self)
+
+    self:emit_signal("property::preferred_alignments", value)
 end
 
 --- Change displayed text.
 --
 -- @property text
--- @tparam tooltip self The tooltip object.
 -- @tparam string  text New tooltip text, passed to
 --   `wibox.widget.textbox.set_text`.
+-- @propemits true false
 -- @see wibox.widget.textbox
 
 function tooltip:set_text(text)
@@ -420,14 +434,16 @@ function tooltip:set_text(text)
     if self._private.visible then
         set_geometry(self)
     end
+
+    self:emit_signal("property::text", text)
 end
 
 --- Change displayed markup.
 --
 -- @property markup
--- @tparam tooltip self The tooltip object.
 -- @tparam string  text New tooltip markup, passed to
 --   `wibox.widget.textbox.set_markup`.
+-- @propemits true false
 -- @see wibox.widget.textbox
 
 function tooltip:set_markup(text)
@@ -435,18 +451,21 @@ function tooltip:set_markup(text)
     if self._private.visible then
         set_geometry(self)
     end
+
+    self:emit_signal("property::markup", text)
 end
 
 --- Change the tooltip's update interval.
 --
 -- @property timeout
--- @tparam tooltip self A tooltip object.
 -- @tparam number timeout The timeout value.
+-- @propemits true false
 
 function tooltip:set_timeout(timeout)
     if self.timer then
         self.timer.timeout = timeout
     end
+    self:emit_signal("property::timeout", timeout)
 end
 
 --- Set all margins around the tooltip textbox
@@ -454,11 +473,12 @@ end
 -- @DOC_awful_tooltip_margins_EXAMPLE@
 --
 -- @property margins
--- @tparam tooltip self A tooltip object
--- @tparam number New margins value
+-- @tparam number|table New margins value
+-- @propemits true false
 
 function tooltip:set_margins(val)
     self.marginbox:set_margins(val)
+    self:emit_signal("property::margins", val)
 end
 
 --- The border width.
@@ -467,9 +487,12 @@ end
 --
 -- @property border_width
 -- @param number
+-- @propemits true false
+-- @propbeautiful
 
 function tooltip:set_border_width(val)
     self.widget.border_width = val
+    self:emit_signal("property::border_width", val)
 end
 
 --- The border color.
@@ -478,10 +501,11 @@ end
 --
 -- @property border_color
 -- @param color
--- @param gears.color
+-- @propemits true false
 
 function tooltip:set_border_color(val)
     self.widget.border_color = val
+    self:emit_signal("property::border_color", val)
 end
 
 --- Set the margins around the left and right of the tooltip textbox
@@ -489,12 +513,13 @@ end
 -- @DOC_awful_tooltip_margins_leftright_EXAMPLE@
 --
 -- @property margins_leftright
--- @tparam tooltip self A tooltip object
 -- @tparam number New margins value
+-- @propemits true false
 
 function tooltip:set_margin_leftright(val)
     self.marginbox:set_left(val)
     self.marginbox:set_right(val)
+    self:emit_signal("property::margin_leftright", val)
 end
 
 --TODO v5 deprecate this
@@ -507,12 +532,13 @@ end
 -- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@
 --
 -- @property margins_topbottom
--- @tparam tooltip self A tooltip object
 -- @tparam number New margins value
+-- @propemits true false
 
 function tooltip:set_margin_topbottom(val)
     self.marginbox:set_top(val)
     self.marginbox:set_bottom(val)
+    self:emit_signal("property::margin_topbottom", val)
 end
 
 --TODO v5 deprecate this
@@ -727,6 +753,8 @@ function tooltip.mt:__call(...)
     return tooltip.new(...)
 end
 
+--@DOC_object_COMMON@
+
 return setmetatable(tooltip, tooltip.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

From c32c2bf43d87862cbf83f5ccb386fccd975c1840 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage-Vallee <elv1313@gmail.com>
Date: Sat, 21 Dec 2019 21:27:21 -0800
Subject: [PATCH 5/7] doc: Upgrade the keygrabber to the newest standards.

---
 lib/awful/keygrabber.lua | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua
index 6d5c45ae..eca79fa1 100644
--- a/lib/awful/keygrabber.lua
+++ b/lib/awful/keygrabber.lua
@@ -406,7 +406,7 @@ end
 -- poluting the original object of having extra boilerplate code.
 --
 -- @tfield keygrabber current_instance
--- @see property::current_instance
+-- @emits property::current_instance
 
 --- The global signal used to track the `current_instance`.
 --
@@ -422,6 +422,8 @@ end
 --
 -- @method start
 -- @treturn boolean If the keygrabber was successfully started.
+-- @emits started
+-- @emits property::current_instance
 function keygrabber:start()
     if self.grabber or keygrab.current_instance then
         return false
@@ -473,6 +475,8 @@ end
 
 --- Stop the keygrabber.
 -- @method stop
+-- @emits stopped
+-- @emits property::current_instance
 function keygrabber:stop(_stop_key, _stop_mods) -- (at)function disables ldoc params
     keygrab.stop(self.grabber)
 

From 9f42f57a76a4c3b8d24294089c06ae8942ee2c28 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage-Vallee <elv1313@gmail.com>
Date: Sat, 21 Dec 2019 21:35:12 -0800
Subject: [PATCH 6/7] doc: Upgrade the gears.timer documentation to the new
 standards.

---
 lib/gears/timer.lua | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua
index 5eb5ec4a..ee1778d7 100644
--- a/lib/gears/timer.lua
+++ b/lib/gears/timer.lua
@@ -85,6 +85,7 @@ local timer = { mt = {} }
 
 --- Start the timer.
 -- @method start
+-- @emits start
 function timer:start()
     if self.data.source_id ~= nil then
         gdebug.print_error(traceback("timer already started"))
@@ -99,6 +100,7 @@ end
 
 --- Stop the timer.
 -- @method stop
+-- @emits stop
 function timer:stop()
     if self.data.source_id == nil then
         gdebug.print_error(traceback("timer not started"))
@@ -113,6 +115,8 @@ end
 -- This is equivalent to stopping the timer if it is running and then starting
 -- it.
 -- @method again
+-- @emits start
+-- @emits stop
 function timer:again()
     if self.data.source_id ~= nil then
         self:stop()
@@ -128,6 +132,7 @@ end
 -- **Signal:** property::timeout
 -- @property timeout
 -- @param number
+-- @propemits true false
 
 local timer_instance_mt = {
     __index = function(self, property)
@@ -143,7 +148,7 @@ local timer_instance_mt = {
     __newindex = function(self, property, value)
         if property == "timeout" then
             self.data.timeout = tonumber(value)
-            self:emit_signal("property::timeout")
+            self:emit_signal("property::timeout", value)
         end
     end
 }

From 833948ea67917227f4cfa3c3258453e606758c42 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage-Vallee <elv1313@gmail.com>
Date: Sat, 21 Dec 2019 21:53:57 -0800
Subject: [PATCH 7/7] doc: Polish the awful.widget doc.

A lot of them were missing the inheritance includes.
---
 lib/awful/widget/clienticon.lua     | 2 ++
 lib/awful/widget/keyboardlayout.lua | 4 ++++
 lib/awful/widget/launcher.lua       | 4 ++++
 lib/awful/widget/layoutlist.lua     | 4 ++++
 lib/awful/widget/prompt.lua         | 4 ++++
 lib/awful/widget/taglist.lua        | 4 ++++
 lib/awful/widget/tasklist.lua       | 4 ++++
 lib/awful/widget/watch.lua          | 4 ++++
 8 files changed, 30 insertions(+)

diff --git a/lib/awful/widget/clienticon.lua b/lib/awful/widget/clienticon.lua
index 69e53aca..3d6a8238 100644
--- a/lib/awful/widget/clienticon.lua
+++ b/lib/awful/widget/clienticon.lua
@@ -84,6 +84,7 @@ end
 --
 -- @property client
 -- @param client
+-- @propemits true false
 
 function clienticon:get_client()
     return self._private.client
@@ -94,6 +95,7 @@ function clienticon:set_client(c)
     self._private.client = c
     self:emit_signal("widget::layout_changed")
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::client", c)
 end
 
 --- Returns a new clienticon.
diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua
index 99d9e7a9..14442aed 100644
--- a/lib/awful/widget/keyboardlayout.lua
+++ b/lib/awful/widget/keyboardlayout.lua
@@ -310,6 +310,10 @@ function keyboardlayout.mt:__call(...)
     return _instance
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(keyboardlayout, keyboardlayout.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/lib/awful/widget/launcher.lua b/lib/awful/widget/launcher.lua
index 79dfabbb..0b6e675c 100644
--- a/lib/awful/widget/launcher.lua
+++ b/lib/awful/widget/launcher.lua
@@ -50,6 +50,10 @@ function launcher.mt:__call(...)
     return launcher.new(...)
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(launcher, launcher.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua
index 1241bf5e..43a702f9 100644
--- a/lib/awful/widget/layoutlist.lua
+++ b/lib/awful/widget/layoutlist.lua
@@ -178,12 +178,14 @@ local layoutlist = {}
 -- automatically.
 -- @property base_layout
 -- @param widget
+-- @propemits true false
 -- @see wibox.layout.fixed.vertical
 -- @see base_layout
 
 --- The delegate widget template.
 -- @property widget_template
 -- @param table
+-- @propemits true false
 
 --- The layoutlist screen.
 -- @property screen
@@ -329,6 +331,7 @@ function layoutlist:set_base_layout(layout)
 
     self:emit_signal("widget::layout_changed")
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::base_layout", layout)
 end
 
 function layoutlist:set_widget_template(widget_template)
@@ -345,6 +348,7 @@ function layoutlist:set_widget_template(widget_template)
 
     self:emit_signal("widget::layout_changed")
     self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::widget_template", widget_template)
 end
 
 function layoutlist:layout(_, width, height)
diff --git a/lib/awful/widget/prompt.lua b/lib/awful/widget/prompt.lua
index a3b29d2b..611b80a3 100644
--- a/lib/awful/widget/prompt.lua
+++ b/lib/awful/widget/prompt.lua
@@ -158,6 +158,10 @@ function widgetprompt.mt:__call(...)
     return widgetprompt.new(...)
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(widgetprompt, widgetprompt.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua
index 7d2150c8..7e8b117c 100644
--- a/lib/awful/widget/taglist.lua
+++ b/lib/awful/widget/taglist.lua
@@ -607,6 +607,10 @@ function taglist.mt:__call(...)
     return taglist.new(...)
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(taglist, taglist.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua
index 89942037..d2fe7cfe 100644
--- a/lib/awful/widget/tasklist.lua
+++ b/lib/awful/widget/tasklist.lua
@@ -739,6 +739,10 @@ function tasklist.mt:__call(...)
     return tasklist.new(...)
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(tasklist, tasklist.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/lib/awful/widget/watch.lua b/lib/awful/widget/watch.lua
index 03926c14..b45fe644 100644
--- a/lib/awful/widget/watch.lua
+++ b/lib/awful/widget/watch.lua
@@ -88,6 +88,10 @@ function watch.mt.__call(_, ...)
     return watch.new(...)
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(watch, watch.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80