background: Add some property signals and update the doc.

It had no signals for the properties. That's non standard and has
been fixed.

The documentation tags were also upgraded to the latest standards.

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, {