diff --git a/config.ld.in b/config.ld.in index a29b834b..cdc01170 100644 --- a/config.ld.in +++ b/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') diff --git a/lib/awful/client.lua.in b/lib/awful/client.lua.in index ab671885..ffdb390a 100644 --- a/lib/awful/client.lua.in +++ b/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 diff --git a/lib/awful/rules.lua.in b/lib/awful/rules.lua.in index e344828c..c771df1c 100644 --- a/lib/awful/rules.lua.in +++ b/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 diff --git a/lib/awful/screen.lua.in b/lib/awful/screen.lua.in index ab544780..07a9bc17 100644 --- a/lib/awful/screen.lua.in +++ b/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") diff --git a/lib/gears/timer.lua.in b/lib/gears/timer.lua.in index 2ff3ed03..8d5e57b2 100644 --- a/lib/gears/timer.lua.in +++ b/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) diff --git a/lib/wibox/widget/textbox.lua.in b/lib/wibox/widget/textbox.lua.in index 4ebd31ad..17bc8531 100644 --- a/lib/wibox/widget/textbox.lua.in +++ b/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. bold) +--- Set the text of the textbox (with Pango markup). +-- @param text The text to set. This can contain pango markup (e.g. +--
bold
). 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 diff --git a/luadoc/client.lua b/luadoc/client.lua index c7efcb93..ee56394f 100644 --- a/luadoc/client.lua +++ b/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 diff --git a/luadoc/mouse.lua b/luadoc/mouse.lua index 7c06b62b..153bb49b 100644 --- a/luadoc/mouse.lua +++ b/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 diff --git a/luadoc/root.lua b/luadoc/root.lua index dde12a4b..126e408b 100644 --- a/luadoc/root.lua +++ b/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