containers: Fix documentation

local functions and metatable based constructors are not
documented unless an explicit @function is added.

Also add missing return values and fix formatting.

lib/wibox/container/background.lua

@@ -193,11 +193,14 @@ function background:set_bgimage(image, ...)
     self:emit_signal("widget::redraw_needed")
 end
 
---- Returns a new background layout. A background layout applies a background
--- and foreground color to another widget.
+--- Returns a new background container.
+--
+-- 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.
 -- @param[opt] shape A `gears.shape` compatible shape function
+-- @function wibox.container.background
 local function new(widget, bg, shape)
     local ret = base.make_widget()
 

lib/wibox/container/constraint.lua

@@ -101,7 +101,8 @@ function constraint:reset()
     self:set_widget(nil)
 end
 
---- Returns a new constraint layout. This layout will constraint the size of a
+--- 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
 -- (fully) respect widget's requested size, the inner widget still might get
@@ -111,6 +112,8 @@ end
 -- 'exact'.
 -- @param[opt] width The maximum width of the widget. nil for no limit.
 -- @param[opt] height The maximum height of the widget. nil for no limit.
+-- @treturn table A new constraint container
+-- @function wibox.container.constraint
 local function new(widget, strategy, width, height)
     local ret = base.make_widget()
 

lib/wibox/container/margin.lua

@@ -157,7 +157,7 @@ for _, v in pairs({ "left", "right", "top", "bottom" }) do
     end
 end
 
---- Returns a new margin layout.
+--- 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.
@@ -165,6 +165,8 @@ end
 -- @param[opt] bottom A margin to use on the bottom side of the widget.
 -- @param[opt] color A color for the margins.
 -- @param[opt] draw_empty whether or not to draw the margin when the content is empty
+-- @treturn table A new margin container
+-- @function wibox.container.margin
 local function new(widget, left, right, top, bottom, color, draw_empty)
     local ret = base.make_widget()
 

lib/wibox/container/mirror.lua

@@ -95,12 +95,15 @@ function mirror:get_reflection()
     return { horizontal = self.horizontal, vertical = self.vertical }
 end
 
---- Returns a new mirror layout. A mirror layout mirrors a given widget. Use
--- :set_widget() to set the widget and
--- :set_horizontal() and :set_vertical() for the direction.
+--- Returns a new mirror container.
+-- A mirror container mirrors a given widget. Use
+-- `:set_widget()` to set the widget and
+-- `:set_horizontal()` and `:set_vertical()` for 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.
+-- @treturn table A new mirror container
+-- @function wibox.container.mirror
 local function new(widget, reflection)
     local ret = base.make_widget()
     ret.horizontal = false

lib/wibox/container/rotate.lua

@@ -108,11 +108,14 @@ function rotate:get_direction()
     return self.direction or "north"
 end
 
---- Returns a new rotate layout. A rotate layout rotates a given widget. Use
+--- 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.
 -- The default direction is "north" which doesn't change anything.
 -- @param[opt] widget The widget to display.
 -- @param[opt] dir The direction to rotate to.
+-- @treturn table A new rotate container.
+-- @function wibox.container.rotate
 local function new(widget, dir)
     local ret = base.make_widget()
 

lib/wibox/container/scroll.lua

@@ -390,7 +390,7 @@ local function get_layout(dir, widget, fps, speed, extra_space, expand, max_size
     return ret
 end
 
---- Get a new horizontal scrolling layout.
+--- Get a new horizontal scrolling container.
 -- @param[opt] widget The widget that should be scrolled
 -- @param[opt=20] fps The number of frames per second
 -- @param[opt=10] speed The speed of the animation
@@ -404,7 +404,7 @@ function scroll.horizontal(widget, fps, speed, extra_space, expand, max_size, st
     return get_layout("h", widget, fps, speed, extra_space, expand, max_size, step_function, space_for_scrolling)
 end
 
---- Get a new vertical scrolling layout.
+--- Get a new vertical scrolling container.
 -- @param[opt] widget The widget that should be scrolled
 -- @param[opt=20] fps The number of frames per second
 -- @param[opt=10] speed The speed of the animation