diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc
index b60cb511..a48b7530 100644
--- a/docs/common/wibox.ldoc
+++ b/docs/common/wibox.ldoc
@@ -217,10 +217,12 @@
 
 --- The default background color.
 -- @beautiful beautiful.bg_normal
+-- @param color
 -- @see bg
 
 --- The default foreground (text) color.
 -- @beautiful beautiful.fg_normal
+-- @param color
 -- @see fg
 
 --- Set a declarative widget hierarchy description.
@@ -232,6 +234,7 @@
 -- @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
 -- @see gears.color
 
 --- The background image of the drawable.
@@ -245,6 +248,7 @@
 -- @param c The foreground to use. This must either be a cairo pattern object,
 --   nil or a string that gears.color() understands.
 -- @property fg
+-- @param color
 -- @see gears.color
 
 --- Find a widget by a point.
diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua
index 1068c16e..a3aeab25 100644
--- a/lib/awful/hotkeys_popup/widget.lua
+++ b/lib/awful/hotkeys_popup/widget.lua
@@ -49,13 +49,16 @@ local widget = {
 }
 
 --- Don't show hotkeys without descriptions.
+-- @tfield boolean widget.hide_without_description
+-- @param boolean
 widget.hide_without_description = true
 
 --- Merge hotkey records into one if they have the same modifiers and
 -- description.
+-- @tfield boolean widget.merge_duplicates
+-- @param boolean
 widget.merge_duplicates = true
 
-
 --- Hotkeys widget background color.
 -- @beautiful beautiful.hotkeys_bg
 -- @tparam color hotkeys_bg
diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua
index 4c94e66d..2d076c67 100644
--- a/lib/awful/keygrabber.lua
+++ b/lib/awful/keygrabber.lua
@@ -314,6 +314,7 @@ end
 -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@
 --
 -- @property timeout
+-- @param number
 -- @see gears.timer
 -- @see timeout_callback
 
@@ -393,6 +394,7 @@ end
 -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@
 --
 -- @property root_keybindings
+-- @param table
 -- @see export_keybindings
 -- @see keybindings
 
diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua
index cc1d29ac..ee7acc9b 100644
--- a/lib/awful/menu.lua
+++ b/lib/awful/menu.lua
@@ -50,6 +50,7 @@ end
 
 --- The icon used for sub-menus.
 -- @beautiful beautiful.menu_submenu_icon
+-- @tparam string|gears.surface menu_submenu_icon
 
 --- The menu text font.
 -- @beautiful beautiful.menu_font
diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua
index b9043f97..443b6417 100644
--- a/lib/awful/screen.lua
+++ b/lib/awful/screen.lua
@@ -248,7 +248,7 @@ function screen.preferred(c)
 end
 
 --- The defaults arguments for `awful.screen.focused`.
--- @tfield[opt=nil] table awful.screen.default_focused_args
+-- @tfield[opt={}] table awful.screen.default_focused_args
 
 --- Get the focused screen.
 --
@@ -537,7 +537,7 @@ end
 
 --- The number of pixels per inch of the screen.
 -- @property dpi
--- @treturn number the DPI value.
+-- @param number the DPI value.
 
 local xft_dpi, fallback_dpi
 
diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index de66251b..d54f0c29 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -742,7 +742,7 @@ end
 --         -- awful.layout.suit.corner.se,
 --     }
 --
--- @field awful.tag.layouts
+-- @tfield table awful.tag.layouts
 
 --- The tag client layout.
 --
diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua
index 60e602c0..1aabd66f 100644
--- a/lib/awful/titlebar.lua
+++ b/lib/awful/titlebar.lua
@@ -38,9 +38,11 @@ local titlebar = {
 
 --- Show tooltips when hover on titlebar buttons.
 -- @tfield[opt=true] boolean awful.titlebar.enable_tooltip
+-- @param boolean
 
 --- Title to display if client name is not set.
 -- @field[opt='\<unknown\>'] awful.titlebar.fallback_name
+-- @tparam[opt='\<unknown\>'] string fallback_name
 
 
 --- The titlebar foreground (text) color.
@@ -55,7 +57,7 @@ local titlebar = {
 
 --- The titlebar background image image.
 -- @beautiful beautiful.titlebar_bgimage_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The titlebar foreground (text) color.
@@ -70,7 +72,7 @@ local titlebar = {
 
 --- The titlebar background image image.
 -- @beautiful beautiful.titlebar_bgimage
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The focused titlebar foreground (text) color.
@@ -85,347 +87,347 @@ local titlebar = {
 
 --- The focused titlebar background image image.
 -- @beautiful beautiful.titlebar_bgimage_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal.
 -- @beautiful beautiful.titlebar_floating_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal.
 -- @beautiful beautiful.titlebar_maximized_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_normal.
 -- @beautiful beautiful.titlebar_minimize_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_normal_hover.
 -- @beautiful beautiful.titlebar_minimize_button_normal_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_normal_press.
 -- @beautiful beautiful.titlebar_minimize_button_normal_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_normal.
 -- @beautiful beautiful.titlebar_close_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_normal_hover.
 -- @beautiful beautiful.titlebar_close_button_normal_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_normal_press.
 -- @beautiful beautiful.titlebar_close_button_normal_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal.
 -- @beautiful beautiful.titlebar_ontop_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal.
 -- @beautiful beautiful.titlebar_sticky_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus.
 -- @beautiful beautiful.titlebar_floating_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus.
 -- @beautiful beautiful.titlebar_maximized_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_focus.
 -- @beautiful beautiful.titlebar_minimize_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_focus_hover.
 -- @beautiful beautiful.titlebar_minimize_button_focus_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_focus_press.
 -- @beautiful beautiful.titlebar_minimize_button_focus_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_focus.
 -- @beautiful beautiful.titlebar_close_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_focus_hover.
 -- @beautiful beautiful.titlebar_close_button_focus_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_focus_press.
 -- @beautiful beautiful.titlebar_close_button_focus_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus.
 -- @beautiful beautiful.titlebar_ontop_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus.
 -- @beautiful beautiful.titlebar_sticky_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_active.
 -- @beautiful beautiful.titlebar_floating_button_normal_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_active_hover.
 -- @beautiful beautiful.titlebar_floating_button_normal_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_active_press.
 -- @beautiful beautiful.titlebar_floating_button_normal_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_active.
 -- @beautiful beautiful.titlebar_maximized_button_normal_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_active_hover.
 -- @beautiful beautiful.titlebar_maximized_button_normal_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_active_press.
 -- @beautiful beautiful.titlebar_maximized_button_normal_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_active.
 -- @beautiful beautiful.titlebar_ontop_button_normal_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_active_hover.
 -- @beautiful beautiful.titlebar_ontop_button_normal_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_active_press.
 -- @beautiful beautiful.titlebar_ontop_button_normal_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_active.
 -- @beautiful beautiful.titlebar_sticky_button_normal_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_active_hover.
 -- @beautiful beautiful.titlebar_sticky_button_normal_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_active_press.
 -- @beautiful beautiful.titlebar_sticky_button_normal_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_active.
 -- @beautiful beautiful.titlebar_floating_button_focus_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_active_hover.
 -- @beautiful beautiful.titlebar_floating_button_focus_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_active_press.
 -- @beautiful beautiful.titlebar_floating_button_focus_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_active.
 -- @beautiful beautiful.titlebar_maximized_button_focus_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_active_hover.
 -- @beautiful beautiful.titlebar_maximized_button_focus_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_active_press.
 -- @beautiful beautiful.titlebar_maximized_button_focus_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_active.
 -- @beautiful beautiful.titlebar_ontop_button_focus_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_active_hover.
 -- @beautiful beautiful.titlebar_ontop_button_focus_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_active_press.
 -- @beautiful beautiful.titlebar_ontop_button_focus_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_active.
 -- @beautiful beautiful.titlebar_sticky_button_focus_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_active_hover.
 -- @beautiful beautiful.titlebar_sticky_button_focus_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_active_press.
 -- @beautiful beautiful.titlebar_sticky_button_focus_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_inactive.
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_inactive_hover.
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_inactive_press.
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_inactive.
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_inactive_hover.
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_inactive_press.
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_inactive.
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_inactive_hover.
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_inactive_press.
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_inactive.
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_inactive_hover.
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_inactive_press.
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_inactive.
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_inactive_hover.
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_inactive_press.
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_inactive.
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_inactive_hover.
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_inactive_press.
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_inactive.
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_inactive_hover.
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_inactive_press.
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_inactive.
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_inactive_hover.
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_inactive_press.
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- Set a declarative widget hierarchy description.
diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua
index 930010ad..44363d3d 100644
--- a/lib/awful/tooltip.lua
+++ b/lib/awful/tooltip.lua
@@ -86,27 +86,34 @@ local offset = {
 
 --- The tooltip border color.
 -- @beautiful beautiful.tooltip_border_color
+-- @param color
 
 --- The tooltip background color.
 -- @beautiful beautiful.tooltip_bg
+-- @param color
 
 --- The tooltip foregound (text) color.
 -- @beautiful beautiful.tooltip_fg
+-- @param color
 
 --- The tooltip font.
 -- @beautiful beautiful.tooltip_font
+-- @param string
 
 --- The tooltip border width.
 -- @beautiful beautiful.tooltip_border_width
+-- @param number
 
 --- The tooltip opacity.
 -- @beautiful beautiful.tooltip_opacity
+-- @param number opacity Between 0 and 1
 
 --- The default tooltip shape.
--- The default shape for all tooltips is a rectangle. However, by setting this variable
--- they can default to rounded rectangle or stretched octogons.
+-- The default shape for all tooltips is a rectangle. However, by setting
+-- this variable they can default to rounded rectangle or stretched octogons.
 -- @beautiful beautiful.tooltip_shape
--- @tparam[opt=gears.shape.rectangle] function shape A `gears.shape` compatible function
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape A `gears.shape`
+--  compatible function
 -- @see shape
 -- @see gears.shape
 
@@ -251,6 +258,7 @@ end
 -- * top
 --
 -- @property align
+-- @param string
 -- @see beautiful.tooltip_align
 -- @see mode
 -- @see preferred_positions
@@ -280,6 +288,7 @@ end
 -- @DOC_awful_tooltip_shape_EXAMPLE@
 --
 -- @property shape
+-- @tparam gears.shape shape
 -- @see gears.shape
 -- @see beautiful.tooltip_shape
 
@@ -466,6 +475,7 @@ end
 -- @DOC_awful_tooltip_border_color_EXAMPLE@
 --
 -- @property border_color
+-- @param color
 -- @param gears.color
 
 function tooltip:set_border_color(val)
diff --git a/lib/awful/util.lua b/lib/awful/util.lua
index d0a14d1f..c9d13f6a 100644
--- a/lib/awful/util.lua
+++ b/lib/awful/util.lua
@@ -31,6 +31,7 @@ local util = {}
 util.table = {}
 
 --- The default shell used when spawing processes.
+-- @param string
 util.shell = os.getenv("SHELL") or "/bin/sh"
 
 --- Execute a system command and road the output.
diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua
index 8be36dc5..4b39d4e9 100644
--- a/lib/awful/widget/taglist.lua
+++ b/lib/awful/widget/taglist.lua
@@ -153,7 +153,7 @@ taglist.filter, taglist.source = {}, {}
 -- This will be the fallback for state specific shapes.
 -- To get a shape for the whole taglist, use `wibox.container.background`.
 -- @beautiful beautiful.taglist_shape
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 -- @see beautiful.taglist_shape_empty
 -- @see beautiful.taglist_shape_focus
@@ -172,7 +172,7 @@ taglist.filter, taglist.source = {}, {}
 
 --- The shape used for the empty elements.
 -- @beautiful beautiful.taglist_shape_empty
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The shape used for the empty elements border width.
@@ -187,7 +187,7 @@ taglist.filter, taglist.source = {}, {}
 
 --- The shape used for the selected elements.
 -- @beautiful beautiful.taglist_shape_focus
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The shape used for the selected elements border width.
@@ -202,7 +202,7 @@ taglist.filter, taglist.source = {}, {}
 
 --- The shape used for the urgent elements.
 -- @beautiful beautiful.taglist_shape_urgent
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The shape used for the urgent elements border width.
@@ -217,7 +217,7 @@ taglist.filter, taglist.source = {}, {}
 
 --- The shape used for the volatile elements.
 -- @beautiful beautiful.taglist_shape_volatile
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The shape used for the volatile elements border width.
diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua
index 5ab2d582..63ced04b 100644
--- a/lib/beautiful/init.lua
+++ b/lib/beautiful/init.lua
@@ -89,34 +89,44 @@ local active_font
 
 --- The default font.
 -- @beautiful beautiful.font
+-- @param string
 
 -- The default background color.
 -- @beautiful beautiful.bg_normal
+-- @param color
 
 -- The default focused element background color.
 -- @beautiful beautiful.bg_focus
+-- @param color
 
 -- The default urgent element background color.
 -- @beautiful beautiful.bg_urgent
+-- @param color
 
 -- The default minimized element background color.
 -- @beautiful beautiful.bg_minimize
+-- @param color
 
 -- The system tray background color.
 -- Please note that only solid colors are currently supported.
 -- @beautiful beautiful.bg_systray
+-- @param color
 
 -- The default focused element foreground (text) color.
 -- @beautiful beautiful.fg_normal
+-- @param color
 
 -- The default focused element foreground (text) color.
 -- @beautiful beautiful.fg_focus
+-- @param color
 
 -- The default urgent element foreground (text) color.
 -- @beautiful beautiful.fg_urgent
+-- @param color
 
 -- The default minimized element foreground (text) color.
 -- @beautiful beautiful.fg_minimize
+-- @param color
 
 --- The gap between clients.
 -- @beautiful beautiful.useless_gap
@@ -124,31 +134,39 @@ local active_font
 
 --- The client border width.
 -- @beautiful beautiful.border_width
+-- @param number
 
 --- The default clients border color.
 -- Note that only solid colors are supported.
 -- @beautiful beautiful.border_normal
+-- @param color
 
 --- The focused client border color.
 -- Note that only solid colors are supported.
 -- @beautiful beautiful.border_focus
+-- @param color
 
 --- The marked clients border color.
 -- Note that only solid colors are supported.
 -- @beautiful beautiful.border_marked
+-- @param color
 
 --- The wallpaper path.
 -- @beautiful beautiful.wallpaper
+-- @tparam string|gears.surface wallpaper
 
 -- The icon theme name.
 -- It has to be a directory in `/usr/share/icons` or an XDG icon folder.
 -- @beautiful beautiful.icon_theme
+-- @param string
 
 --- The Awesome icon path.
 -- @beautiful beautiful.awesome_icon
+-- @tparam string|gears.surface icon
 
 --- The current theme path (if any)
 -- @tfield string beautiful.theme_path
+-- @param string
 
 --- Load a font from a string or a font description.
 --
diff --git a/lib/gears/matrix.lua b/lib/gears/matrix.lua
index f66a4004..92878256 100644
--- a/lib/gears/matrix.lua
+++ b/lib/gears/matrix.lua
@@ -217,6 +217,7 @@ matrix_mt.__mul = matrix.multiply
 matrix_mt.__tostring = matrix.tostring
 
 --- A constant for the identity matrix.
+-- @param matrix
 matrix.identity = matrix.create(1, 0, 0, 1, 0, 0)
 
 return matrix
diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua
index 16cf5d5b..c76b58a6 100644
--- a/lib/menubar/init.lua
+++ b/lib/menubar/init.lua
@@ -48,9 +48,11 @@ end
 
 --- Menubar normal text color.
 -- @beautiful beautiful.menubar_fg_normal
+-- @param color
 
 --- Menubar normal background color.
 -- @beautiful beautiful.menubar_bg_normal
+-- @param color
 
 --- Menubar border width.
 -- @beautiful beautiful.menubar_border_width
@@ -58,12 +60,15 @@ end
 
 --- Menubar border color.
 -- @beautiful beautiful.menubar_border_color
+-- @param color
 
 --- Menubar selected item text color.
 -- @beautiful beautiful.menubar_fg_normal
+-- @param color
 
 --- Menubar selected item background color.
 -- @beautiful beautiful.menubar_bg_normal
+-- @param color
 
 
 -- menubar
diff --git a/lib/menubar/utils.lua b/lib/menubar/utils.lua
index ae081747..b112397a 100644
--- a/lib/menubar/utils.lua
+++ b/lib/menubar/utils.lua
@@ -32,6 +32,7 @@ local utils = {}
 -- Options section
 
 --- Terminal which applications that need terminal would open in.
+-- @param[opt="xterm"] string
 utils.terminal = 'xterm'
 
 --- The default icon for applications that don't provide any icon in
@@ -39,6 +40,7 @@ utils.terminal = 'xterm'
 local default_icon = nil
 
 --- Name of the WM for the OnlyShowIn entry in the .desktop file.
+-- @param[opt="awesome"] string
 utils.wm_name = "awesome"
 
 -- Maps keys in desktop entries to suitable getter function.
diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua
index bf98e712..28e0de03 100644
--- a/lib/naughty/action.lua
+++ b/lib/naughty/action.lua
@@ -41,7 +41,7 @@ local action = {}
 
 --- The action icon.
 -- @property icon
--- @param gears.surface
+-- @tparam gears.surface|string icon
 
 --- The notification.
 -- @property notification
diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua
index 4e00d58f..d7f2a77c 100644
--- a/lib/naughty/notification.lua
+++ b/lib/naughty/notification.lua
@@ -163,6 +163,7 @@ local notification = {}
 --- Widget shape.
 --@DOC_naughty_shape_EXAMPLE@
 -- @property shape
+-- @param gears.shape
 
 --- Widget opacity.
 -- @property opacity
diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua
index 5b5f495a..2c5a0551 100644
--- a/lib/wibox/container/arcchart.lua
+++ b/lib/wibox/container/arcchart.lua
@@ -22,12 +22,15 @@ local arcchart = { mt = {} }
 
 --- The progressbar border background color.
 -- @beautiful beautiful.arcchart_border_color
+-- @param color
 
 --- The progressbar foreground color.
 -- @beautiful beautiful.arcchart_color
+-- @param color
 
 --- The progressbar border width.
 -- @beautiful beautiful.arcchart_border_width
+-- @param number
 
 --- The padding between the outline and the progressbar.
 -- @beautiful beautiful.arcchart_paddings
@@ -233,6 +236,7 @@ end
 --- The border background color.
 --@DOC_wibox_container_arcchart_border_color_EXAMPLE@
 -- @property border_color
+-- @param color
 
 --- The arcchart values foreground colors.
 --@DOC_wibox_container_arcchart_color_EXAMPLE@
@@ -246,9 +250,11 @@ end
 
 --- The minimum value.
 -- @property min_value
+-- @param number
 
 --- The maximum value.
 -- @property max_value
+-- @param number
 
 --- The radial background.
 --@DOC_wibox_container_arcchart_bg_EXAMPLE@
diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua
index 0d937707..756ddb03 100644
--- a/lib/wibox/container/constraint.lua
+++ b/lib/wibox/container/constraint.lua
@@ -62,6 +62,7 @@ end
 --- Set the strategy to use for the constraining. Valid values are 'max',
 -- 'min' or 'exact'. Throws an error on invalid values.
 -- @property strategy
+-- @tparam string strategy Either 'max', 'min' or 'exact'
 
 function constraint:set_strategy(val)
     local func = {
diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua
index 3d698792..b7bfa055 100644
--- a/lib/wibox/container/radialprogressbar.lua
+++ b/lib/wibox/container/radialprogressbar.lua
@@ -24,12 +24,15 @@ local radialprogressbar = { mt = {} }
 
 --- The progressbar border background color.
 -- @beautiful beautiful.radialprogressbar_border_color
+-- @param color
 
 --- The progressbar foreground color.
 -- @beautiful beautiful.radialprogressbar_color
+-- @param color
 
 --- The progressbar border width.
 -- @beautiful beautiful.radialprogressbar_border_width
+-- @param number
 
 --- The padding between the outline and the progressbar.
 -- @beautiful beautiful.radialprogressbar_paddings
@@ -190,10 +193,12 @@ end
 --- The border background color.
 --@DOC_wibox_container_radialprogressbar_border_color_EXAMPLE@
 -- @property border_color
+-- @param color
 
 --- The border foreground color.
 --@DOC_wibox_container_radialprogressbar_color_EXAMPLE@
 -- @property color
+-- @param color
 
 --- The border width.
 --@DOC_wibox_container_radialprogressbar_border_width_EXAMPLE@
@@ -202,9 +207,11 @@ end
 
 --- The minimum value.
 -- @property min_value
+-- @param number
 
 --- The maximum value.
 -- @property max_value
+-- @param number
 
 for _, prop in ipairs {"max_value", "min_value", "border_color", "color",
     "border_width", "paddings"} do
diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua
index 283a395e..766c774e 100644
--- a/lib/wibox/layout/align.lua
+++ b/lib/wibox/layout/align.lua
@@ -142,6 +142,7 @@ end
 --- Set the layout's first widget.
 -- This is the widget that is at the left/top
 -- @property first
+-- @param widget
 
 function align:set_first(widget)
     if self._private.first == widget then
@@ -153,6 +154,7 @@ end
 
 --- Set the layout's second widget. This is the centered one.
 -- @property second
+-- @param widget
 
 function align:set_second(widget)
     if self._private.second == widget then
@@ -165,6 +167,7 @@ end
 --- Set the layout's third widget.
 -- This is the widget that is at the right/bottom
 -- @property third
+-- @param widget
 
 function align:set_third(widget)
     if self._private.third == widget then
@@ -184,6 +187,7 @@ end
 -- This can be used to replace all 3 widgets at once.
 -- @treturn table a list of all widgets
 -- @property children
+-- @param table
 
 function align:get_children()
     return gtable.from_sparse {self._private.first, self._private.second, self._private.third}
diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua
index aedfbeac..c9d2e74c 100644
--- a/lib/wibox/layout/fixed.lua
+++ b/lib/wibox/layout/fixed.lua
@@ -291,6 +291,7 @@ end
 -- widget will get all the space that is left. If this is false, the last widget
 -- won't be handled specially and there can be space left unused.
 -- @property fill_space
+-- @param boolean
 
 function fixed:fill_space(val)
     if self._private.fill_space ~= val then
diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua
index efe10ec4..53571ca4 100644
--- a/lib/wibox/widget/checkbox.lua
+++ b/lib/wibox/widget/checkbox.lua
@@ -21,29 +21,37 @@ local checkbox = {}
 
 --- The outer (unchecked area) border width.
 -- @beautiful beautiful.checkbox_border_width
+-- @param number
 
 --- The outer (unchecked area) background color, pattern or gradient.
 -- @beautiful beautiful.checkbox_bg
+-- @param color
 
 --- The outer (unchecked area) border color.
 -- @beautiful beautiful.checkbox_border_color
+-- @param color
 
 --- The checked part border color.
 -- @beautiful beautiful.checkbox_check_border_color
+-- @param color
 
 --- The checked part border width.
 -- @beautiful beautiful.checkbox_check_border_width
+-- @param number
 
 --- The checked part filling color.
 -- @beautiful beautiful.checkbox_check_color
+-- @param number
 
 --- The outer (unchecked area) shape.
 -- @beautiful beautiful.checkbox_shape
+-- @tparam gears.shape shape
 -- @see gears.shape
 
 --- The checked part shape.
 -- If none is set, then the `shape` property will be used.
 -- @beautiful beautiful.checkbox_check_shape
+-- @tparam gears.shape shape
 -- @see gears.shape
 
 --- The padding between the outline and the progressbar.
@@ -59,35 +67,44 @@ local checkbox = {}
 -- filling color. Note that `check_color` and `border_color` have priority
 -- over this property.
 -- @beautiful beautiful.checkbox_color
+-- @param color
 
 --- The outer (unchecked area) border width.
 -- @property border_width
+-- @param number
 
 --- The outer (unchecked area) background color, pattern or gradient.
 --@DOC_wibox_widget_checkbox_bg_EXAMPLE@
 -- @property bg
+-- @param color
 
 --- The outer (unchecked area) border color.
 -- @property border_color
+-- @param color
 
 --- The checked part border color.
 -- @property check_border_color
+-- @param color
 
 --- The checked part border width.
 -- @property check_border_width
+-- @param number
 
 --- The checked part filling color.
 -- @property check_color
+-- @param color
 
 --- The outer (unchecked area) shape.
 --@DOC_wibox_widget_checkbox_shape_EXAMPLE@
 -- @property shape
+-- @tparam gears.shape shape
 -- @see gears.shape
 
 --- The checked part shape.
 -- If none is set, then the `shape` property will be used.
 --@DOC_wibox_widget_checkbox_check_shape_EXAMPLE@
 -- @property check_shape
+-- @tparam gears.shape shape
 -- @see gears.shape
 
 --- The padding between the outline and the progressbar.
@@ -103,6 +120,7 @@ local checkbox = {}
 -- filling color. Note that `check_color` and `border_color` have priority
 -- over this property.
 -- @property color
+-- @param color
 
 local function outline_workarea(self, width, height)
     local offset = (self._private.border_width or
@@ -210,9 +228,6 @@ for _, prop in ipairs {"border_width", "bg", "border_color", "check_border_color
     end
 end
 
---- The checkbox color.
--- @property color
-
 function checkbox:set_paddings(val)
     self._private.paddings = type(val) == "number" and {
         left   = val,
diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua
index 0482969f..3747a2a9 100644
--- a/lib/wibox/widget/graph.lua
+++ b/lib/wibox/widget/graph.lua
@@ -97,12 +97,15 @@ local graph = { mt = {} }
 
 --- The graph background color.
 -- @beautiful beautiful.graph_bg
+-- @param color
 
 --- The graph foreground color.
 -- @beautiful beautiful.graph_fg
+-- @param color
 
 --- The graph border color.
 -- @beautiful beautiful.graph_border_color
+-- @param color
 
 local properties = { "width", "height", "border_color", "stack",
                      "stack_colors", "color", "background_color",
diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua
index 61e35f8c..76ee97a2 100644
--- a/lib/wibox/widget/imagebox.lua
+++ b/lib/wibox/widget/imagebox.lua
@@ -119,7 +119,7 @@ end
 -- is trimmed.
 --
 -- @property clip_shape
--- @tparam function clip_shape A `gears_shape` compatible shape function
+-- @tparam gears.shape clip_shape A `gears_shape` compatible shape function
 -- @see gears.shape
 -- @see set_clip_shape
 
diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua
index d6497476..0eb2bc62 100644
--- a/lib/wibox/widget/progressbar.lua
+++ b/lib/wibox/widget/progressbar.lua
@@ -41,6 +41,7 @@ local progressbar = { mt = {} }
 
 --- The progressbar border width.
 -- @property border_width
+-- @param number
 
 --- The progressbar inner border color.
 -- If the value is nil, no border will be drawn.
@@ -51,6 +52,7 @@ local progressbar = { mt = {} }
 
 --- The progressbar inner border width.
 -- @property bar_border_width
+-- @param number
 
 --- The progressbar foreground color.
 --
@@ -114,29 +116,37 @@ local progressbar = { mt = {} }
 
 --- The progressbar background color.
 -- @beautiful beautiful.progressbar_bg
+-- @param color
 
 --- The progressbar foreground color.
 -- @beautiful beautiful.progressbar_fg
+-- @param color
 
 --- The progressbar shape.
 -- @beautiful beautiful.progressbar_shape
+-- @tparam gears.shape shape
 -- @see gears.shape
 
 --- The progressbar border color.
 -- @beautiful beautiful.progressbar_border_color
+-- @param color
 
 --- The progressbar outer border width.
 -- @beautiful beautiful.progressbar_border_width
+-- @param number
 
 --- The progressbar inner shape.
 -- @beautiful beautiful.progressbar_bar_shape
+-- @tparam gears.shape shape
 -- @see gears.shape
 
 --- The progressbar bar border width.
 -- @beautiful beautiful.progressbar_bar_border_width
+-- @param number
 
 --- The progressbar bar border color.
 -- @beautiful beautiful.progressbar_bar_border_color
+-- @param color
 
 --- The progressbar margins.
 -- Note that if the `clip` is disabled, this allows the background to be smaller
diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua
index a02e8433..e56f9ba7 100644
--- a/lib/wibox/widget/separator.lua
+++ b/lib/wibox/widget/separator.lua
@@ -87,7 +87,7 @@ local separator = {}
 
 --- The separator border color.
 -- @beautiful beautiful.separator_border_color
--- @param gears.color
+-- @param color
 -- @see border_color
 
 --- The separator border width.
diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua
index 6c70d6eb..2bb9998d 100644
--- a/lib/wibox/widget/textbox.lua
+++ b/lib/wibox/widget/textbox.lua
@@ -20,6 +20,7 @@ local textbox = { mt = {} }
 
 --- The textbox font.
 -- @beautiful beautiful.font
+-- @param string
 
 --- Set the DPI of a Pango layout
 local function setup_dpi(box, dpi)