doc: config.ld: setup @client alias, and use it

It also adds the "@tab" alias, which did not work for me, but should be
the default?!

config.ld.in

@@ -5,3 +5,9 @@ description='highly configurable X window manager'
 --format='markdown' or should it be discount? what is that anyway? how about plain?
 dir='doc'
 file={ 'lib/', '@SOURCE_DIR@/luadoc' }
+
+-- Setup @client to be an alias for "@tparam client.client"
+tparam_alias('client', 'client.client')
+
+-- Should be default, but is not.  Sets up "@tab" => "@tparam table".
+tparam_alias('tab', 'table')

lib/awful/client.lua.in

@@ -669,7 +669,7 @@ function client.floating.toggle(c)
 end
 
 --- Remove the floating information on a client.
--- @param c The client.
+-- @client c The client.
 function client.floating.delete(c)
     client.floating.set(c, nil)
 end

lib/awful/rules.lua.in

@@ -106,8 +106,8 @@ local rules = {}
 rules.rules = {}
 
 --- Check if a client matches a rule.
--- @param c The client.
--- @param rule The rule to check.
+-- @client c The client.
+-- @tab rule The rule to check.
 -- @return True if it matches, false otherwise.
 function rules.match(c, rule)
     if not rule then return false end
@@ -128,8 +128,8 @@ function rules.match(c, rule)
 end
 
 --- Check if a client matches any part of a rule.
--- @param c The client.
--- @param rule The rule to check.
+-- @client c The client.
+-- @tab rule The rule to check.
 -- @return True if at least one rule is matched, false otherwise.
 function rules.match_any(c, rule)
     if not rule then return false end
@@ -148,10 +148,10 @@ function rules.match_any(c, rule)
 end
 
 --- Get list of matching rules for a client.
--- @param c The client.
--- @param _rules The rules to check. List with "rule", "rule_any", "except" and
--- "except_any" keys.
--- @return The list of matched rules.
+-- @client c The client.
+-- @tab _rules The rules to check. List with "rule", "rule_any", "except" and
+--             "except_any" keys.
+-- @treturn table The list of matched rules.
 function rules.matching_rules(c, _rules)
     local result = {}
     for _, entry in ipairs(_rules) do
@@ -164,17 +164,17 @@ function rules.matching_rules(c, _rules)
 end
 
 --- Check if a client matches a given set of rules.
--- @param c The client.
--- @param rules The rules to check. List with "rule", "rule_any", "except" and
--- "except_any" keys.
--- @return True if at least one rule is matched, false otherwise.
+-- @client c The client.
+-- @tab rules The rules to check. List with "rule", "rule_any", "except" and
+--                     "except_any" keys.
+-- @treturn boolean True if at least one rule is matched, false otherwise.
 function rules.does_match(c, rules)
     local result = rules.matching_rules(c, rules)
     return #result == 0 and false or result
 end
 
 --- Apply awful.rules.rules to a client.
--- @param c The client.
+-- @client c The client.
 function rules.apply(c)
     local props = {}
     local callbacks = {}
@@ -195,9 +195,9 @@ end
 
 
 --- Apply properties and callbacks to a client.
--- @param c The client.
--- @param props Properties to apply.
--- @param callbacks Callbacks to apply (optional).
+-- @client c The client.
+-- @tab props Properties to apply.
+-- @tab callbacks Callbacks to apply (optional).
 function rules.execute(c, props, callbacks)
     for property, value in pairs(props) do
         if property ~= "focus" and type(value) == "function" then

luadoc/client.lua

@@ -105,7 +105,7 @@ module("client")
 -- @class function
 
 --- Swap a client with another one in global client list.
--- @param c A client to swap with.
+-- @client A client to swap with.
 -- @name swap
 -- @class function
 

luadoc/mouse.lua

@@ -5,17 +5,19 @@ module("mouse")
 
 --- Mouse library.
 -- @field screen Mouse screen number.
--- @class table
--- @name mouse
+-- @table mouse
+
+--- A table with X and Y coordinates.
+-- @field x X coordinate.
+-- @field y Y coordinate.
+-- @table coords_table
 
 --- Get or set the mouse coords.
--- @param coords_table None or a table with x and y keys as mouse coordinates.
--- @param silent Disable mouse::enter or mouse::leave events that could be triggered by the pointer when moving.
--- @return A table with mouse coordinates.
--- @name coords
--- @class function
+-- @tparam coords_table coords_table None or a table with x and y keys as mouse coordinates.
+-- @tparam boolean silent Disable mouse::enter or mouse::leave events that could be triggered by the pointer when moving.
+-- @treturn coords_table A table with mouse coordinates.
+-- @function coords
 
 --- Get the client or any object which is under the pointer.
--- @return A client or nil.
--- @name object_under_pointer
--- @class function
+-- @treturn client.client|nil A client or nil.
+-- @function object_under_pointer

luadoc/root.lua

@@ -11,8 +11,8 @@ module("root")
 -- @class function
 
 --- Get or set global key bindings.
--- This binding will be available when you'll press keys on root window.
--- @param keys_array An array of key bindings objects, or nothing.
+-- These binding will be available when you press keys on the root window.
+-- @param keys_array An array of key binding objects, or nothing.
 -- @return The array of key bindings objects of this client.
 -- @name keys
 -- @class function