From 29d1b473f8703ec83a953c6b5376b190319a54fa Mon Sep 17 00:00:00 2001
From: Daniel Hahler <git@thequod.de>
Date: Mon, 24 Mar 2014 01:01:41 +0100
Subject: [PATCH 1/4] Fix doc for textbox:set_markup

---
 lib/wibox/widget/textbox.lua.in | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/lib/wibox/widget/textbox.lua.in b/lib/wibox/widget/textbox.lua.in
index 4ebd31ad0..17bc85312 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. <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

From 302e698ba8187a203078a610f53930582fe75b40 Mon Sep 17 00:00:00 2001
From: Daniel Hahler <git@thequod.de>
Date: Mon, 2 Feb 2015 11:19:38 +0100
Subject: [PATCH 2/4] minor

---
 lib/awful/screen.lua.in | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lib/awful/screen.lua.in b/lib/awful/screen.lua.in
index ab544780b..07a9bc179 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")

From 47ffb1610c19d2c8cfd7d074d7739033fc345324 Mon Sep 17 00:00:00 2001
From: Daniel Hahler <git@thequod.de>
Date: Sun, 15 Feb 2015 22:26:47 +0100
Subject: [PATCH 3/4] doc: improve meta info / structure for gears.timer

---
 lib/gears/timer.lua.in | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/lib/gears/timer.lua.in b/lib/gears/timer.lua.in
index 2ff3ed036..8d5e57b2a 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)

From 289bc26a3c7b8902d3745f1dd8e3a86c08933cab Mon Sep 17 00:00:00 2001
From: Daniel Hahler <git@thequod.de>
Date: Sun, 15 Feb 2015 22:33:23 +0100
Subject: [PATCH 4/4] 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            |  6 ++++++
 lib/awful/client.lua.in |  2 +-
 lib/awful/rules.lua.in  | 32 ++++++++++++++++----------------
 luadoc/client.lua       |  2 +-
 luadoc/mouse.lua        | 22 ++++++++++++----------
 luadoc/root.lua         |  4 ++--
 6 files changed, 38 insertions(+), 30 deletions(-)

diff --git a/config.ld.in b/config.ld.in
index a29b834ba..cdc011702 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 ab6718853..ffdb390a9 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 e344828cb..c771df1c7 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/luadoc/client.lua b/luadoc/client.lua
index c7efcb93d..ee56394f4 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 7c06b62b5..153bb49b3 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 dde12a4b5..126e408b8 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