diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua
index eb8ff267a..eb28eb576 100644
--- a/lib/wibox/container/margin.lua
+++ b/lib/wibox/container/margin.lua
@@ -74,7 +74,7 @@ end
 --- The widget to be wrapped the the margins.
 --
 -- @property widget
--- @tparam widget widget The widget
+-- @tparam[opt=nil] widget|nil widget
 -- @interface container
 
 margin.set_widget = base.set_widget_common
@@ -94,8 +94,15 @@ end
 --- Set all the margins to val.
 --
 -- @property margins
--- @tparam number|table margins The margin value. It can be a number or a table with
---  the *left*/*right*/*top*/*bottom* keys.
+-- @tparam[opt=0] number|table margins
+-- @tparam[opt=0] number margins.left
+-- @tparam[opt=0] number margins.right
+-- @tparam[opt=0] number margins.top
+-- @tparam[opt=0] number margins.bottom
+-- @propertytype number A single value for all margins.
+-- @propertytype table A different value for each side.
+-- @propertyunit pixel
+-- @negativeallowed false
 -- @propemits false false
 
 function margin:set_margins(val)
@@ -126,7 +133,8 @@ end
 --- Set the margins color to create a border.
 --
 -- @property color
--- @tparam gears.color color A color used to fill the margin.
+-- @tparam[opt=nil] color|nil color A color used to fill the margin.
+-- @propertytype nil Transparent margins.
 -- @propemits true false
 
 function margin:set_color(color)
@@ -142,7 +150,7 @@ end
 --- Draw the margin even if the content size is 0x0.
 --
 -- @property draw_empty
--- @tparam[opt=true] boolean draw_empty Draw nothing is content is 0x0 or draw
+-- @tparam[opt=true] boolean draw_empty Draw nothing is content is `0x0` or draw
 --  the margin anyway.
 -- @propemits true false
 
@@ -156,7 +164,8 @@ function margin:get_draw_empty()
     return self._private.draw_empty
 end
 
---- Reset this layout. The widget will be unreferenced, the margins set to 0
+--- Reset this layout.
+-- The widget will be unreferenced, the margins set to 0
 -- and the color erased
 -- @method reset
 -- @noreturn
@@ -170,25 +179,33 @@ end
 --- Set the left margin that this layout adds to its widget.
 --
 -- @property left
--- @tparam number left The new margin to use.
+-- @tparam[opt=0] number left
+-- @negativeallowed false
+-- @propertyunit pixel
 -- @propemits true false
 
 --- Set the right margin that this layout adds to its widget.
 --
 -- @property right
--- @tparam number right The new margin to use.
+-- @tparam[opt=0] number right
+-- @negativeallowed false
+-- @propertyunit pixel
 -- @propemits true false
 
 --- Set the top margin that this layout adds to its widget.
 --
 -- @property top
--- @tparam number top The new margin to use.
+-- @tparam[opt=0] number top
+-- @negativeallowed false
+-- @propertyunit pixel
 -- @propemits true false
 
 --- Set the bottom margin that this layout adds to its widget.
 --
 -- @property bottom
--- @tparam number bottom The new margin to use.
+-- @tparam[opt=0] number bottom
+-- @negativeallowed false
+-- @propertyunit pixel
 -- @propemits true false
 
 -- Create setters for each direction