diff --git a/docs/common/signals.ldoc b/docs/common/signals.ldoc
index 2c636169b..30499a8ef 100644
--- a/docs/common/signals.ldoc
+++ b/docs/common/signals.ldoc
@@ -10,7 +10,7 @@
 --
 -- @tparam string name The name of the signal
 -- @tparam function func The function to attach
--- @function naughty.connect_signal
+-- @staticfct naughty.connect_signal
 -- @usage naughty.connect_signal("added", function(notif)
 --    -- do something
 -- end)
@@ -18,10 +18,10 @@
 --- Emit a module signal.
 -- @tparam string name The signal name.
 -- @param ... The signal callback arguments
--- @function naughty.emit_signal
+-- @staticfct naughty.emit_signal
 
 --- Disconnect a signal from a source.
 -- @tparam string name The name of the signal
 -- @tparam function func The attached function
--- @function naughty.disconnect_signal
+-- @staticfct naughty.disconnect_signal
 -- @treturn boolean If the disconnection was successful
diff --git a/lib/awful/client.lua b/lib/awful/client.lua
index 3d2336a7c..98f41b6bf 100644
--- a/lib/awful/client.lua
+++ b/lib/awful/client.lua
@@ -174,7 +174,7 @@ end
 -- @DOC_sequences_client_jump_to1_EXAMPLE@
 --
 -- @method jump_to
--- @tparam bool|function merge If true then merge tags (select the client's
+-- @tparam[opt] bool|function merge If true then merge tags (select the client's
 --   first tag additionally) when the client is not visible.
 --   If it is a function, it will be called with the client and its first
 --   tag as arguments.
@@ -212,7 +212,7 @@ end
 --
 -- @deprecated awful.client.visible
 -- @see screen.clients
--- @tparam[opt] integer|screen s The screen, or nil for all screens.
+-- @tparam[opt] nil|integer|screen s The screen, or nil for all screens.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table A table with all visible clients.
 function client.visible(s, stacked)
@@ -230,7 +230,7 @@ end
 --
 -- @deprecated awful.client.tiled
 -- @see screen.tiled_clients
--- @tparam integer|screen s The screen, or nil for all screens.
+-- @tparam nil|integer|screen s The screen, or nil for all screens.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table A table with all visible and tiled clients.
 function client.tiled(s, stacked)
@@ -253,8 +253,8 @@ end
 -- If no client is passed, the focused client will be used.
 --
 -- @staticfct awful.client.next
--- @tparam int i The index.  Use 1 to get the next, -1 to get the previous.
--- @tparam[opt] client sel The client.
+-- @tparam int i The index.  Use `1` to get the next, `-1` to get the previous.
+-- @tparam[opt=client.focus] client sel The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @treturn[opt] client|nil A client, or nil if no client is available.
 -- @see client.get
@@ -296,7 +296,7 @@ end
 --
 -- @staticfct awful.client.swap.bydirection
 -- @tparam string dir The direction, can be either "up", "down", "left" or "right".
--- @tparam[opt=focused] client c The client.
+-- @tparam[opt="focused"] client c The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @see swap
 -- @see swapped
@@ -328,7 +328,7 @@ end
 --
 -- @staticfct awful.client.swap.global_bydirection
 -- @tparam string dir The direction, can be either "up", "down", "left" or "right".
--- @tparam[opt] client sel The client.
+-- @tparam[opt=client.focus] client sel The client.
 -- @request client activate client.swap.global_bydirection granted When a client
 --  could be activated because `awful.client.swap.global_bydirection` was called.
 -- @see swap
@@ -370,13 +370,14 @@ end
 -- @DOC_sequences_client_swap_byidx1_EXAMPLE@
 --
 -- @staticfct awful.client.swap.byidx
--- @tparam integer i The index.
--- @tparam[opt] client c The client, otherwise focused one is used.
+-- @tparam integer i The index. Use `1` to get the next, `-1` to get the previous.
+-- @tparam[opt=client.focus] client c The client, otherwise focused one is used.
 -- @see swap
 -- @see swapped
 -- @see awful.client.swap.bydirection
 -- @see awful.client.swap.global_bydirection
 -- @see awful.client.cycle
+-- @see awful.client.next
 function client.swap.byidx(i, c)
     local sel = c or capi.client.focus
     local target = client.next(i, sel)
@@ -393,8 +394,8 @@ end
 -- @DOC_sequences_client_cycle1_EXAMPLE@
 --
 -- @staticfct awful.client.cycle
--- @tparam boolean clockwise True to cycle clients clockwise.
--- @tparam[opt] screen s The screen where to cycle clients.
+-- @tparam[opt=false] boolean clockwise True to cycle clients clockwise.
+-- @tparam[opt=awful.screen.focused()] screen s The screen where to cycle clients.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @see swap
 -- @see swapped
@@ -510,7 +511,7 @@ end
 -- @tparam integer y The relative y coordinate.
 -- @tparam integer w The relative width.
 -- @tparam integer h The relative height.
--- @tparam[opt] client c The client, otherwise focused one is used.
+-- @tparam[opt=client.focus] client c The client, otherwise focused one is used.
 -- @see client.relative_move
 function client.moveresize(x, y, w, h, c)
     gdebug.deprecate("Use c:relative_move(x, y, w, h) instead of awful.client.moveresize", {deprecated_in=4})
@@ -522,11 +523,16 @@ end
 -- @DOC_sequences_client_relative_move1_EXAMPLE@
 --
 -- @method relative_move
+-- @tparam[opt=0] integer x The relative x coordinate.
+-- @tparam[opt=0] integer y The relative y coordinate.
+-- @tparam[opt=0] integer w The relative width.
+-- @tparam[opt=0] integer h The relative height.
 -- @see geometry
--- @tparam[opt=0] number x The relative x coordinate.
--- @tparam[opt=0] number y The relative y coordinate.
--- @tparam[opt=0] number w The relative width.
--- @tparam[opt=0] number h The relative height.
+-- @see x
+-- @see y
+-- @see width
+-- @see height
+-- @see floating
 function client.object.relative_move(self, x, y, w, h)
     local geometry = self:geometry()
     geometry['x'] = geometry['x'] + (x or 0)
@@ -571,7 +577,7 @@ end
 --
 -- @deprecated awful.client.toggletag
 -- @tparam tag target The tag to toggle.
--- @tparam[opt] client c The client to toggle, otherwise the focused one is used.
+-- @tparam[opt=client.focus] client c The client to toggle, otherwise the focused one is used.
 -- @see client.toggle_tag
 -- @see tags
 function client.toggletag(target, c)
@@ -610,7 +616,7 @@ end
 
 --- Move a client to a screen. Default is next screen, cycling.
 -- @deprecated awful.client.movetoscreen
--- @tparam client c The client to move.
+-- @tparam[opt=client.focus] client c The client to move.
 -- @tparam screen s The screen, default to current + 1.
 -- @see screen
 -- @see client.move_to_screen
@@ -791,16 +797,27 @@ end
 -- Floating client are not handled by tiling layouts.
 -- @deprecated awful.client.floating.set
 -- @tparam client c A client.
--- @tparam boolean s True or false.
+-- @tparam boolean s `true` is the client is to become floating or `false`.
 function client.floating.set(c, s)
     gdebug.deprecate("Use c.floating = true instead of awful.client.floating.set", {deprecated_in=4})
     client.object.set_floating(c, s)
 end
 
 -- Set a client floating state, overriding auto-detection.
--- Floating client are not handled by tiling layouts.
+--
+-- Floating client are not handled by tiling layouts. They can be
+-- moved around and resized freely unless other restriction, such as `maximized`
+-- or the `size_hints` restrict their geometry.
+--
+-- An easy way to position floating clients is to use the `awful.placement`
+-- module.
+--
 -- @tparam client c A client.
--- @tparam boolan s True or false.
+-- @tparam boolean floating.
+-- @see is_immobilized_vertical
+-- @see is_immobilized_horizontal
+-- @see is_fixed
+-- @see size_hints
 function client.object.set_floating(c, s)
     c = c or capi.client.focus
     if c and client.property.get(c, "floating") ~= s then
@@ -838,7 +855,7 @@ capi.client.connect_signal("property::geometry", store_floating_geometry)
 
 --- Return if a client has a fixed size or not.
 -- This function is deprecated, use `c.is_fixed`
--- @tparam client c The client.
+-- @tparam[opt=client.focus] client c The client.
 -- @deprecated awful.client.isfixed
 -- @see is_fixed
 -- @see size_hints_honor
@@ -851,7 +868,7 @@ end
 --- Return if a client has a fixed size or not.
 --
 -- @property is_fixed
--- @tparam[opt=false] boolean is_fixed The fixed size state
+-- @tparam[opt=false] boolean is_fixed The fixed size state.
 -- @propemits false false
 -- @readonly
 -- @see size_hints
@@ -874,10 +891,10 @@ end
 --- Is the client immobilized horizontally?
 --
 -- Does the client have a fixed horizontal position and width, i.e. is it
--- fullscreen, maximized, or horizontally maximized?
+-- `fullscreen`, `maximized`, or `maximized_horizontal`?
 --
 -- @property immobilized_horizontal
--- @tparam[opt=false] boolean immobilized_horizontal The immobilized state
+-- @tparam[opt=false] boolean immobilized_horizontal The immobilized state.
 -- @readonly
 -- @see maximized
 -- @see maximized_horizontal
@@ -1274,7 +1291,7 @@ end
 -- @tparam number add Amount to increase/decrease the client's window factor by.
 --   Should be between `-current_window_factor` and something close to
 --   infinite. Normalisation then ensures that the sum of all factors is 1.
--- @tparam client c the client.
+-- @tparam[opt=client.focus] client c the client.
 -- @emits property::windowfact
 function client.incwfact(add, c)
     c = c or capi.client.focus
@@ -1448,7 +1465,7 @@ end
 -- @tparam function filter a function that returns true to indicate a positive match.
 -- @tparam integer start  what index to start iterating from.  Defaults to using the
 --   index of the currently focused client.
--- @tparam screen s which screen to use.  nil means all screens.
+-- @tparam[opt=nil] screen s which screen to use.  nil means all screens.
 --
 -- @staticfct awful.client.iterate
 -- @usage -- un-minimize all urxvt instances
@@ -1640,7 +1657,7 @@ end
 --
 -- @method activate
 -- @tparam table args
--- @tparam[opt=other] string args.context Why was this activate called?
+-- @tparam[opt="other"] string args.context Why was this activate called?
 -- @tparam[opt=true] boolean args.raise Raise the client to the top of its layer
 --  and unminimize it (if needed).
 -- @tparam[opt=false] boolean args.force Force the activation even for unfocusable
@@ -1649,6 +1666,8 @@ end
 -- @tparam[opt=false] boolean args.switch_to_tag
 -- @tparam[opt=false] boolean args.action Once activated, perform an action.
 -- @tparam[opt=false] boolean args.toggle_minimization
+-- @request client activate args.context granted Will use the context defined in
+--  `args.context`.
 -- @see awful.permissions.add_activate_filter
 -- @see awful.permissions.activate
 -- @see request::activate
diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua
index 5a9890e70..92c9ac462 100644
--- a/lib/awful/mouse/init.lua
+++ b/lib/awful/mouse/init.lua
@@ -77,11 +77,11 @@ mouse.wibox = {}
 
 --- The resize cursor name.
 -- @beautiful beautiful.cursor_mouse_resize
--- @tparam[opt=cross] string cursor
+-- @tparam[opt="cross"] string cursor
 
 --- The move cursor name.
 -- @beautiful beautiful.cursor_mouse_move
--- @tparam[opt=fleur] string cursor
+-- @tparam[opt="fleur"] string cursor
 
 --- Get the client object under the pointer.
 -- @deprecated awful.mouse.client_under_pointer
diff --git a/lib/awful/permissions/init.lua b/lib/awful/permissions/init.lua
index 64673d3f7..93be8eb95 100644
--- a/lib/awful/permissions/init.lua
+++ b/lib/awful/permissions/init.lua
@@ -38,18 +38,18 @@ local permissions = {
 -- @beautiful beautiful.maximized_hide_border
 -- @tparam[opt=false] boolean maximized_hide_border
 
---- The list of all registered generic request::activate (focus stealing)
+--- The list of all registered generic `request::activate` (focus stealing)
 -- filters. If a filter is added to only one context, it will be in
 -- `permissions.contextual_activate_filters`["context_name"].
--- @table[opt={}] generic_activate_filters
+-- @table[opt={}] awful.permissions.generic_activate_filters
 -- @see permissions.activate
 -- @see permissions.add_activate_filter
 -- @see permissions.remove_activate_filter
 
---- The list of all registered contextual request::activate (focus stealing)
+--- The list of all registered contextual `request::activate` (focus stealing)
 -- filters. If a filter is added to only one context, it will be in
 -- `permissions.generic_activate_filters`.
--- @table[opt={}] contextual_activate_filters
+-- @table[opt={}] awful.permissions.contextual_activate_filters
 -- @see permissions.activate
 -- @see permissions.add_activate_filter
 -- @see permissions.remove_activate_filter
@@ -288,8 +288,9 @@ end
 --
 -- @signalhandler awful.permissions.tag
 -- @tparam client c A client to tag
--- @tparam[opt] tag|boolean t A tag to use. If true, then the client is made sticky.
--- @tparam[opt={}] table hints Extra information
+-- @tparam[opt] tag|boolean t A tag to use. If `true`, then the client is made `sticky`.
+-- @tparam[opt={}] table hints Extra information.
+-- @tparam[opt=nil] nil|string hints.reason Why the tag is being changed.
 function permissions.tag(c, t, hints) --luacheck: no unused
     -- There is nothing to do
     if not t and #get_valid_tags(c, c.screen) > 0 then return end
@@ -338,6 +339,10 @@ local context_mapper = {
 -- @tparam client c The client
 -- @tparam string context The context
 -- @tparam[opt={}] table hints The hints to pass to the handler
+-- @tparam[opt=true] boolean hints.store_geometry Create a memento of the
+--  previous geometry in case it has to be restored.
+-- @tparam[opt=true] boolean hints.honor_workarea Avoid overlapping the `wibar`s
+--  or other desktop decoration when applying the geometry.
 function permissions.geometry(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -407,6 +412,10 @@ end
 -- @tparam wibox w The wibox.
 -- @tparam string context The context
 -- @tparam[opt={}] table hints The hints to pass to the handler
+-- @tparam[opt] integer hints.x The horizontal position.
+-- @tparam[opt] integer hints.y The vertical position.
+-- @tparam[opt] integer hints.width The wibox width.
+-- @tparam[opt] integer hints.height The wibox height.
 function permissions.wibox_geometry(w, context, hints)
     if not pcommon.check(w, "wibox", "geometry", context) then return end
 
@@ -416,14 +425,16 @@ end
 --- Merge the 2 requests sent by clients wanting to be maximized.
 --
 -- The X clients set 2 flags (atoms) when they want to be maximized. This caused
--- 2 request::geometry to be sent. This code gives some time for them to arrive
+-- 2 `request::geometry` to be sent. This code gives some time for them to arrive
 -- and send a new `request::geometry` (through the property change) with the
 -- combined state.
 --
 -- @signalhandler awful.permissions.merge_maximization
 -- @tparam client c The client
 -- @tparam string context The context
--- @tparam[opt={}] table hints The hints to pass to the handler
+-- @tparam[opt={}] table hints The hints to pass to the handler.
+-- @tparam[opt=false] boolean hints.toggle Toggle the maximization state rather
+--  than set it to `true`.
 function permissions.merge_maximization(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -506,7 +517,11 @@ end
 -- @signalhandler awful.permissions.client_geometry_requests
 -- @tparam client c The client
 -- @tparam string context The context
--- @tparam[opt={}] table hints The hints to pass to the handler
+-- @tparam[opt={}] table hints The hints to pass to the handler.
+-- @tparam[opt] integer hints.x The horizontal position.
+-- @tparam[opt] integer hints.y The vertical position.
+-- @tparam[opt] integer hints.width The client width.
+-- @tparam[opt] integer hints.height The client height.
 function permissions.client_geometry_requests(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -539,13 +554,15 @@ end, "mouse_enter")
 --
 -- To replace this handler with your own, use:
 --
---    client.disconnect_signal("request::border", awful.ewmh.update_border)
+--    client.disconnect_signal("request::border", awful.permisions.update_border)
 --
 -- The default implementation chooses from dozens beautiful theme variables
 -- depending if the client is tiled, floating, maximized and then from its state
 -- (urgent, new, active, normal)
 --
 -- @signalhandler awful.permissions.update_border
+-- @tparam client c The client.
+-- @tparam string context Why is the border changed.
 -- @usebeautiful beautiful.border_color_marked
 -- @usebeautiful beautiful.border_color_active
 -- @usebeautiful beautiful.border_color_normal
@@ -604,6 +621,8 @@ end, "mouse_enter")
 -- @usebeautiful beautiful.opacity_normal
 -- @usebeautiful beautiful.opacity_new
 -- @usebeautiful beautiful.opacity_urgent
+-- @see client.border_width
+-- @see client.border_color
 
 function permissions.update_border(c, context)
     if not pcommon.check(c, "client", "border", context) then return end
@@ -729,6 +748,11 @@ local activate_context_map = {
 -- * history    : *autofocus.check_focus*
 --
 -- @signalhandler awful.permissions.autoactivate
+-- @tparam client c The client.
+-- @tparam string context Why is the client auto-activated.
+-- @tparam[opt={}] table hints Extra arguments.
+-- @see activate
+-- @see client:activate
 function permissions.autoactivate(c, context, args)
     if not pcommon.check(c, "client", "autoactivate", context) then return end
 
diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua
index 8757634f1..cde263434 100644
--- a/lib/awful/popup.lua
+++ b/lib/awful/popup.lua
@@ -338,9 +338,9 @@ end
 --
 -- @DOC_awful_popup_position3_EXAMPLE@
 -- @property offset
--- @tparam table|number offset An integer value or a `{x=, y=}` table.
--- @tparam[opt=offset] number offset.x The horizontal distance.
--- @tparam[opt=offset] number offset.y The vertical distance.
+-- @tparam table|integer offset An integer value or a `{x=, y=}` table.
+-- @tparam[opt=offset] integer offset.x The horizontal distance.
+-- @tparam[opt=offset] integer offset.y The vertical distance.
 -- @propemits true false
 
 function popup:set_offset(offset)
@@ -370,7 +370,7 @@ end
 -- (or false to disable placement)
 --
 -- @property placement
--- @tparam[opt=next_to] function|string|boolean placement The placement function or name
+-- @tparam[opt=awful.placement.next_to] function|string|boolean placement The placement function or name
 -- @propemits true false
 -- @see awful.placement
 
@@ -496,4 +496,6 @@ end
 
 --@DOC_wibox_COMMON@
 
+--@DOC_object_COMMON@
+
 return setmetatable(module, {__call = create_popup})
diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 39fda931b..d5ceeee5f 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -203,11 +203,10 @@ function tag.object.get_index(query_tag)
     end
 end
 
---- Move a tag to an absolute position in the screen[]:tags() table.
+--- Move a tag to an absolute position in the `screen[]:tags()` table.
 -- @deprecated awful.tag.move
 -- @tparam integer new_index Integer absolute position in the table to insert.
--- @tparam tag target_tag The tag that should be moved. If null, the currently
--- selected tag is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag target_tag The tag that should be moved.
 -- @see index
 function tag.move(new_index, target_tag)
     gdebug.deprecate("Use t.index = new_index instead of awful.tag.move", {deprecated_in=4})
@@ -308,7 +307,7 @@ end
 --
 -- @staticfct awful.tag.new
 -- @tparam table names The tag name, in a table
--- @tparam[opt=1] screen|number screen The tag screen (defaults to screen 1).
+-- @tparam[opt=1] screen|number screen The tag screen.
 -- @tparam table layout The layout or layout table to set for this tags by default.
 -- @treturn table A table with all created tags.
 function tag.new(names, screen, layout)
@@ -334,8 +333,8 @@ end
 
 --- Find a suitable fallback tag.
 -- @staticfct awful.tag.find_fallback
--- @tparam screen screen The screen to look for a tag on. [awful.screen.focused()]
--- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. [selectedlist(scr)]
+-- @tparam[opt=awful.screen.focused()] screen screen The screen to look for a tag on.
+-- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable.
 function tag.find_fallback(screen, invalids)
     local scr = screen or ascreen.focused()
     local t = invalids or scr.selected_tags
@@ -465,8 +464,8 @@ end
 --- Delete a tag.
 -- @deprecated awful.tag.delete
 -- @see tag.delete
--- @tparam tag target_tag Optional tag object to delete. [selected()]
--- @tparam tag|nil fallback_tag Tag to assign stickied tags to. [~selected()]
+-- @tparam[opt=mouse.screen.selected_tag] tag target_tag Optional tag object to delete.
+-- @tparam[opt] tag|nil fallback_tag Tag to assign stickied tags to.
 -- @treturn boolean Returns true if the tag is successfully deleted, nil otherwise.
 -- If there are no clients exclusively on this tag then delete it. Any
 -- stickied clients are assigned to the optional 'fallback_tag'.
@@ -694,7 +693,7 @@ end
 --- The default master width factor
 --
 -- @beautiful beautiful.master_width_factor
--- @tparam number master_width_factor (default: 0.5)
+-- @tparam[opt=0.5] number master_width_factor
 -- @see master_width_factor
 -- @see gap
 
@@ -741,7 +740,7 @@ end
 -- @see master_fill_policy
 -- @see master_width_factor
 -- @tparam number mwfact Master width factor.
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.setmwfact(mwfact, t)
     gdebug.deprecate("Use t.master_width_factor = mwfact instead of awful.tag.setmwfact", {deprecated_in=4})
 
@@ -752,7 +751,7 @@ end
 -- @staticfct awful.tag.incmwfact
 -- @see master_width_factor
 -- @tparam number add Value to add to master width factor.
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.incmwfact(add, t)
     t = t or t or ascreen.focused().selected_tag
     tag.object.set_master_width_factor(t, tag.object.get_master_width_factor(t) + add)
@@ -797,6 +796,9 @@ end
 -- @tfield table awful.tag.layouts
 -- @tparam[opt={}] table awful.tag.layouts
 -- @see request::layouts
+-- @see awful.layout.append_default_layouts
+-- @see awful.layout.append_default_layout
+-- @see awful.layout.remove_default_layout
 
 --- The tag client layout.
 --
@@ -1055,7 +1057,7 @@ end
 -- @deprecated awful.tag.setvolatile
 -- @see volatile
 -- @tparam boolean volatile If the tag must be deleted when the last client is untagged
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.setvolatile(volatile, t)
     gdebug.deprecate("Use t.volatile = volatile instead of awful.tag.setvolatile", {deprecated_in=4})
 
@@ -1065,7 +1067,7 @@ end
 --- Get if the tag must be deleted when the last client closes
 -- @deprecated awful.tag.getvolatile
 -- @see volatile
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 -- @treturn boolean If the tag will be deleted when the last client is untagged
 function tag.getvolatile(t)
     gdebug.deprecate("Use t.volatile instead of awful.tag.getvolatile", {deprecated_in=4})
@@ -1076,7 +1078,7 @@ end
 --- The default gap.
 --
 -- @beautiful beautiful.useless_gap
--- @tparam tag number (default: 0)
+-- @tparam[opt=0] number useless_gap
 -- @see gap
 -- @see gap_single_client
 
@@ -1115,7 +1117,7 @@ end
 -- @deprecated awful.tag.setgap
 -- @see gap
 -- @tparam number|nil useless_gap The spacing between clients
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.setgap(useless_gap, t)
     gdebug.deprecate("Use t.gap = useless_gap instead of awful.tag.setgap", {deprecated_in=4})
 
@@ -1124,9 +1126,10 @@ end
 
 --- Increase the spacing between clients
 -- @staticfct awful.tag.incgap
--- @see gap
 -- @tparam number add Value to add to the spacing between clients
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
+-- @see gap
+-- @see beautiful.useless_gap
 function tag.incgap(add, t)
     t = t or t or ascreen.focused().selected_tag
     tag.object.set_gap(t, tag.object.get_gap(t) + add)
@@ -1135,7 +1138,7 @@ end
 --- Enable gaps for a single client.
 --
 -- @beautiful beautiful.gap_single_client
--- @tparam boolean gap_single_client (default: true)
+-- @tparam[opt=true] boolean gap_single_client
 -- @see gap
 -- @see gap_single_client
 
@@ -1201,7 +1204,7 @@ end
 --   `master_width_factor`
 --
 -- @beautiful beautiful.master_fill_policy
--- @tparam string master_fill_policy (default: "expand")
+-- @tparam[opt="expand"] string master_fill_policy
 -- @see master_fill_policy
 
 --- Set size fill policy for the master client(s).
@@ -1227,7 +1230,7 @@ end
 -- redistributed on both side.
 --
 -- @property master_fill_policy
--- @tparam string master_fill_policy "expand" or "master_width_factor"
+-- @tparam string master_fill_policy "expand" or "master\_width\_factor"
 -- @propemits false false
 -- @see awful.tag.togglemfpol
 
@@ -1252,10 +1255,10 @@ function tag.setmfpol(policy, t)
 end
 
 --- Toggle size fill policy for the master client(s)
--- between "expand" and "master_width_factor".
+-- between "expand" and `master_width_factor`.
 -- @staticfct awful.tag.togglemfpol
 -- @see master_fill_policy
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.togglemfpol(t)
     t = t or ascreen.focused().selected_tag
 
@@ -1285,7 +1288,7 @@ end
 --- The default number of master windows.
 --
 -- @beautiful beautiful.master_count
--- @tparam integer master_count (default: 1)
+-- @tparam[opt=1] integer master_count
 -- @see master_count
 
 --- Set the number of master windows.
@@ -1337,7 +1340,7 @@ end
 -- @staticfct awful.tag.incnmaster
 -- @see master_count
 -- @tparam number add Value to add to number of master windows.
--- @tparam[opt] tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 -- @tparam[opt=false] boolean sensible Limit nmaster based on the number of
 --   visible tiled windows?
 function tag.incnmaster(add, t, sensible)
@@ -1400,7 +1403,7 @@ end
 --- The default number of columns.
 --
 -- @beautiful beautiful.column_count
--- @tparam integer column_count (default: 1)
+-- @tparam[opt=1] integer column_count
 -- @see column_count
 
 --- Set the number of columns.
@@ -1430,7 +1433,7 @@ end
 -- @deprecated awful.tag.setncol
 -- @see column_count
 -- @tparam integer ncol The number of column.
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.setncol(ncol, t)
     gdebug.deprecate("Use t.column_count = new_index instead of awful.tag.setncol", {deprecated_in=4})
 
@@ -1455,7 +1458,7 @@ end
 --- Increase number of column windows.
 -- @staticfct awful.tag.incncol
 -- @tparam number add Value to add to number of column windows.
--- @tparam[opt] tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 -- @tparam[opt=false] boolean sensible Limit column_count based on the number
 --   of visible tiled windows?
 function tag.incncol(add, t, sensible)
@@ -1734,9 +1737,9 @@ end
 -- future. When a tag is detached from the screen, its signal is removed.
 --
 -- @staticfct awful.tag.attached_connect_signal
--- @tparam screen screen The screen concerned, or all if nil.
--- @tparam[opt] string signal The signal name.
--- @tparam[opt] function Callback
+-- @tparam screen|nil screen The screen concerned, or all if `nil`.
+-- @tparam string signal The signal name.
+-- @tparam function Callback
 function tag.attached_connect_signal(screen, ...)
     if screen then
         attached_connect_signal_screen(screen, ...)
diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua
index 9952a743a..5345851f6 100644
--- a/lib/awful/titlebar.lua
+++ b/lib/awful/titlebar.lua
@@ -1,6 +1,8 @@
 ---------------------------------------------------------------------------
 --- Titlebars for awful.
---**Create a titlebar:**
+--
+-- Create a titlebar
+-- =================
 --
 -- This example reproduces what the default `rc.lua` does. It shows how to
 -- handle the titlebars on a lower level.
diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua
index 2fffe2bbf..9edc97e23 100644
--- a/lib/awful/widget/layoutlist.lua
+++ b/lib/awful/widget/layoutlist.lua
@@ -238,7 +238,7 @@ local layoutlist = {}
 
 --- The selected layout alignment.
 -- @beautiful beautiful.layoutlist_align
--- @tparam[opt=left] string align *left*, *right* or *center*
+-- @tparam[opt="left"] string align *left*, *right* or *center*
 
 --- The selected layout title font.
 -- @beautiful beautiful.layoutlist_font_selected
diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua
index de24bac4d..3b8f895f5 100644
--- a/lib/awful/widget/taglist.lua
+++ b/lib/awful/widget/taglist.lua
@@ -65,22 +65,22 @@ taglist.filter, taglist.source = {}, {}
 
 --- The tag list main foreground (text) color.
 -- @beautiful beautiful.taglist_fg_focus
--- @param[opt=fg_focus] color
+-- @param[opt=beautiful.fg_focus] color
 -- @see gears.color
 
 --- The tag list main background color.
 -- @beautiful beautiful.taglist_bg_focus
--- @param[opt=bg_focus] color
+-- @param[opt=beautiful.bg_focus] color
 -- @see gears.color
 
 --- The tag list urgent elements foreground (text) color.
 -- @beautiful beautiful.taglist_fg_urgent
--- @param[opt=fg_urgent] color
+-- @param[opt=beautiful.fg_urgent] color
 -- @see gears.color
 
 --- The tag list urgent elements background color.
 -- @beautiful beautiful.taglist_bg_urgent
--- @param[opt=bg_urgent] color
+-- @param[opt=beautiful.bg_urgent] color
 -- @see gears.color
 
 --- The tag list occupied elements background color.
diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua
index c563f830a..7fbff70c3 100644
--- a/lib/awful/widget/tasklist.lua
+++ b/lib/awful/widget/tasklist.lua
@@ -248,7 +248,7 @@ local instances
 -- @DOC_wibox_awidget_tasklist_style_align_EXAMPLE@
 --
 -- @beautiful beautiful.tasklist_align
--- @tparam[opt=left] string align *left*, *right* or *center*
+-- @tparam[opt="left"] string align *left*, *right* or *center*
 
 --- The tasklist font.
 --
@@ -823,7 +823,7 @@ end
 -- @tparam[opt='⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical
 -- @tparam[opt=false] boolean args.style.disable_task_name
 -- @tparam[opt=nil] string args.style.font
--- @tparam[opt=left] string args.style.align *left*, *right* or *center*
+-- @tparam[opt="left"] string args.style.align *left*, *right* or *center*
 -- @tparam[opt=nil] string args.style.font_focus
 -- @tparam[opt=nil] string args.style.font_minimized
 -- @tparam[opt=nil] string args.style.font_urgent
diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua
index 38c05796c..a0c2d2b8f 100644
--- a/lib/gears/surface.lua
+++ b/lib/gears/surface.lua
@@ -169,8 +169,8 @@ end
 -- @tparam number width The surface width
 -- @tparam number height The surface height
 -- @param shape A `gears.shape` compatible function
--- @param[opt=white] shape_color The shape color or pattern
--- @param[opt=transparent] bg_color The surface background color
+-- @param[opt="#000000"] shape_color The shape color or pattern
+-- @param[opt="#00000000"] bg_color The surface background color
 -- @treturn cairo.surface the new surface
 -- @staticfct load_from_shape
 function surface.load_from_shape(width, height, shape, shape_color, bg_color, ...)
diff --git a/lib/naughty/core.lua b/lib/naughty/core.lua
index bedb3ede3..98106ef33 100644
--- a/lib/naughty/core.lua
+++ b/lib/naughty/core.lua
@@ -24,20 +24,23 @@ local naughty = {}
 
 --- Naughty configuration - a table containing common popup settings.
 --
+-- The callback has the follwing format:
+--
+--     naughty.config.notify_callback = function(args)
+--         args.text = 'prefix: ' .. args.text
+--         return args
+--     end
+--
 -- @table naughty.config
--- @tfield[opt=apply_dpi(4)] int padding Space between popups and edge of the
+-- @tfield[opt=beautiful.xresources.apply_dpi(4)] integer padding Space between popups and edge of the
 --   workarea.
--- @tfield[opt=apply_dpi(1)] int spacing Spacing between popups.
+-- @tfield[opt=beautiful.xresources.apply_dpi(1)] integer spacing Spacing between popups.
 -- @tfield[opt={"/usr/share/pixmaps/"}] table icon_dirs List of directories
 --   that will be checked by `getIcon()`.
 -- @tfield[opt={ "png", "gif" }] table icon_formats List of formats that will be
 --   checked by `getIcon()`.
 -- @tfield[opt] function notify_callback Callback used to modify or reject
 -- notifications, e.g.
---     naughty.config.notify_callback = function(args)
---         args.text = 'prefix: ' .. args.text
---         return args
---     end
 --   To reject a notification return `nil` from the callback.
 --   If the notification is a freedesktop notification received via DBUS, you can
 --   access the freedesktop hints via `args.freedesktop_hints` if any where
@@ -45,7 +48,7 @@ local naughty = {}
 --
 -- @tfield table presets Notification presets.  See `config.presets`.
 --
--- @tfield table defaults Default values for the params to `notify()`.  These can
+-- @tfield table defaults Default values for the params to `naughty.notification{}`.  These can
 --   optionally be overridden by specifying a preset.  See `config.defaults`.
 
 -- It's done that way to preserve compatibility with Awesome 4.0 while allowing
@@ -55,46 +58,61 @@ gtable.crush(naughty, require("naughty.constants"))
 
 --- Notification presets for `naughty.notify`.
 -- This holds presets for different purposes.  A preset is a table of any
--- parameters for `notify()`, overriding the default values
+-- parameters for `naughty.notification{}`, overriding the default values
 -- (`naughty.config.defaults`).
 --
--- You have to pass a reference of a preset in your `notify()` as the `preset`
+-- You have to pass a reference of a preset in your `naughty.notification{}` as the `preset`
 -- argument.
 --
 -- The presets `"low"`, `"normal"` and `"critical"` are used for notifications
 -- over DBUS.
 --
--- @table config.presets
+-- @table naughty.config.presets
 -- @tfield table low The preset for notifications with low urgency level.
--- @tfield[opt=5] int low.timeout
--- @tfield[opt=empty] table normal The default preset for every notification without a
+-- @tfield[opt=5] integer low.timeout
+-- @tfield[opt={}] table normal The default preset for every notification without a
 --   preset that will also be used for normal urgency level.
+-- @tfield table ok
+-- @tfield[opt="#00bb00"] string ok.bg
+-- @tfield[opt="#ffffff"] string ok.fg
+-- @tfield[opt=5] integer ok.timeout
 -- @tfield table critical The preset for notifications with a critical urgency
 --   level.
 -- @tfield[opt="#ff0000"] string critical.bg
 -- @tfield[opt="#ffffff"] string critical.fg
--- @tfield[opt=0] string critical.timeout
+-- @tfield[opt=0] integer critical.timeout
+-- @tfield table info
+-- @tfield[opt="#0000ff"] string info.bg
+-- @tfield[opt="#ffffff"] string info.fg
+-- @tfield[opt=5] integer info.timeout
+-- @tfield table warn
+-- @tfield[opt="#ffaa00"] string warn.bg
+-- @tfield[opt="#00000"] string warn.fg
+-- @tfield[opt=5] integer warn.timeout
 
 --- Defaults for `naughty.notify`.
 --
--- @table config.defaults
--- @tfield[opt=5] int timeout
+-- @table naughty.config.defaults
+-- @tfield[opt=5] integer timeout
 -- @tfield[opt=""] string text
--- @tfield[opt] int screen Defaults to `awful.screen.focused`.
+-- @tfield[opt=awful.screen.focused()] integer screen
 -- @tfield[opt=true] boolean ontop
--- @tfield[opt=apply_dpi(5)] int margin
--- @tfield[opt=apply_dpi(1)] int border_width
+-- @tfield[opt=beautiful.xresources.apply_dpi(5)] integer margin
+-- @tfield[opt=beautiful.xresources.apply_dpi(1)] integer border_width
 -- @tfield[opt="top_right"] string position
 
 --- The reason why a notification is to be closed.
+--
 -- See [the specification](https://developer.gnome.org/notification-spec/#signals)
 -- for more details.
--- @tfield number silent
--- @tfield number expired
--- @tfield number dismissed_by_user
--- @tfield number dismissed_by_command
--- @tfield number undefined
--- @table notification_closed_reason
+--
+-- @table naughty.notification_closed_reason
+-- @tfield[opt=-2] number too_many_on_screen
+-- @tfield[opt=-1] number silent
+-- @tfield[opt=1] number expired
+-- @tfield[opt=2] number dismissed_by_user
+-- @tfield[opt=3] number dismissed_by_command
+-- @tfield[opt=4] number undefined
 
 --- The global suspension state.
 --
@@ -177,16 +195,6 @@ local properties = {
 
 --TODO v5 Deprecate the public `naughty.notifications` (to make it private)
 
---- Index of notifications per screen and position.
--- See config table for valid 'position' values.
--- Each element is a table consisting of:
---
--- @field box Wibox object containing the popup
--- @field height Popup height
--- @field width Popup width
--- @field die Function to be executed on timeout
--- @field id Unique notification id based on a counter
--- @table notifications
 naughty.notifications = { suspended = { }, _expired = {{}} }
 
 naughty._active = {}
@@ -749,7 +757,7 @@ end
 -- @int[opt=5] args.timeout Time in seconds after which popup expires.
 --   Set 0 for no timeout.
 -- @int[opt] args.hover_timeout Delay in seconds after which hovered popup disappears.
--- @tparam[opt=focused] integer|screen args.screen Target screen for the notification.
+-- @tparam[opt=awful.screen.focused()] integer|screen args.screen Target screen for the notification.
 -- @string[opt="top_right"] args.position Corner of the workarea displaying the popups.
 --   Values: `"top_right"`, `"top_left"`, `"bottom_left"`,
 --   `"bottom_right"`, `"top_middle"`, `"bottom_middle"`, `"middle"`.
@@ -766,17 +774,17 @@ end
 -- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape.
 -- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity.
 -- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin.
--- @tparam[opt] func args.run Function to run on left click.  The notification
+-- @tparam[opt] function args.run Function to run on left click.  The notification
 --   object will be passed to it as an argument.
 --   You need to call e.g.
 --   `notification.die(naughty.notification_closed_reason.dismissedByUser)` from
 --   there to dismiss the notification yourself.
--- @tparam[opt] func args.destroy Function to run when notification is destroyed.
+-- @tparam[opt] function args.destroy Function to run when notification is destroyed.
 -- @tparam[opt] table args.preset Table with any of the above parameters.
 --   Note: Any parameters specified directly in args will override ones defined
 --   in the preset.
--- @tparam[opt] int args.replaces_id Replace the notification with the given ID.
--- @tparam[opt] func args.callback Function that will be called with all arguments.
+-- @tparam[opt] integer args.replaces_id Replace the notification with the given ID.
+-- @tparam[opt] function args.callback Function that will be called with all arguments.
 --   The notification will only be displayed if the function returns true.
 --   Note: this function is only relevant to notifications sent via dbus.
 -- @tparam[opt] table args.actions A list of `naughty.action`s.
diff --git a/tests/examples/sequences/tag/clear.lua b/tests/examples/sequences/tag/clear.lua
index 586f5da6b..2161176ad 100644
--- a/tests/examples/sequences/tag/clear.lua
+++ b/tests/examples/sequences/tag/clear.lua
@@ -43,7 +43,7 @@ module.display_tags() --DOC_HIDE
 module.add_event("Call `:clear()` on the first tag.", function() --DOC_HIDE
     -- Call :clear() on the first tag.
     screen[1].tags[1]:clear{}
-end)
+end) --DOC_HIDE
 
 module.display_tags() --DOC_HIDE