diff --git a/lib/awful/client.lua b/lib/awful/client.lua
index ae74a9f46..246b7f245 100644
--- a/lib/awful/client.lua
+++ b/lib/awful/client.lua
@@ -74,7 +74,7 @@ client.focus = require("awful.client.focus")
 
 --- When applying the placement, honor the screen padding.
 -- @clientruleproperty honor_padding
--- @param[opt=true] boolean
+-- @tparam[opt=true] boolean honor_padding
 -- @see awful.placement
 
 --- When applying the placement, honor the screen work area.
@@ -82,7 +82,7 @@ client.focus = require("awful.client.focus")
 -- The workarea is the part of the screen that excludes the bars and docks.
 --
 -- @clientruleproperty honor_workarea
--- @param[opt=true] boolean
+-- @tparam[opt=true] boolean honor_workarea
 -- @see awful.placement
 
 --- The client default tag.
@@ -90,7 +90,7 @@ client.focus = require("awful.client.focus")
 -- @DOC_sequences_client_rules_tags_EXAMPLE@
 --
 -- @clientruleproperty tag
--- @param tag
+-- @tparam tag tag
 -- @see tag
 -- @see new_tag
 -- @see tags
@@ -102,7 +102,7 @@ client.focus = require("awful.client.focus")
 -- issues.
 --
 -- @clientruleproperty tags
--- @param[opt={tag}] table
+-- @tparam[opt={tag}] table tags
 -- @see tag
 -- @see new_tag
 -- @see tags
@@ -130,7 +130,7 @@ client.focus = require("awful.client.focus")
 -- @DOC_sequences_client_rules_switch_to_tags_EXAMPLE@
 --
 -- @clientruleproperty switch_to_tags
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean switch_to_tags
 -- @see tag.selected
 
 --- Define if the client should grab focus by default.
@@ -138,11 +138,11 @@ client.focus = require("awful.client.focus")
 -- The `request::activate` context for this call is `rules`.
 --
 -- @clientruleproperty focus
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean focus
 
 --- Should this client have a titlebar by default.
 -- @clientruleproperty titlebars_enabled
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean titlebars_enabled
 -- @see awful.titlebar
 
 --- A function to call when this client is ready.
@@ -177,6 +177,8 @@ end
 --   tag as arguments.
 -- @request client activate client.jumpto granted When a client is activated
 --  because `c:jump_to()` is called.
+-- @see activate
+-- @see active
 function client.object.jump_to(self, merge)
     local s = get_screen(screen.focused())
     -- focus the screen
@@ -251,7 +253,7 @@ end
 -- @tparam int i The index.  Use 1 to get the next, -1 to get the previous.
 -- @client[opt] sel The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
--- @return A client, or nil if no client is available.
+-- @treturn[opt] client|nil A client, or nil if no client is available.
 --
 -- @usage -- focus the next window in the index
 -- awful.client.next(1)
@@ -282,10 +284,16 @@ function client.next(i, sel, stacked)
 end
 
 --- Swap a client with another client in the given direction.
+--
 -- @staticfct awful.client.swap.bydirection
 -- @tparam string dir The direction, can be either "up", "down", "left" or "right".
 -- @client[opt=focused] c The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
+-- @see swap
+-- @see swapped
+-- @see awful.client.swap.global_bydirection
+-- @see awful.client.swap.byidx
+-- @see awful.client.cycle
 function client.swap.bydirection(dir, c, stacked)
     local sel = c or capi.client.focus
     if sel then
@@ -304,12 +312,18 @@ function client.swap.bydirection(dir, c, stacked)
 end
 
 --- Swap a client with another client in the given direction.
+--
 -- Swaps across screens.
 -- @staticfct awful.client.swap.global_bydirection
--- @param dir The direction, can be either "up", "down", "left" or "right".
+-- @tparam string dir The direction, can be either "up", "down", "left" or "right".
 -- @client[opt] 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
+-- @see swapped
+-- @see awful.client.swap.bydirection
+-- @see awful.client.swap.byidx
+-- @see awful.client.cycle
 function client.swap.global_bydirection(dir, sel)
     sel = sel or capi.client.focus
     local scr = get_screen(sel and sel.screen or screen.focused())
@@ -340,9 +354,15 @@ function client.swap.global_bydirection(dir, sel)
 end
 
 --- Swap a client by its relative index.
+--
 -- @staticfct awful.client.swap.byidx
--- @param i The index.
+-- @tparam integer i The index.
 -- @client[opt] 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
 function client.swap.byidx(i, c)
     local sel = c or capi.client.focus
     local target = client.next(i, sel)
@@ -351,12 +371,20 @@ function client.swap.byidx(i, c)
     end
 end
 
---- Cycle clients.
+--- Cycle through the clients to change the focus.
+--
+-- This will swap the client from one position to the next
+-- in the layout.
 --
 -- @staticfct awful.client.cycle
--- @param clockwise True to cycle clients clockwise.
--- @param[opt] s The screen where to cycle clients.
+-- @tparam boolean clockwise True to cycle clients clockwise.
+-- @tparam[opt] screen s The screen where to cycle clients.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
+-- @see swap
+-- @see swapped
+-- @see awful.client.swap.bydirection
+-- @see awful.client.swap.global_bydirection
+-- @see awful.client.swap.byidx
 function client.cycle(clockwise, s, stacked)
     s = s or screen.focused()
     local cls = client.visible(s, stacked)
@@ -402,7 +430,7 @@ end
 --
 -- @legacylayout awful.client.getmaster
 -- @screen_or_idx[opt=awful.screen.focused()] s The screen.
--- @return The master window.
+-- @treturn client The master client.
 function client.getmaster(s)
     s = s or screen.focused()
     return client.visible(s)[1]
@@ -431,10 +459,10 @@ end
 
 --- Move/resize a client relative to current coordinates.
 -- @deprecated awful.client.moveresize
--- @param x The relative x coordinate.
--- @param y The relative y coordinate.
--- @param w The relative width.
--- @param h The relative height.
+-- @tparam integer x The relative x coordinate.
+-- @tparam integer y The relative y coordinate.
+-- @tparam integer w The relative width.
+-- @tparam integer h The relative height.
 -- @client[opt] c The client, otherwise focused one is used.
 -- @see client.relative_move
 function client.moveresize(x, y, w, h, c)
@@ -460,7 +488,7 @@ end
 
 --- Move a client to a tag.
 -- @deprecated awful.client.movetotag
--- @param target The tag to move the client to.
+-- @tparam tag target The tag to move the client to.
 -- @client[opt] c The client to move, otherwise the focused one is used.
 -- @see client.move_to_tag
 function client.movetotag(target, c)
@@ -469,10 +497,12 @@ function client.movetotag(target, c)
 end
 
 --- Move a client to a tag.
+--
 -- @method move_to_tag
 -- @tparam tag target The tag to move the client to.
 -- @request client activate client.movetotag granted When a client could be
 --  activated because `c:move_to_tag()` was called.
+-- @see tags
 function client.object.move_to_tag(self, target)
     local s = target.screen
     if self and s then
@@ -486,18 +516,22 @@ function client.object.move_to_tag(self, target)
 end
 
 --- Toggle a tag on a client.
+--
 -- @deprecated awful.client.toggletag
--- @param target The tag to toggle.
+-- @tparam tag target The tag to toggle.
 -- @client[opt] c The client to toggle, otherwise the focused one is used.
 -- @see client.toggle_tag
+-- @see tags
 function client.toggletag(target, c)
     gdebug.deprecate("Use c:toggle_tag(target) instead of awful.client.toggletag", {deprecated_in=4})
     client.object.toggle_tag(c or capi.client.focus, target)
 end
 
 --- Toggle a tag on a client.
+--
 -- @method toggle_tag
 -- @tparam tag target The tag to move the client to.
+-- @see tags
 function client.object.toggle_tag(self, target)
     -- Check that tag and client screen are identical
     if self and get_screen(self.screen) == get_screen(target.screen) then
@@ -523,7 +557,7 @@ end
 --- Move a client to a screen. Default is next screen, cycling.
 -- @deprecated awful.client.movetoscreen
 -- @client c The client to move.
--- @param s The screen, default to current + 1.
+-- @tparam screen s The screen, default to current + 1.
 -- @see screen
 -- @see client.move_to_screen
 function client.movetoscreen(c, s)
@@ -590,14 +624,11 @@ end
 
 --- If a client is marked or not.
 --
--- **Signal:**
---
--- * *marked* (for legacy reasons, use `property::marked`)
--- * *unmarked* (for legacy reasons, use `property::marked`)
--- * *property::marked*
---
 -- @property marked
--- @param boolean
+-- @tparam boolean marked
+-- @emits marked (for legacy reasons, use `property::marked`)
+-- @emits unmarker (for legacy reasons, use `property::marked`)
+-- @emits property::marked
 
 --- The border color when the client is focused.
 --
@@ -664,7 +695,7 @@ end
 
 --- Return the marked clients and empty the marked table.
 -- @deprecated awful.client.getmarked
--- @return A table with all marked clients.
+-- @treturn table A table with all marked clients.
 function client.getmarked()
     local copy = gtable.clone(client.data.marked, false)
 
@@ -682,7 +713,7 @@ end
 -- Floating client are not handled by tiling layouts.
 -- @deprecated awful.client.floating.set
 -- @client c A client.
--- @param s True or false.
+-- @tparam boolean s True 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)
@@ -691,7 +722,7 @@ end
 -- Set a client floating state, overriding auto-detection.
 -- Floating client are not handled by tiling layouts.
 -- @client c A client.
--- @param s True or false.
+-- @tparam boolan s True or false.
 function client.object.set_floating(c, s)
     c = c or capi.client.focus
     if c and client.property.get(c, "floating") ~= s then
@@ -741,13 +772,10 @@ end
 
 --- Return if a client has a fixed size or not.
 --
--- **Signal:**
---
---  * *property::is_fixed*
---
 -- This property is read only.
 -- @property is_fixed
--- @param boolean The fixed size state
+-- @tparam[opt=false] boolean is_fixed The fixed size state
+-- @propemits false false
 -- @see size_hints
 -- @see size_hints_honor
 
@@ -772,7 +800,7 @@ end
 --
 -- This property is read only.
 -- @property immobilized_horizontal
--- @param boolean The immobilized state
+-- @tparam[opt=false] boolean immobilized_horizontal The immobilized state
 -- @see maximized
 -- @see maximized_horizontal
 -- @see fullscreen
@@ -788,7 +816,7 @@ end
 --
 -- This property is read only.
 -- @property immobilized_vertical
--- @param boolean The immobilized state
+-- @tparam[opt=false] boolean immobilized_vertical The immobilized state
 -- @see maximized
 -- @see maximized_vertical
 -- @see fullscreen
@@ -801,7 +829,7 @@ end
 -- @client c A client.
 -- @see floating
 -- @deprecated awful.client.floating.get
--- @return True or false. Note that some windows might be floating even if you
+-- @treturn boolean True or false. Note that some windows might be floating even if you
 -- did not set them manually. For example, windows with a type different than
 -- normal.
 function client.floating.get(c)
@@ -817,10 +845,6 @@ end
 -- did not set them manually. For example, windows with a type different than
 -- normal.
 --
--- **Signal:**
---
---  * *property::floating*
---
 -- @property floating
 -- @tparam boolean floating The floating state.
 -- @request client border floating granted When a border update is required
@@ -829,6 +853,7 @@ end
 --  floating.
 -- @request client border inactive granted When a client stop being active and
 --  is not floating.
+-- @propemits false false
 
 function client.object.get_floating(c)
     c = c or capi.client.focus
@@ -901,39 +926,43 @@ end
 
 --- The x coordinates.
 --
--- **Signal:**
---
---  * *property::x*
---
 -- @property x
--- @param integer
+-- @tparam integer x
+-- @emits property::geometry
+-- @emitstparam property::geometry table geo The
+--  geometry (with `x`, `y`, `width`, `height`).
+-- @emits property::x
+-- @emits property::position
 
 --- The y coordinates.
 --
--- **Signal:**
---
---  * *property::y*
---
 -- @property y
--- @param integer
+-- @tparam integer y
+-- @emits property::geometry
+-- @emitstparam property::geometry table geo The
+--  geometry (with `x`, `y`, `width`, `height`).
+-- @emits property::y
+-- @emits property::position
 
 --- The width of the client.
 --
--- **Signal:**
---
---  * *property::width*
---
 -- @property width
--- @param width
+-- @tparam integer width
+-- @emits property::geometry
+-- @emitstparam property::geometry table geo The
+--  geometry (with `x`, `y`, `width`, `height`).
+-- @emits property::width
+-- @emits property::size
 
 --- The height of the client.
 --
--- **Signal:**
---
---  * *property::height*
---
 -- @property height
--- @param height
+-- @tparam integer height
+-- @emits property::geometry
+-- @emitstparam property::geometry table geo The
+--  geometry (with `x`, `y`, `width`, `height`).
+-- @emits property::height
+-- @emits property::size
 
 -- Add the geometry helpers to match the wibox API
 for _, v in ipairs {"x", "y", "width", "height"} do
@@ -949,8 +978,8 @@ end
 
 --- Restore (=unminimize) a random client.
 -- @staticfct awful.client.restore
--- @param s The screen to use.
--- @return The restored client if some client was restored, otherwise nil.
+-- @tparam screen s The screen to use.
+-- @treturn client The restored client if some client was restored, otherwise nil.
 function client.restore(s)
     s = s or screen.focused()
     local cls = capi.client.get(s)
@@ -970,8 +999,8 @@ function client.restore(s)
 end
 
 --- Normalize a set of numbers to 1.
--- @param set the set of numbers to normalize
--- @param num the number of numbers to normalize
+-- @tparam table set the set of numbers to normalize.
+-- @tparam number num the number of numbers to normalize.
 local function normalize(set, num)
     num = num or #set
     local total = 0
@@ -998,9 +1027,9 @@ end
 --
 -- @legacylayout awful.client.idx
 -- @client c the client
--- @return col the column number
--- @return idx index of the client in the column
--- @return num the number of visible clients in the column
+-- @treturn integer col The column number.
+-- @treturn integer idx Index of the client in the column.
+-- @treturn integer num The number of visible clients in the column.
 function client.idx(c)
     c = c or capi.client.focus
     if not c then return end
@@ -1058,8 +1087,9 @@ end
 --- Set the window factor of a client
 --
 -- @legacylayout awful.client.setwfact
--- @param wfact the window factor value
+-- @tparam number wfact the window factor value
 -- @client c the client
+-- @emits property::windowfact
 function client.setwfact(wfact, c)
     -- get the currently selected window
     c = c or capi.client.focus
@@ -1114,7 +1144,8 @@ end
 -- @tparam number add Amount to increase/decrease the client's window factor.
 --   Should be between `-current_window_factor` and something close to
 --   infinite.  The normalisation then ensures that the sum of all factors is 1.
--- @client c the client
+-- @client c the client.
+-- @emits property::windowfact
 function client.incwfact(add, c)
     c = c or capi.client.focus
     if not c then return end
@@ -1152,12 +1183,9 @@ end
 -- Clients with a type of "utility", "toolbar" or "dock" are dockable by
 -- default.
 --
--- **Signal:**
---
--- * *property::dockable*
---
 -- @property dockable
--- @param boolean The dockable state
+-- @tparam boolean dockable The dockable state
+-- @propemits false false
 
 function client.object.get_dockable(c)
     local value = client.property.get(c, "dockable")
@@ -1180,7 +1208,7 @@ end
 -- to the edge of the workarea.
 --
 -- @client c A client.
--- @param value True or false.
+-- @tparam boolean value True or false.
 -- @deprecated awful.client.dockable.set
 function client.dockable.set(c, value)
     gdebug.deprecate("Use c.dockable = value instead of awful.client.dockable.set", {deprecated_in=4})
@@ -1193,12 +1221,10 @@ end
 -- various ways. This property uses the motif MWM_DECOR_TITLE hint and
 -- interprets it as the client (not) wanting a titlebar.
 --
--- **Signal:**
---
--- * *property::requests_no_titlebar*
---
 -- @property requests_no_titlebar
--- @param boolean Whether the client requests not to get a titlebar
+-- @tparam boolean requests_no_titlebar Whether the client
+--  requests not to get a titlebar.
+-- @propemits false false
 
 function client.object.get_requests_no_titlebar(c)
     local hints = c.motif_wm_hints
@@ -1224,8 +1250,8 @@ end)
 -- This method is deprecated. It is now possible to use `c.value` directly.
 --
 -- @client c The client.
--- @param prop The property name.
--- @return The property.
+-- @tparam string prop The property name.
+-- @return The property value.
 -- @deprecated awful.client.property.get
 function client.property.get(c, prop)
     if not c._private._persistent_properties_loaded then
@@ -1248,8 +1274,8 @@ end
 -- directly.
 --
 -- @client c The client.
--- @param prop The property name.
--- @param value The value.
+-- @tparam string prop The property name.
+-- @param value The property value.
 -- @deprecated awful.client.property.set
 function client.property.set(c, prop, value)
     if not c._private.awful_client_properties then
@@ -1267,8 +1293,8 @@ end
 --- Set a client property to be persistent across restarts (via X properties).
 --
 -- @staticfct awful.client.property.persist
--- @param prop The property name.
--- @param kind The type (used for register_xproperty).
+-- @tparam string prop The property name.
+-- @tparam string kind The type (used for register_xproperty).
 --   One of "string", "number" or "boolean".
 function client.property.persist(prop, kind)
     local xprop = "awful.client.property." .. prop
@@ -1288,10 +1314,10 @@ end
 -- Starting from the client in focus or the given index, all clients that match
 -- a given criteria.
 --
--- @param filter a function that returns true to indicate a positive match
--- @param start  what index to start iterating from.  Defaults to using the
+-- @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.
--- @param s which screen to use.  nil means all screens.
+-- @tparam screen s which screen to use.  nil means all screens.
 --
 -- @staticfct awful.client.iterate
 -- @usage -- un-minimize all urxvt instances
@@ -1313,8 +1339,8 @@ end
 -- If multiple clients match the given condition then the next one is
 -- focussed.
 --
--- @param cmd the command to execute
--- @param matcher a function that returns true to indicate a matching client
+-- @tparam string cmd the command to execute
+-- @tparam function matcher a function that returns true to indicate a matching client
 -- @tparam 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 as argument.
@@ -1354,7 +1380,7 @@ end
 -- @client c The client.
 -- @tparam function matcher A function that should return true, if
 --   a matching parent client is found.
--- @treturn client.client|nil The matching parent client or nil.
+-- @treturn client|nil The matching parent client or nil.
 function client.get_transient_for_matching(c, matcher)
     gdebug.deprecate("Use c:get_transient_for_matching(matcher) instead of"..
         "awful.client.get_transient_for_matching", {deprecated_in=4})
@@ -1366,7 +1392,10 @@ end
 -- @method get_transient_for_matching
 -- @tparam function matcher A function that should return true, if
 --   a matching parent client is found.
--- @treturn client.client|nil The matching parent client or nil.
+-- @treturn client|nil The matching parent client or nil.
+-- @see transient_for
+-- @see modal
+-- @see is_transient_for
 function client.object.get_transient_for_matching(self, matcher)
     local tc = self.transient_for
     while tc do
@@ -1379,11 +1408,12 @@ function client.object.get_transient_for_matching(self, matcher)
 end
 
 --- Is a client transient for another one?
+--
 -- @deprecated awful.client.is_transient_for
 -- @see client.is_transient_for
 -- @client c The child client (having transient_for).
 -- @client c2 The parent client to check.
--- @treturn client.client|nil The parent client or nil.
+-- @treturn client|nil The parent client or nil.
 function client.is_transient_for(c, c2)
     gdebug.deprecate("Use c:is_transient_for(c2) instead of"..
         "awful.client.is_transient_for", {deprecated_in=4})
@@ -1391,9 +1421,20 @@ function client.is_transient_for(c, c2)
 end
 
 --- Is a client transient for another one?
+--
+-- This will traverse the chain of `transient_for` client
+-- until a client which is transient for `c2` is found. If
+-- one is found, it will be returned. If none is found, then
+-- `nil` will be returned. Most of the time there is no
+-- long chain of clients, so `self` or `nil` are the most
+-- likely return values.
+--
 -- @method is_transient_for
 -- @client c2 The parent client to check.
--- @treturn client.client|nil The parent client or nil.
+-- @treturn client|nil The parent client or nil.
+-- @see transient_for
+-- @see modal
+-- @see client.get_transient_for_matching
 function client.object.is_transient_for(self, c2)
     local tc = self
     while tc.transient_for do
@@ -1418,12 +1459,15 @@ object.properties._legacy_accessors(client, "keys", "_keys", true, function(new_
 end, true, true, "keybinding")
 
 --- Set the client shape.
+--
 -- @property shape
 -- @tparam gears.shape A gears.shape compatible function.
+-- @propemits true false
 -- @see gears.shape
 function client.object.set_shape(self, shape)
     client.property.set(self, "_shape", shape)
     set_shape(self)
+    self:emit_signal("property::shape", shape)
 end
 
 -- Proxy those properties to decorate their accessors with an extra flag to
@@ -1643,7 +1687,7 @@ capi.client.connect_signal("request::manage", function (c)
         require("awful.placement").no_offscreen(c)
     end
 
-    if awesome.startup then
+    if capi.awesome.startup then
         client.focus.history.add(c)
     end
 
diff --git a/objects/client.c b/objects/client.c
index 7856eb630..7bd1cd359 100644
--- a/objects/client.c
+++ b/objects/client.c
@@ -140,6 +140,7 @@
  * initialized, but before clients are added.
  *
  * @signal scanning
+ * @classsignal
  */
 
 /** AwesomeWM is done scanning for clients.
@@ -147,14 +148,17 @@
  * This is emitted before the `startup` signal and after the `scanning` signal.
  *
  * @signal scanned
+ * @classsignal
  */
 
 /** When a client gains focus.
  * @signal focus
+ * @classsignal
  */
 
 /** Before manage, after unmanage, and when clients swap.
  * @signal list
+ * @classsignal
  */
 
 /** When 2 clients are swapped
@@ -179,6 +183,7 @@
  *  with the other `request::` signals).
  * @request client border added granted When a new client needs a its initial
  *  border settings.
+ * @classsignal
  */
 
 /** When a client is going away.
@@ -198,6 +203,7 @@
  * @tparam string context Why was the client unmanaged.
  * @tparam table hints More metadata (currently empty, it exists for compliance
  *  with the other `request::` signals).
+ * @classsignal
  */
 
 /** Use `request::manage`.
@@ -208,30 +214,31 @@
  * @deprecatedsignal unmanage
  */
 
-/**
+/** When a mouse button is pressed in a client.
  * @signal button::press
  */
 
-/**
+/** When a mouse button is released in a client.
+ *
  * @signal button::release
  */
 
-/**
+/** When the mouse enters a client.
+ *
  * @signal mouse::enter
  */
 
-/**
+/** When the mouse leaves a client.
+ *
  * @signal mouse::leave
  */
 
 /**
+ * When the mouse moves within a client.
+ *
  * @signal mouse::move
  */
 
-/**
- * @signal property::window
- */
-
 /** When a client should get activated (focused and/or raised).
  *
  * **Contexts are:**
@@ -267,6 +274,7 @@
  * @tparam[opt] table hints A table with additional hints:
  * @tparam[opt=false] boolean hints.raise should the client be raised?
  * @request client activate ewmh granted When the client asks to be activated.
+ * @classsignal
  */
 
 /** When an event could lead to the client being activated.
@@ -286,6 +294,7 @@
  * @tparam string context The context where this signal was used.
  * @tparam[opt] table hints A table with additional hints:
  * @tparam[opt=false] boolean hints.raise should the client be raised?
+ * @classsignal
  *
  */
 
@@ -301,14 +310,19 @@
  *  (programmatically) asks for the maximization to be changed.
  * @request client geometry client_maximize_vertical granted When a client
  *  (programmatically) asks for the maximization to be changed.
+ * @classsignal
  */
 
-/**
+/** When the tag requests to be moved to a tag or needs a new tag.
+ *
  * @signal request::tag
+ * @classsignal
  */
 
-/**
+/** When the client requests to become urgent.
+ *
  * @signal request::urgent
+ * @classsignal
  */
 
 /** Emitted during startup to gather the default client mousebindings.
@@ -363,151 +377,231 @@
  */
 
 /**
+ * Emitted when the client is raised within its layer.
+ *
  * @signal raised
+ * @see below
+ * @see above
+ * @see ontop
+ * @see raise
+ * @see lower
+ * @see lowered
  */
 
-/**
+/** Emitted when the client is lowered within its layer.
+ *
  * @signal lowered
+ * @see below
+ * @see above
+ * @see ontop
+ * @see raise
+ * @see lower
+ * @see raised
  */
 
 /**
  * The focused `client` or nil (in case there is none).
  *
+ * It is not recommanded to set the focused client using
+ * this property. Please use `c:activate{}` instead of
+ * `client.focus = c`. Setting the focus directly bypasses
+ * all the filters and emits fewer signals, which tend to
+ * cause unwanted side effects and make it harder to alter
+ * the code behavior in the future. It usually takes *more*
+ * code to use this rather than `:activate{}` because all
+ * the boilerplate code (such as `c:raise()`) needs to be
+ * added everywhere.
+ *
+ * The main use case for this field is to check *when* there
+ * is an active client.
+ *
+ *     if client.focus ~= nil then
+ *         -- do something
+ *     end
+ *
+ * If you want to check if a client is active, use:
+ *
+ *     if c.active then
+ *         -- do something
+ *     end
+ *
  * @tfield client focus
+ * @see active
+ * @see activate
+ * @see request::activate
  */
 
 /**
  * The X window id.
  *
- * **Signal:**
- *
- *  * *property::window*
+ * This is rarely useful, but some DBus protocols will
+ * have this ID in their API, so it can be useful when
+ * writing AwesomeWM bindings for them.
  *
  * @property window
- * @param string
+ * @tparam integer window
+ * @propemits false false
  */
 
 /**
  * The client title.
  *
- * **Signal:**
- *
- *  * *property::name*
+ * This is the text which will be shown in the `awful.widget.tasklist`
+ * and the `awful.titlebar`.
  *
  * @property name
- * @param string
+ * @tparam string name
+ * @propemits false false
+ * @see awful.titlebar
+ * @see awful.widget.tasklist
  */
 
 /**
  * True if the client does not want to be in taskbar.
  *
- * **Signal:**
+ * Some clients, like docked bars or some `sticky` clients
+ * such as wallpaper sensors like Conky have no value in
+ * the `awful.widget.tasklist` and should not be shown there.
  *
- *  * *property::skip\_taskbar*
+ * The default value of this property reflects the value of the
+ * `_NET_WM_STATE_SKIP_TASKBAR` X11 protocol xproperty.
  *
  * @property skip_taskbar
- * @param boolean
+ * @tparam[opt=false] boolean skip_taskbar
+ * @propemits false false
+ * @see sticky
  */
 
+//TODO v5: Rename to skip_tasklist?
+
 /**
  * The window type.
  *
+ * This is useful in, among other places, the `ruled.client` rules to apply
+ * different properties depending on the client types. It is also used
+ * throughout the API to alter the client (and `wibox`) behavior depending on
+ * the `type`. For example, clients with the `dock` type are placed on the side
+ * of the screen while other like `combo` are totally ignored and never
+ * considered `client`s in the first place.
+ *
  * Valid types are:
  *
- * * **desktop**: The root client, it cannot be moved or resized.
- * * **dock**: A client attached to the side of the screen.
- * * **splash**: A client, usually without titlebar shown when an application starts.
- * * **dialog**: A dialog, see `transient_for`.
- * * **menu**: A context menu.
- * * **toolbar**: A floating toolbar.
- * * **utility**:
- * * **dropdown_menu**: A context menu attached to a parent position.
- * * **popup_menu**: A context menu.
- * * **notification**: A notification popup.
- * * **combo**: A combobox list menu.
- * * **dnd**: A drag and drop indicator.
- * * **normal**: A normal application main window.
+ * <table class='widget_list' border=1>
+ * <tr style='font-weight: bold;'>
+ *  <th align='center'>Name</th>
+ *  <th align='center'>Description</th>
+ * </tr>
+ * <tr><td><b>desktop</b></td><td>The root client, it cannot be moved or resized.</td></tr>
+ * <tr><td><b>dock</b></td><td>A client attached to the side of the screen.</td></tr>
+ * <tr><td><b>splash</b></td><td>A client, usually without titlebar shown when an application starts.</td></tr>
+ * <tr><td><b>dialog</b></td><td>A dialog, see `transient_for`.</td></tr>
+ * <tr><td><b>menu</b></td><td>A context menu.</td></tr>
+ * <tr><td><b>toolbar</b></td><td>A floating toolbar.</td></tr>
+ * <tr><td><b>utility</b></td><td></td></tr>
+ * <tr><td><b>dropdown_menu</b></td><td>A context menu attached to a parent position.</td></tr>
+ * <tr><td><b>popup_menu</b></td><td>A context menu.</td></tr>
+ * <tr><td><b>notification</b></td><td>A notification popup.</td></tr>
+ * <tr><td><b>combo</b></td><td>A combobox list menu.</td></tr>
+ * <tr><td><b>dnd</b></td><td>A drag and drop indicator.</td></tr>
+ * <tr><td><b>normal</b></td><td>A normal application main window.</td></tr>
+ * </table>
  *
  * More information can be found [here](https://specifications.freedesktop.org/wm-spec/wm-spec-latest.html#idm140200472629520)
  *
- * **Signal:**
- *
- *  * *property::type*
- *
  * @property type
- * @param string
+ * @tparam string type
+ * @propemits false false
+ * @see ruled.client
  */
 
 /**
  * The client class.
  *
- * To get a client class from the command line, use the command `xprop
- * WM_CLASS`. The class will be the second string.
+ * A class usually maps to the application name. It is useful in, among other
+ * places, the rules to apply different properties to different clients. It
+ * is also useful, along with `instance`, so implement "windows counter"
+ * used in many popular docks and Alt-Tab like popups.
  *
- * **Signal:**
+ * To get a client class from the command line, use the command:
  *
- *  * *property::class*
+ *    xprop WM_CLASS
+ *
+ * The class will be the second string.
+ *
+ * This *should* never change after the client is created, but some
+ * buggy application like the Spotify desktop client are known to
+ * violate the specification and do it anyway. There *is* a signal for
+ * this property, but it should hopefully never be useful. If your
+ * applications change their classes, please report a bug to them.
+ * It tends to break `ruled.client` and other AwesomeWM APIs.
  *
  * @property class
- * @param string
+ * @tparam string class
+ * @propemits false false
+ * @see instance
+ * @see ruled.client
  */
 
 /**
  * The client instance.
  *
- * To get a client instance from the command line, use the command `xprop
- * WM_CLASS`. The instance will be the first string.
+ * The `instance` is a subtype of the `class`. Each `class` can have
+ * multiple instances. This is useful in the `ruled.client` rules to
+ * filter clients and apply different properties to them.
  *
- * **Signal:**
+ * To get a client instance from the command line, use the command:
  *
- *  * *property::instance*
+ *     xprop WM_CLASS
+ *
+ * The instance will be the first string.
  *
  * @property instance
- * @param string
+ * @tparam string instance
+ * @propemits false false
+ * @see class
+ * @see ruled.client
  */
 
 /**
  * The client PID, if available.
  *
- * **Signal:**
- *
- *  * *property::pid*
+ * This will never change.
  *
  * @property pid
- * @param number
+ * @tparam integer pid
+ * @propemits false false
  */
 
 /**
  * The window role, if available.
  *
- * **Signal:**
- *
- *  * *property::role*
- *
  * @property role
- * @param string
+ * @tparam string role
+ * @propemits false false
+ * @see instance
+ * @see class
  */
 
 /**
  * The machine client is running on.
  *
- * **Signal:**
- *
- *  * *property::machine*
+ * X11 windows can "live" in another computer but shown
+ * in another one. This is called "network transparency"
+ * and is either used directly by allowing remote windows
+ * using the `xhosts` command for using proxies such as
+ * `ssh -X` or `ssh -Y`.
  *
  * @property machine
- * @param string
+ * @tparam string machine
+ * @propemits false false
  */
 
 /**
  * The client name when iconified.
  *
- * **Signal:**
- *
- *  * *property::icon\_name*
- *
  * @property icon_name
- * @param string
+ * @tparam string icon_name
+ * @propemits false false
  */
 
 /**
@@ -526,67 +620,65 @@
  * the same icon, it will cause a double-free error and Awesome will crash. To
  * get a copy of the icon, you can use:
  *
- *     local s = gears.surface(c.icon)
- *     local img = cairo.ImageSurface.create(cairo.Format.ARGB32, s:get_width(), s:get_height())
- *     local cr  = cairo.Context(img)
- *     cr:set_source_surface(s, 0, 0)
- *     cr:paint()
- *
- * **Signal:**
- *
- *  * *property::icon*
+ *    local s = gears.surface(c.icon)
+ *    local img = cairo.ImageSurface.create(cairo.Format.ARGB32, s:get_width(), s:get_height())
+ *    local cr  = cairo.Context(img)
+ *    cr:set_source_surface(s, 0, 0)
+ *    cr:paint()
  *
  * @property icon
- * @param surface
+ * @tparam surface icon
+ * @propemits false false
  * @usage local ib = wibox.widget.imagebox(c.icon)
+ * @see awful.widget.clienticon
  */
 
 /**
  * The available sizes of client icons. This is a table where each entry
  * contains the width and height of an icon.
  *
- * **Signal:**
- *
- *  * *property::icon\_sizes*
- *
  * @property icon_sizes
  * @tparam table sizes
+ * @propemits false false
+ * @see awful.widget.clienticon
  * @see get_icon
  */
 
 /**
  * Client screen.
  *
- * **Signal:**
+ * The `screen` corresponds to the top-left corner of the window.
  *
- *  * *property::screen*
+ * Please note that clients can only be on one screen at once. X11
+ * does not natively allow clients to be in multiple locations at
+ * once. Changing the screen directly will affect the tags and may
+ * cause several other changes to the state in order to ensure no
+ * screen specific code is changing the other screens clients.
  *
  * @property screen
- * @param screen
+ * @tparam screen screen
+ * @propemits false false
+ * @see move_to_screen
  */
 
 /**
  * Define if the client must be hidden, i.e. never mapped,
  *   invisible in taskbar.
  *
- * **Signal:**
- *
- *  * *property::hidden*
- *
  * @property hidden
- * @param boolean
+ * @tparam boolean hidden
+ * @propemits false false
+ * @see minimized
  */
 
 /**
  * Define it the client must be iconify, i.e. only visible in
  *   taskbar.
  *
- * **Signal:**
- *
- *  * *property::minimized*
- *
  * @property minimized
- * @param boolean
+ * @tparam boolean minimized
+ * @propemits false false
+ * @see hidden
  */
 
 /**
@@ -598,19 +690,17 @@
  *
  * This is enabled by default. To disable it by default, see `ruled.client`.
  *
- * **Signal:**
- *
- *  * *property::size\_hints\_honor*
- *
  * @property size_hints_honor
- * @param boolean
+ * @tparam boolean size_hints_honor
+ * @propemits false false
  * @see size_hints
  */
 
 /**
  * The client border width.
+ *
  * @property border_width
- * @param integer
+ * @tparam integer border_width
  * @propemits false false
  * @see request::border
  */
@@ -619,7 +709,7 @@
  * The client border color.
  *
  * @property border_color
- * @param color Any string, gradients and patterns will be converted to a
+ * @tparam color border_color Any string, gradients and patterns will be converted to a
  *  cairo pattern.
  * @propemits false false
  * @see request::border
@@ -629,12 +719,8 @@
 /**
  * The client urgent state.
  *
- * **Signal:**
- *
- *  * *property::urgent*
- *
  * @property urgent
- * @param boolean
+ * @tparam boolean urgent
  * @propemits false false
  * @see request::border
  */
@@ -650,49 +736,58 @@
  *
  *    gears.surface(c.content):write_to_png(path)
  *
+ * Please note that once taken, the surface wont be
+ * updated when the client content changes. Since
+ * AwesomeWM does not have a compositor, the only way
+ * to get an animated client screenshot widget is to
+ * poll this property multiple time per seconds. This
+ * is very slow and should be used only when the said
+ * widget is visible rather than all the time.
+ *
+ * This property has no signals when the content changes.
+ *
  * @property content
- * @param surface
+ * @tparam surface content
+ * @see gears.surface
  */
 
 /**
  * The client opacity.
  *
- * **Signal:**
- *
- *  * *property::opacity*
- *
  * @property opacity
- * @param number Between 0 (transparent) to 1 (opaque)
+ * @tparam number opacity Between 0 (transparent) to 1 (opaque).
  * @propemits false false
  * @see request::border
  */
 
 /**
  * The client is on top of every other windows.
+ *
  * @property ontop
- * @param boolean
+ * @tparam boolean ontop
+ * @propemits false false
+ * @see below
+ * @see above
  */
 
 /**
  * The client is above normal windows.
  *
- * **Signal:**
- *
- *  * *property::above*
- *
  * @property above
- * @param boolean
+ * @tparam boolean above
+ * @propemits false false
+ * @see below
+ * @see ontop
  */
 
 /**
  * The client is below normal windows.
  *
- * **Signal:**
- *
- *  * *property::below*
- *
  * @property below
- * @param boolean
+ * @tparam boolean below
+ * @propemits false false
+ * @see above
+ * @see ontop
  */
 
 /**
@@ -747,42 +842,98 @@
 /**
  * The client the window is transient for.
  *
+ * A transient window is a client that "belongs" to another
+ * client. If the client is also `modal`, then it always has
+ * to be on top of the other window *and* the parent client
+ * cannot be focused while the child client exists.
+ * This is common for "Save as" dialogs or other dialogs where
+ * isn't possible to modify the content of the "parent" client
+ * while the dialog is open.
+ *
+ * However, `modal` isn't a requirement for using the `transient_for`
+ * concept. "Tools" such as popup palette in canvas-and-palettes
+ * applications can belong to each other without being modal.
+ *
+ * However this it is also
+ * possible to have
+ *
  * @property transient_for
- * @param client
+ * @tparam client transient_for
  * @propemits false false
+ * @see modal
+ * @see type
+ * @see is_transient_for
+ * @see get_transient_for_matching
  */
 
 /**
  * Window identification unique to a group of windows.
  *
+ * This is the ID of the group window, not a client object.
+ *
  * @property group_window
- * @param client
+ * @tparam integer group_window
  * @propemits false false
+ * @see leader_window
  */
 
 /**
  * Identification unique to windows spawned by the same command.
+ *
+ * This is the ID of the group window, not a client object.
+ *
  * @property leader_window
- * @param client
+ * @tparam number leader_window
+ * @propemits false false
+ * @see transient_for
+ * @see modal
+ * @see group_window
  */
 
 /**
  * A table with size hints of the client.
  *
+ * Please note that most fields are optional and may or may not be set.
+ *
+ * When the client is tiled, the `size_hints` usually get in the way and
+ * cause the layouts to behave incorrectly. To mitigate this, it is often
+ * advised to set `size_hints_honor` to `false` in the `ruled.client` rules.
+ *
  * @property size_hints
- * @param table
- * @tfield integer table.user_position
- * @tfield integer table.user_size
- * @tfield integer table.program_position
- * @tfield integer table.program_size
- * @tfield integer table.max_width
- * @tfield integer table.max_height
- * @tfield integer table.min_width
- * @tfield integer table.min_height
- * @tfield integer table.width_inc
- * @tfield integer table.height_inc
+ * @tparam[opt] table|nil hints The hints.
+ * @tparam[opt] table|nil hints.user_position A table with `x` and `y` keys. It
+ *  contains the preferred position of the client. This is set when the
+ *  position has been modified by the user. See `program_position`.
+ * @tparam[opt] table|nil hints.program_position A table with `x` and `y` keys. It
+ *  contains the preferred position of the client. This is set when the
+ *  application itself requests a specific position. See `user_position`.
+ * @tparam[opt] table|nil hints.user_size A table with `width` and `height`. This
+ *  contains the client preferred size when it has previously been set by
+ *  the user. See `program_size` for the equivalent when the applications
+ *  itself wants to specify its preferred size.
+ * @tparam[opt] table|nil hints.program_size A table with `width` and `height`. This
+ *  contains the client preferred size as specified by the application.
+ * @tparam[opt] integer|nil hints.max_width The maximum width (in pixels).
+ * @tparam[opt] integer|nil hints.max_height The maximum height (in pixels).
+ * @tparam[opt] integer|nil hints.min_width The minimum width (in pixels).
+ * @tparam[opt] integer|nil hints.min_height The minimum height (in pixels).
+ * @tparam[opt] integer|nil hints.width_inc The number of pixels by which the
+ *  client width may be increased or decreased. For example, for terminals,
+ *  the size has to be proportional with the monospace font size.
+ * @tparam[opt] integer|nil hints.height_inc The number of pixels by which the
+ *  client height may be increased or decreased. For example, for terminals,
+ *  the size has to be proportional with the monospace font size.
+ * @tparam[opt] string|nil hints.win_gravity The client `gravity` defines the corder
+ *   from which the size is computed. For most clients, it is `north_west`, which
+ *   corresponds to the top-left of the window. This will affect how the client
+ *   is resized and other size related operations.
+ * @tparam[opt] integer|nil hints.min_aspect_num
+ * @tparam[opt] integer|nil hints.min_aspect_den
+ * @tparam[opt] integer|nil hints.max_aspect_num
+ * @tparam[opt] integer|nil hints.max_aspect_den
  * @propemits false false
  * @see size_hints_honor
+ * @see geometry
  */
 
 /**
@@ -797,103 +948,168 @@
  * should be enabled.
  *
  * @property motif_wm_hints
- * @param table
- * @tfield[opt] table table.functions
- * @tfield[opt] boolean table.functions.all
- * @tfield[opt] boolean table.functions.resize
- * @tfield[opt] boolean table.functions.move
- * @tfield[opt] boolean table.functions.minimize
- * @tfield[opt] boolean table.functions.maximize
- * @tfield[opt] boolean table.functions.close
- * @tfield[opt] table table.decorations
- * @tfield[opt] boolean table.decorations.all
- * @tfield[opt] boolean table.decorations.border
- * @tfield[opt] boolean table.decorations.resizeh
- * @tfield[opt] boolean table.decorations.title
- * @tfield[opt] boolean table.decorations.menu
- * @tfield[opt] boolean table.decorations.minimize
- * @tfield[opt] boolean table.decorations.maximize
- * @tfield[opt] string table.input_mode
- * @tfield[opt] table table.status
- * @tfield[opt] boolean table.status.tearoff_window
+ * @tparam table hints The hints.
+ * @tparam[opt] boolean hints.functions.all
+ * @tparam[opt] boolean hints.functions.resize
+ * @tparam[opt] boolean hints.functions.move
+ * @tparam[opt] boolean hints.functions.minimize
+ * @tparam[opt] boolean hints.functions.maximize
+ * @tparam[opt] boolean hints.functions.close
+ * @tparam[opt] boolean hints.decorations.all
+ * @tparam[opt] boolean hints.decorations.border
+ * @tparam[opt] boolean hints.decorations.resizeh
+ * @tparam[opt] boolean hints.decorations.title
+ * @tparam[opt] boolean hints.decorations.menu
+ * @tparam[opt] boolean hints.decorations.minimize
+ * @tparam[opt] boolean hints.decorations.maximize
+ * @tparam[opt] string hints.input_mode This is either `modeless`,
+ *  `primary_application_modal`, `system_modal`,
+ *  `full_application_modal` or `unknown`.
+ * @tparam[opt] boolean hints.status.tearoff_window
  * @propemits false false
  */
 
 /**
  * Set the client sticky, i.e. available on all tags.
  *
+ * Please note that AwesomeWM implements `sticky` clients
+ * per screens rather than globally like some other
+ * implementations.
+ *
  * @property sticky
- * @param boolean
+ * @tparam boolean sticky
  * @propemits false false
+ * @see skip_taskbar
  */
 
 /**
  * Indicate if the client is modal.
  *
+ * A transient window is a client that "belongs" to another
+ * client. If the client is also `modal`, then it always has
+ * to be on top of the other window *and* the parent client
+ * cannot be focused while the child client exists.
+ * This is common for "Save as" dialogs or other dialogs where
+ * isn't possible to modify the content of the "parent" client
+ * while the dialog is open.
+ *
+ * However, `modal` isn't a requirement for using the `transient_for`
+ * concept. "Tools" such as popup palette in canvas-and-palettes
+ * applications can belong to each other without being modal.
+ *
  * @property modal
- * @param boolean
+ * @tparam boolean modal
  * @propemits false false
+ * @see transient_for
  */
 
 /**
  * True if the client can receive the input focus.
  *
+ * The client wont get focused even when the user
+ * click on it.
+ *
  * @property focusable
- * @param boolean
+ * @tparam boolean focusable
  * @propemits false false
+ * @see shape_input
+ * @see client.focus
+ * @see active
+ * @see activate
  */
 
 /**
  * The client's bounding shape as set by awesome as a (native) cairo surface.
  *
- * @see gears.surface.apply_shape_bounding
+ * The bounding shape is the outer shape of the client. It is outside of the
+ * border.
+ *
+ * Do not use this directly unless you want total control over the shape (such
+ * as shape with holes). Even then, it is usually recommended to use transparency
+ * in the titlebars and a compositing manager. For the vast majority use use
+ * cases, use the `shape` property.
+ *
  * @property shape_bounding
- * @param surface
+ * @tparam surface shape_bounding
  * @propemits false false
+ * @see shape
+ * @see gears.surface.apply_shape_bounding
+ * @see gears.shape
+ * @see shape_clip
+ * @see shape_input
+ * @see client_shape_bounding
+ * @see client_shape_clip
+ * @see gears.surface
  */
 
 /**
  * The client's clip shape as set by awesome as a (native) cairo surface.
  *
- * **Signal:**
- *
- *  * *property::shape\_clip*
+ * The shape_clip is the shape of the client *content*. It is *inside* the
+ * border.
  *
  * @property shape_clip
- * @param surface
+ * @tparam surface shape_clip
+ * @propemits false false
+ * @see shape_bounding
+ * @see shape_input
+ * @see shape
+ * @see gears.surface.apply_shape_bounding
+ * @see gears.shape
+ * @see client_shape_bounding
+ * @see client_shape_clip
+ * @see gears.surface
  */
 
 /**
  * The client's input shape as set by awesome as a (native) cairo surface.
  *
- * **Signal:**
- *
- *  * *property::shape\_input*
+ * The input shape is the shape where mouse input will be passed to the
+ * client rather than propagated below it.
  *
  * @property shape_input
- * @param surface
+ * @tparam surface shape_input
+ * @propemits false false
+ * @see shape_bounding
+ * @see shape_clip
+ * @see shape
+ * @see gears.surface.apply_shape_bounding
+ * @see gears.shape
+ * @see client_shape_bounding
+ * @see client_shape_clip
+ * @see gears.surface
  */
 
 /**
  * The client's bounding shape as set by the program as a (native) cairo surface.
  *
- * **Signal:**
- *
- *  * *property::shape\_client\_bounding*
- *
  * @property client_shape_bounding
- * @param surface
+ * @tparam surface client_shape_bounding
+ * @propemits false false
+ * @see shape_bounding
+ * @see shape_clip
+ * @see shape_input
+ * @see shape
+ * @see gears.surface.apply_shape_bounding
+ * @see gears.shape
+ * @see client_shape_clip
+ * @see gears.surface
  */
 
 /**
  * The client's clip shape as set by the program as a (native) cairo surface.
  *
- * **Signal:**
- *
- *  * *property::shape\_client\_clip*
- *
  * @property client_shape_clip
- * @param surface
+ * @tparam surface client_shape_clip
+ * @propemits false false
+ * @see shape_bounding
+ * @see shape_clip
+ * @see shape_input
+ * @see shape
+ * @see gears.surface.apply_shape_bounding
+ * @see gears.shape
+ * @see client_shape_bounding
+ * @see gears.surface
  */
 
 /**
@@ -950,12 +1166,9 @@
  *        "snid", fix_startup_id, {}, {"awful.spawn", "ruled.client"}
  *    )
  *
- * **Signal:**
- *
- *  * *property::startup\_id*
- *
  * @property startup_id
- * @param string
+ * @tparam string startup_id
+ * @propemits false false
  * @see awful.spawn
  */
 
@@ -966,52 +1179,49 @@
  *
  *    local is_valid = pcall(function() return c.valid end) and c.valid
  *
- * **Signal:**
- *
- *  * *property::valid*
- *
  * @property valid
- * @param boolean
+ * @tparam boolean valid
+ * @propemits false false
+ * @see kill
  */
 
 /**
- * The first tag of the client.  Optimized form of `c:tags()[1]`.
+ * The first tag of the client.
  *
- * **Signal:**
- *
- *  * *property::first\_tag*
+ * Optimized form of `c:tags()[1]`. Not every workflow uses the
+ * ability to set multiple tags to a client. It is often enough
+ * to only get the first tag and ignore everything else.
  *
  * @property first_tag
- * @param tag
- */
-
-/** When the height or width changed.
- * @signal property::size
- * @see client.geometry
- */
-
-/** When the x or y coordinate changed.
- * @signal property::position
- * @see client.geometry
+ * @tparam tag first_tag
+ * @propemits false false
+ * @see tags
  */
 
 /** Return client struts (reserved space at the edge of the screen).
  *
- * @param struts A table with new strut values, or none.
- * @return A table with strut values.
+ * The struts area is a table with a `left`, `right`, `top` and `bottom`
+ * keys to define how much space of the screen `workarea` this client
+ * should reserve for itself.
+ *
+ * @tparam table struts A table with new strut values, or none.
+ * @treturn table A table with strut values.
  * @method struts
+ * @see geometry
+ * @see screen.workarea
  */
 
 /** Get or set mouse buttons bindings for a client.
  *
  * @property buttons
- * @param table
+ * @tparam table buttons
+ * @propemits false false
  * @see awful.button
  */
 
 /** Get the number of instances.
  *
- * @return The number of client objects alive.
+ * @treturn integer The number of client objects alive.
  * @staticfct instances
  */
 
@@ -2561,6 +2771,9 @@ client_kill(client_t *c)
  *   top to bottom).
  * @treturn table A table with clients.
  * @staticfct get
+ * @usage for _, c in client.get() do
+ *     -- do something
+ * end
  */
 static int
 luaA_client_get(lua_State *L)
@@ -2600,7 +2813,7 @@ luaA_client_get(lua_State *L)
 
 /** Check if a client is visible on its screen.
  *
- * @return A boolean value, true if the client is visible, false otherwise.
+ * @treturn boolean A boolean value, true if the client is visible, false otherwise.
  * @method isvisible
  */
 static int
@@ -2710,8 +2923,13 @@ out:
 
 
 /** Kill a client.
+ *
+ * This method can be used to close (kill) a **client** using the
+ * X11 protocol. To use the POSIX way to kill a **process**, use
+ * `awesome.kill`.
  *
  * @method kill
+ * @see awesome.kill
  */
 static int
 luaA_client_kill(lua_State *L)
@@ -2724,6 +2942,17 @@ luaA_client_kill(lua_State *L)
 /** Swap a client with another one in global client list.
  * @client c A client to swap with.
  * @method swap
+ * @emits swapped
+ * @emitstparam swapped client The other client.
+ * @emitstparam swapped boolean `true` when `:swap()` was called
+ *  on *self* rather than the other client. `false` when
+ *  `:swap()` was called on the other client.
+ * @emits list
+ * @see swapped
+ * @see awful.client.swap.bydirection
+ * @see awful.client.swap.global_bydirection
+ * @see awful.client.swap.byidx
+ * @see awful.client.cycle
  */
 static int
 luaA_client_swap(lua_State *L)
@@ -2766,14 +2995,13 @@ luaA_client_swap(lua_State *L)
  *
  * Use the `first_tag` field to access the first tag of a client directly.
  *
- * **Signal:**
- *
- *  * *property::tags*
- *
  * @tparam table tags_table A table with tags to set, or `nil` to get the
  *   current tags.
  * @treturn table A table with all tags.
  * @method tags
+ * @emits property::tags
+ * @see first_tag
+ * @see toggle_tag
  */
 static int
 luaA_client_tags(lua_State *L)
@@ -2843,6 +3071,11 @@ luaA_client_get_first_tag(lua_State *L, client_t *c)
 /** Raise a client on top of others which are on the same layer.
  *
  * @method raise
+ * @emits raised
+ * @see above
+ * @see below
+ * @see ontop
+ * @see lower
  */
 static int
 luaA_client_raise(lua_State *L)
@@ -2864,6 +3097,11 @@ luaA_client_raise(lua_State *L)
 /** Lower a client on bottom of others which are on the same layer.
  *
  * @method lower
+ * @emits lowered
+ * @see above
+ * @see below
+ * @see ontop
+ * @see raise
  */
 static int
 luaA_client_lower(lua_State *L)
@@ -3119,8 +3357,17 @@ HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT)
 /** Return or set client geometry.
  *
  * @tparam table|nil geo A table with new coordinates, or nil.
+ * @tparam integer geo.x The horizontal position.
+ * @tparam integer geo.y The vertical position.
+ * @tparam integer geo.width The width.
+ * @tparam integer geo.width The height.
  * @treturn table A table with client geometry and coordinates.
  * @method geometry
+ * @see struts
+ * @see x
+ * @see y
+ * @see width
+ * @see height
  */
 static int
 luaA_client_geometry(lua_State *L)
@@ -3153,11 +3400,19 @@ luaA_client_geometry(lua_State *L)
 
 /** Apply size hints to a size.
  *
- * @param width Desired width of client
- * @param height Desired height of client
- * @return Actual width of client
- * @return Actual height of client
+ * This method applies the client size hints. The client
+ * will be resized according to the size hints as long
+ * as `size_hints_honor` is true. Regardless of the
+ * status of `size_hints_honor`, this method will
+ * return the size with the size hints applied.
+ *
+ * @tparam integer width Desired width of client
+ * @tparam integer height Desired height of client
+ * @treturn integer Actual width of client
+ * @treturn integer Actual height of client
  * @method apply_size_hints
+ * @see size_hints
+ * @see size_hints_honor
  */
 static int
 luaA_client_apply_size_hints(lua_State *L)
@@ -3773,7 +4028,8 @@ luaA_client_set_shape_input(lua_State *L, client_t *c)
 /** Get or set keys bindings for a client.
  *
  * @property keys
- * @param table
+ * @tparam table keys
+ * @propemits false false
  * @see awful.key
  */
 static int
@@ -3816,10 +4072,6 @@ luaA_client_get_icon_sizes(lua_State *L, client_t *c)
 }
 
 /** Get the client's n-th icon.
- *
- * **Signal:**
- *
- *  * *property::icon*
  *
  * @tparam interger index The index in the list of icons to get.
  * @treturn surface A lightuserdata for a cairo surface. This reference must be