awful.tooltip: Update the property documentation.

lib/awful/tooltip.lua

@@ -207,6 +207,7 @@ end
 --- The wibox containing the tooltip widgets.
 -- @property wibox
 -- @tparam wibox wibox
+-- @propertydefault Autogenerated.
 
 function tooltip:get_wibox()
     if self._private.wibox then
@@ -257,23 +258,20 @@ end
 --
 -- @DOC_awful_tooltip_align2_EXAMPLE@
 --
--- The following values are valid:
---
--- * top_left
--- * left
--- * bottom_left
--- * right
--- * top_right
--- * bottom_right
--- * bottom
--- * top
---
 -- @property align
--- @tparam string align
--- @see mode
--- @see preferred_positions
+-- @tparam[opt="right"] string|nil align
+-- @propertyvalue "top_left"
+-- @propertyvalue "left"
+-- @propertyvalue "bottom_left"
+-- @propertyvalue "right"
+-- @propertyvalue "top_right"
+-- @propertyvalue "bottom_right"
+-- @propertyvalue "bottom"
+-- @propertyvalue "top"
 -- @propemits true false
 -- @propbeautiful
+-- @see mode
+-- @see preferred_positions
 
 --- The default tooltip alignment.
 -- @beautiful beautiful.tooltip_align
@@ -300,7 +298,7 @@ end
 -- @DOC_awful_tooltip_shape_EXAMPLE@
 --
 -- @property shape
--- @tparam gears.shape shape
+-- @tparam[opt=gears.shape.rectangle] shap|nil shape
 -- @see gears.shape
 -- @propemits true false
 -- @propbeautiful
@@ -324,13 +322,10 @@ end
 --
 -- @DOC_awful_tooltip_mode2_EXAMPLE@
 --
--- Valid modes are:
---
--- * "mouse": Next to the mouse cursor
--- * "outside": Outside of the widget
---
 -- @property mode
--- @tparam string mode
+-- @tparam[opt="mouse"] string mode
+-- @propertyvalue "mouse" Next to the mouse cursor.
+-- @propertyvalue "outside" Outside of the widget.
 -- @propemits true false
 
 function tooltip:set_mode(mode)
@@ -358,12 +353,10 @@ end
 -- * "left"
 -- * "bottom"
 --
--- The default is:
---
---    {"top", "right", "left", "bottom"}
---
 -- @property preferred_positions
 -- @tparam table preferred_positions The position, ordered by priorities
+-- @propertydefault `{"top", "right", "left", "bottom"}`
+-- @tablerowtype A list of strings.
 -- @propemits true false
 -- @see align
 -- @see mode
@@ -401,16 +394,14 @@ end
 --
 -- The valid table values are:
 --
--- * front
--- * middle
--- * back
---
--- The default is:
---
---    {"front", "back", "middle"}
+-- * "front"
+-- * "middle"
+-- * "back"
 --
 -- @property preferred_alignments
--- @tparam string preferred_alignments
+-- @tparam table preferred_alignments
+-- @tablerowtype A list of strings.
+-- @propertydefault `{"front", "back", "middle"}`
 -- @propemits true false
 -- @see preferred_positions
 
@@ -430,7 +421,7 @@ end
 --- Change displayed text.
 --
 -- @property text
--- @tparam string  text New tooltip text, passed to
+-- @tparam[opt=""] string text New tooltip text, passed to
 --   `wibox.widget.textbox.set_text`.
 -- @propemits true false
 -- @see wibox.widget.textbox
@@ -447,7 +438,7 @@ end
 --- Change displayed markup.
 --
 -- @property markup
--- @tparam string markup New tooltip markup, passed to
+-- @tparam[opt=""] string markup New tooltip markup, passed to
 --   `wibox.widget.textbox.set_markup`.
 -- @propemits true false
 -- @see wibox.widget.textbox
@@ -464,7 +455,9 @@ end
 --- Change the tooltip's update interval.
 --
 -- @property timeout
--- @tparam number timeout The timeout value.
+-- @tparam[opt=1] number timeout
+-- @negativeallowed false
+-- @propertyunit second
 -- @propemits true false
 
 function tooltip:set_timeout(timeout)
@@ -479,7 +472,15 @@ end
 -- @DOC_awful_tooltip_margins_EXAMPLE@
 --
 -- @property margins
--- @tparam number|table margins New margins value.
+-- @tparam[opt=0] number|table margins
+-- @tparam[opt=0] number margins.top
+-- @tparam[opt=0] number margins.bottom
+-- @tparam[opt=0] number margins.left
+-- @tparam[opt=0] number margins.right
+-- @negativeallowed true
+-- @propertyunit pixel
+-- @propertytype number A single value for each sides.
+-- @propertytype table A different value for each side.
 -- @propemits true false
 
 function tooltip:set_margins(val)
@@ -492,7 +493,9 @@ end
 -- @DOC_awful_tooltip_border_width_EXAMPLE@
 --
 -- @property border_width
--- @tparam[opt=0] number border_width
+-- @tparam[opt=0] number|nil border_width
+-- @negativeallowed false
+-- @propertyunit pixel
 -- @propemits true false
 -- @propbeautiful
 
@@ -507,7 +510,7 @@ end
 --
 -- @property border_color
 -- @tparam[opt=beautiful.tooltip_border_color or beautiful.border_color_normal or beautiful.fg_normal]
---  gears.color border_color
+--  color|nil border_color
 -- @propemits true false
 -- @propbeautiful
 
@@ -521,8 +524,12 @@ end
 -- @DOC_awful_tooltip_margins_leftright_EXAMPLE@
 --
 -- @property margins_leftright
--- @tparam number margins_leftright New margins value.
+-- @tparam[opt=0] number margins_leftright
+-- @negativeallowed true
+-- @propertyunit pixel
 -- @propemits true false
+-- @see margins
+-- @see margins_topbottom
 
 function tooltip:set_margin_leftright(val)
     self.marginbox:set_left(val)
@@ -540,8 +547,12 @@ end
 -- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@
 --
 -- @property margins_topbottom
--- @tparam number margins_topbottom New margins value.
+-- @tparam[opt=0] number margins_topbottom
+-- @negativeallowed true
+-- @propertyunit pixel
 -- @propemits true false
+-- @see margins
+-- @see margins_leftright
 
 function tooltip:set_margin_topbottom(val)
     self.marginbox:set_top(val)
@@ -559,8 +570,17 @@ end
 -- @DOC_awful_tooltip_gaps_EXAMPLE@
 --
 -- @property gaps
--- @tparam number|table gaps New margins value.
+-- @tparam[opt=0] number|table|nil gaps
+-- @tparam[opt=0] number gaps.top
+-- @tparam[opt=0] number gaps.bottom
+-- @tparam[opt=0] number gaps.left
+-- @tparam[opt=0] number gaps.right
+-- @negativeallowed true
+-- @propertytype number A single value for each sides.
+-- @propertytype table A different value for each side.
+-- @propertyunit pixel
 -- @propemits true false
+-- @propbeautiful
 
 function tooltip:set_gaps(val)
     self._private.gaps = val
@@ -572,7 +592,6 @@ end
 
 --- Add tooltip to an object.
 --
--- @tparam tooltip self The tooltip.
 -- @tparam gears.object obj An object with `mouse::enter` and
 --   `mouse::leave` signals.
 -- @noreturn
@@ -586,7 +605,6 @@ end
 
 --- Remove tooltip from an object.
 --
--- @tparam tooltip self The tooltip.
 -- @tparam gears.object obj An object with `mouse::enter` and
 --   `mouse::leave` signals.
 -- @noreturn