Merge pull request #132 from awesomeWM/doc-fixes

A new set of doc fixes / improvements

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

lib/awful/screen.lua.in

@@ -43,7 +43,8 @@ function screen.getbycoord(x, y, default)
     return default
 end
 
---- Give the focus to a screen, and move pointer. Keeps relative position of the pointer on the screen.
+--- Give the focus to a screen, and move pointer.
+-- Keeps relative position of the pointer on the screen.
 -- @param _screen Screen number.
 function screen.focus(_screen)
     client = client or require("awful.client")

lib/gears/timer.lua.in

@@ -1,3 +1,4 @@
+--- Timer objects and functions.
 ---------------------------------------------------------------------------
 -- @author Uli Schlachter
 -- @copyright 2014 Uli Schlachter
@@ -18,12 +19,12 @@ local object = require("gears.object")
 --- Timer objects. This type of object is useful when triggering events repeatedly.
 -- The timer will emit the "timeout" signal every N seconds, N being the timeout
 -- value.
--- @field timeout Interval in seconds to emit the timeout signal. Can be any
--- value, including floating point ones (i.e. 1.5 seconds).
--- @field started Read-only boolean field indicating if the timer has been
--- started.
--- @class table
--- @name timer
+-- @tfield number timeout Interval in seconds to emit the timeout signal.
+--                        Can be any value, including floating point ones
+--                        (e.g. 1.5 seconds).
+-- @tfield boolean started Read-only boolean field indicating if the timer has been
+--                         started.
+-- @table timer
 
 local timer = { mt = {} }
 
@@ -81,7 +82,11 @@ local timer_instance_mt = {
     end
 }
 
-local function new(args)
+--- Create a new timer object.
+-- @tparam table args Arguments.
+-- @tparam number args.timeout Timeout in seconds (e.g. 1.5).
+-- @treturn timer
+timer.new = function(args)
     local ret = object()
 
     ret:add_signal("property::timeout")
@@ -109,7 +114,7 @@ capi.awesome.connect_signal("refresh", function()
 end)
 
 --- Call the given function at the end of the current main loop iteration
--- @param callback The function that should be called
+-- @tparam function callback The function that should be called
 -- @param ... Arguments to the callback function
 function timer.delayed_call(callback, ...)
     assert(type(callback) == "function", "callback must be a function, got: " .. type(callback))
@@ -117,7 +122,7 @@ function timer.delayed_call(callback, ...)
 end
 
 function timer.mt:__call(...)
-    return new(...)
+    return timer.new(...)
 end
 
 return setmetatable(timer, timer.mt)

lib/wibox/widget/textbox.lua.in

@@ -53,8 +53,10 @@ function textbox:fit(width, height)
     return logical.width, logical.height
 end
 
---- Set a textbox' text.
--- @param text The text to set. This can contain pango markup (e.g. <b>bold</b>)
+--- Set the text of the textbox (with Pango markup).
+-- @param text The text to set. This can contain pango markup (e.g.
+-- <pre><b>bold</b></pre>). You can use awful.util.escape to escape
+-- parts of it.
 function textbox:set_markup(text)
     local attr, parsed = Pango.parse_markup(text, -1, 0)
     -- In case of error, attr is false and parsed is an error message

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