doc: Add documentation linting and fix all issues it found.

dbus.c

@@ -19,7 +19,14 @@
  *
  */
 
-/** awesome D-Bus API
+/** A deprecated low-level D-Bus API **DO NOT USE**.
+ *
+ * `lgi.GDBus` is always better. This module will eventually be removed.
+ * If it ever breaks due to an upstream API change, it wont be fixed.
+ *
+ * It still exists for compatibility reasons since some user have used it
+ * in the past.
+ *
  * @author Julien Danjou <julien@danjou.info>
  * @copyright 2008-2009 Julien Danjou
  * @module dbus
@@ -798,10 +805,10 @@ luaA_dbus_disconnect_signal(lua_State *L)
  * @param path A string with the dbus path.
  * @param interface A string with the dbus interface.
  * @param method A string with the dbus method name.
- * @param type_1st_arg type of 1st argument
+ * @param type_1st_arg Type of 1st argument
- * @param value_1st_arg value of 1st argument
+ * @param value_1st_arg Value of 1st argument
- * @param type_2nd_arg type of 2nd argument
+ * @param type_2nd_arg Type of 2nd argument
- * @param value_2nd_arg value of 2nd argument
+ * @param value_2nd_arg Value of 2nd argument
  * ... etc
  * @function emit_signal
  */

docs/05-awesomerc.md.lua

@@ -324,6 +324,8 @@ rc_lua:close()
 
 
 table.insert(output_script, "-- @script rc.lua")
+table.insert(output_script, "-- @usebeautiful beautiful.awesome_icon")
+table.insert(output_script, "-- @usebeautiful beautiful.wallpaper")
 
 rc_script = assert(io.open(rc_script, "w"))
 rc_script:write(table.concat(output_script, "\n"))

docs/common/client_theme.ldoc

@@ -344,6 +344,21 @@
  * @see request::border
  */
 
+/**
+ * The client border width for the fullscreen clients.
+ *
+ * This is the fallback if the more stateful version, like
+ * `beautiful.border_width_fullscreen_urgent` isn't set.
+ *
+ * @beautiful beautiful.border_width_fullscreen
+ * @param integer
+ * @see request::border
+ * @see beautiful.border_width_fullscreen_active
+ * @see beautiful.border_width_fullscreen_normal
+ * @see beautiful.border_width_fullscreen_urgent
+ * @see beautiful.border_width_fullscreen_new
+ */
+
 /**
  * The client opacity for the normal clients.
  *
@@ -391,7 +406,6 @@
  *
  * @beautiful beautiful.opacity_floating_normal
  * @param[opt=1] number
- * @see request::border
  */
 
 /**
@@ -424,6 +438,21 @@
  * @see request::border
  */
 
+/**
+ * The client opacity for the floating clients.
+ *
+ * A number between 0 and 1. This is the fallback if the more stateful
+ * variables, like `beautiful.opacity_floating_new` are not set.
+ *
+ * @beautiful beautiful.opacity_floating
+ * @param[opt=1] number
+ * @see request::border
+ * @see beautiful.opacity_floating_normal
+ * @see beautiful.opacity_floating_active
+ * @see beautiful.opacity_floating_urgent
+ * @see beautiful.opacity_floating_new
+ */
+
 /**
  * The client opacity for the normal maximized clients.
  *
@@ -431,7 +460,6 @@
  *
  * @beautiful beautiful.opacity_maximized_normal
  * @param[opt=1] number
- * @see request::border
  */
 
 /**
@@ -463,6 +491,22 @@
  * @param[opt=1] number
  * @see request::border
  */
+
+/**
+ * The client opacity for the maximized clients.
+ *
+ * A number between 0 and 1. This is the fallback if a more stateful
+ * variable, like `beautiful.opacity_maximized_urgent`, isn't set.
+ *
+ * @beautiful beautiful.opacity_maximized
+ * @param[opt=1] number
+ * @see request::border
+ * @see beautiful.opacity_maximized_normal
+ * @see beautiful.opacity_maximized_active
+ * @see beautiful.opacity_maximized_urgent
+ * @see beautiful.opacity_maximized_new
+ */
+
 /**
  * The client opacity for the normal fullscreen clients.
  *
@@ -470,7 +514,6 @@
  *
  * @beautiful beautiful.opacity_fullscreen_normal
  * @param[opt=1] number
- * @see request::border
  */
 
 /**
@@ -503,4 +546,21 @@
  * @see request::border
  */
 
+/**
+ * The client opacity for the fullscreen clients.
+ *
+ * A number between 0 and 1. This is the fallback if the variables
+ * for more stateful versions, like `beautiful.opacity_fullscreen_urgent`,
+ * are not set.
+ *
+ * @beautiful beautiful.opacity_fullscreen
+ * @param[opt=1] number
+ * @see request::border
+ * @see beautiful.opacity_fullscreen_new
+ * @see beautiful.opacity_fullscreen_urgent
+ * @see beautiful.opacity_fullscreen_active
+ * @see beautiful.opacity_fullscreen_normal
+ */
+
+
 /*

docs/common/notification_rules_index.ldoc

@@ -37,6 +37,7 @@
 --   <tr><td><a href='../core_components/notification.html#auto_reset_timeout'>auto\_reset\_timeout</a></td><td>If the timeout needs to be reset when a property changes</td></tr>
 --   <tr><td><a href='../core_components/notification.html#ignore_suspend'>ignore\_suspend</a></td><td></td></tr>
 --   <tr><td><a href='../core_components/notification.html#clients'>clients</a></td><td>A list of clients associated with this notification</td></tr>
+--   <tr><td><a href='../core_components/notification.html#max_width'>max\_width</a></td><td>The maximum popup width</td></tr>
 --   <tr><td><a href='../core_components/notification.html#app_name'>app\_name</a></td><td>The application name specified by the notification</td></tr>
 --   <tr><td><a href='../core_components/notification.html#widget_template'>widget\_template</a></td><td>The widget template used to represent the notification</td></tr>
 -- </table>

docs/common/wibox.ldoc

@@ -2,7 +2,7 @@
 --
 -- @baseclass wibox
 -- @property border_width
--- @param integer
+-- @tparam[opt=0] integer border_width
 -- @propemits false false
 
 --- Border color.
@@ -25,21 +25,21 @@
 --
 -- @baseclass wibox
 -- @property border_color
--- @param string
+-- @tparam[opt=beautiful.fg_normal] string border_color
 -- @propemits false false
 
 --- On top of other windows.
 --
 -- @baseclass wibox
 -- @property ontop
--- @param boolean
+-- @tparam[opt=false] boolean ontop
 -- @propemits false false
 
 --- The mouse cursor.
 --
 -- @baseclass wibox
 -- @property cursor
--- @param string
+-- @tparam string cursor
 -- @see mouse
 -- @propemits false false
 
@@ -47,7 +47,7 @@
 --
 -- @baseclass wibox
 -- @property visible
--- @param boolean
+-- @tparam boolean visible
 -- @propemits false false
 
 --- The opacity of the wibox, between 0 and 1.
@@ -61,7 +61,7 @@
 --
 -- @baseclass wibox
 -- @property type
--- @param string
+-- @tparam string type
 -- @see client.type
 -- @propemits false false
 
@@ -69,35 +69,35 @@
 --
 -- @baseclass wibox
 -- @property x
--- @param integer
+-- @tparam integer x
 -- @propemits false false
 
 --- The y coordinates.
 --
 -- @baseclass wibox
 -- @property y
--- @param integer
+-- @tparam integer y
 -- @propemits false false
 
 --- The width of the wibox.
 --
 -- @baseclass wibox
 -- @property width
--- @param width
+-- @tparam integer width
 -- @propemits false false
 
 --- The height of the wibox.
 --
 -- @baseclass wibox
 -- @property height
--- @param height
+-- @tparam integer height
 -- @propemits false false
 
 --- The wibox screen.
 --
 -- @baseclass wibox
 -- @property screen
--- @param screen
+-- @tparam screen screen
 -- @propemits true false
 
 ---  The wibox's `drawable`.
@@ -110,14 +110,14 @@
 --- The widget that the `wibox` displays.
 -- @baseclass wibox
 -- @property widget
--- @param widget
+-- @tparam[opt=nil] wibox.widget widget
 -- @propemits true false
 
 --- The X window id.
 --
 -- @baseclass wibox
 -- @property window
--- @param string
+-- @tparam string window
 -- @see client.window
 -- @propemits false false
 
@@ -129,7 +129,7 @@
 --
 -- @baseclass wibox
 -- @property shape_bounding
--- @param surface._native
+-- @tparam surface._native shape_bounding
 -- @propemits false false
 -- @see shape
 
@@ -140,7 +140,7 @@
 --
 -- @baseclass wibox
 -- @property shape_clip
--- @param surface._native
+-- @tparam surface._native shape_clip
 -- @propemits false false
 -- @see shape
 
@@ -152,7 +152,7 @@
 --
 -- @baseclass wibox
 -- @property shape_input
--- @param surface._native
+-- @tparam surface._native shape_input
 -- @propemits false false
 -- @see input_passthrough
 
@@ -174,7 +174,7 @@
 --
 -- @baseclass wibox
 -- @property input_passthrough
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean input_passthrough
 -- @see shape_input
 -- @propemits true false
 
@@ -182,14 +182,15 @@
 --
 -- @baseclass wibox
 -- @property buttons
--- @param buttons_table A table of buttons objects, or nothing.
+-- @tparam table buttons A table of buttons objects, or nothing.
 -- @propemits false false
 
 --- Get or set wibox geometry. That's the same as accessing or setting the x,
 -- y, width or height properties of a wibox.
 --
 -- @baseclass wibox
--- @param A table with coordinates to modify.
+-- @tparam[opt=nil] table|nil geo A table with coordinates to modify. If
+--  nothing is specified, it only returns the current geometry.
 -- @return A table with wibox coordinates and geometry.
 -- @method geometry
 -- @emits property::geometry When the geometry change.
@@ -205,31 +206,12 @@
 -- the side of the screen).
 --
 -- @baseclass wibox
--- @param strut A table with new strut, or nothing
 -- @return The wibox strut in a table.
 -- @method struts
+-- @tparam table struts A table with new strut, or nothing.
 -- @see client.struts
 -- @emits property::struts
 
---- The default background color.
---
--- The background color can be transparent. If there is a
--- compositing manager such as compton, then it will be
--- real transparency and may include blur (provided by the
--- compositor). When there is no compositor, it will take
--- a picture of the wallpaper and blend it.
---
--- @baseclass wibox
--- @beautiful beautiful.bg_normal
--- @param color
--- @see bg
-
---- The default foreground (text) color.
--- @baseclass wibox
--- @beautiful beautiful.fg_normal
--- @param color
--- @see fg
-
 --- Set a declarative widget hierarchy description.
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
 -- @param args An array containing the widgets disposition
@@ -246,8 +228,8 @@
 --
 -- @baseclass wibox
 -- @property bg
--- @tparam c The background to use. This must either be a cairo pattern object,
+-- @tparam[opt=beautiful.bg_normal] color bg The background to use. This
---   nil or a string that gears.color() understands.
+--  must either be a cairo pattern object, nil or a string that gears.color() understands.
 -- @see gears.color
 -- @propemits true false
 -- @usebeautiful beautiful.bg_normal The default (fallback) bg color.
@@ -257,18 +239,17 @@
 -- If `image` is a function, it will be called with `(context, cr, width, height)`
 -- as arguments. Any other arguments passed to this method will be appended.
 --
--- @tparam gears.suface|string|function image A background image or a function.
 -- @baseclass wibox
 -- @property bgimage
+-- @tparam gears.suface|string|function bgimage A background image or a function.
 -- @see gears.surface
 -- @propemits true false
 
 --- The foreground (text) of the wibox.
--- @tparam color c The foreground to use. This must either be a cairo pattern object,
+--
---   nil or a string that gears.color() understands.
 -- @baseclass wibox
 -- @property fg
--- @param color
+-- @tparam[opt=beautiful.fg_normal] gears.color fg
 -- @see gears.color
 -- @propemits true false
 -- @usebeautiful beautiful.fg_normal The default (fallback) fg color.

docs/common/widget.ldoc

@@ -19,23 +19,23 @@
 -- Warning: This method it prone to stack overflow id the widget, or any of its
 -- children, contain (directly or indirectly) itself.
 -- @property all_children
--- @tparam table children The children.
+-- @tparam table all_children The children.
 -- @baseclass wibox.widget
 
 --- Set a declarative widget hierarchy description.
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
--- @param args An array containing the widgets disposition
+-- @tparam table args An array containing the widgets disposition
 -- @method setup
 -- @baseclass wibox.widget
 
 --- Force a widget height.
 -- @property forced_height
--- @tparam number|nil height The height (`nil` for automatic)
+-- @tparam number|nil forced_height The height (`nil` for automatic)
 -- @baseclass wibox.widget
 
 --- Force a widget width.
 -- @property forced_width
--- @tparam number|nil width The width (`nil` for automatic)
+-- @tparam number|nil forced_width The width (`nil` for automatic)
 -- @baseclass wibox.widget
 
 --- The widget opacity (transparency).
@@ -45,7 +45,7 @@
 
 --- The widget visibility.
 -- @property visible
--- @param boolean
+-- @tparam[opt=true] boolean visible
 -- @baseclass wibox.widget
 
 --- The widget buttons.
@@ -53,7 +53,7 @@
 -- The table contains a list of `awful.button` objects.
 --
 -- @property buttons
--- @param table
+-- @tparam table buttons
 -- @see awful.button
 -- @baseclass wibox.widget
 
@@ -96,7 +96,7 @@
 -- @tparam number button The button number.
 -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -127,7 +127,7 @@
 -- @tparam number button The button number.
 -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -152,7 +152,7 @@
 -- @signal mouse::enter
 -- @tparam table self The current object instance itself.
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -177,7 +177,7 @@
 -- @signal mouse::leave
 -- @tparam table self The current object instance itself.
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.

docs/config.ld

@@ -1,24 +1,27 @@
 local args = ...
+local ldoc = nil
 
+-- luacheck: globals new_type
 
 -- Configuration file for ldoc
 
-project='awesome'
+project='awesome' -- luacheck: globals project
-title='awesome API documentation'
+title='awesome API documentation'  -- luacheck: globals title
-description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).'
+description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).'  -- luacheck: globals description
 
--- More on it: https://github.com/stevedonovan/LDoc/blob/master/doc/doc.md#markdown-support
+format='discount'  -- luacheck: globals format
-format='discount'
+dir='../doc'  -- luacheck: globals dir
-dir='../doc'
 
 -- Make the docs prettier
-pretty='lua'
+pretty='lua'  -- luacheck: globals pretty
-style=true
+style=true  -- luacheck: globals style
-template=true
+template=true  -- luacheck: globals template
-backtick_references=true
+backtick_references=true  -- luacheck: globals backtick_references
-merge=true
+merge=true  -- luacheck: globals merge
-use_markdown_titles=true
+use_markdown_titles=true  -- luacheck: globals use_markdown_titles
-wrap=true
+wrap=true  -- luacheck: globals wrap
+
+ -- luacheck: globals full_description
 full_description = [[
 Welcome to the documentation for the Awesome window manager. Below you find an
 overview of the individual parts which links to the full documentation.
@@ -92,52 +95,327 @@ topics={
     '89-NEWS.md',
 }
 
+local databases, named_tags, item_id, is_init = {}, {}, 1, false
+local all_theme_vars, delayed_collect = nil, {}
+
+local function collect_item_common(tab, mod, item)
+    tab[item.name] = tab[item.name] or {}
+
+    local var = tab[item.name]
+    var[mod.name] = var[mod.name] or {}
+    var[mod.name][#var[mod.name] + 1] = item
+end
+
+--- Add another custom tag **value** to an existing item.
+-- @tparam string tag_data The raw/unparsed string for the
+--  tag. It will be parsed like any other tags.
+local function add_custom_tag_common(item, tag_name, meta_tag, tag_data)
+    item.tags = item.tags or {}
+
+    item.tags[tag_name] = item.tags[tag_name] or {}
+
+    item.tags[tag_name][#item.tags[tag_name] + 1] = tag_data
+
+    if meta_tag.collect_callback then
+        delayed_collect[#delayed_collect+1] = {item, item.module, tag_name, tag_data}
+    end
+end
+
+-- Wrap the global `new_type` to allow us to extend what types can do, the
+-- same is done below for custom tags.
+local function create_type(args)
+    new_type(args.name, args.title, args.project_level, args.subfield_title)
+
+    databases[args.name] = databases[args.name] or {}
+    databases[args.name].collect = args.collect_callback
+    databases[args.name].finish  = args.finish_callback
+
+    return args
+end
+
+-- Add the @usebeautiful from the optional/default value.
+local function auto_add_usebeautiful(item)
+        local vars, var_names = {}, {}
+
+        -- Datamine the default values to autogenerate the @usebeautiful.
+        for parm in ldoc.modules.iter(item.params) do
+            for p in ldoc.modules.iter(item:subparam(parm)) do
+                local def = item:default_of_param(p)
+
+                if def and def ~= true then
+                    for var in def:gmatch("beautiful[.][a-z_]+") do
+                        if not var_names[var] then
+                            vars[#vars+1] = var
+                        end
+                        var_names[var] = true
+                    end
+                end
+            end
+        end
+
+        for _, var in ipairs(vars) do
+            named_tags.usebeautiful:add_to_item(item, var)
+        end
+    end
+
 -- The first stereotype are the constructors.
-new_type("constructorfct", "Constructors", false, "Parameters")
+create_type  {
-new_type("constructorfct2", "ldoc_skip", false, "Parameters")
+    name             = "constructorfct",
+    title            = "Constructors",
+    project_level    = false,
+    subfield_title   = "Parameters",
+    collect_callback = auto_add_usebeautiful,
+}
+
+-- Some constructors like `awful.key` have both a named parameter
+-- syntax and a multiple function parameter syntax.
+create_type {
+    name           = "constructorfct2",
+    title          = "ldoc_skip",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- Hack to get the functions on top of the signals and properties
-new_type("function", "Functions", false, "Parameters")
+create_type {
+    name           = "function",
+    title          = "Functions",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- For "classes", use an explicit type for static functions. This allows
 -- @function and its implicit cousin to be banned in the CI.
-new_type("staticfct", "Static module functions", false, "Parameters")
+create_type {
+    name           = "staticfct",
+    title          = "Static module functions",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- Documentation for objects properties
-new_type("property", "Object properties", false, "Type constraints")
+create_type {
+    name             = "property",
+    title            = "Object properties",
+    project_level    = false,
+    subfield_title   = "Type constraints",
+    collect_callback = auto_add_usebeautiful,
+    finish_callback  = function(item)
+        -- All properties need to have a type. Otherwise they don't render
+        -- properly. Also, because typed properties are kind of the point of
+        -- switching to ldoc in the first place.
+        if (not item.params) or not item.params[1] then
+            print(
+                "WARNING: The ".. item.name .." property from "..item.module.name.." is missing it's type."
+            )
+            return
+        end
+
+        local param = item:subparam(item.params[1])
+        local type  = item:type_of_param(param[1])
+
+        -- Force people to use @tparam because it is easier to lint and allows
+        -- multiple types.
+        if (not type) or type == "" then
+            print(
+                "WARNING: Property ".. item.name .." from "..item.module.name.." either "..
+                " doesn't have a type or uses @param instead of @tparam. @tparam is required"..
+                " because it allows multi-type and better default value handling."
+            )
+        end
+
+        -- One of the repeated problem we have is the first word of the
+        -- description being removed because it is used as the property name.
+        -- This "rule" might be stupid, but it prevents it from accidentally
+        -- happening again.
+        if item.params[1] ~= item.name:match("[.]?("..item.params[1]..")$") then
+            print(
+                "WARNING: Property ".. item.name .." from "..item.module.name.." @tparam name"..
+                " doesn't match the property name. For linting purpose, please fix this."
+            )
+        end
+    end
+}
+
 -- Documentation for objects deprecated properties
-new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints")
+create_type {
+    name           = "deprecatedproperty",
+    title          = "Deprecated object properties",
+    project_level  = false,
+    subfield_title = "Type constraints",
+}
+
 -- Documentation for objects deprecated methods
-new_type("deprecatedmethod", "Deprecated object methods", false, "Parameters")
+create_type {
+    name           = "deprecatedmethod",
+    title          = "Deprecated object methods",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- Use a custom type for the methods to bypass the faulty ldoc built-in detection.
 -- (yes, the space after Methods *is* on purpose to avoid clashing with ldoc
 --  internal "methods" concept)
-new_type("method", "Object methods ", false, "Parameters")
+create_type {
--- New type for signals
+    name           = "method",
-new_type("signal", "Signals", false, "Arguments")
+    title          = "Object methods ",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
+-- New type for signals.
+local all_signals
+all_signals = create_type {
+    name           = "signal",
+    title          = "Signals",
+    project_level  = false,
+    subfield_title = "Arguments",
+    collection     = {},
+    collect_callback = function(item, mod)
+        collect_item_common(all_signals.collection, mod, item)
+    end,
+}
+
 -- Deprecated signals.
-new_type("deprecatedsignal", "Deprecated signals", false, "Arguments")
+create_type {
+    name           = "deprecatedsignal",
+    title          = "Deprecated signals",
+    project_level  = false,
+    subfield_title = "Arguments",
+}
+
 -- New type for signals connections
-new_type("signalhandler", "Request handlers", false, "Arguments")
+create_type {
+    name           = "signalhandler",
+    title          = "Request handlers",
+    project_level  = false,
+    subfield_title = "Arguments",
+}
+
 -- Allow objects to define a set of beautiful properties affecting them
-new_type("beautiful", "Theme variables", false, "Type constraints")
+all_theme_vars = create_type {
+    name           = "beautiful",
+    title          = "Theme variables",
+    project_level  = false,
+    subfield_title = "Type constraints",
+    collection     = {},
+    collect_callback = function(item, mod)
+        if item.name:sub(1,4) ~= "beau" then
+            -- This would be a bug.
+            if item.name:match("[.]") then
+                print("WANRING: A beautiful variable is called `", item.name, "`. This name is invalid.")
+            end
+
+            -- This happens because the `ldoc` messes with the name. All variables
+            if item.module.name == "beautiful" then
+                item.name = "beautiful." .. item.name
+            else
+                print(
+                    "WARNING: All theme variable need a `beautiful.` prefix. It appears",
+                    item.name,
+                    " lacks it"
+                )
+            end
+        end
+
+        collect_item_common(all_theme_vars.collection, mod, item)
+
+        -- Those are global variables, there can be only one per name.
+        if all_theme_vars.collection[item.name] then
+            local mod = pairs(all_theme_vars.collection[item.name])(all_theme_vars.collection[item.name])
+
+            if mod ~= item.module.name then
+                print("ERROR: "..item.name, "from", item.module.name, "is already defined in module ", mod)
+            end
+        end
+    end,
+    finish_callback = function(item)
+        if item.tags["beautiful_used_by"] then return end
+
+        -- Every variable should be consumed by something. Better "park" some
+        -- variable in the constructors than leave them disconnected from the
+        -- global model.
+        print("WARNING: ", item.name, "is not used by anything, add @usebeautiful or @propbeautiful")
+    end
+}
+
 -- Put deprecated methods in their own section
-new_type("deprecated", "Deprecated functions", false, "Parameters")
+create_type {
+    name           = "deprecated",
+    title          = "Deprecated functions",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- For the legacy stateless layout related functions
-new_type("legacylayout", "Layout related functions", false, "Parameters")
+create_type {
+    name           = "legacylayout",
+    title          = "Layout related functions",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- Have a category for the client layouts
-new_type("clientlayout", "Client layouts", false, "Parameters")
+create_type {
+    name           = "clientlayout",
+    title          = "Client layouts",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- Source functions for the taglist/tasklist/layoutlist
-new_type("sourcefunction", "List source functions", false)
+create_type {
+    name          = "sourcefunction",
+    title         = "List source functions",
+    project_level = false,
+}
+
 -- Document some callback prototypes
-new_type("callback", "Callback functions prototype", false, "Parameters")
+create_type {
+    name           = "callback",
+    title          = "Callback functions prototype",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- gears.matcher / awful.rules sources
-new_type("rulesources", "Rule sources", false, "Parameters")
+create_type {
+    name           = "rulesources",
+    title          = "Rule sources",
+    project_level  = false,
+    subfield_title = "Parameters",
+}
+
 -- gears.matcher / awful.rules rule components
-new_type("rulecomponent", "Rule components", false, "Type")
+create_type {
+    name           = "rulecomponent",
+    title          = "Rule components",
+    project_level  = false,
+    subfield_title = "Type",
+}
+
 -- Filter functions for the taglist/tasklist/layoutlist
-new_type("filterfunction", "List filters", false)
+create_type {
+    name          = "filterfunction",
+    title         = "List filters",
+    project_level = false,
+}
+
 -- Extra client properties available only in awful.rules/spawn constructs
-new_type("clientruleproperty", "Extra properties available in the rules", false, "Type")
+create_type {
+    name           = "clientruleproperty",
+    title          = "Extra properties available in the rules",
+    project_level  = false,
+    subfield_title = "Type",
+}
+
 -- Extra *matching* properties for rules.
-new_type("matchingproperty", "Extra matching properties used in rules", false, "Type")
+create_type {
+    name           = "matchingproperty",
+    title          = "Extra matching properties used in rules",
+    project_level  = false,
+    subfield_title = "Type",
+}
 
 -- Simulate the default "params" parser format, except the optional "[]" section
 -- needs a space.
@@ -224,15 +502,17 @@ local function default_format_callback(self, params, _, md)
 end
 
 -- Generate a format function.
-local function default_format(self, callback)
+local function default_format(self, callback, name)
     return function(raw, item, md)
-        return (callback or default_format_callback)(
+        local p = name and item.parsed_tags and item.parsed_tags[name] and item.parsed_tags[name][raw]
-            self, parse_custom_tags(raw, self.params or {}), item, md
+
-        )
+        if not p then
-    end
+            p = parse_custom_tags(raw, self.params or {})
         end
 
-local named_tags, item_id = {}, 1
+        return (callback or default_format_callback)(self, p, item, md)
+    end
+end
 
 -- Add a new @something which can be used in any types.
 -- @tparam table args
@@ -250,9 +530,26 @@ add_custom_tag = function(args)
 
     custom_tags = custom_tags or {}
 
+    databases[name] = databases[name] or {}
+    databases[name].collect = args.collect_callback
+
     local f = args.format
 
-    args.format = default_format(args, f)
+    args.format = default_format(args, f, name)
+
+    function args:add_to_item(item, tag_value)
+        add_custom_tag_common(item, name, args, tag_value)
+
+        local parsed = parse_custom_tags(tag_value, args.params or {})
+
+        if parsed then
+            item.parsed_tags = item.parsed_tags or {}
+            item.parsed_tags[name] = item.parsed_tags[name] or {}
+            item.parsed_tags[name][tag_value] = parsed
+        end
+
+        item.has_show_more = item.has_show_more or (not args.hidden)
+    end
 
     custom_tags[#custom_tags+1] = args
     named_tags[name] = args
@@ -288,7 +585,17 @@ add_custom_tag {
         {
             name = "name"
         }
-    }
+    },
+    collect_callback = function(item, mod, tag, value)
+        local parsed = parse_custom_tags(value, named_tags.emits.params)
+
+        all_signals.collection[parsed.name.value] = all_signals.collection[parsed.name.value] or {}
+
+        local var = all_signals.collection[parsed.name.value]
+
+        var[mod.name] = var[mod.name] or {}
+        var[mod.name][#var[mod.name] + 1] = item
+    end
 }
 
 -- Avoid repetitive boilerplate code for property signals.
@@ -349,7 +656,25 @@ add_custom_tag {
             name     = "name",
             markdown = true,
         }
-    }
+    },
+    collect_callback = function(item, mod, tag, value)
+        local params = parse_custom_tags(value, named_tags.usebeautiful.params)
+
+        if all_theme_vars.collection[params.name.value] then
+            local sig_mods = all_theme_vars.collection[params.name.value]
+            local _, themed_items = pairs(sig_mods)(sig_mods)
+            local themed_item = themed_items[1]
+
+            named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary)
+
+            -- Auto fill the description if its empty.
+            if (not params.description) or params.description == "" then
+                params.description = themed_item.summary
+            end
+        else
+            print("WARNING: Could not find theme variable", params.name.value)
+        end
+    end
 }
 
 -- For all properties which have a standard `@beautiful` variable for them
@@ -380,6 +705,18 @@ add_custom_tag {
         end
 
         return ret
+    end,
+    finish_callback = function(item, raw, params, modules)
+        local modname = item.module.name:gmatch("[^.]+$")()
+        local name = "beautiful."..(modname.."_"..item.name):gsub("[.]", "_")
+
+        if all_theme_vars.collection[name] then
+            local sig_mods = all_theme_vars.collection[name]
+            local _, themed_items = pairs(sig_mods)(sig_mods)
+            local themed_item = themed_items[1]
+
+            named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary)
+        end
     end
 }
 
@@ -476,7 +813,6 @@ add_custom_tag {
 add_custom_tag {
     name = "hidden",
     hidden = true,
-    auto_subtags = false
 }
 
 -- Mark the item as readonly.
@@ -487,6 +823,87 @@ add_custom_tag {
     hidden = true,
     auto_subtags = false
 }
+
+add_custom_tag {
+    name   = "signalhandler",
+    hidden = false,
+    title  = "Request handler",
+    auto_subtags = false,
+    params = {
+        { name = "source" },
+    },
+    format = function(self, params, item, md)
+        return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description
+    end
+}
+
+add_custom_tag {
+    name = "beautiful_used_by",
+    hidden = false,
+    title = "Used by",
+    auto_subtags = false,
+    params = {
+        { name = "source" },
+    },
+    format = function(self, params, item, md)
+        return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description
+    end
+}
+
+-- Auto generate some code for replacing request handlers.
+add_custom_tag {
+    name   = "sourcesignal",
+    title  = "Source signal",
+    hidden = false,
+    params = {
+        { name = "class"   },
+        { name = "signal"  },
+    },
+    format  = function(self, params, item, md)
+        return ldoc.markup("`"..params.signal.value.."` from the `"..params.class.value.."` module.")..
+            " This code allows to disconnect this handler and implement your own:"
+    end,
+    finish_callback = function(item, raw, params, modules)
+        if all_signals.collection[params.signal.value] then
+            local sig_mods = all_signals.collection[params.signal.value]
+            local _, signal_items = pairs(sig_mods)(sig_mods)
+            local signal_item = signal_items[1]
+
+            -- Auto generate some code.
+            local code = "-- Disconnect the original handler.\n"
+            code = code .. signal_item.module.name .. ".disconnect_signal('".. params.signal.value .."', "..item.name..")\n\n"
+            code = code .. "-- Connect a custom handler.\n"
+            code = code .. signal_item.module.name .. ".connect_signal('".. params.signal.value .."', function("
+
+
+            if signal_item.type == "signal" then
+                for idx, parm in ipairs(signal_item.params) do
+                    code = code .. parm .. (idx == #signal_item.params and "" or ", ")
+                end
+
+                code = code .. ")\n    -- code here\nend)"
+
+                named_tags.signalhandler:add_to_item(signal_item, item.name.." "..item.summary)
+            end
+
+            item.tag_extra_data = item.tag_extra_data or {}
+            item.tag_extra_data["sourcesignal"] = item.tag_extra_data["sourcesignal"] or {}
+            item.tag_extra_data["sourcesignal"][raw] = item.tag_extra_data["sourcesignal"][raw] or {}
+            item.tag_extra_data["sourcesignal"][raw].usage = ldoc.prettify(code)
+
+            item.has_show_more = true
+        end
+    end
+}
+
+-- @rangestart
+-- @rangeend
+-- @minimumvalue
+-- @maximumvalue
+-- @tenumvalue
+-- @increments
+-- @tablekey or not?
+
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries', script='Sample files'}
 
@@ -514,7 +931,6 @@ file = {
     '../selection.c',
     '../spawn.c',
     '../xkb.c',
-    '../common/luaobject.c',
     '../objects/client.c',
     '../objects/drawable.c',
     '../objects/screen.c',
@@ -573,6 +989,7 @@ file = {
         '../lib/wibox/layout/rotate.lua',
         '../lib/wibox/layout/scroll.lua',
         '../lib/wibox/widget/background.lua',
+        '../lib/wibox/drawable.lua',
     }
 }
 
@@ -588,7 +1005,13 @@ local named_args = {
     [ "(args)"                                     ] = true,
     [ "([args])"                                   ] = true,
     [ "([args=nil])"                               ] = true,
-    [ "([args={}])"  ] = true
+    [ "([args={}])"                                ] = true,
+    [ '(<span class="optional_param">args</span>)' ] = true,
+}
+
+local param_name_whitelist = {
+    Mod2 = true,
+    Lock = true,
 }
 
 -- Sections which are hidden by default, but visible when clicked.
@@ -607,6 +1030,27 @@ local delimiter_for_tag = {
     usebeautiful  = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}},
     propbeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}},
     request       = { "table class='widget_list' border=1", "table", "tr", "tr", {"Class", "Permission", "Context", "Default", "Description"}},
+    sourcesignal  = { "div", "div", "span", "span" }
+}
+
+--- If the title is short and descritive, there is no point to bloat it.
+--
+-- That test is mostly to catch empty or lazy description (such as the module
+-- name and nothing else).
+local short_title_whitelist = {
+    [ "rc.lua"                  ] = true,
+    [ "naughty.action"          ] = true,
+    [ "naughty.layout.box"      ] = true,
+    [ "naughty.widget.title"    ] = true,
+    [ "theme.lua"               ] = true,
+    [ "wibox.container.margin"  ] = true,
+    [ "wibox.container.arcchart"] = true,
+    [ "wibox.widget.checkbox"   ] = true,
+    [ "wibox.widget.imagebox"   ] = true,
+    [ "wibox.widget.separator"  ] = true,
+    [ "wibox.widget.progressbar"] = true,
+    [ "naughty"                 ] = true,
+    [ "xproperties"             ] = true,
 }
 
 -- Use the first word of the subtag content to map it to its tag.
@@ -636,7 +1080,7 @@ local function generate_summary(item)
         end
     end
 
-    local ret, has_show_more = {}, false
+    local ret, has_show_more = {}, item.has_show_more or false
 
     for k, v in ipairs(tgs) do
         if v.count > 0 then
@@ -719,20 +1163,26 @@ local function init_custom_types(item)
 
     -- Allow the template to fetch the right sub-tags.
     function item.get_auto_params(tag, value)
+        local extra = (item.tag_extra_data and item.tag_extra_data[tag] and item.tag_extra_data[tag][value]) or {}
+
         -- Makes auto-generated subtags easier to implement.
         if item.auto_params[tag.."tparam_override"] then
-            return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"]
+            return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"], extra
         end
 
-        if not item.auto_params[tag.."tparam"] then return nil, nil end
+        local parsed = nil
 
-        local parsed = parse_custom_tags(value, named_tags[tag].params)
+        if item.parsed_tags and item.parsed_tags[tag] and item.parsed_tags[tag][value] then
+            parsed = item.parsed_tags[tag][value]
+        end
+
+        if not item.auto_params[tag.."tparam"] then return nil, nil, extra end
 
         if parsed.name and item.auto_params[tag.."tparam"][parsed.name.value] then
-            return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"]
+            return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"], extra
         end
 
-        return nil, nil
+        return nil, nil, extra
     end
 
     item.is_init = true
@@ -780,8 +1230,7 @@ local function pipe_to_or(s)
 end
 
 -- Parse the magic parameters to type in something the template eats.
-local function sanitize_type(item, ldoc)
+local function sanitize_type(item)
-
     for parm in ldoc.modules.iter(item.params) do
         local t = item:type_of_param(parm)
 
@@ -810,9 +1259,37 @@ local function sanitize_type(item, ldoc)
     item.display_type = "<span class='summary_type'>N/A</span>"
 end
 
+-- Detect error prone markdown formatting.
+local function detect_markdown_footguns(string)
+    for line in string:gmatch("[^\n]*") do
+        if line:sub(1,4) ~= "    " then
+            local is_tick = false
+
+            -- Detect unquoted code with 2 underscores. They will render as italic,
+            -- which is definitively not wanted. Add "`" to fix.
+            for part in line:gmatch("[^`]*") do
+                if not is_tick then
+                    local count = 0
+
+                    for under in part:gmatch("[^\\]_") do
+                        count = count + 1
+                    end
+
+                    if count > 1 then
+                        return false
+                    end
+                end
+
+                is_tick = not is_tick
+            end
+        end
+    end
+
+    return true
+end
 
 -- Add parentheses when there is alternative return types.
-local function generate_return_tuple(item, group, ldoc)
+local function generate_return_tuple(item, group)
     local tuple = {}
 
     for r in group:iter() do
@@ -843,7 +1320,7 @@ local function generate_return_tuple(item, group, ldoc)
 end
 
 -- Create a return type string.
-local function sanitize_return_type(item, ldoc)
+local function sanitize_return_type(item)
 
     local groups = item.retgroups
 
@@ -870,6 +1347,164 @@ local function sanitize_return_type(item, ldoc)
     item.compact_signature = true
 end
 
+-- Traverse the entire doc and reverse-map the links between our custom
+-- tags and the content it is pointing toward. From that, we add some
+-- "consumers"/"providers" tables to each (relevant) item.
+local function global_init(_ldoc)
+    ldoc = _ldoc
+
+    if is_init then return end
+    is_init = true
+
+    local module_by_name = {}
+
+    -- First pass, gather the providers.
+    for _, mod in ipairs(ldoc.modules) do
+        module_by_name[mod.name] = mod
+
+        if mod.type ~= "topic" and ((not mod.summary) or mod.summary == "" or mod.summary:lower():sub(1,8) == "awesome") then
+            print("WARNING: Each module needs a good summary as its first line", mod.name, "doesn't")
+        end
+
+        local sum_count = 0
+
+        for line in (mod.summary or ""):gmatch("[^\n]*") do
+            sum_count = sum_count + 1
+        end
+
+        if sum_count > 1 and #mod.summary > 120 then
+            print("WARNING:", mod.name, "summary has to be only 1 line.")
+        end
+
+        if mod.summary and #mod.summary < 30 and not short_title_whitelist[mod.name] then
+            print("WARNING:", mod.name, "summary is too short.")
+        end
+
+        for tag, values in pairs(mod.tags) do
+            for _, value in ipairs(values.gmatch and {values} or values) do
+                -- Collect instances of some types.
+                if databases[tag] and databases[tag].collect then
+                    delayed_collect[#delayed_collect+1] = {mod, mod, tag, value}
+                end
+            end
+        end
+
+        for kind, items in mod.kinds() do
+            for item in items() do
+                -- Decorate the item with our customizations.
+                init_custom_types(item)
+
+                -- print(item.description)
+
+                if item.summary and not detect_markdown_footguns(item.summary) then
+                    print(
+                        "WARNING: "..item.name.." from "..item.module.name.." seems to have"..
+                        " ambiguous markdown in its summary, probably underscores. Please either"..
+                        " use '`' or HTML."
+                    )
+                end
+
+                -- Collect instances of some types.
+                if databases[item.type] and databases[item.type].collect then
+                    databases[item.type].collect(item, mod)
+                end
+
+                for tag, values in pairs(item.tags) do
+                    for _, value in ipairs(values.gmatch and {values} or values) do
+                        -- Collect instances of some types.
+                        if databases[tag] and databases[tag].collect then
+                            delayed_collect[#delayed_collect+1] = {item, mod, tag, value}
+                        end
+                    end
+                end
+
+                -- Lint the parameters too.
+                for parm in ldoc.modules.iter(item.params) do
+                    local first = parm:match("^[ ]*(.)")
+
+                    -- If the first letter of a parameter is capital, the type is probably missing.
+                    -- That's what happen if you rename @param to @tparam without actually adding the type.
+                    if first and first ~= first:lower() and parm:upper() ~= parm and not param_name_whitelist[parm] then
+                        print(
+                            "ERROR: Parameter "..parm.." from ".. item.name .. " ".. item.module.name..
+                            " starts with a capital letter. This is forbidden."
+                        )
+                    end
+
+                    for p in ldoc.modules.iter(item:subparam(parm)) do
+                        local desc = item.params.map[p]
+
+                        if not detect_markdown_footguns(desc) then
+                            print(
+                                "WARNING: Always use '`' to encapsulate code in the parameters." ..
+                                p .. " from " .. item.name .. " " .. item.module.name .. " contains " ..
+                                "some ambiguous markup. If this is a false positive, use HTML."
+                            )
+                        end
+
+                        -- It *sometime* works, but is at risk if being  interpreted as code by markdown.
+                        if desc:match("^ [ ]+") then
+                            print(
+                                "WARNING: ", item.name, "from", item.module.name, "has a parameter description "..
+                                "with leading spaces. This will not render correctly", "'"..desc.."'"
+                            )
+                        end
+
+                        first = desc:match("^[ ]*([a-z])")
+
+                        if first and first ~= first:upper() then
+                            print("WARNING: Sentences starts with a capital letter. Please fix", item.module.name, item.name)
+                        end
+
+                        --TODO convert @propbeautiful to @usebeautiful and lint them
+                        --TODO check the module summary.
+                    end
+                end
+            end
+        end
+    end
+
+    -- Second pass, collect the custom tags. This is delayed because
+    -- the tags depend on the items. Not all items have been processed if
+    -- this was called during the first pass. Also, collect callbacks can
+    -- themselves create more delayed_collect entries recursively.
+    for _, to_collect in ipairs(delayed_collect) do
+        databases[to_collect[3]].collect(to_collect[1], to_collect[2], to_collect[3], to_collect[4])
+    end
+
+    -- Third pass, parse every custom tags and fill the consumers tables.
+    for _, mod in ipairs(ldoc.modules) do
+        for kind, items in mod.kinds() do
+            for item in items() do
+                for tag_name, values in pairs(item.tags) do
+                    for _, tag in ipairs(values.gmatch and {values} or values) do
+                        local parsed = named_tags[tag_name]
+                            and named_tags[tag_name].params
+                            and parse_custom_tags(tag, named_tags[tag_name].params)
+
+                        -- Allow the tags to, ie, auto-generate some extra content.
+                        if named_tags[tag_name] and named_tags[tag_name].finish_callback then
+                            named_tags[tag_name].finish_callback(item, tag, parsed, module_by_name)
+                        end
+
+                        -- Save the parsed content to be used in get_auto_params.
+                        if parsed then
+                            item.parsed_tags = item.parsed_tags or {}
+                            item.parsed_tags[tag_name] = item.parsed_tags[tag_name] or {}
+                            item.parsed_tags[tag_name][tag] = parsed
+                        end
+                    end
+                end
+
+                -- Mostly for linting.
+                if databases[item.type] and databases[item.type].finish then
+                    databases[item.type].finish(item, mod, module_by_name)
+                end
+            end
+        end
+    end
+end
+
 -- Work around the fact that tag/awful.tag client/awful.client pages
 -- are merged.
 local function compare_module_name(input, module)
@@ -956,6 +1591,8 @@ local is_deprecated = {
 }
 
 custom_display_name_handler = function(item, default_handler)
+    item.global_init = global_init
+
     if is_deprecated[item.type] then
         item.tags.is_deprecated = {true}
     end

docs/ldoc.css

@@ -190,11 +190,11 @@ span.default_value,
     border-bottom: solid 1px #bcd;
 }
 
-#content pre {
+#content pre, .auto_genenerated_code {
     margin: 15px;
 }
 
-pre {
+pre, .auto_genenerated_code {
     background-color: rgb(50, 55, 68);
     color: white;
     border-radius: 3px;

docs/ldoc.ltp

@@ -37,6 +37,15 @@
 # local no_underscores = function(s) return s:gsub("_", " ") end
 # local get_item = function(mod, name) for item in iter(mod.items) do if item.name == name then return item end end; return name == "" and mod or nil end
 
+# -- Poke a hole to allow config.ld code to have a global initialization.
+# for m in iter(ldoc.modules) do
+#    if #m.items > 0 then
+#      display_name(m.items[1])
+#      m.items[1].global_init(ldoc)
+#      break
+#    end
+# end
+
 # --------- modules hierarchy -------------
 # local hierarchy = {}
 # local curr = module
@@ -532,7 +541,7 @@
 #       end -- if group_header then
 #       for value in iter(tag) do
           <$(row_type_begin)>$(custom.format and custom.format(value, item, M) or M(value))</$(row_type_end)>
-#         local sub_values, sub_custom = item.get_auto_params(custom[1], value)
+#         local sub_values, sub_custom, extra_data = item.get_auto_params(custom[1], value)
 #         if sub_values then
            <ul>
 #          for _, value in ldoc.ipairs(sub_values) do
@@ -540,6 +549,12 @@
 #          end -- for auto_params
            </ul>
 #         end -- if item.auto_params
+#          if extra_data.usage then
+           <br/>
+           <p>
+           <pre class="auto_genenerated_code">$(extra_data.usage)</pre>
+#          end -- extra_data.usage
+
 #       end -- for
      </$(group_end)>
 #      end -- if tag

lib/awful/button.lua

@@ -70,38 +70,39 @@ button.names = {
 -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock).
 --
 -- @property modifiers
+-- @tparam table modifiers
 
 --- The mouse button identifier.
 --
 -- ![Mouse buttons](../images/mouse.svg)
 --
 -- @property button
--- @param integer
+-- @tparam integer button
 
 --- The button description.
 --
 -- @property description
--- @param string
+-- @tparam string description
 
 --- The button name.
 --
 -- @property name
--- @param string
+-- @tparam string name
 
 --- The button group.
 --
 -- @property group
--- @param string
+-- @tparam string group
 
 --- The callback when this button is pressed.
 --
 -- @property on_press
--- @param function
+-- @tparam function on_press
 
 --- The callback when this button is released.
 --
 -- @property on_release
--- @param function
+-- @tparam function on_release
 
 --- Execute this mousebinding.
 -- @method :trigger

lib/awful/client.lua

@@ -157,7 +157,7 @@ client.focus = require("awful.client.focus")
 --
 -- @deprecated awful.client.jumpto
 -- @see client.jump_to
--- @tparam client c the client to jump to
+-- @tparam client c The client to jump to
 -- @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 and its first
@@ -1153,7 +1153,7 @@ end
 -- @DOC_screen_wfact4_EXAMPLE@
 --
 -- @legacylayout awful.client.idx
--- @tparam client c the client
+-- @tparam client c The client
 -- @treturn table data A table with "col", "idx" and "num" keys.
 -- @treturn integer data.col The column number.
 -- @treturn integer data.idx Index of the client in the column.
@@ -1224,8 +1224,8 @@ end
 -- @DOC_screen_wfact3_EXAMPLE@
 --
 -- @legacylayout awful.client.setwfact
--- @tparam number wfact the window factor value
+-- @tparam number wfact The window factor value
--- @tparam client c the client
+-- @tparam client c The client
 -- @emits property::windowfact Emitted on the c.first_tag object.
 -- @see tag.master_width_factor
 function client.setwfact(wfact, c)
@@ -1291,7 +1291,7 @@ end
 -- @tparam number add Amount to increase/decrease the client's window factor by.
 --   Should be between `-current_window_factor` and something close to
 --   infinite. Normalisation then ensures that the sum of all factors is 1.
--- @tparam[opt=client.focus] client c the client.
+-- @tparam[opt=client.focus] client c The client.
 -- @emits property::windowfact
 function client.incwfact(add, c)
     c = c or capi.client.focus
@@ -1462,10 +1462,10 @@ end
 -- Starting from the client in focus or the given index, all clients that match
 -- a given criteria.
 --
--- @tparam function filter a function that returns true to indicate a positive match.
+-- @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
+-- @tparam integer start What index to start iterating from.  Defaults to using the
 --   index of the currently focused client.
--- @tparam[opt=nil] screen s which screen to use.  nil means all screens.
+-- @tparam[opt=nil] screen s Which screen to use.  nil means all screens.
 --
 -- @staticfct awful.client.iterate
 -- @usage -- un-minimize all urxvt instances
@@ -1487,8 +1487,8 @@ end
 -- If multiple clients match the given condition then the next one is
 -- focused.
 --
--- @tparam string cmd the command to execute
+-- @tparam string cmd The command to execute
--- @tparam function matcher a function that returns true to indicate a matching client
+-- @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.
@@ -1611,7 +1611,7 @@ end, true, true, "keybinding")
 -- @DOC_awful_client_shape1_EXAMPLE@
 --
 -- @property shape
--- @tparam gears.shape A gears.shape compatible function.
+-- @tparam gears.shape shape A gears.shape compatible function.
 -- @propemits true false
 -- @see gears.shape
 function client.object.set_shape(self, shape)
@@ -1811,6 +1811,7 @@ end)
 
 --- Emitted when a client need to get a titlebar.
 -- @signal request::titlebars
+-- @tparam client c The client.
 -- @tparam[opt=nil] string content The context (like "rules")
 -- @tparam[opt=nil] table hints Some hints.
 -- @classsignal
@@ -1834,6 +1835,7 @@ end)
 -- * **floating**: When the floating or maximization state changes.
 --
 -- @signal request::border
+-- @tparam client c The client.
 -- @tparam string context The context.
 -- @tparam table hints The hints.
 -- @classsignal

lib/awful/completion.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Completion module.
+--- Helper utilities for bash-like completion lists.
 --
 -- This module store a set of function using shell to complete commands name.
 --
@@ -31,7 +31,7 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion"
 
 --- Enable programmable bash completion in awful.completion.bash at the price of
 -- a slight overhead.
--- @param src The bash completion source file, /etc/bash_completion by default.
+-- @tparam string src The bash completion source file, `/etc/bash_completion` by default.
 -- @staticfct awful.completion.bashcomp_load
 function completion.bashcomp_load(src)
     if src then bashcomp_src = src end
@@ -189,11 +189,13 @@ end
 --- Run a generic completion.
 -- For this function to run properly the awful.completion.keyword table should
 -- be fed up with all keywords. The completion is run against these keywords.
--- @param text The current text the user had typed yet.
+-- @tparam string text The current text the user had typed yet.
--- @param cur_pos The current cursor position.
+-- @tparam number cur_pos The current cursor position.
--- @param ncomp The number of yet requested completion using current text.
+-- @tparam number ncomp The number of yet requested completion using current text.
--- @param keywords The keywords table uised for completion.
+-- @tparam table keywords The keywords table uised for completion.
--- @return The new match, the new cursor position, the table of all matches.
+-- @treturn string The new match.
+-- @treturn number The new cursor position.
+-- @treturn table The table of all matches.
 -- @staticfct awful.completion.generic
 function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args
     -- The keywords table may be empty

lib/awful/hotkeys_popup/init.lua

@@ -10,7 +10,7 @@ local hotkeys_popup = {
   widget = require("awful.hotkeys_popup.widget"),
 }
 
---- This is the same as awful.hotkeys_popup.widget.show_help.
+--- This is the same as `awful.hotkeys_popup.widget.show_help`.
 --
 -- example usage:
 --

lib/awful/hotkeys_popup/widget.lua

@@ -249,6 +249,21 @@ widget.labels = {
 -- @tparam[opt] table args.group_rules Rules for showing 3rd-party hotkeys. @see `awful.hotkeys_popup.keys.vim`.
 -- @return Widget instance.
 -- @constructorfct awful.widget.hotkeys_popup.widget.new
+-- @usebeautiful beautiful.hotkeys_fg
+-- @usebeautiful beautiful.hotkeys_bg
+-- @usebeautiful beautiful.hotkeys_border_width
+-- @usebeautiful beautiful.hotkeys_border_color
+-- @usebeautiful beautiful.hotkeys_shape
+-- @usebeautiful beautiful.hotkeys_modifiers_fg
+-- @usebeautiful beautiful.hotkeys_label_bg
+-- @usebeautiful beautiful.hotkeys_label_fg
+-- @usebeautiful beautiful.hotkeys_font
+-- @usebeautiful beautiful.hotkeys_description_font
+-- @usebeautiful beautiful.hotkeys_group_margin
+-- @usebeautiful beautiful.bg_normal Fallback.
+-- @usebeautiful beautiful.fg_normal Fallback.
+-- @usebeautiful beautiful.fg_minimize Fallback.
+-- @usebeautiful beautiful.border_width Fallback.
 function widget.new(args)
     args = args or {}
     local widget_instance = {
@@ -755,8 +770,8 @@ function widget.new(args)
     end
 
     --- Add hotkey group rules for third-party applications.
-    -- @tparam string group hotkeys group name,
+    -- @tparam string group Hotkeys group name,
-    -- @tparam table data rule data for the group
+    -- @tparam table data Rule data for the group
     -- see `awful.hotkeys_popup.key.vim` as an example.
     -- @method add_group_rules
     function widget_instance:add_group_rules(group, data)
@@ -795,8 +810,8 @@ end
 
 --- Add hotkey group rules for third-party applications
 -- (default widget instance will be used).
--- @tparam string group rule group name,
+-- @tparam string group Rule group name,
--- @tparam table data rule data for the group
+-- @tparam table data Rule data for the group
 -- see `awful.hotkeys_popup.key.vim` as an example.
 -- @staticfct awful.hotkeys_popup.widget.add_group_rules
 function widget.add_group_rules(group, data)

lib/awful/key.lua

@@ -43,7 +43,7 @@ local gobject = require("gears.object")
 -- keycode such as `#65`.
 --
 -- @property key
--- @param string
+-- @tparam string key
 
 --- The table of modifier keys.
 --
@@ -75,31 +75,31 @@ local gobject = require("gears.object")
 -- This is used, for example, by `awful.hotkeys_popup`.
 --
 -- @property description
--- @param string
+-- @tparam string description
 
 --- The key name.
 --
 -- This can be useful when searching for keybindings by keywords.
 --
 -- @property name
--- @param string
+-- @tparam string name
 
 --- The key group bound to a function in a key binding.
 --
 -- This is used, for example, by `awful.hotkeys_popup`.
 --
 -- @property group
--- @param string
+-- @tparam string group
 
 --- The callback when this key is pressed.
 --
 -- @property on_press
--- @param function
+-- @tparam function on_press
 
 --- The callback when this key is released.
 --
 -- @property on_release
--- @param function
+-- @tparam function on_release
 
 local key = { mt = {}, hotkeys = {} }
 

lib/awful/keygrabber.lua

@@ -296,7 +296,7 @@ end
 -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@
 --
 -- @property timeout
--- @param number
+-- @tparam number timeout
 -- @see gears.timer
 -- @see timeout_callback
 
@@ -321,7 +321,7 @@ end
 -- their corresponding key names such as `Control_L`.
 --
 -- @property stop_key
--- @param[opt=nil] string|table stop_key
+-- @tparam[opt=nil] string|table stop_key
 -- @see stop_event
 
 --- The event on which the keygrabbing will be terminated.
@@ -332,7 +332,7 @@ end
 -- * "release"
 --
 -- @property stop_event
--- @param string
+-- @tparam string stop_event
 -- @see stop_key
 
 --- Whether or not to execute the key press/release callbacks when keybindings are called.
@@ -344,14 +344,14 @@ end
 -- By default, keybindings block those callbacks from being executed.
 --
 -- @property mask_event_callback
--- @param[opt=true] boolean
+-- @tparam[opt=true] boolean mask_event_callback
 -- @see keybindings
 -- @see keyreleased_callback
 -- @see keypressed_callback
 
 --- Do not call the callbacks on modifier keys (like `Control` or `Mod4`) events.
 -- @property mask_modkeys
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean mask_modkeys
 -- @see mask_event_callback
 
 --- Export all keygrabber keybindings as root (global) keybindings.
@@ -365,7 +365,7 @@ end
 -- have a single instance.
 --
 -- @property export_keybindings
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean export_keybindings
 
 --- The root (global) keybinding to start this keygrabber.
 --
@@ -376,7 +376,7 @@ end
 -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@
 --
 -- @property root_keybindings
--- @param table
+-- @tparam table root_keybindings
 -- @see export_keybindings
 -- @see keybindings
 
@@ -385,7 +385,7 @@ end
 -- This property contains a table of `awful.key` objects.
 --
 -- @property keybindings
--- @param table
+-- @tparam table keybindings
 -- @see export_keybindings
 -- @see root_keybindings
 -- @see awful.key
@@ -415,7 +415,7 @@ end
 -- @DOC_text_awful_keygrabber_autostart_EXAMPLE@
 --
 -- @property sequence
--- @param string
+-- @tparam string sequence
 --
 
 --- The current (running) instance of this keygrabber.

lib/awful/layout/init.lua

@@ -1,5 +1,29 @@
 ---------------------------------------------------------------------------
---- Layout module for awful.
+--- Deterministically lay the clients in a screen workarea.
+--
+-- The `awful.layout` module contains many sub-modules. Each of them contain
+-- one or more layout. `awful.layout` offers static layouts rather than
+-- tree based like other WMs. The layout have a small number of configuration
+-- variables:
+--
+-- * `master_width_factor`: The ratio between the main (master) section of the
+--  layout and a sub-section. For example, in the `tile.left` layout, the main
+--  (master) part contains `master_count` clients and the secondary part contains
+--  all other clients.
+-- * `master_count`: The number of clients which belong to the main (master) area.
+-- * `column_count`: The number of columns to store the clients in the secondary
+--   area.
+-- * `master_fill_policy`: When the number of clients is below `master_count`,
+--  how is the remaining space used.
+-- * `gaps`: The empty space between the clients.
+-- * `gap_single_client`: Same as gap, but when there is a single client. Gaps
+--  are often useful as a visual cue to know where a client starts and ends.
+--  This makes no sense when there is only one.
+--
+-- Not all layouts make use of all variables. Having such an overloaded meaning
+-- to a small set of variable is useful to attach those values to keybindings
+-- without having special logic for each layouts. AwesomeWM keybindings are not
+-- modal, so such "limitation" actually improves usability.
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou

lib/awful/layout/suit/corner.lua

@@ -171,6 +171,7 @@ end
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- @clientlayout awful.layout.suit.corner.nw
+-- @usebeautiful beautiful.layout_cornernw
 corner.nw = {
         name = "cornernw",
         arrange = function (p) return do_corner(p, "NW") end,
@@ -181,6 +182,7 @@ corner.nw = {
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- @clientlayout awful.layout.suit.corner.ne
+-- @usebeautiful beautiful.layout_cornerne
 corner.ne = {
         name = "cornerne",
         arrange = function (p) return do_corner(p, "NE") end,
@@ -191,6 +193,7 @@ corner.ne = {
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- @clientlayout awful.layout.suit.corner.sw
+-- @usebeautiful beautiful.layout_cornersw
 corner.sw = {
         name = "cornersw",
         arrange = function (p) return do_corner(p, "SW") end,
@@ -201,6 +204,7 @@ corner.sw = {
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- @clientlayout awful.layout.suit.corner.se
+-- @usebeautiful beautiful.layout_cornerse
 corner.se = {
         name = "cornerse",
         arrange = function (p) return do_corner(p, "SE") end,

lib/awful/layout/suit/fair.lua

@@ -107,10 +107,12 @@ end
 --- The fair layout.
 -- Try to give all clients the same size.
 -- @clientlayout awful.layout.suit.fair
+-- @usebeautiful beautiful.layout_fairv
 
 --- The horizontal fair layout.
 -- Try to give all clients the same size.
 -- @clientlayout awful.layout.suit.fair.horizontal
+-- @usebeautiful beautiful.layout_fairh
 
 return fair
 

lib/awful/layout/suit/floating.lua

@@ -114,6 +114,7 @@ end
 
 --- The floating layout.
 -- @clientlayout awful.layout.suit.floating
+-- @usebeautiful beautiful.layout_floating
 
 floating.name = "floating"
 

lib/awful/layout/suit/magnifier.lua

@@ -143,6 +143,7 @@ end
 
 --- The magnifier layout.
 -- @clientlayout awful.layout.suit.magnifier
+-- @usebeautiful beautiful.layout_magnifier
 
 magnifier.name = "magnifier"
 

lib/awful/layout/suit/max.lua

@@ -43,6 +43,7 @@ end
 
 --- Maximized layout.
 -- @clientlayout awful.layout.suit.max
+-- @usebeautiful beautiful.layout_max
 max.name = "max"
 function max.arrange(p)
     return fmax(p, false)
@@ -53,6 +54,7 @@ end
 
 --- Fullscreen layout.
 -- @clientlayout awful.layout.suit.max.fullscreen
+-- @usebeautiful beautiful.layout_fullscreen
 max.fullscreen = {}
 max.fullscreen.name = "fullscreen"
 max.fullscreen.skip_gap = max.skip_gap

lib/awful/layout/suit/spiral.lua

@@ -71,6 +71,7 @@ end
 
 --- Dwindle layout.
 -- @clientlayout awful.layout.suit.spiral.dwindle
+-- @usebeautiful beautiful.layout_dwindle
 spiral.dwindle = {}
 spiral.dwindle.name = "dwindle"
 function spiral.dwindle.arrange(p)
@@ -79,6 +80,7 @@ end
 
 --- Spiral layout.
 -- @clientlayout awful.layout.suit.spiral.name
+-- @usebeautiful beautiful.layout_spiral
 spiral.name = "spiral"
 function spiral.arrange(p)
     return do_spiral(p, true)

lib/awful/layout/suit/tile.lua

@@ -312,6 +312,7 @@ end
 --- The main tile algo, on the right.
 -- @param screen The screen number to tile.
 -- @clientlayout awful.layout.suit.tile.right
+-- @usebeautiful beautiful.layout_tile
 tile.right = {}
 tile.right.name = "tile"
 tile.right.arrange = do_tile
@@ -323,6 +324,7 @@ end
 --- The main tile algo, on the left.
 -- @param screen The screen number to tile.
 -- @clientlayout awful.layout.suit.tile.left
+-- @usebeautiful beautiful.layout_tileleft
 tile.left = {}
 tile.left.name = "tileleft"
 tile.left.skip_gap = tile.skip_gap
@@ -336,6 +338,7 @@ end
 --- The main tile algo, on the bottom.
 -- @param screen The screen number to tile.
 -- @clientlayout awful.layout.suit.tile.bottom
+-- @usebeautiful beautiful.layout_tilebottom
 tile.bottom = {}
 tile.bottom.name = "tilebottom"
 tile.bottom.skip_gap = tile.skip_gap
@@ -349,6 +352,7 @@ end
 --- The main tile algo, on the top.
 -- @param screen The screen number to tile.
 -- @clientlayout awful.layout.suit.tile.top
+-- @usebeautiful beautiful.layout_tiletop
 tile.top = {}
 tile.top.name = "tiletop"
 tile.top.skip_gap = tile.skip_gap

lib/awful/menu.lua

@@ -1,5 +1,5 @@
 --------------------------------------------------------------------------------
---- A menu for awful.
+--- Create context menus, optionally with sub-menus.
 --
 -- @author Damien Leone <damien.leone@gmail.com>
 -- @author Julien Danjou <julien@danjou.info>
@@ -93,7 +93,7 @@ end
 -- @param color
 -- @see gears.color
 
---- The default sub-menu indicator if no menu_submenu_icon is provided.
+--- The default sub-menu indicator if no `menu_submenu_icon` is provided.
 -- @beautiful beautiful.menu_submenu
 -- @tparam[opt="▶"] string menu_submenu The sub-menu text.
 -- @see beautiful.menu_submenu_icon
@@ -357,8 +357,9 @@ end
 
 
 --- Show a menu.
--- @param args The arguments
+-- @tparam[opt={}] table args The arguments
--- @param args.coords Menu position defaulting to mouse.coords()
+-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with
+--  `x` and `y` as keys and position (in pixels) as values.
 -- @method show
 function menu:show(args)
     args = args or {}
@@ -390,8 +391,9 @@ function menu:hide()
 end
 
 --- Toggle menu visibility.
--- @param args The arguments
+-- @tparam table args The arguments.
--- @param args.coords Menu position {x,y}
+-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with
+--  `x` and `y` as keys and position (in pixels) as values.
 -- @method toggle
 function menu:toggle(args)
     if self.wibox.visible then
@@ -419,10 +421,10 @@ end
 
 --- Add a new menu entry.
 -- args.* params needed for the menu entry constructor.
--- @param args The item params
+-- @tparam table args The item params.
--- @param args.new (Default: awful.menu.entry) The menu entry constructor.
+-- @tparam[opt=awful.menu.entry] function args.new The menu entry constructor.
--- @param[opt] args.theme The menu entry theme.
+-- @tparam[opt] table args.theme The menu entry theme.
--- @param[opt] index The index where the new entry will inserted.
+-- @tparam[opt] number index The index where the new entry will inserted.
 -- @method add
 function menu:add(args, index)
     if not args then return end
@@ -479,7 +481,7 @@ function menu:add(args, index)
 end
 
 --- Delete menu entry at given position.
--- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself.
+-- @tparam table|number num The index in the table of the menu entry to be deleted; can be also the menu entry itself.
 -- @method delete
 function menu:delete(num)
     if type(num) == "table" then
@@ -580,8 +582,8 @@ end
 
 --- Default awful.menu.entry constructor.
 -- @param parent The parent menu (TODO: This is apparently unused)
--- @param args the item params
+-- @param args The item params
--- @return table with 'widget', 'cmd', 'akey' and all the properties the user wants to change
+-- @return table With 'widget', 'cmd', 'akey' and all the properties the user wants to change
 -- @constructorfct awful.menu.entry
 function menu.entry(parent, args) -- luacheck: no unused args
     args = args or {}
@@ -673,14 +675,24 @@ end
 --------------------------------------------------------------------------------
 
 --- Create a menu popup.
--- @param args Table containing the menu information.
---
--- * Key items: Table containing the displayed items. Each element is a table by default (when element 'new' is
---   awful.menu.entry) containing: item name, triggered action (submenu table or function), item icon (optional).
--- * Keys theme.[fg|bg]_[focus|normal], theme.border_color, theme.border_width, theme.submenu_icon, theme.height
---   and theme.width override the default display for your menu and/or of your menu entry, each of them are optional.
--- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false.
 --
+-- @tparam table args Table containing the menu information.
+-- @tparam[opt=true] boolean args.auto_expand Controls the submenu auto expand behaviour.
+-- @tparam table args.items Table containing the displayed items. Each element is a
+--   table by default (when element 'new' is awful.menu.entry) containing: item
+--   name, triggered action (submenu table or function), item icon (optional).
+-- @tparam table args.theme
+-- @tparam[opt=beautiful.menu_fg_normal] color args.theme.fg_normal
+-- @tparam[opt=beautiful.menu_bg_normal] color args.theme.bg_normal
+-- @tparam[opt=beautiful.menu_fg_focus] color args.theme.fg_focus
+-- @tparam[opt=beautiful.menu_bg_focus] color args.theme.bg_focus
+-- @tparam[opt=beautiful.menu_border_color] color args.theme.border
+-- @tparam[opt=beautiful.menu_border_width] integer args.theme.border_width
+-- @tparam[opt=beautiful.menu_height] integer args.theme.height
+-- @tparam[opt=beautiful.menu_width] integer args.theme.width
+-- @tparam[opt=beautiful.menu_font] string args.theme.font
+-- @tparam[opt=beautiful.menu_submenu_icon] gears.surface|string args.theme.submenu_icon
+-- @tparam[opt=beautiful.menu_submenu] string args.theme.submenu
 -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user.
 -- @constructorfct awful.menu
 -- @usage -- The following function builds and shows a menu of clients that match

lib/awful/mouse/client.lua

@@ -69,8 +69,8 @@ end
 --- Get a client corner coordinates.
 -- @deprecated awful.mouse.client.corner
 -- @tparam[opt=client.focus] client c The client to get corner from, focused one by default.
--- @tparam string corner The corner to use: auto, top_left, top_right, bottom_left,
+-- @tparam string corner The corner to use: `auto`, `top_left`, `top_right`, `bottom_left`,
--- bottom_right, left, right, top bottom. Default is auto, and auto find the
+-- `bottom_right`, `left`, `right`, `top` or `bottom`. Default is `auto`. `auto` finds the
 -- nearest corner.
 -- @treturn string The corner name
 -- @treturn number x The horizontal position

lib/awful/mouse/init.lua

@@ -116,7 +116,7 @@ end, "mouse.resize")
 
 --- Get the client currently under the mouse cursor.
 -- @property current_client
--- @tparam client|nil The client
+-- @tparam client|nil current_client The client
 
 function mouse.object.get_current_client()
     local obj = capi.mouse.object_under_pointer()
@@ -127,7 +127,7 @@ end
 
 --- Get the wibox currently under the mouse cursor.
 -- @property current_wibox
--- @tparam wibox|nil The wibox
+-- @tparam wibox|nil current_wibox The wibox
 
 function mouse.object.get_current_wibox()
     local obj = capi.mouse.object_under_pointer()
@@ -139,7 +139,7 @@ end
 --- Get the widgets currently under the mouse cursor.
 --
 -- @property current_widgets
--- @tparam nil|table list The widget list
+-- @tparam nil|table current_widgets The widget list
 -- @treturn table The list of widgets.The first element is the biggest
 -- container while the last is the topmost widget. The table contains *x*, *y*,
 -- *width*, *height* and *widget*.
@@ -164,7 +164,7 @@ end
 
 --- Get the topmost widget currently under the mouse cursor.
 -- @property current_widget
--- @tparam widget|nil widget The widget
+-- @tparam widget|nil current_widget The widget
 -- @treturn ?widget The widget
 -- @see current_widget_geometry
 
@@ -178,7 +178,7 @@ end
 
 --- Get the current widget geometry.
 -- @property current_widget_geometry
--- @tparam ?table The geometry.
+-- @tparam ?table current_widget_geometry The geometry.
 -- @see current_widget
 
 function mouse.object.get_current_widget_geometry()
@@ -189,7 +189,7 @@ end
 
 --- Get the current widget geometries.
 -- @property current_widget_geometries
--- @tparam ?table A list of geometry tables.
+-- @tparam ?table current_widget_geometries A list of geometry tables.
 -- @see current_widgets
 
 function mouse.object.get_current_widget_geometries()
@@ -238,7 +238,7 @@ end
 
 --- True if the middle mouse button is pressed.
 -- @property is_middle_mouse_button_pressed
--- @tparam boolean is_right_mouse_button_pressed
+-- @tparam boolean is_middle_mouse_button_pressed
 
 --- Add an `awful.button` based mousebinding to the global set.
 --

lib/awful/mouse/resize.lua

@@ -52,7 +52,7 @@ end
 -- This callback will be executed before the mouse grabbing starts.
 -- @function awful.mouse.resize.add_enter_callback
 -- @tparam function cb The callback (or nil)
--- @tparam[default=other] string context The callback context
+-- @tparam[opt="other"] string context The callback context
 function module.add_enter_callback(cb, context)
     context = context or "other"
     callbacks.enter[context] = callbacks.enter[context] or {}
@@ -64,7 +64,7 @@ end
 -- applying the operation.
 -- @function awful.mouse.resize.add_move_callback
 -- @tparam function cb The callback (or nil)
--- @tparam[default=other] string context The callback context
+-- @tparam[opt="other"] string context The callback context
 function module.add_move_callback(cb, context)
     context = context or  "other"
     callbacks.move[context] = callbacks.move[context]  or {}
@@ -75,7 +75,7 @@ end
 -- This callback is executed just before the `mousegrabber` stop
 -- @function awful.mouse.resize.add_leave_callback
 -- @tparam function cb The callback (or nil)
--- @tparam[default=other] string context The callback context
+-- @tparam[opt="other"] string context The callback context
 function module.add_leave_callback(cb, context)
     context = context or  "other"
     callbacks.leave[context] = callbacks.leave[context]  or {}
@@ -93,9 +93,11 @@ end
 --
 -- @function awful.mouse.resize
 -- @tparam client client A client.
--- @tparam[default=mouse.resize] string context The resizing context.
+-- @tparam[opt=mouse.resize] string context The resizing context.
 -- @tparam[opt={}] table args A set of `awful.placement` arguments.
 -- @request wibox geometry mouse.resize granted Requests to resize the wibox.
+-- @usebeautiful beautiful.cursor_mouse_move
+-- @usebeautiful beautiful.cursor_mouse_resize
 local function handler(_, client, context, args) --luacheck: no unused_args
     args = args or {}
     context = context or "mouse.resize"

lib/awful/mouse/snap.lua

@@ -200,6 +200,10 @@ end
 -- @tparam boolean fixed_x True if the client isn't allowed to move in the x direction.
 -- @tparam boolean fixed_y True if the client isn't allowed to move in the y direction.
 -- @treturn table The new geometry.
+-- @usebeautiful beautiful.snap_bg
+-- @usebeautiful beautiful.snap_border_width
+-- @usebeautiful beautiful.snap_shape
+-- @usebeautiful beautiful.snapper_gap
 function module.snap(c, snap, x, y, fixed_x, fixed_y)
     snap = snap or module.default_distance
     c = c or capi.client.focus

lib/awful/permissions/init.lua

@@ -1,5 +1,19 @@
 ---------------------------------------------------------------------------
---- Implements EWMH requests handling.
+--- Default implementation of the various requests handers.
+--
+-- AwesomeWM has many `request::` signals across the core APIs. They help
+-- decouple the default behavior from the core API. The request handlers
+-- can be disconnected and replaced by module or `rc.lua` to alter
+-- AwesomeWM behavior.
+--
+-- This module provides the default implementation of those request handlers.
+-- Beside some legacy signals, most request handlers have a main object, a
+-- named context and a table containing any low-level hints the core code is
+-- aware of. Each default handler implement a context based filter mechanism.
+-- This filter is called the "permissions". It allows requests to be denied.
+-- For example, if a tiled client asks to be resized or moved, the permission
+-- and deny it. In the documentation, many objects and properties have a
+-- "permissions" section you can display by clicking "show more".
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
@@ -143,12 +157,13 @@ end
 -- @tparam client c A client to use
 -- @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 unminimized
+-- @tparam[opt=false] boolean hints.raise Should the client be unminimized
 --  and raised?
--- @tparam[opt=false] boolean hints.switch_to_tag should the client's first tag
+-- @tparam[opt=false] boolean hints.switch_to_tag Should the client's first tag
 --  be selected if none of the client's tags are selected?
 -- @tparam[opt=false] boolean hints.switch_to_tags Select all tags associated
 --  with the client.
+-- @sourcesignal client request::activate
 function permissions.activate(c, context, hints) -- luacheck: no unused args
     if not pcommon.check(c, "client", "activate", context) then return end
 
@@ -291,6 +306,7 @@ end
 -- @tparam[opt] tag|boolean t A tag to use. If `true`, then the client is made `sticky`.
 -- @tparam[opt={}] table hints Extra information.
 -- @tparam[opt=nil] nil|string hints.reason Why the tag is being changed.
+-- @sourcesignal client request::tag
 function permissions.tag(c, t, hints) --luacheck: no unused
     -- There is nothing to do
     if not t and #get_valid_tags(c, c.screen) > 0 then return end
@@ -317,6 +333,7 @@ end
 -- @signalhandler awful.permissions.urgent
 -- @tparam client c A client
 -- @tparam boolean urgent If the client should be urgent
+-- @sourcesignal client request::urgent
 function permissions.urgent(c, urgent)
     if c ~= client.focus and not aclient.property.get(c,"ignore_urgent") then
         c.urgent = urgent
@@ -343,6 +360,7 @@ local context_mapper = {
 --  previous geometry in case it has to be restored.
 -- @tparam[opt=true] boolean hints.honor_workarea Avoid overlapping the `wibar`s
 --  or other desktop decoration when applying the geometry.
+-- @sourcesignal client request::geometry
 function permissions.geometry(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -416,6 +434,7 @@ end
 -- @tparam[opt] integer hints.y The vertical position.
 -- @tparam[opt] integer hints.width The wibox width.
 -- @tparam[opt] integer hints.height The wibox height.
+-- @sourcesignal client request::geometry
 function permissions.wibox_geometry(w, context, hints)
     if not pcommon.check(w, "wibox", "geometry", context) then return end
 
@@ -435,6 +454,7 @@ end
 -- @tparam[opt={}] table hints The hints to pass to the handler.
 -- @tparam[opt=false] boolean hints.toggle Toggle the maximization state rather
 --  than set it to `true`.
+-- @sourcesignal client request::geometry
 function permissions.merge_maximization(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -522,6 +542,7 @@ end
 -- @tparam[opt] integer hints.y The vertical position.
 -- @tparam[opt] integer hints.width The client width.
 -- @tparam[opt] integer hints.height The client height.
+-- @sourcesignal client request::geometry
 function permissions.client_geometry_requests(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -563,6 +584,7 @@ end, "mouse_enter")
 -- @signalhandler awful.permissions.update_border
 -- @tparam client c The client.
 -- @tparam string context Why is the border changed.
+-- @sourcesignal client request::border
 -- @usebeautiful beautiful.border_color_marked
 -- @usebeautiful beautiful.border_color_active
 -- @usebeautiful beautiful.border_color_normal
@@ -751,6 +773,7 @@ local activate_context_map = {
 -- @tparam client c The client.
 -- @tparam string context Why is the client auto-activated.
 -- @tparam[opt={}] table hints Extra arguments.
+-- @sourcesignal client request::activated
 -- @see activate
 -- @see client:activate
 function permissions.autoactivate(c, context, args)

lib/awful/prompt.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Prompt module for awful.
+--- Convert a `wibox.widget.textbox` into an input prompt.
 --
 -- **Keyboard navigation**:
 --
@@ -444,21 +444,21 @@ end
 --         return command
 --       end}
 --     }
--- @param textbox The textbox to use for the prompt. [**DEPRECATED**]
+-- @tparam wibox.widget.textbox textbox The textbox to use for the prompt. [**DEPRECATED**]
--- @param exe_callback The callback function to call with command as argument
+-- @tparam[opt] function|nil exe_callback The callback function to call with command as argument
 -- when finished. [**DEPRECATED**]
--- @param completion_callback The callback function to call to get completion.
+-- @tparam[opt] function completion_callback The callback function to call to get completion.
 --   [**DEPRECATED**]
--- @param[opt] history_path File path where the history should be
+-- @tparam[opt] string history_path File path where the history should be
 -- saved, set nil to disable history [**DEPRECATED**]
--- @param[opt] history_max Set the maximum entries in history
+-- @tparam[opt] number history_max Set the maximum entries in history
 -- file, 50 by default [**DEPRECATED**]
--- @param[opt] done_callback The callback function to always call
+-- @tparam[opt] function done_callback The callback function to always call
 -- without arguments, regardless of whether the prompt was cancelled.
 --  [**DEPRECATED**]
--- @param[opt] changed_callback The callback function to call
+-- @tparam[opt] function changed_callback The callback function to call
 -- with command as argument when a command was changed. [**DEPRECATED**]
--- @param[opt] keypressed_callback The callback function to call
+-- @tparam[opt] function keypressed_callback The callback function to call
 --   with mod table, key and command as arguments when a key was pressed.
 --   [**DEPRECATED**]
 -- @see gears.color

lib/awful/screen.lua

@@ -380,7 +380,7 @@ end
 --
 -- This method computes the different variants of the "usable" screen geometry.
 --
--- @staticfct screen.get_bounding_geometry
+-- @method screen.get_bounding_geometry
 -- @tparam[opt={}] table args The arguments
 -- @tparam[opt=false] boolean args.honor_padding Whether to honor the screen's padding.
 -- @tparam[opt=false] boolean args.honor_workarea Whether to honor the screen's workarea.
@@ -772,7 +772,7 @@ end
 -- the lowest of the resulting virtual DPIs.
 --
 -- @property preferred_dpi
--- @tparam number preferred_dpi the DPI value.
+-- @tparam number preferred_dpi The DPI value.
 -- @readonly
 
 --- The maximum diagonal size in millimeters.
@@ -953,6 +953,8 @@ end
 -- `request::remove` and `request::resize`.
 --
 -- @signalhandler awful.screen.create_screen_handler
+-- @tparam table viewport
+-- @sourcesignal screen request::create
 -- @see request::create
 
 --- Default handler for `request::remove`.
@@ -972,6 +974,8 @@ end
 --    end
 --
 -- @signalhandler awful.screen.remove_screen_handler
+-- @tparam table viewport
+-- @sourcesignal screen request::remove
 -- @see request::remove
 
 --- Default handler for `request::resize`.
@@ -993,6 +997,8 @@ end
 --    end
 --
 -- @signalhandler awful.screen.resize_screen_handler
+-- @tparam table viewport
+-- @sourcesignal screen request::resize
 -- @see request::resize
 
 -- Add the DPI properties.

lib/awful/spawn.lua

@@ -1,7 +1,7 @@
 --luacheck: no max line length
 
 ---------------------------------------------------------------------------
---- Spawning of programs.
+--- Spawn sub-processes and optionally get their output.
 --
 -- This module provides methods to start programs and supports startup
 -- notifications, which allows for callbacks and applying properties to the

lib/awful/tag.lua

@@ -637,7 +637,7 @@ end
 -- @deprecated awful.tag.setscreen
 -- @see screen
 -- @tparam screen s Screen
--- @tparam tag t tag object
+-- @tparam tag t The tag object
 function tag.setscreen(s, t)
     -- For API consistency, the arguments have been swapped for Awesome 3.6
     -- this method is already deprecated, so be silent and swap the args
@@ -653,7 +653,7 @@ end
 --- Get a tag's screen
 -- @deprecated awful.tag.getscreen
 -- @see screen
--- @tparam[opt] tag|nil t tag object
+-- @tparam[opt=awful.screen.focused().selected_taga] tag|nil t Tag object
 -- @treturn screen The tag screen.
 function tag.getscreen(t)
     gdebug.deprecate("Use t.screen instead of awful.tag.getscreen(t)", {deprecated_in=4})
@@ -713,7 +713,7 @@ end
 -- @DOC_screen_mwfact2_EXAMPLE@
 --
 -- @property master_width_factor
--- @tparam number master_width_factor Between 0 and 1
+-- @tparam[opt=beautiful.master_width_factor] number master_width_factor Between 0 and 1
 -- @emits property::mwfact When the value changes (deprecated).
 -- @emits property::master_width_factor When the value changes.
 -- @see master_count
@@ -1006,7 +1006,7 @@ end
 --- Set layout.
 -- @deprecated awful.tag.setlayout
 -- @see layout
--- @param layout a layout table or a constructor function
+-- @param layout A layout table or a constructor function
 -- @tparam tag t The tag to modify
 -- @return The layout
 function tag.setlayout(layout, t)
@@ -1096,7 +1096,7 @@ end
 -- @DOC_screen_gaps2_EXAMPLE@
 --
 -- @property gap
--- @tparam number gap The value has to be greater than zero.
+-- @tparam[opt=beautiful.useless_gap] number gap The value has to be greater than zero.
 -- @emits property::useless_gap When the gap changes.
 -- @see gap_single_client
 -- @see awful.tag.incgap
@@ -1158,7 +1158,7 @@ end
 -- @DOC_screen_gap_single_client_false_EXAMPLE@
 --
 -- @property gap_single_client
--- @tparam boolean gap_single_client Enable gaps for a single client
+-- @tparam[opt=beautiful.gap_single_client] boolean gap_single_client Enable gaps for a single client
 -- @propemits false false
 -- @see awful.tag.incgap
 
@@ -1230,7 +1230,7 @@ end
 -- redistributed on both side.
 --
 -- @property master_fill_policy
--- @tparam string master_fill_policy "expand" or "master\_width\_factor"
+-- @tparam[opt=beautiful.master_fill_policy] string master_fill_policy "expand" or "master\_width\_factor"
 -- @propemits false false
 -- @see awful.tag.togglemfpol
 
@@ -1245,7 +1245,7 @@ end
 -- @see master_fill_policy
 -- @tparam string policy Can be set to
 -- "expand" (fill all the available workarea) or
--- "master_width_factor" (fill only an area inside the master width factor)
+-- `master_width_factor` (fill only an area inside the master width factor)
 -- @tparam[opt=tag.selected()] tag t The tag to modify
 function tag.setmfpol(policy, t)
     gdebug.deprecate("Use t.master_fill_policy = policy instead of awful.tag.setmfpol", {deprecated_in=4})
@@ -1296,7 +1296,7 @@ end
 -- @DOC_sequences_tag_master_count_EXAMPLE@
 --
 -- @property master_count
--- @tparam integer master_count nmaster Only positive values are accepted
+-- @tparam[opt=beautiful.master_count] integer master_count Only positive values are accepted
 -- @emits property::nmaster Deprecated.
 -- @emits property::master_count When the value changes.
 -- @see awful.tag.incnmaster
@@ -1317,7 +1317,7 @@ end
 --- The number of master clients.
 -- @deprecated awful.tag.setnmaster
 -- @see master_count
--- @tparam nmaster The number of master windows.
+-- @tparam number nmaster The number of master windows.
 -- @tparam[opt] tag t The tag.
 function tag.setnmaster(nmaster, t)
     gdebug.deprecate("Use t.master_count = nmaster instead of awful.tag.setnmaster", {deprecated_in=4})
@@ -1379,9 +1379,9 @@ end
 
 --- Set the tag icon
 -- @deprecated awful.tag.seticon
+-- @tparam gears.surface|string icon The icon to set, either path or image object
+-- @tparam tag tag The tag
 -- @see icon
--- @tparam gears.surface|string icon the icon to set, either path or image object
--- @tparam tag tag the tag
 function tag.seticon(icon, _tag)
     gdebug.deprecate("Use t.icon = icon instead of awful.tag.seticon", {deprecated_in=4})
 
@@ -1392,7 +1392,7 @@ end
 --- Get the tag icon
 -- @deprecated awful.tag.geticon
 -- @see icon
--- @tparam tag tag the tag
+-- @tparam tag tag The tag
 function tag.geticon(_tag)
     gdebug.deprecate("Use t.icon instead of awful.tag.geticon", {deprecated_in=4})
 
@@ -1411,7 +1411,7 @@ end
 -- @DOC_sequences_tag_column_count_EXAMPLE@
 --
 -- @property column_count
--- @tparam integer ncol Has to be greater than 1
+-- @tparam[opt=beautiful.column_count or 1] integer column_count Has to be greater than 1
 -- @emits property::ncol Deprecated.
 -- @emits property::column_count When the value changes.
 -- @see awful.tag.incncol
@@ -1739,7 +1739,7 @@ end
 -- @staticfct awful.tag.attached_connect_signal
 -- @tparam screen|nil screen The screen concerned, or all if `nil`.
 -- @tparam string signal The signal name.
--- @tparam function Callback
+-- @tparam function callback
 function tag.attached_connect_signal(screen, ...)
     if screen then
         attached_connect_signal_screen(screen, ...)

lib/awful/titlebar.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Titlebars for awful.
+--- Create widget area on the edge of a client.
 --
 -- Create a titlebar
 -- =================
@@ -41,417 +41,499 @@ local titlebar = {
 
 
 --- Show tooltips when hover on titlebar buttons.
+--
 -- @tfield[opt=true] boolean awful.titlebar.enable_tooltip
 -- @param boolean
 
 --- Title to display if client name is not set.
+--
 -- @field[opt='\<unknown\>'] awful.titlebar.fallback_name
 -- @tparam[opt='\<unknown\>'] string fallback_name
 
-
 --- The titlebar foreground (text) color.
+--
 -- @beautiful beautiful.titlebar_fg_normal
 -- @param color
 -- @see gears.color
 
 --- The titlebar background color.
+--
 -- @beautiful beautiful.titlebar_bg_normal
 -- @param color
 -- @see gears.color
 
 --- The titlebar background image image.
+--
 -- @beautiful beautiful.titlebar_bgimage_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The titlebar foreground (text) color.
+--
 -- @beautiful beautiful.titlebar_fg
 -- @param color
 -- @see gears.color
 
 --- The titlebar background color.
+--
 -- @beautiful beautiful.titlebar_bg
 -- @param color
 -- @see gears.color
 
 --- The titlebar background image image.
+--
 -- @beautiful beautiful.titlebar_bgimage
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The focused titlebar foreground (text) color.
+--
 -- @beautiful beautiful.titlebar_fg_focus
 -- @param color
 -- @see gears.color
 
 --- The focused titlebar background color.
+--
 -- @beautiful beautiful.titlebar_bg_focus
 -- @param color
 -- @see gears.color
 
 --- The focused titlebar background image image.
+--
 -- @beautiful beautiful.titlebar_bgimage_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The urgent titlebar foreground (text) color.
+--
 -- @beautiful beautiful.titlebar_fg_urgent
 -- @param color
 -- @see gears.color
 
 --- The urgent titlebar background color.
+--
 -- @beautiful beautiful.titlebar_bg_urgent
 -- @param color
 -- @see gears.color
 
---- The urgent titlebar background image image.
+--- The urgent titlebar background image.
+--
 -- @beautiful beautiful.titlebar_bgimage_urgent
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal.
+--- The normal non-floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal.
+--- The normal non-maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_normal.
+--- The normal minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_normal_hover.
+--- The hovered minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_normal_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_normal_press.
+--- The pressed minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_normal_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_normal.
+--- The normal close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_normal_hover.
+--- The hovered close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_normal_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_normal_press.
+--- The pressed close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_normal_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal.
+--- The normal non-ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal.
+--- The normal non-sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus.
+--- The focused client non-floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus.
+--- The focused client non-maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_focus.
+--- The focused client minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_focus_hover.
+--- The hovered+focused client minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_focus_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_focus_press.
+--- The pressed+focused minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_focus_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_focus.
+--- The focused client close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_focus_hover.
+--- The hovered+focused close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_focus_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_focus_press.
+--- The pressed+focused close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_focus_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus.
+--- The focused client non-ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus.
+--- The focused client sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_active.
+--- The normal floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_active_hover.
+--- The hovered floating client button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_active_press.
+--- The pressed floating client button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_active.
+--- The maximized client button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_active_hover.
+--- The hozered+maximized client button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_active_press.
+--- The pressed+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_active.
+--- The ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_active_hover.
+--- The hovered+ontop client button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_active_press.
+--- The pressed+ontop client button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_active.
+--- The sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_active_hover.
+--- The hovered+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_active_press.
+--- The pressed+sticky client button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_active.
+--- The floating+focused client button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_active_hover.
+--- The hovered+floating+focused button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_active_press.
+--- The pressed+floating+focused button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_active.
+--- The maximized+focused button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_active_hover.
+--- The hovered+maximized+focused button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_active_press.
+--- The pressed+maximized+focused button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_active.
+--- The ontop+focused button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_active_hover.
+--- The hovered+ontop+focused button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_active_press.
+--- The pressed+ontop+focused button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_active.
+--- The sticky+focused button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_active_hover.
+--- The hovered+sticky+focused button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_active_press.
+--- The pressed+sticky+focused button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_inactive.
+--- The inactive+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_inactive_hover.
+--- The hovered+inactive+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_inactive_press.
+--- The pressed+inactive+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_inactive.
+--- The inactive+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_inactive_hover.
+--- The hovered+inactive+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_inactive_press.
+--- The pressed+maximized+inactive button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_inactive.
+--- The inactive+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_inactive_hover.
+--- The hovered+inactive+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_inactive_press.
+--- The pressed+inactive+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_inactive.
+--- The inactive+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_inactive_hover.
+--- The hovered+inactive+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_inactive_press.
+--- The pressed+inactive+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_inactive.
+--- The inactive+focused+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_inactive_hover.
+--- The hovered+inactive+focused+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_inactive_press.
+--- The pressed+inactive+focused+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_inactive.
+--- The inactive+focused+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_inactive_hover.
+--- The hovered+inactive+focused+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_inactive_press.
+--- The pressed+inactive+focused+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_inactive.
+--- The inactive+focused+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_inactive_hover.
+--- The hovered+inactive+focused+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_inactive_press.
+--- The pressed+inactive+focused+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_inactive.
+--- The inactive+focused+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_inactive_hover.
+--- The hovered+inactive+focused+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_inactive_press.
+--- The pressed+inactive+focused+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- Set a declarative widget hierarchy description.
+--
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
--- @param args An array containing the widgets disposition
+-- @tparam table args An array containing the widgets disposition
 -- @method setup
 
 
@@ -554,6 +636,18 @@ end
 -- @tparam[opt] string args.font
 -- @constructorfct awful.titlebar
 -- @treturn wibox.drawable The newly created titlebar object.
+-- @usebeautiful beautiful.titlebar_fg_normal
+-- @usebeautiful beautiful.titlebar_bg_normal
+-- @usebeautiful beautiful.titlebar_bgimage_normal
+-- @usebeautiful beautiful.titlebar_fg
+-- @usebeautiful beautiful.titlebar_bg
+-- @usebeautiful beautiful.titlebar_bgimage
+-- @usebeautiful beautiful.titlebar_fg_focus
+-- @usebeautiful beautiful.titlebar_bg_focus
+-- @usebeautiful beautiful.titlebar_bgimage_focus
+-- @usebeautiful beautiful.titlebar_fg_urgent
+-- @usebeautiful beautiful.titlebar_bg_urgent
+-- @usebeautiful beautiful.titlebar_bgimage_urgent
 local function new(c, args)
     args = args or {}
     local position = args.position or "top"
@@ -616,7 +710,7 @@ local function new(c, args)
 end
 
 --- Show the client's titlebar.
--- @param c The client whose titlebar is modified
+-- @tparam client c The client whose titlebar is modified
 -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
 --   `"right"`, `"top"`, `"bottom"`.
 -- @staticfct awful.titlebar.show
@@ -632,7 +726,7 @@ function titlebar.show(c, position)
 end
 
 --- Hide the client's titlebar.
--- @param c The client whose titlebar is modified
+-- @tparam client c The client whose titlebar is modified
 -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
 --   `"right"`, `"top"`, `"bottom"`.
 -- @staticfct awful.titlebar.hide
@@ -642,7 +736,7 @@ function titlebar.hide(c, position)
 end
 
 --- Toggle the client's titlebar, hiding it if it is visible, otherwise showing it.
--- @param c The client whose titlebar is modified
+-- @tparam client c The client whose titlebar is modified
 -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
 --   `"right"`, `"top"`, `"bottom"`.
 -- @staticfct awful.titlebar.toggle
@@ -706,7 +800,7 @@ end
 -- Please note that this returns a textbox and all of textbox' API is available.
 -- This way, you can e.g. modify the font that is used.
 --
--- @param c The client for which a titlewidget should be created.
+-- @tparam client c The client for which a titlewidget should be created.
 -- @return The title widget.
 -- @constructorfct awful.titlebar.widget.titlewidget
 function titlebar.widget.titlewidget(c)
@@ -730,7 +824,7 @@ end
 -- Please note that this returns an imagebox and all of the imagebox' API is
 -- available. This way, you can e.g. disallow resizes.
 --
--- @param c The client for which an icon widget should be created.
+-- @tparam client c The client for which an icon widget should be created.
 -- @return The icon widget.
 -- @constructorfct awful.titlebar.widget.iconwidget
 function titlebar.widget.iconwidget(c)
@@ -747,12 +841,12 @@ end
 -- then found in the theme as `titlebar_[name]_button_[normal/focus]_[state]`.
 -- If that value does not exist, the focused state is ignored for the next try.
 --
--- @param c The client for which a button is created.
+-- @tparam client c The client for which a button is created.
 -- @tparam string name Name of the button, used for accessing the theme and
 --   in the tooltip.
--- @param selector A function that selects the image that should be displayed.
+-- @tparam function selector A function that selects the image that should be displayed.
--- @param action Function that is called when the button is clicked.
+-- @tparam function action Function that is called when the button is clicked.
--- @return The widget
+-- @treturn wibox.widget The widget
 -- @constructorfct awful.titlebar.widget.button
 function titlebar.widget.button(c, name, selector, action)
     local ret = imagebox()
@@ -840,8 +934,23 @@ function titlebar.widget.button(c, name, selector, action)
 end
 
 --- Create a new float button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.floatingbutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_floating_button_normal
+-- @usebeautiful beautiful.titlebar_floating_button_focus
+-- @usebeautiful beautiful.titlebar_floating_button_normal_active
+-- @usebeautiful beautiful.titlebar_floating_button_normal_active_hover
+-- @usebeautiful beautiful.titlebar_floating_button_normal_active_press
+-- @usebeautiful beautiful.titlebar_floating_button_focus_active
+-- @usebeautiful beautiful.titlebar_floating_button_focus_active_hover
+-- @usebeautiful beautiful.titlebar_floating_button_focus_active_press
+-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive
+-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_hover
+-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_press
+-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive
+-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_hover
+-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_press
 function titlebar.widget.floatingbutton(c)
     local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle)
     update_on_signal(c, "property::floating", widget)
@@ -849,8 +958,23 @@ function titlebar.widget.floatingbutton(c)
 end
 
 --- Create a new maximize button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.maximizedbutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_active
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_hover
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_press
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_hover
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_press
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_hover
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_press
+-- @usebeautiful beautiful.titlebar_maximized_button_normal
+-- @usebeautiful beautiful.titlebar_maximized_button_focus
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_active
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_hover
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_press
 function titlebar.widget.maximizedbutton(c)
     local widget = titlebar.widget.button(c, "maximized", function(cl)
         return cl.maximized
@@ -862,8 +986,15 @@ function titlebar.widget.maximizedbutton(c)
 end
 
 --- Create a new minimize button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.minimizebutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_minimize_button_normal
+-- @usebeautiful beautiful.titlebar_minimize_button_normal_hover
+-- @usebeautiful beautiful.titlebar_minimize_button_normal_press
+-- @usebeautiful beautiful.titlebar_minimize_button_focus
+-- @usebeautiful beautiful.titlebar_minimize_button_focus_hover
+-- @usebeautiful beautiful.titlebar_minimize_button_focus_press
 function titlebar.widget.minimizebutton(c)
     local widget = titlebar.widget.button(c, "minimize",
                                           function() return "" end,
@@ -873,15 +1004,37 @@ function titlebar.widget.minimizebutton(c)
 end
 
 --- Create a new closing button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.closebutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_close_button_normal
+-- @usebeautiful beautiful.titlebar_close_button_normal_hover
+-- @usebeautiful beautiful.titlebar_close_button_normal_press
+-- @usebeautiful beautiful.titlebar_close_button_focus
+-- @usebeautiful beautiful.titlebar_close_button_focus_hover
+-- @usebeautiful beautiful.titlebar_close_button_focus_press
 function titlebar.widget.closebutton(c)
     return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end)
 end
 
 --- Create a new ontop button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.ontopbutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_ontop_button_normal
+-- @usebeautiful beautiful.titlebar_ontop_button_focus
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_active
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_hover
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_press
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_active
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_hover
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_press
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_hover
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_press
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_hover
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_press
 function titlebar.widget.ontopbutton(c)
     local widget = titlebar.widget.button(c, "ontop",
                                           function(cl) return cl.ontop end,
@@ -891,8 +1044,22 @@ function titlebar.widget.ontopbutton(c)
 end
 
 --- Create a new sticky button for a client.
--- @param c The client for which the button is wanted.
 -- @constructorfct awful.titlebar.widget.stickybutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_sticky_button_normal
+-- @usebeautiful beautiful.titlebar_sticky_button_focus
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_active
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_hover
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_press
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_active
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_hover
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_press
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_hover
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_press
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_hover
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_press
 function titlebar.widget.stickybutton(c)
     local widget = titlebar.widget.button(c, "sticky",
                                           function(cl) return cl.sticky end,

lib/awful/tooltip.lua

@@ -107,7 +107,7 @@ local offset = {
 
 --- The tooltip opacity.
 -- @beautiful beautiful.tooltip_opacity
--- @param number opacity Between 0 and 1
+-- @tparam number opacity Between 0 and 1
 
 --- The tooltip margins.
 -- @beautiful beautiful.tooltip_gaps
@@ -206,7 +206,7 @@ end
 
 --- The wibox containing the tooltip widgets.
 -- @property wibox
--- @param wibox
+-- @tparam wibox wibox
 
 function tooltip:get_wibox()
     if self._private.wibox then
@@ -229,7 +229,7 @@ end
 
 --- Is the tooltip visible?
 -- @property visible
--- @param boolean
+-- @tparam[opt=true] boolean visible
 -- @propemits true false
 
 function tooltip:get_visible()
@@ -269,7 +269,7 @@ end
 -- * top
 --
 -- @property align
--- @param string
+-- @tparam string align
 -- @see mode
 -- @see preferred_positions
 -- @propemits true false
@@ -277,7 +277,7 @@ end
 
 --- The default tooltip alignment.
 -- @beautiful beautiful.tooltip_align
--- @param string
+-- @tparam string tooltip_align
 -- @see align
 
 function tooltip:get_align()
@@ -330,7 +330,7 @@ end
 -- * "outside": Outside of the widget
 --
 -- @property mode
--- @param string
+-- @tparam string mode
 -- @propemits true false
 
 function tooltip:set_mode(mode)
@@ -410,7 +410,7 @@ end
 --    {"front", "back", "middle"}
 --
 -- @property preferred_alignments
--- @param string
+-- @tparam string preferred_alignments
 -- @propemits true false
 -- @see preferred_positions
 
@@ -447,7 +447,7 @@ end
 --- Change displayed markup.
 --
 -- @property markup
--- @tparam string  text New tooltip markup, passed to
+-- @tparam string markup New tooltip markup, passed to
 --   `wibox.widget.textbox.set_markup`.
 -- @propemits true false
 -- @see wibox.widget.textbox
@@ -479,7 +479,7 @@ end
 -- @DOC_awful_tooltip_margins_EXAMPLE@
 --
 -- @property margins
--- @tparam number|table New margins value.
+-- @tparam number|table margins New margins value.
 -- @propemits true false
 
 function tooltip:set_margins(val)
@@ -492,7 +492,7 @@ end
 -- @DOC_awful_tooltip_border_width_EXAMPLE@
 --
 -- @property border_width
--- @param number
+-- @tparam[opt=0] number border_width
 -- @propemits true false
 -- @propbeautiful
 
@@ -506,8 +506,10 @@ end
 -- @DOC_awful_tooltip_border_color_EXAMPLE@
 --
 -- @property border_color
--- @param color
+-- @tparam[opt=beautiful.tooltip_border_color or beautiful.border_color_normal or beautiful.fg_normal]
+--  gears.color border_color
 -- @propemits true false
+-- @propbeautiful
 
 function tooltip:set_border_color(val)
     self.widget.border_color = val
@@ -519,7 +521,7 @@ end
 -- @DOC_awful_tooltip_margins_leftright_EXAMPLE@
 --
 -- @property margins_leftright
--- @tparam number New margins value.
+-- @tparam number margins_leftright New margins value.
 -- @propemits true false
 
 function tooltip:set_margin_leftright(val)
@@ -538,7 +540,7 @@ end
 -- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@
 --
 -- @property margins_topbottom
--- @tparam number New margins value.
+-- @tparam number margins_topbottom New margins value.
 -- @propemits true false
 
 function tooltip:set_margin_topbottom(val)
@@ -557,7 +559,7 @@ end
 -- @DOC_awful_tooltip_gaps_EXAMPLE@
 --
 -- @property gaps
--- @tparam number|table New margins value.
+-- @tparam number|table gaps New margins value.
 -- @propemits true false
 
 function tooltip:set_gaps(val)
@@ -617,14 +619,14 @@ end
 -- @tparam[opt=apply_dpi(5)] integer args.margin_leftright The left/right margin for the text.
 -- @tparam[opt=apply_dpi(3)] integer args.margin_topbottom The top/bottom margin for the text.
 -- @tparam[opt=nil] gears.shape args.shape The shape.
--- @tparam[opt] string args.bg The background color.
+-- @tparam[opt=beautiful.tooltip_bg] string args.bg The background color.
--- @tparam[opt] string args.fg The foreground color.
+-- @tparam[opt=beautiful.tooltip_fg] string args.fg The foreground color.
--- @tparam[opt] string args.border_color The tooltip border color.
+-- @tparam[opt=beautiful.tooltip_border_color] string args.border_color The tooltip border color.
--- @tparam[opt] number args.border_width The tooltip border width.
+-- @tparam[opt=beautiful.tooltip_border_width] number args.border_width The tooltip border width.
 -- @tparam[opt] string args.align The horizontal alignment.
--- @tparam[opt] string args.font The tooltip font.
+-- @tparam[opt=beautiful.tooltip_font] string args.font The tooltip font.
--- @tparam[opt] number args.opacity The tooltip opacity.
+-- @tparam[opt=beautiful.tooltip_opacity] number args.opacity The tooltip opacity.
--- @tparam[opt] table|number args.gaps The tooltip margins.
+-- @tparam[opt=beautiful.tooltip_gaps] table|number args.gaps The tooltip margins.
 -- @treturn awful.tooltip The created tooltip.
 -- @see add_to_object
 -- @see timeout

lib/awful/util.lua

@@ -1,5 +1,8 @@
 ---------------------------------------------------------------------------
---- Utility module for awful.
+--- Various small utility functions not worth putting into new modules.
+--
+-- Most functions in this module are eventually moved into new modules are
+-- deprecated.
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
@@ -19,11 +22,7 @@ local gstring = require("gears.string")
 local grect = require("gears.geometry").rectangle
 local gcolor = require("gears.color")
 local gfs = require("gears.filesystem")
-local capi =
+local capi = { awesome = awesome }
-{
-    awesome = awesome,
-    mouse = mouse
-}
 local gdebug = require("gears.debug")
 local gmath = require("gears.math")
 
@@ -38,6 +37,7 @@ util.shell = os.getenv("SHELL") or "/bin/sh"
 -- This function implementation **has been removed** and no longer
 -- do anything. Use `awful.spawn.easy_async`.
 -- @deprecated awful.util.pread
+-- @see awful.spawn.easy_async
 
 --- Display a deprecation notice, but only once per traceback.
 -- @deprecated deprecate
@@ -99,6 +99,12 @@ function util.mkdir(dir)
 end
 
 --- Eval Lua code.
+--
+-- It can either be "real" code or expressions like `2 ~= 3`.
+-- If the expression cannot be interpreted or returns false, this
+-- function calls `error`.
+--
+-- @tparam string code The code to evaluate.
 -- @return The return value of Lua code.
 -- @staticfct awful.util.eval
 function util.eval(s)
@@ -128,7 +134,7 @@ end
 
 --- Check if a file is a Lua valid file.
 -- This is done by loading the content and compiling it with loadfile().
--- @param path The file path.
+-- @tparam string path The file path.
 -- @return A function if everything is alright, a string with the error
 -- otherwise.
 -- @staticfct awful.util.checkfile
@@ -222,13 +228,16 @@ function util.getdir(d)
 end
 
 --- Search for an icon and return the full path.
+--
 -- It searches for the icon path under the given directories with respect to the
 -- given extensions for the icon filename.
--- @param iconname The name of the icon to search for.
+-- @tparam string iconname The name of the icon to search for.
--- @param exts Table of image extensions allowed, otherwise { 'png', gif' }
+-- @tparam[opt={'png','gif'}] table exts Table of image extensions allowed.
--- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' }
+-- @tparam[opt={'/usr/share/pixmaps/','/usr/share/icons/hicolor/'}] table dirs
+--  Table of dirs to search.
 -- @tparam[opt] string size The size. If this is specified, subdirectories `x`
 --   of the dirs are searched first.
+-- @treturn string|nil The icon path or `nil` if not found.
 -- @staticfct awful.util.geticonpath
 function util.geticonpath(iconname, exts, dirs, size)
     exts = exts or { 'png', 'gif' }
@@ -326,8 +335,8 @@ end
 --
 -- Note that this method doesn't copy entries found in `__index`.
 -- @deprecated util.table.crush
--- @tparam table t the table to be overridden
+-- @tparam table t The table to be overridden
--- @tparam table set the table used to override members of `t`
+-- @tparam table set The table used to override members of `t`
 -- @tparam[opt=false] boolean raw Use rawset (avoid the metatable)
 -- @treturn table t (for convenience)
 -- @see gears.table
@@ -387,7 +396,7 @@ end
 
 --- Get a sorted table with all keys from a table.
 -- @deprecated util.table.keys
--- @param t the table for which the keys to get
+-- @param t The table for which the keys to get
 -- @return A table with keys
 -- @see gears.table
 function util.table.keys(t)
@@ -398,7 +407,7 @@ end
 --- Filter a tables keys for certain content types
 -- @deprecated util.table.keys_filter
 -- @param t The table to retrieve the keys for
--- @param ... the types to look for
+-- @param ... The types to look for
 -- @return A filtered table with keys
 -- @see gears.table
 function util.table.keys_filter(t, ...)
@@ -408,7 +417,7 @@ end
 
 --- Reverse a table
 -- @deprecated util.table.reverse
--- @param t the table to reverse
+-- @param t The table to reverse
 -- @return the reversed table
 -- @see gears.table
 function util.table.reverse(t)
@@ -418,7 +427,7 @@ end
 
 --- Clone a table
 -- @deprecated util.table.clone
--- @param t the table to clone
+-- @param t The table to clone
 -- @param deep Create a deep clone? (default: true)
 -- @return a clone of t
 -- @see gears.table
@@ -432,9 +441,9 @@ end
 -- given index, all elements of a table that match a given criteria.
 --
 -- @deprecated util.table.iterate
--- @param t      the table to iterate
+-- @tparam table t The table to iterate.
--- @param filter a function that returns true to indicate a positive match
+-- @tparam function filter A function that returns true to indicate a positive match
--- @param start  what index to start iterating from.  Default is 1 (=> start of
+-- @param start What index to start iterating from. Default is 1 (=> start of
 -- the table)
 -- @see gears.table
 function util.table.iterate(t, filter, start)
@@ -445,8 +454,8 @@ end
 
 --- Merge items from the one table to another one
 -- @deprecated util.table.merge
--- @tparam table t the container table
+-- @tparam table t The container table
--- @tparam table set the mixin table
+-- @tparam table set The mixin table
 -- @treturn table Return `t` for convenience
 -- @see gears.table
 function util.table.merge(t, set)

lib/awful/wallpaper.lua

@@ -470,6 +470,7 @@ end)
 --
 -- @property bg
 -- @tparam gears.color bg
+-- @usebeautiful beautiful.wallpaper_bg
 -- @see gears.color
 
 --- The foreground color.
@@ -485,6 +486,7 @@ end)
 --- The default wallpaper background color.
 -- @beautiful beautiful.wallpaper_bg
 -- @tparam gears.color wallpaper_bg
+-- @usebeautiful beautiful.wallpaper_fg
 -- @see bg
 
 --- The default wallpaper foreground color.

lib/awful/wibar.lua

@@ -537,6 +537,19 @@ end
 --@DOC_wibox_constructor_COMMON@
 -- @return The new wibar
 -- @constructorfct awful.wibar
+-- @usebeautiful beautiful.wibar_favor_vertical
+-- @usebeautiful beautiful.wibar_border_width
+-- @usebeautiful beautiful.wibar_border_color
+-- @usebeautiful beautiful.wibar_ontop
+-- @usebeautiful beautiful.wibar_cursor
+-- @usebeautiful beautiful.wibar_opacity
+-- @usebeautiful beautiful.wibar_type
+-- @usebeautiful beautiful.wibar_width
+-- @usebeautiful beautiful.wibar_height
+-- @usebeautiful beautiful.wibar_bg
+-- @usebeautiful beautiful.wibar_bgimage
+-- @usebeautiful beautiful.wibar_fg
+-- @usebeautiful beautiful.wibar_shape
 function awfulwibar.new(args)
     args = args or {}
     local position = args.position or "top"

lib/awful/widget/button.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- A simple button widget.
+-- A simple button widget based on a background image.
 --
 -- @DOC_wibox_awidget_defaults_button_EXAMPLE@
 --

lib/awful/widget/calendar_popup.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- A calendar popup wibox.
+-- A popup wibox containing a `wibox.widget,calendar` widget.
 --
 -- Display a month or year calendar popup using `calendar_popup.month` or `calendar_popup.year`.
 -- The calendar style can be tweaked by providing tables of style properties at creation:
@@ -386,6 +386,7 @@ end
 -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`)
 -- @treturn wibox A wibox containing the calendar
 -- @constructorfct awful.widget.calendar_popup.month
+-- @usebeautiful beautiful.calendar_style
 function calendar_popup.month(args)
     return get_cal_wibox("month", args)
 end

lib/awful/widget/clienticon.lua

@@ -86,7 +86,7 @@ end
 --- The widget's @{client}.
 --
 -- @property client
--- @param client
+-- @tparam client client
 -- @propemits true false
 
 function clienticon:get_client()

lib/awful/widget/common.lua

@@ -1,4 +1,10 @@
 ---------------------------------------------------------------------------
+-- This module contains helper functions to manage a layout widgets.
+--
+-- This is the boilerplate code to manage a "list" of objects and display
+-- them in a `wibox.layout`. It uses signals to detect when an object change
+-- and its widget be updated.
+--
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @classmod awful.widget.common

lib/awful/widget/keyboardlayout.lua

@@ -1,4 +1,7 @@
 ---------------------------------------------------------------------------
+-- Display the current keyboard layout name in a widget.
+--
+--
 -- @author Aleksey Fedotov <lexa@cfotr.com>
 -- @copyright 2015 Aleksey Fedotov
 -- @widgetmod awful.widget.keyboardlayout
@@ -132,7 +135,7 @@ end
 -- Create an array whose element is a table consisting of the four fields:
 -- vendor, file, section and group_idx, which all correspond to the
 -- xkb_symbols pattern "vendor/file(section):group_idx".
--- @tparam string group_names The string awesome.xkb_get_group_names() returns.
+-- @tparam string group_names The string `awesome.xkb_get_group_names()` returns.
 -- @treturn table An array of tables whose keys are vendor, file, section, and group_idx.
 -- @staticfct awful.keyboardlayout.get_groups_from_group_names
 function keyboardlayout.get_groups_from_group_names(group_names)
@@ -260,7 +263,7 @@ end
 -- It shows current keyboard layout name in a textbox.
 --
 -- @constructorfct awful.widget.keyboardlayout
--- @return A keyboard layout widget.
+-- @treturn awful.widget.keyboardlayout A keyboard layout widget.
 function keyboardlayout.new()
     local widget = textbox()
     local self = widget_base.make_widget(widget, nil, {enable_properties=true})

lib/awful/widget/layoutlist.lua

@@ -178,33 +178,38 @@ end
 local layoutlist = {}
 
 --- The layoutlist default widget layout.
+--
 -- If no layout is specified, a `wibox.layout.fixed.vertical` will be created
 -- automatically.
 -- @property base_layout
--- @param widget
+-- @tparam[opt=wibox.layout.fixed.vertical] wibox.layout base_layout
 -- @propemits true false
 -- @see wibox.layout.fixed.vertical
 -- @see base_layout
 
 --- The delegate widget template.
+--
 -- @property widget_template
--- @param table
+-- @tparam[opt=nil] table widget_template
 -- @propemits true false
 
 --- The layoutlist screen.
+--
 -- @property screen
--- @param screen
+-- @tparam screen screen
 
 --- A function that returns the list of layout to display.
 --
 -- @property source
--- @param[opt=awful.widget.layoutlist.source.for_screen] function
+-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function source
 
 --- The layoutlist filter function.
+--
 -- @property filter
--- @param[opt=awful.widget.layoutlist.source.for_screen] function
+-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function filter
 
 --- The default foreground (text) color.
+--
 -- @beautiful beautiful.layoutlist_fg_normal
 -- @tparam[opt=nil] string|pattern fg_normal
 -- @see gears.color
@@ -276,17 +281,17 @@ local layoutlist = {}
 
 --- The currenly displayed layouts.
 -- @property layouts
--- @param table
+-- @tparam table layouts
 
 --- The currently selected layout.
 -- @property current_layout
--- @param layout
+-- @tparam layout current_layout
 
 --- The current number of layouts.
 --
 -- @property count
 -- @readonly
--- @tparam number The number of layouts.
+-- @tparam number count The number of layouts.
 -- @propemits true false
 
 function layoutlist:get_layouts()
@@ -395,22 +400,22 @@ end
 -- @tparam[opt] table args.widget_template A custom widget to be used for each action.
 -- @tparam[opt=ascreen.focused()] screen args.screen A screen
 -- @tparam[opt={}] table args.style Extra look and feel parameters
--- @tparam boolean args.style.disable_icon
+-- @tparam[opt=beautiful.layoutlist_disable_icon] boolean args.style.disable_icon
--- @tparam boolean args.style.disable_name
+-- @tparam[opt=beautiful.layoutlist_disable_name] boolean args.style.disable_name
--- @tparam string|pattern args.style.fg_normal
+-- @tparam[opt=beautiful.layoutlist_fg_normal] string|pattern args.style.fg_normal
--- @tparam string|pattern args.style.bg_normal
+-- @tparam[opt=beautiful.layoutlist_bg_normal] string|pattern args.style.bg_normal
--- @tparam string|pattern args.style.fg_selected
+-- @tparam[opt=beautiful.layoutlist_fg_selected] string|pattern args.style.fg_selected
--- @tparam string|pattern args.style.bg_selected
+-- @tparam[opt=beautiful.layoutlist_bg_selected] string|pattern args.style.bg_selected
--- @tparam string args.style.font
+-- @tparam[opt=beautiful.layoutlist_font] string args.style.font
--- @tparam string args.style.font_selected
+-- @tparam[opt=beautiful.layoutlist_font_selected] string args.style.font_selected
--- @tparam string args.style.align *left*, *right* or *center*
+-- @tparam[opt=beautiful.layoutlist_align] string args.style.align *left*, *right* or *center*
--- @tparam number args.style.spacing
+-- @tparam[opt=beautiful.layoutlist_spacing] number args.style.spacing
--- @tparam gears.shape args.style.shape
+-- @tparam[opt=beautiful.layoutlist_shape] gears.shape args.style.shape
--- @tparam number args.style.shape_border_width
+-- @tparam[opt=beautiful.layoutlist_shape_border_width] number args.style.shape_border_width
--- @tparam string|pattern args.style.shape_border_color
+-- @tparam[opt=beautiful.layoutlist_shape_border_color] string|pattern args.style.shape_border_color
--- @tparam gears.shape args.style.shape_selected
+-- @tparam[opt=beautiful.layoutlist_shape_selected] gears.shape args.style.shape_selected
--- @tparam string|pattern args.style.shape_border_width_selected
+-- @tparam[opt=beautiful.layoutlist_shape_border_width_selected] string|pattern args.style.shape_border_width_selected
--- @tparam string|pattern args.style.shape_border_color_selected
+-- @tparam[opt=beautiful.layoutlist_shape_border_color_selected] string|pattern args.style.shape_border_color_selected
 -- @treturn widget The action widget.
 -- @constructorfct awful.widget.layoutlist
 

lib/awful/widget/only_on_screen.lua

@@ -80,7 +80,7 @@ function only_on_screen:get_screen()
     return self._private.screen
 end
 
---- Returns a new only_on_screen container.
+--- Returns a new `awful.widget.only_on_screen` container.
 -- This widget makes some other widget visible on just some screens. Use
 -- `:set_widget()` to set the widget and `:set_screen()` to set the screen.
 -- @param[opt] widget The widget to display.

lib/awful/widget/prompt.lua

@@ -73,7 +73,7 @@ end
 -- of `awful.spawn`. Depending on the amount of customization to your shell
 -- environment, this can increase startup time.
 -- @property with_shell
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean with_shell
 
 --- Create a prompt widget which will launch a command.
 -- For additional documentation about `args` parameter, please refer to
@@ -85,10 +85,10 @@ end
 --   Prompt background color.
 -- @tparam[opt=`beautiful.prompt_fg` or `beautiful.fg_normal`] color args.fg
 --   Prompt foreground color.
--- @tparam[opt] gears.color args.fg_cursor
+-- @tparam[opt=beautiful.prompt_fg_cursor] gears.color args.fg_cursor
--- @tparam[opt] gears.color args.bg_cursor
+-- @tparam[opt=beautiful.prompt_bg_cursor] gears.color args.bg_cursor
 -- @tparam[opt] gears.color args.ul_cursor
--- @tparam[opt] string args.font
+-- @tparam[opt=beautiful.prompt_font] string args.font
 -- @tparam[opt] boolean args.autoexec
 -- @tparam[opt] function args.highlighter A function to add syntax highlighting
 --   to the command.
@@ -116,6 +116,10 @@ end
 -- @return An instance of prompt widget, inherits from
 --   `wibox.container.background`.
 -- @constructorfct awful.widget.prompt
+-- @usebeautiful beautiful.prompt_fg
+-- @usebeautiful beautiful.prompt_bg
+-- @usebeautiful beautiful.fg_normal When `beautiful.prompt_fg` isn't set.
+-- @usebeautiful beautiful.bg_normal When `beautiful.prompt_bg` isn't set.
 function widgetprompt.new(args)
     args = args or {}
     local promptbox = background()

lib/awful/widget/taglist.lua

@@ -431,7 +431,7 @@ end
 --
 -- @property count
 -- @readonly
--- @tparam number The number of tags.
+-- @tparam number count The number of tags.
 -- @propemits true false
 
 function taglist:set_base_layout(layout)
@@ -482,7 +482,7 @@ end
 -- API is very low level.
 --
 -- @property update_function
--- @tparam function update_function.
+-- @tparam function update_function
 
 --- A function to restrict the content of the taglist.
 --
@@ -542,34 +542,45 @@ end
 --  function used to generate the list of tag.
 -- @tparam[opt] table args.widget_template A custom widget to be used for each tag
 -- @tparam[opt={}] table args.style The style overrides default theme.
--- @tparam[opt=nil] string|pattern args.style.fg_focus
+-- @tparam[opt=beautiful.taglist_fg_focus] string|pattern args.style.fg_focus
--- @tparam[opt=nil] string|pattern args.style.bg_focus
+-- @tparam[opt=beautiful.taglist_bg_focus] string|pattern args.style.bg_focus
--- @tparam[opt=nil] string|pattern args.style.fg_urgent
+-- @tparam[opt=beautiful.taglist_fg_urgent] string|pattern args.style.fg_urgent
--- @tparam[opt=nil] string|pattern args.style.bg_urgent
+-- @tparam[opt=beautiful.taglist_bg_urgent] string|pattern args.style.bg_urgent
--- @tparam[opt=nil] string|pattern args.style.bg_occupied
+-- @tparam[opt=beautiful.taglist_bg_occupied] string|pattern args.style.bg_occupied
--- @tparam[opt=nil] string|pattern args.style.fg_occupied
+-- @tparam[opt=beautiful.taglist_fg_occupied] string|pattern args.style.fg_occupied
--- @tparam[opt=nil] string|pattern args.style.bg_empty
+-- @tparam[opt=beautiful.taglist_bg_empty] string|pattern args.style.bg_empty
--- @tparam[opt=nil] string|pattern args.style.fg_empty
+-- @tparam[opt=beautiful.taglist_fg_empty] string|pattern args.style.fg_empty
--- @tparam[opt=nil] string|pattern args.style.bg_volatile
+-- @tparam[opt=beautiful.taglist_bg_volatile] string|pattern args.style.bg_volatile
--- @tparam[opt=nil] string|pattern args.style.fg_volatile
+-- @tparam[opt=beautiful.taglist_fg_volatile] string|pattern args.style.fg_volatile
--- @tparam[opt=nil] string args.style.squares_sel
+-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel
--- @tparam[opt=nil] string args.style.squares_unsel
+-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel
--- @tparam[opt=nil] string args.style.squares_sel_empty
+-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty
--- @tparam[opt=nil] string args.style.squares_unsel_empty
+-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty
--- @tparam[opt=nil] string args.style.squares_resize
+-- @tparam[opt=beautiful.taglist_squares_resize] string args.style.squares_resize
--- @tparam[opt=nil] string args.style.disable_icon
+-- @tparam[opt=beautiful.taglist_disable_icon] string args.style.disable_icon
--- @tparam[opt=nil] string args.style.font
+-- @tparam[opt=beautiful.taglist_font] string args.style.font
--- @tparam[opt=nil] number args.style.spacing The spacing between tags.
+-- @tparam[opt=beautiful.taglist_spacing] number args.style.spacing The spacing between tags.
--- @tparam[opt] string args.style.squares_sel A user provided image for selected squares.
+-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel A user provided image for selected squares.
--- @tparam[opt] string args.style.squares_unsel A user provided image for unselected squares.
+-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel A user provided image for unselected squares.
--- @tparam[opt] string args.style.squares_sel_empty A user provided image for selected squares for empty tags.
+-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty A user provided image for selected squares for empty tags.
--- @tparam[opt] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags.
+-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags.
--- @tparam[opt] boolean args.style.squares_resize True or false to resize squares.
+-- @tparam[opt=beautiful.taglist_squares_resize] boolean args.style.squares_resize True or false to resize squares.
--- @tparam string|pattern args.style.bg_focus The background color for focused client.
+-- @tparam[opt=beautiful.taglist_font] string args.style.font The font.
--- @tparam string|pattern args.style.fg_focus The foreground color for focused client.
+-- @tparam[opt=beautiful.taglist_shape] gears.shape|function args.style.shape
--- @tparam string|pattern args.style.bg_urgent The background color for urgent clients.
+-- @tparam[opt=beautiful.taglist_shape_border_width] number args.style.shape_border_width
--- @tparam string|pattern args.style.fg_urgent The foreground color for urgent clients.
+-- @tparam[opt=beautiful.taglist_shape_border_color] string args.style.shape_border_color
--- @tparam string args.style.font The font.
+-- @tparam[opt=beautiful.taglist_shape_empty] gears.shape|function args.style.shape_empty
+-- @tparam[opt=beautiful.taglist_shape_border_width_empty] number args.style.shape_border_width_empty
+-- @tparam[opt=beautiful.taglist_shape_border_color_empty] string args.style.border_color_empty
+-- @tparam[opt=beautiful.taglist_shape_focus] gears.shape|function args.style.shape_focus
+-- @tparam[opt=beautiful.taglist_shape_border_width_focus] number args.style.shape_border_width_focus
+-- @tparam[opt=beautiful.taglist_shape_border_color_focus] string args.style.shape_border_color_focus
+-- @tparam[opt=beautiful.taglist_shape_urgent] gears.shape|function args.style.shape_urgent
+-- @tparam[opt=beautiful.taglist_shape_border_width_urgent] number args.style.shape_border_width_urgent
+-- @tparam[opt=beautiful.taglist_shape_border_color_urgent] string args.style.shape_border_color_urgent
+-- @tparam[opt=beautiful.taglist_shape_volatile] gears.shape|function args.style.shape_volatile
+-- @tparam[opt=beautiful.taglist_shape_border_width_volatile] number args.style.shape_border_width_volatile
+-- @tparam[opt=beautiful.taglist_shape_border_color_volatile] string args.style.shape_border_color_volatile
 -- @param filter **DEPRECATED** use args.filter
 -- @param buttons **DEPRECATED** use args.buttons
 -- @param style **DEPRECATED** use args.style

lib/awful/widget/tasklist.lua

@@ -377,6 +377,10 @@ local instances
 -- @tparam[opt=nil] string|color shape_border_color_urgent
 -- @see gears.color
 
+--- The icon size.
+-- @beautiful beautiful.tasklist_icon_size
+-- @tparam[opt=nil] integer tasklist_icon_size
+
 -- Public structures
 tasklist.filter, tasklist.source = {}, {}
 
@@ -605,7 +609,7 @@ end
 --
 -- @property count
 -- @readonly
--- @tparam number The number of client.
+-- @tparam number count The number of client.
 -- @propemits true false
 
 --- Set the tasklist layout.
@@ -799,53 +803,54 @@ end
 --  function used to generate the list of client.
 -- @tparam[opt] table args.widget_template A custom widget to be used for each client
 -- @tparam[opt={}] table args.style The style overrides default theme.
--- @tparam[opt=nil] string|pattern args.style.fg_normal
+-- @tparam[opt=beautiful.tasklist_fg_normal] string|pattern args.style.fg_normal
--- @tparam[opt=nil] string|pattern args.style.bg_normal
+-- @tparam[opt=beautiful.tasklist_bg_normal] string|pattern args.style.bg_normal
--- @tparam[opt=nil] string|pattern args.style.fg_focus
+-- @tparam[opt=beautiful.tasklist_fg_focus or beautiful.fg_focus] string|pattern args.style.fg_focus
--- @tparam[opt=nil] string|pattern args.style.bg_focus
+-- @tparam[opt=beautiful.tasklist_bg_focus or beautiful.bg_focus] string|pattern args.style.bg_focus
--- @tparam[opt=nil] string|pattern args.style.fg_urgent
+-- @tparam[opt=beautiful.tasklist_fg_urgent or beautiful.fg_urgent] string|pattern args.style.fg_urgent
--- @tparam[opt=nil] string|pattern args.style.bg_urgent
+-- @tparam[opt=beautiful.tasklist_bg_urgent or beautiful.bg_urgent] string|pattern args.style.bg_urgent
--- @tparam[opt=nil] string|pattern args.style.fg_minimize
+-- @tparam[opt=beautiful.tasklist_fg_minimize or beautiful.fg_minimize] string|pattern args.style.fg_minimize
--- @tparam[opt=nil] string|pattern args.style.bg_minimize
+-- @tparam[opt=beautiful.tasklist_bg_minimize or beautiful.bg_minimize] string|pattern args.style.bg_minimize
--- @tparam[opt=nil] string args.style.bg_image_normal
+-- @tparam[opt=beautiful.tasklist_bg_image_normal] string args.style.bg_image_normal
--- @tparam[opt=nil] string args.style.bg_image_focus
+-- @tparam[opt=beautiful.tasklist_bg_image_focus] string args.style.bg_image_focus
--- @tparam[opt=nil] string args.style.bg_image_urgent
+-- @tparam[opt=beautiful.tasklist_bg_image_urgent] string args.style.bg_image_urgent
--- @tparam[opt=nil] string args.style.bg_image_minimize
+-- @tparam[opt=beautiful.tasklist_bg_image_minimize] string args.style.bg_image_minimize
--- @tparam[opt=nil] boolean args.style.disable_icon
+-- @tparam[opt=beautiful.tasklist_disable_icon] boolean args.style.disable_icon
--- @tparam[opt=nil] number args.style.icon_size The size of the icon
+-- @tparam[opt=beautiful.tasklist_icon_size] number args.style.icon_size The size of the icon
--- @tparam[opt='▪'] string args.style.sticky Extra icon when client is sticky
+-- @tparam[opt=beautiful.tasklist_sticky or '▪'] string args.style.sticky Extra icon when client is sticky
--- @tparam[opt='⌃'] string args.style.ontop Extra icon when client is ontop
+-- @tparam[opt=beautiful.tasklist_ontop or '⌃'] string args.style.ontop Extra icon when client is ontop
--- @tparam[opt='▴'] string args.style.above Extra icon when client is above
+-- @tparam[opt=beautiful.tasklist_above or '▴'] string args.style.above Extra icon when client is above
--- @tparam[opt='▾'] string args.style.below Extra icon when client is below
+-- @tparam[opt=beautiful.tasklist_below or '▾'] string args.style.below Extra icon when client is below
--- @tparam[opt='✈'] string args.style.floating Extra icon when client is floating
+-- @tparam[opt=beautiful.tasklist_floating or '✈'] string args.style.floating Extra icon when client is floating
--- @tparam[opt='<b>+</b>'] string args.style.maximized Extra icon when client is maximized
+-- @tparam[opt=beautiful.tasklist_maximized or '<b>+</b>'] string args.style.maximized Extra icon when client is maximized
--- @tparam[opt='⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal
+-- @tparam[opt=beautiful.tasklist_maximized_horizontal or '⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal
--- @tparam[opt='⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical
+-- @tparam[opt=beautiful.tasklist_maximized_vertical or '⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical
--- @tparam[opt=false] boolean args.style.disable_task_name
+-- @tparam[opt=beautiful.tasklist_disable_task_name or false] boolean args.style.disable_task_name
--- @tparam[opt=nil] string args.style.font
+-- @tparam[opt=beautiful.tasklist_font] string args.style.font
--- @tparam[opt="left"] string args.style.align *left*, *right* or *center*
+-- @tparam[opt=beautiful.tasklist_align or "left"] string args.style.align *left*, *right* or *center*
--- @tparam[opt=nil] string args.style.font_focus
+-- @tparam[opt=beautiful.tasklist_font_focus] string args.style.font_focus
--- @tparam[opt=nil] string args.style.font_minimized
+-- @tparam[opt=beautiful.tasklist_font_minimized] string args.style.font_minimized
--- @tparam[opt=nil] string args.style.font_urgent
+-- @tparam[opt=beautiful.tasklist_font_urgent] string args.style.font_urgent
--- @tparam[opt=nil] number args.style.spacing The spacing between tags.
+-- @tparam[opt=beautiful.tasklist_spacing] number args.style.spacing The spacing between tags.
--- @tparam[opt=nil] gears.shape args.style.shape
+-- @tparam[opt=beautiful.tasklist_shape] gears.shape args.style.shape
--- @tparam[opt=nil] number args.style.shape_border_width
+-- @tparam[opt=beautiful.tasklist_shape_border_width] number args.style.shape_border_width
--- @tparam[opt=nil] string|color args.style.shape_border_color
+-- @tparam[opt=beautiful.tasklist_shape_border_color] string|color args.style.shape_border_color
--- @tparam[opt=nil] gears.shape args.style.shape_focus
+-- @tparam[opt=beautiful.tasklist_shape_focus] gears.shape args.style.shape_focus
--- @tparam[opt=nil] number args.style.shape_border_width_focus
+-- @tparam[opt=beautiful.tasklist_shape_border_width_focus] number args.style.shape_border_width_focus
--- @tparam[opt=nil] string|color args.style.shape_border_color_focus
+-- @tparam[opt=beautiful.tasklist_shape_border_color_focus] string|color args.style.shape_border_color_focus
--- @tparam[opt=nil] gears.shape args.style.shape_minimized
+-- @tparam[opt=beautiful.tasklist_shape_minimized] gears.shape args.style.shape_minimized
--- @tparam[opt=nil] number args.style.shape_border_width_minimized
+-- @tparam[opt=beautiful.tasklist_shape_border_width_minimized] number args.style.shape_border_width_minimized
--- @tparam[opt=nil] string|color args.style.shape_border_color_minimized
+-- @tparam[opt=beautiful.tasklist_shape_border_color_minimized] string|color args.style.shape_border_color_minimized
--- @tparam[opt=nil] gears.shape args.style.shape_urgent
+-- @tparam[opt=beautiful.tasklist_shape_urgent] gears.shape args.style.shape_urgent
--- @tparam[opt=nil] number args.style.shape_border_width_urgent
+-- @tparam[opt=beautiful.tasklist_shape_border_width_urgent] number args.style.shape_border_width_urgent
--- @tparam[opt=nil] string|color args.style.shape_border_color_urgent
+-- @tparam[opt=beautiful.tasklist_shape_border_color_urgent] string|color args.style.shape_border_color_urgent
 -- @param filter **DEPRECATED** use args.filter
 -- @param buttons **DEPRECATED** use args.buttons
 -- @param style **DEPRECATED** use args.style
 -- @param update_function **DEPRECATED** use args.update_function
 -- @param base_widget **DEPRECATED** use args.base_layout
 -- @constructorfct awful.widget.tasklist
+-- @usebeautiful beautiful.tasklist_plain_task_name
 function tasklist.new(args, filter, buttons, style, update_function, base_widget)
     local screen = nil
 

lib/awful/widget/watch.lua

@@ -1,5 +1,6 @@
 ---------------------------------------------------------------------------
---- Watch widget.
+--- Execute a command at a set interval and display its output.
+--
 -- Here is an example of simple temperature widget which will update each 15
 -- seconds implemented in two different ways.
 -- The first, simpler one, will just display the return command output
@@ -7,20 +8,18 @@
 -- In the other example `sensors` returns to the widget its full output
 -- and it's trimmed in the widget callback function:
 --
---     211             mytextclock,
+--    -- one way to do that:
---     212             wibox.widget.textbox('  |  '),
+--    local w = awful.widget.watch('bash -c "sensors | grep temp1"', 15)
---     213             -- one way to do that:
+--
---     214             awful.widget.watch('bash -c "sensors | grep temp1"', 15),
+--    -- another way:
---     215             -- another way:
+--    local w = awful.widget.watch('sensors', 15, function(widget, stdout)
---     216             awful.widget.watch('sensors', 15, function(widget, stdout)
+--        for line in stdout:gmatch("[^\r\n]+") do
---     217               for line in stdout:gmatch("[^\r\n]+") do
+--            if line:match("temp1") then
---     218                 if line:match("temp1") then
+--                widget:set_text(line)
---     219                   widget:set_text(line)
+--                return
---     220                   return
+--            end
---     221                 end
+--        end
---     222               end
+--    end)
---     223             end),
---     224             s.mylayoutbox,
 --
 -- ![Example screenshot](../images/awful_widget_watch.png)
 --
@@ -55,7 +54,7 @@ local watch = { mt = {} }
 --     function(widget, stdout, stderr, exitreason, exitcode)
 --         widget:set_text(stdout)
 --     end
--- @param callback.widget Base widget instance.
+-- @tparam wibox.widget callback.widget Base widget instance.
 -- @tparam string callback.stdout Output on stdout.
 -- @tparam string callback.stderr Output on stderr.
 -- @tparam string callback.exitreason Exit Reason.
@@ -64,7 +63,7 @@ local watch = { mt = {} }
 -- For "exit" reason it's the exit code.
 -- For "signal" reason — the signal causing process termination.
 --
--- @param[opt=wibox.widget.textbox()] base_widget Base widget.
+-- @tparam[opt=wibox.widget.textbox()] wibox.widget base_widget Base widget.
 --
 -- @return The widget used by this watch.
 -- @return Its gears.timer.

lib/beautiful/init.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- Theme library.
+--- Key+value based theme library and associated utility modules.
 --
 -- @author Damien Leone <damien.leone@gmail.com>
 -- @author Julien Danjou <julien@danjou.info>
@@ -89,62 +89,52 @@ local active_font
 
 --- The default font.
 -- @beautiful beautiful.font
--- @param string
+-- @param[opt="sans 8"] string
 
--- The default background color.
+--- The default background color.
+--
+-- The background color can be transparent. If there is a
+-- compositing manager such as compton, then it will be
+-- real transparency and may include blur (provided by the
+-- compositor). When there is no compositor, it will take
+-- a picture of the wallpaper and blend it.
+--
 -- @beautiful beautiful.bg_normal
 -- @param color
 
--- The default focused element background color.
+--- The default focused element background color.
 -- @beautiful beautiful.bg_focus
 -- @param color
 
--- The default urgent element background color.
+--- The default urgent element background color.
 -- @beautiful beautiful.bg_urgent
 -- @param color
 
--- The default minimized element background color.
+--- The default minimized element background color.
 -- @beautiful beautiful.bg_minimize
 -- @param color
 
--- The system tray background color.
+--- The default focused element foreground (text) color.
--- Please note that only solid colors are currently supported.
--- @beautiful beautiful.bg_systray
--- @param color
-
--- The default focused element foreground (text) color.
 -- @beautiful beautiful.fg_normal
 -- @param color
 
--- The default focused element foreground (text) color.
+--- The default focused element foreground (text) color.
 -- @beautiful beautiful.fg_focus
 -- @param color
 
--- The default urgent element foreground (text) color.
+--- The default urgent element foreground (text) color.
 -- @beautiful beautiful.fg_urgent
 -- @param color
 
--- The default minimized element foreground (text) color.
+--- The default minimized element foreground (text) color.
 -- @beautiful beautiful.fg_minimize
 -- @param color
 
---- The gap between clients.
--- @beautiful beautiful.useless_gap
--- @param[opt=0] number
-
---- The fallback border width.
--- @beautiful beautiful.border_width
--- @param number
-
---- The fallback border color.
--- @beautiful beautiful.border_color
--- @param color
-
 --- The wallpaper path.
 -- @beautiful beautiful.wallpaper
 -- @tparam string|gears.surface wallpaper
 
--- The icon theme name.
+--- The icon theme name.
 -- It has to be a directory in `/usr/share/icons` or an XDG icon folder.
 -- @beautiful beautiful.icon_theme
 -- @param string
@@ -234,7 +224,7 @@ end
 
 --- Get the height of a font.
 --
--- @param name Name of the font.
+-- @tparam string name Name of the font.
 -- @staticfct beautiful.get_font_height
 function beautiful.get_font_height(name)
     return load_font(name).height

lib/gears/debug.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Utility functions to make development easier.
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @utillib gears.debug
@@ -141,7 +143,7 @@ end
 -- @tparam table fallback The new class.
 -- @tparam string old_name The old class name.
 -- @tparam string new_name The new class name.
--- @tparam[opt={}] args The name.
+-- @tparam[opt={}] table args The name.
 -- @tparam[opt] number args.deprecated_in The version which deprecated this
 --  class.
 -- @treturn table A proxy class.

lib/gears/filesystem.lua

@@ -1,5 +1,8 @@
 ---------------------------------------------------------------------------
---- Filesystem module for gears.
+--- Various filesystem utility functions.
+--
+-- Note that these functions are blocking. If you need to do a large number of
+-- I/O operations, it is better to use `lgi.Gio` async functions.
 --
 -- @utillib gears.filesystem
 ---------------------------------------------------------------------------

lib/gears/math.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Various math related functions.
+--
 --- Math module for gears.
 --
 -- @utillib gears.math

lib/gears/protected_call.lua

@@ -1,4 +1,9 @@
 ---------------------------------------------------------------------------
+-- Safely call a function and handle errors using `gears.debug`.
+--
+-- This is a `pcall`/`xpcall` wrapper. All it does is to integrate into the
+-- AwesomeWM-wide error handling and logging.
+--
 -- @author Uli Schlachter
 -- @copyright 2016 Uli Schlachter
 -- @utillib gears.protected_call

lib/gears/shape.lua

@@ -215,7 +215,7 @@ end
 -- @param cr A cairo content
 -- @tparam number width The rectangle width
 -- @tparam number height The rectangle height
--- @tparam number radius the corner radius
+-- @tparam number radius The corner radius
 -- @staticfct gears.shape.rounded_rect
 function module.rounded_rect(cr, width, height, radius)
 
@@ -627,8 +627,8 @@ end
 -- @tparam[opt=math.min(width height)/2] number thickness The arc thickness
 -- @tparam[opt=0] number start_angle The start angle (in radian)
 -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian)
--- @tparam[opt=false] boolean start_rounded if the arc start rounded
+-- @tparam[opt=false] boolean start_rounded If the arc start rounded
--- @tparam[opt=false] boolean end_rounded if the arc end rounded
+-- @tparam[opt=false] boolean end_rounded If the arc end rounded
 -- @staticfct gears.shape.arc
 function module.arc(cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded)
     start_angle = start_angle or 0

lib/gears/sort/init.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Extra sorting algorithms.
+--- Utilities to sort and arrange data.
 --
 -- @utillib gears.sort
 ---------------------------------------------------------------------------

lib/gears/string.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- String module for gears.
+--- Various string manipulation and introspection fuctions.
 --
 -- @utillib gears.string
 ---------------------------------------------------------------------------
@@ -10,7 +10,7 @@ local xml_entity_names = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;",
 
 --- Escape a string from XML char.
 -- Useful to set raw text in textbox.
--- @param text Text to escape.
+-- @tparam string text Text to escape.
 -- @treturn string Escaped text.
 -- @staticfct gears.string.xml_escape
 function gstring.xml_escape(text)
@@ -21,7 +21,7 @@ local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "
                            amp = "&" };
 
 --- Unescape a string from entities.
--- @param text Text to unescape.
+-- @tparam string text Text to unescape.
 -- @treturn string Unescaped text.
 -- @staticfct gears.string.xml_unescape
 function gstring.xml_unescape(text)

lib/gears/surface.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Utilities to integrate and manipulate Cairo drawing surfaces.
+--
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
 -- @module gears.surface
@@ -195,10 +197,9 @@ end
 --
 --  If the wibox or client size change, this function need to be called
 --   again.
--- @param draw A wibox or a client
+-- @tparam client|wibox draw A wibox or a client.
--- @param shape or gears.shape function or a custom function with a context,
+-- @tparam gears.shape|function shape The shape.
---   width and height as parameter.
+-- @param[opt] ... Any additional parameters will be passed to the shape function.
--- @param[opt] Any additional parameters will be passed to the shape function.
 -- @staticfct apply_shape_bounding
 function surface.apply_shape_bounding(draw, shape, ...)
   local geo = draw:geometry()

lib/gears/table.lua

@@ -1,8 +1,8 @@
 ---------------------------------------------------------------------------
---- Table module for gears.
+--- Various functions to worj with tables.
 --
 -- Examples
--- =======
+-- ========
 --
 -- Using `cycle_value`, you can cycle through values in a table.
 -- When the end of the table is reached, `cycle_value` loops around to the beginning.

lib/gears/timer.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Timer objects and functions.
+--- Class to execute code at specific intervals.
 --
 -- @usage
 --    -- Create a widget and update its content using the output of a shell
@@ -134,13 +134,18 @@ function timer:again()
 end
 
 --- The timer is started.
--- @property started
+--
--- @param boolean
+-- For this to be `true` by default, pass `autostart` to the constructor.
+--
+-- @property[opt=false] started
+-- @tparam boolean started
+-- @see start
+-- @see stop
 
 --- The timer timeout value.
--- **Signal:** property::timeout
+--
 -- @property timeout
--- @param number
+-- @tparam number timeout
 -- @propemits true false
 
 local timer_instance_mt = {

lib/menubar/icon_theme.lua

@@ -82,6 +82,7 @@ local index_theme_cache = {}
 -- @tparam string icon_theme_name Internal name of icon theme
 -- @tparam table base_directories Paths used for lookup
 -- @treturn table An instance of the class `icon_theme`
+-- @usebeautiful beautiful.icon_theme
 icon_theme.new = function(icon_theme_name, base_directories)
     icon_theme_name = icon_theme_name or beautiful.icon_theme or get_default_icon_theme_name()
     base_directories = base_directories or get_pragmatic_base_directories()

lib/menubar/init.lua

@@ -454,6 +454,13 @@ end
 --- Show the menubar on the given screen.
 -- @param[opt] scr Screen.
 -- @staticfct menubar.show
+-- @usebeautiful beautiful.menubar_fg_normal
+-- @usebeautiful beautiful.menubar_bg_normal
+-- @usebeautiful beautiful.menubar_border_width
+-- @usebeautiful beautiful.menubar_border_color
+-- @usebeautiful beautiful.menubar_fg_focus
+-- @usebeautiful beautiful.menubar_bg_focus
+-- @usebeautiful beautiful.menubar_font
 function menubar.show(scr)
     scr = get_screen(scr or awful.screen.focused() or 1)
     local fg_color = theme.menubar_fg_normal or theme.menu_fg_normal or theme.fg_normal

lib/menubar/utils.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Utility module for menubar
+--- Utility functions for the `menubar` module.
 --
 -- @author Antonio Terceiro
 -- @copyright 2009, 2011-2012 Antonio Terceiro, Alexander Yakushev
@@ -199,7 +199,7 @@ local function get_icon_lookup_path()
 end
 
 --- Remove CR newline from the end of the string.
--- @param s string to trim
+-- @tparam string s The string to trim
 -- @staticfct menubar.utils.rtrim
 function utils.rtrim(s)
     if not s then return end

lib/naughty/action.lua

@@ -35,12 +35,12 @@ local action = {}
 -- implement keyboard navigation.
 --
 -- @property selected
--- @param boolean
+-- @tparam boolean selected
 -- @propemits true false
 
 --- The action position (index).
 -- @property position
--- @param number
+-- @tparam number position
 -- @propemits true false
 
 --- The action icon.
@@ -53,7 +53,7 @@ local action = {}
 -- @DOC_wibox_nwidget_actionlist_icon_only_EXAMPLE@
 --
 -- @property icon_only
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean icon_only
 -- @propemits true false
 
 --- When a notification is invoked.

lib/naughty/container/background.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification background.
+--- A notification background widget.
 --
 -- This widget holds the boilerplate code associated with the notification
 -- background. This includes the color and potentially some other styling
@@ -16,6 +16,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2019 Emmanuel Lepage Vallee
 -- @containermod naughty.widget.background
+-- @supermodule wibox.container.background
 -- @see wibox.container.background
 ----------------------------------------------------------------------------
 local wbg       = require("wibox.container.background")

lib/naughty/init.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Desktop notification handling library.
+--
 -- @author Uli Schlachter <psychon@znc.in>
 -- @copyright 2014 Uli Schlachter
 -- @module naughty

lib/naughty/layout/box.lua

@@ -208,7 +208,7 @@ end)
 --    }
 --
 -- @property widget_template
--- @param widget
+-- @tparam[opt=nil] widget|nil|table widget_template
 -- @usebeautiful beautiful.notification_max_width The maximum width for the
 --  resulting widget.
 

lib/naughty/layout/legacy.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification popup widget.
+--- A notification popup widget (deprecated implementation).
 --
 -- This is the legacy notification widget. It was the default until Awesome
 -- v4.3 but is now being deprecated in favor of a more flexible widget.

lib/naughty/notification.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- A notification object.
+--- Notification manipulation class.
 --
 -- This class creates individual notification objects that can be manipulated
 -- to extend the default behavior.
@@ -110,7 +110,7 @@ local notification = {}
 -- * critical
 --
 -- @property urgency
--- @param string
+-- @tparam string urgency
 -- @propemits true false
 
 --- The notification category.
@@ -167,17 +167,17 @@ local notification = {}
 -- be updated with a date further in the future.
 --
 -- @property resident
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean resident
 -- @propemits true false
 
 --- Delay in seconds after which hovered popup disappears.
 -- @property hover_timeout
--- @param number
+-- @tparam[opt=nil] number|nil hover_timeout
 -- @propemits true false
 
 --- Target screen for the notification.
 -- @property screen
--- @param screen
+-- @tparam screen screen
 -- @propemits true false
 
 --- Corner of the workarea displaying the popups.
@@ -195,34 +195,35 @@ local notification = {}
 --@DOC_awful_notification_box_corner_EXAMPLE@
 --
 -- @property position
--- @param string
+-- @tparam[opt=beautiful.notification_position] string position
 -- @propemits true false
 -- @see awful.placement.next_to
 
 --- Boolean forcing popups to display on top.
 -- @property ontop
--- @param boolean
+-- @tparam[opt=false] boolean ontop
 
 --- Popup height.
 --
 --@DOC_awful_notification_geometry_EXAMPLE@
 --
 -- @property height
--- @param number
+-- @tparam number height
 -- @propemits true false
 -- @see width
 
 --- Popup width.
 -- @property width
--- @param number
+-- @tparam number width
 -- @propemits true false
 -- @see height
 
 --- Notification font.
 --@DOC_naughty_colors_EXAMPLE@
 -- @property font
--- @param string
+-- @tparam string font
 -- @propemits true false
+-- @see wibox.widget.textbox.font
 
 --- "All in one" way to access the default image or icon.
 --
@@ -248,7 +249,7 @@ local notification = {}
 
 --- Desired icon size in px.
 -- @property icon_size
--- @param number
+-- @tparam[opt=beautiful.notification_icon_size] number icon_size
 -- @propemits true false
 
 --- The icon provided in the `app_icon` field of the DBus notification.
@@ -257,7 +258,7 @@ local notification = {}
 -- icon name to be fetched from the theme.
 --
 -- @property app_icon
--- @param string
+-- @tparam string app_icon
 -- @propemits true false
 
 --- The notification image.
@@ -287,7 +288,7 @@ local notification = {}
 --@DOC_awful_notification_fg_EXAMPLE@
 --
 -- @property fg
--- @tparam string|color|pattern fg
+-- @tparam[beautiful.notification_fg] string|color|pattern fg
 -- @propemits true false
 -- @see title
 -- @see gears.color
@@ -297,14 +298,14 @@ local notification = {}
 --@DOC_awful_notification_bg_EXAMPLE@
 --
 -- @property bg
--- @tparam string|color|pattern bg
+-- @tparam[opt=beautiful.notification_bg] string|color|pattern bg
 -- @propemits true false
 -- @see title
 -- @see gears.color
 
 --- Border width.
 -- @property border_width
--- @param number
+-- @tparam[opt=beautiful.notification_border_width or 0] number border_width
 -- @propemits true false
 
 --- Border color.
@@ -312,7 +313,7 @@ local notification = {}
 --@DOC_awful_notification_border_color_EXAMPLE@
 --
 -- @property border_color
--- @param string
+-- @tparam[opt=beautiful.notification_border_color] string border_color
 -- @propemits true false
 -- @see gears.color
 
@@ -368,14 +369,14 @@ local notification = {}
 -- args will override ones defined
 --   in the preset.
 -- @property preset
--- @param table
+-- @tparam table preset
 -- @propemits true false
 
 --- Function that will be called with all arguments.
 --   The notification will only be displayed if the function returns true.
 --   Note: this function is only relevant to notifications sent via dbus.
 -- @property callback
--- @param function
+-- @tparam function callback
 -- @propemits true false
 
 --- A table containing strings that represents actions to buttons.
@@ -383,7 +384,7 @@ local notification = {}
 -- The table key (a number) is used by DBus to set map the action.
 --
 -- @property actions
--- @param table
+-- @tparam table actions
 -- @propemits true false
 
 --- Ignore this notification, do not display.
@@ -392,19 +393,20 @@ local notification = {}
 -- handler.
 --
 -- @property ignore
--- @param boolean
+-- @tparam[opt=false] boolean ignore
 -- @propemits true false
 
 --- Tell if the notification is currently suspended (read only).
 --
 -- This is always equal to `naughty.suspended`
 -- @property suspended
---@param boolean
+-- @tparam[opt=false] boolean suspended
 -- @propemits true false
+-- @see naughty.suspended
 
 --- If the notification is expired.
 -- @property is_expired
--- @param boolean
+-- @tparam boolean is_expired
 -- @propemits true false
 -- @see naughty.expiration_paused
 
@@ -436,7 +438,7 @@ local notification = {}
 -- client.
 --
 -- @property clients
--- @param table
+-- @tparam table clients
 
 --- The maximum popup width.
 --
@@ -444,8 +446,8 @@ local notification = {}
 -- this is ignored by `naughty.list.notifications` because it delegate this
 -- decision to the layout.
 --
--- @property[opt=500] max_width
+-- @property max_width
--- @param number
+-- @tparam[opt=500] number max_width
 -- @propemits true false
 
 --- The application name specified by the notification.
@@ -454,7 +456,7 @@ local notification = {}
 -- property, but can sometime be specified for remote or headless notifications.
 -- In these case, it helps to triage and detect the notification from the rules.
 -- @property app_name
--- @param string
+-- @tparam string app_name
 -- @propemits true false
 
 --- The widget template used to represent the notification.
@@ -463,7 +465,7 @@ local notification = {}
 -- off with a specialized notification widget.
 --
 -- @property widget_template
--- @param table
+-- @tparam table|nil widget_template
 -- @propemits true false
 
 --- Destroy notification by notification object.
@@ -921,9 +923,9 @@ end
 -- @tparam[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] string args.bg Background color.
 -- @tparam[opt=`beautiful.notification_border_width` or 1] integer args.border_width Border width.
 -- @tparam[opt=`beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'`] gears.color args.border_color Border color.
--- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape.
+-- @tparam[opt=beautiful.notification_shape] gears.shape args.shape Widget shape.
--- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity.
+-- @tparam[opt=beautiful.notification_opacity] gears.opacity args.opacity Widget opacity.
--- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin.
+-- @tparam[opt=beautiful.notification_margin] gears.margin args.margin Widget margin.
 -- @tparam[opt] function args.run Function to run on left click.  The notification
 --   object will be passed to it as an argument.
 --   You need to call e.g.

lib/naughty/widget/icon.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification square icon.
+--- A notification square icon widget.
 --
 -- This widget is a specialized `wibox.widget.imagebox` with the following extra
 -- features:
@@ -14,6 +14,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @widgetmod naughty.widget.icon
+-- @supermodule wibox.widget.imagebox
 -- @see wibox.widget.imagebox
 ----------------------------------------------------------------------------
 local imagebox = require("wibox.widget.imagebox")
@@ -24,7 +25,7 @@ local dpi = require("beautiful.xresources").apply_dpi
 
 local icon = {}
 
--- The default way to resize the icon.
+--- The default way to resize the icon.
 -- @beautiful beautiful.notification_icon_resize_strategy
 -- @param number
 
@@ -130,6 +131,11 @@ local valid_strategies = {
 --  there is no specified strategy.
 -- @usebeautiful beautiful.notification_icon_size  The size upper bound.
 
+
+--- The default notification icon size.
+-- @beautiful beautiful.notification_icon_size
+-- @tparam number notification_icon_size The size (in pixels).
+
 function icon:set_resize_strategy(strategy)
     assert(valid_strategies[strategy], "Invalid strategy")
 

lib/naughty/widget/message.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification content message.
+--- A notification content message widget.
 --
 -- This widget is a specialized `wibox.widget.textbox` with the following extra
 -- features:
@@ -12,6 +12,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @widgetmod naughty.widget.message
+-- @supermodule wibox.widget.textbox
 -- @see wibox.widget.textbox
 ----------------------------------------------------------------------------
 local textbox = require("wibox.widget.textbox")

lib/naughty/widget/title.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification title.
+--- A notification title widget.
 --
 -- This widget is a specialized `wibox.widget.textbox` with the following extra
 -- features:
@@ -12,6 +12,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @widgetmod naughty.widget.title
+-- @supermodule wibox.widget.textbox
 -- @see wibox.widget.textbox
 ----------------------------------------------------------------------------
 local textbox = require("wibox.widget.textbox")

lib/ruled/client.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Rules for clients.
+--- Apply properties to a new client based on pre-determined rules.
 --
 -- This module applies @{rules} to clients during startup (via @{client.manage},
 -- but its functions can be used for client matching in general.

lib/ruled/notification.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Rules for notifications.
+--- Apply properties to a new `naughty.notification` based on pre-determined rules.
 --
 --@DOC_wibox_nwidget_rules_urgency_EXAMPLE@
 --

lib/wibox/container/arcchart.lua

@@ -1,6 +1,5 @@
 ---------------------------------------------------------------------------
---
+-- A circular chart (arc chart) container.
--- A circular chart (arc chart).
 --
 -- It can contain a central widget (or not) and display multiple values.
 --
@@ -43,7 +42,19 @@ local arcchart = { mt = {} }
 
 --- The arc thickness.
 -- @beautiful beautiful.arcchart_thickness
--- @param number
+-- @tparam number arcchart_thickness
+
+--- If the chart has rounded edges.
+-- @beautiful beautiful.arcchart_rounded_edge
+-- @tparam boolean arcchart_rounded_edge
+
+--- The radial background.
+-- @beautiful beautiful.arcchart_bg
+-- @tparam gears.color arcchart_bg
+
+--- The (radiant) angle where the first value start.
+-- @beautiful beautiful.arcchart_start_angle
+-- @tparam number arcchart_start_angle
 
 local function outline_workarea(width, height)
     local x, y = 0, 0
@@ -102,7 +113,6 @@ function arcchart:after_draw_children(_, cr, width, height)
     local wa = outline_workarea(width, height)
     cr:translate(wa.x+border_width/2, wa.y+border_width/2)
 
-
     -- Get the min and max value
     --local min_val = self:get_min_value() or 0 --TODO support min_values
     local max_val = self:get_max_value()
@@ -245,9 +255,9 @@ end
 --- The arcchart values foreground colors.
 --@DOC_wibox_container_arcchart_color_EXAMPLE@
 -- @property colors
--- @tparam table values An ordered set of colors for each value in arcchart.
+-- @tparam table colors An ordered set of colors for each value in arcchart.
 -- @propemits true false
--- @propbeautiful
+-- @usebeautiful beautiful.arcchart_color
 
 --- The border width.
 --
@@ -279,7 +289,7 @@ end
 --- The value.
 --@DOC_wibox_container_arcchart_value_EXAMPLE@
 -- @property value
--- @tparam number value Between min_value and max_value
+-- @tparam number value Between `min_value` and `max_value`
 -- @see values
 -- @propemits true false
 
@@ -297,18 +307,21 @@ end
 -- @property rounded_edge
 -- @tparam[opt=false] boolean rounded_edge
 -- @propemits true false
+-- @propbeautiful
 
 --- The arc thickness.
 --@DOC_wibox_container_arcchart_thickness_EXAMPLE@
 -- @property thickness
 -- @propemits true false
 -- @tparam number thickness
+-- @propbeautiful
 
 --- The (radiant) angle where the first value start.
 -- @DOC_wibox_container_arcchart_start_angle_EXAMPLE@
 -- @property start_angle
 -- @tparam[opt=math.pi] number start_angle A number between 0 and 2*math.pi
 -- @propemits true false
+-- @usebeautiful beautiful.arcchart_start_angle
 
 for _, prop in ipairs {"border_width", "border_color", "paddings", "colors",
     "rounded_edge", "bg", "thickness", "values", "min_value", "max_value",

lib/wibox/container/background.lua

@@ -349,7 +349,7 @@ end
 --
 -- See `wibox.container.background.shape` for an usage example.
 -- @property border_width
--- @tparam[opt=0] number width The border width.
+-- @tparam[opt=0] number border_width The border width.
 -- @propemits true false
 -- @introducedin 4.4
 -- @see border_color
@@ -386,7 +386,7 @@ end
 --
 -- @deprecatedproperty shape_border_color
 -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set.
--- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient
+-- @tparam color fg The border color, pattern or gradient
 -- @renamedin 4.4 border_color
 -- @see gears.color
 -- @see border_color
@@ -395,7 +395,7 @@ end
 --
 -- See `wibox.container.background.shape` for an usage example.
 -- @property border_color
--- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient
+-- @tparam[opt=fg] color border_color The border color, pattern or gradient
 -- @propemits true false
 -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set.
 -- @introducedin 4.4
@@ -462,7 +462,7 @@ end
 -- as arguments. Any other arguments passed to this method will be appended.
 --
 -- @property bgimage
--- @tparam string|surface|function image A background image or a function
+-- @tparam string|surface|function bgimage A background image or a function
 -- @see gears.surface
 
 function background:set_bgimage(image, ...)

lib/wibox/container/margin.lua

@@ -94,7 +94,7 @@ end
 --- Set all the margins to val.
 --
 -- @property margins
--- @tparam number|table val The margin value. It can be a number or a table with
+-- @tparam number|table margins The margin value. It can be a number or a table with
 --  the *left*/*right*/*top*/*bottom* keys.
 -- @propemits false false
 
@@ -126,7 +126,7 @@ end
 --- Set the margins color to create a border.
 --
 -- @property color
--- @param color A color used to fill the margin.
+-- @tparam gears.color color A color used to fill the margin.
 -- @propemits true false
 
 function margin:set_color(color)
@@ -206,13 +206,13 @@ end
 
 --- Returns a new margin container.
 --
--- @param[opt] widget A widget to use.
+-- @tparam[opt] widget widget A widget to use.
--- @param[opt] left A margin to use on the left side of the widget.
+-- @tparam[opt] number left A margin to use on the left side of the widget.
--- @param[opt] right A margin to use on the right side of the widget.
+-- @tparam[opt] number right A margin to use on the right side of the widget.
--- @param[opt] top A margin to use on the top side of the widget.
+-- @tparam[opt] number top A margin to use on the top side of the widget.
--- @param[opt] bottom A margin to use on the bottom side of the widget.
+-- @tparam[opt] number bottom A margin to use on the bottom side of the widget.
--- @param[opt] color A color for the margins.
+-- @tparam[opt] gears.color color A color for the margins.
--- @param[opt] draw_empty whether or not to draw the margin when the content is empty
+-- @tparam[opt] boolean draw_empty Whether or not to draw the margin when the content is empty
 -- @treturn table A new margin container
 -- @constructorfct wibox.container.margin
 local function new(widget, left, right, top, bottom, color, draw_empty)

lib/wibox/container/radialprogressbar.lua

@@ -178,7 +178,7 @@ end
 --
 --@DOC_wibox_container_radialprogressbar_value_EXAMPLE@
 -- @property value
--- @tparam number value Between min_value and max_value.
+-- @tparam number value Between `min_value` and `max_value`.
 -- @propemits true false
 
 function radialprogressbar:set_value(val)

lib/wibox/container/rotate.lua

@@ -101,7 +101,7 @@ end
 --
 --@DOC_wibox_container_rotate_angle_EXAMPLE@
 -- @property direction
--- @tparam string dir The direction.
+-- @tparam[opt="north"] string direction The direction.
 -- @propemits true false
 
 function rotate:set_direction(dir)

lib/wibox/container/tile.lua

@@ -110,7 +110,7 @@ end
 --@DOC_wibox_container_tile_horizontal_crop_EXAMPLE@
 --
 -- @property horizontal_crop
--- @tparam[opt=false] boolean tiled
+-- @tparam[opt=false] boolean horizontal_crop
 -- @see vertical_crop
 
 --- Avoid painting incomplete vertical tiles.
@@ -118,7 +118,7 @@ end
 --@DOC_wibox_container_tile_vertical_crop_EXAMPLE@
 --
 -- @property vertical_crop
--- @tparam[opt=false] boolean tiled
+-- @tparam[opt=false] boolean vertical_crop
 -- @see horizontal_crop
 
 --- Enable or disable the tiling.
@@ -199,9 +199,19 @@ end
 
 --- Create a new tile container.
 -- @tparam table args
--- @tparam wibox.widget widget args.widget The widget to tile.
+-- @tparam wibox.widget args.widget args.widget The widget to tile.
 -- @tparam string args.halign Either `left`, `right` or `center`.
 -- @tparam string args.valign Either `top`, `bottom` or `center`.
+-- @tparam number args.horizontal_spacing The horizontal spacing between the tiled.
+-- @tparam number args.vertical_spacing The vertical spacing between the tiled.
+-- @tparam boolean args.horizontal_crop Avoid painting incomplete horizontal tiles.
+-- @tparam boolean args.vertical_crop Avoid painting incomplete vertical tiles.
+-- @tparam boolean args.tiled Enable or disable the tiling.
+-- @tparam wibox.widget args.widget The widget to be placed.
+-- @tparam boolean args.fill_vertical Fill the vertical space.
+-- @tparam boolean args.fill_horizontal Fill the horizontal space.
+-- @tparam boolean args.content_fill_vertical Stretch the contained widget so it takes all the vertical space.
+-- @tparam boolean args.content_fill_horizontal Stretch the contained widget so it takes all the horizontal space.
 -- @constructorfct wibox.container.tile
 function module.mt:__call(...)
     return new(...)

lib/wibox/drawable.lua

@@ -199,7 +199,7 @@ local function find_widgets(self, result, hierarchy, x, y)
     end
 end
 
---- Find a widget by a point.
+-- Find a widget by a point.
 -- The drawable must have drawn itself at least once for this to work.
 -- @param x X coordinate of the point
 -- @param y Y coordinate of the point

lib/wibox/init.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Box where widget can be displayed.
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @popupmod wibox

lib/wibox/layout/align.lua

@@ -273,7 +273,7 @@ end
 -- `"inside"`.
 --
 -- @property expand
--- @tparam[opt="inside"] string mode How to use unused space.
+-- @tparam[opt="inside"] string expand How to use unused space.
 
 function align:set_expand(mode)
     if mode == "none" or mode == "outside" then

lib/wibox/layout/fixed.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Place many widgets in a column or row, until the available space is used up.
+--
 -- A `fixed` layout may be initialized with any number of child widgets, and
 -- during runtime widgets may be added and removed dynamically.
 --

lib/wibox/layout/flex.lua

@@ -1,4 +1,7 @@
 ---------------------------------------------------------------------------
+-- Split the space equally between multiple widgets.
+--
+--
 -- A `flex` layout may be initialized with any number of child widgets, and
 -- during runtime widgets may be added and removed dynamically.
 --
@@ -49,7 +52,7 @@ local flex = {}
 
 --- Remove a widget from the layout.
 --
--- @tparam index The widget index to remove.
+-- @tparam number index The widget index to remove.
 -- @treturn boolean index If the operation is successful.
 -- @method remove
 -- @interface layout

lib/wibox/layout/grid.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- A grid layout.
+--- Place multiple widgets in multiple rows and columns.
 --
 -- Widgets spanning several columns or rows cannot be included using the
 -- declarative system.
@@ -52,7 +52,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
 --  row is filled, creating it if it does not exist.
 --
 --@DOC_wibox_layout_grid_orientation_EXAMPLE@
--- @param[opt="vertical"] string Preferred orientation: "horizontal" or "vertical".
+-- @tparam[opt="vertical"] string orientation Preferred orientation: "horizontal" or "vertical".
 -- @property orientation
 
 --- Allow to superpose widgets in the same cell.
@@ -60,39 +60,39 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
 -- widget and prevent from adding it.
 --
 --@DOC_wibox_layout_grid_superpose_EXAMPLE@
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean superpose
 -- @property superpose
 
 --- Force the number of rows of the layout.
 -- @property forced_num_rows
--- @tparam[opt=nil] number|nil number Forced number of rows (`nil` for automatic).
+-- @tparam[opt=nil] number|nil forced_num_rows Forced number of rows (`nil` for automatic).
 
 --- Force the number of columns of the layout.
 -- @property forced_num_cols
--- @tparam[opt=nil] number|nil number Forced number of columns (`nil` for automatic).
+-- @tparam[opt=nil] number|nil forced_num_cols Forced number of columns (`nil` for automatic).
 
 --- Set the minimum size for the columns.
 --
 --@DOC_wibox_layout_grid_min_size_EXAMPLE@
--- @param[opt=0] number Minimum size of the columns.
+-- @tparam[opt=0] number min_cols_size Minimum size of the columns.
 -- @property min_cols_size
 
 --- Set the minimum size for the rows.
--- @param[opt=0] number Minimum size of the rows.
+-- @tparam[opt=0] number min_rows_size Minimum size of the rows.
 -- @property min_rows_size
 
 --- The spacing between columns.
 --
 -- see `spacing`
 --
--- @param[opt=0] number The spacing
+-- @tparam[opt=0] number horizontal_spacing The spacing
 -- @property horizontal_spacing
 
 --- The spacing between rows.
 --
 -- see `spacing`
 --
--- @param[opt=0] number The spacing
+-- @tparam[opt=0] number vertical_spacing The spacing
 -- @property vertical_spacing
 
 --- The spacing between rows and columns.
@@ -101,21 +101,21 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
 -- preferred `orientation`.
 --
 --@DOC_wibox_layout_grid_spacing_EXAMPLE@
--- @param[opt=0] number The spacing
+-- @tparam[opt=0] number spacing The spacing
 -- @property spacing
 
 --- Controls if the columns are expanded to use all the available width.
 --
 -- see `expand`
 --
--- @param[opt=false] boolean Expand the grid into the available space
+-- @tparam[opt=false] boolean horizontal_expand Expand the grid into the available space
 -- @property horizontal_expand
 
 --- Controls if the rows are expanded to use all the available height.
 --
 -- see `expand`
 --
--- @param[opt=false] boolean Expand the grid into the available space
+-- @tparam[opt=false] boolean vertical_expand Expand the grid into the available space
 -- @property vertical_expand
 
 --- Controls if the columns/rows are expanded to use all the available space.
@@ -124,7 +124,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
 -- preferred `orientation`.
 --
 --@DOC_wibox_layout_grid_expand_EXAMPLE@
--- @param[opt=false] boolean Expand the grid into the available space
+-- @tparam[opt=false] boolean expand Expand the grid into the available space
 -- @property expand
 
 --- Controls if the columns all have the same width or if the width of each
@@ -132,7 +132,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
 --
 -- see `homogeneous`
 --
--- @param[opt=true] boolean All the columns have the same width.
+-- @tparam[opt=true] boolean horizontal_homogeneous All the columns have the same width.
 -- @property horizontal_homogeneous
 
 --- Controls if the rows all have the same height or if the height of each row
@@ -140,7 +140,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
 --
 -- see `homogeneous`
 --
--- @param[opt=true] boolean All the rows have the same height.
+-- @tparam[opt=true] boolean vertical_homogeneous All the rows have the same height.
 -- @property vertical_homogeneous
 
 --- Controls if the columns/rows all have the same size or if the size depends
@@ -150,7 +150,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
 -- by the preferred `orientation`.
 --
 --@DOC_wibox_layout_grid_expand_EXAMPLE@
--- @param[opt=true] boolean All the columns/rows have the same size.
+-- @tparam[opt=true] boolean homogeneous All the columns/rows have the same size.
 -- @property homogeneous
 
 --- Child widget position. Return of `get_widget_position`.
@@ -305,7 +305,7 @@ end
 --@DOC_wibox_layout_grid_add_EXAMPLE@
 --
 -- @method add_widget_at
--- @param child Widget that should be added
+-- @tparam wibox.widget child Widget that should be added
 -- @tparam number row Row number for the top left corner of the widget
 -- @tparam number col Column number for the top left corner of the widget
 -- @tparam[opt=1] number row_span The number of rows the widget spans.
@@ -400,7 +400,7 @@ end
 
 --- Return the coordinates of the widget.
 -- @method get_widget_position
--- @param widget The widget
+-- @tparam widget widget The widget
 -- @treturn table The `position` table of the coordinates in the grid, with
 -- fields `row`, `col`, `row_span` and `col_span`.
 function grid:get_widget_position(widget)
@@ -441,8 +441,8 @@ end
 
 --- Replace old widget by new widget, spanning the same columns and rows.
 -- @method replace_widget
--- @param old The widget to remove
+-- @tparam widget old The widget to remove
--- @param new The widget to add
+-- @tparam widget new The widget to add
 -- @treturn boolean If the operation is successful (widget found)
 function grid:replace_widget(old, new)
     -- check if the new object is a widget

lib/wibox/layout/stack.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- A stacked layout.
+-- Place multiple widgets on top of each other.
 --
 -- This layout display widgets on top of each other. It can be used to overlay
 -- a `wibox.widget.textbox` on top of a `awful.widget.progressbar` or manage
@@ -31,7 +31,7 @@ local stack = {mt={}}
 
 --- Remove a widget from the layout.
 --
--- @tparam index The widget index to remove
+-- @tparam number index The widget index to remove
 -- @treturn boolean index If the operation is successful
 -- @method remove
 -- @interface layout
@@ -115,7 +115,7 @@ end
 --- Raise a widget at `index` to the top of the stack.
 --
 -- @method raise
--- @tparam number index the widget index to raise
+-- @tparam number index The widget index to raise
 function stack:raise(index)
     if (not index) or (not self._private.widgets[index]) then return end
 

lib/wibox/widget/background.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- This class has been moved to `wibox.container.background`
+-- This class has been moved to `wibox.container.background`.
 --
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter

lib/wibox/widget/base.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Base class of every widgets, containers and layouts,
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @classmod wibox.widget.base
@@ -31,17 +33,17 @@ local base = {}
 -- widgets hierarchy. A hierarchy loop is when a widget, or any of its
 -- children, contain (directly or indirectly) itself.
 -- @property all_children
--- @tparam table children The children.
+-- @tparam table all_children The children.
 -- @baseclass wibox.widget.base
 
 --- Force a widget height.
 -- @property forced_height
--- @tparam number|nil height The height (`nil` for automatic)
+-- @tparam number|nil forced_height The height (`nil` for automatic)
 -- @baseclass wibox.widget.base
 
 --- Force a widget width.
 -- @property forced_width
--- @tparam number|nil width The width (`nil` for automatic)
+-- @tparam number|nil forced_width The width (`nil` for automatic)
 -- @baseclass wibox.widget.base
 
 --- The widget opacity (transparency).
@@ -51,14 +53,14 @@ local base = {}
 
 --- The widget visibility.
 -- @property visible
--- @param boolean
+-- @tparam[opt=true] boolean visible
 -- @baseclass wibox.widget.base
 
 --- The widget buttons.
 --
 -- The table contains a list of `awful.button` objects.
 -- @property buttons
--- @param table
+-- @tparam table buttons
 -- @see awful.button
 -- @baseclass wibox.widget.base
 
@@ -92,7 +94,7 @@ local base = {}
 -- @tparam number button The button number.
 -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -123,7 +125,7 @@ local base = {}
 -- @tparam number button The button number.
 -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -148,7 +150,7 @@ local base = {}
 -- @signal mouse::enter
 -- @tparam table self The current object instance itself.
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -173,7 +175,7 @@ local base = {}
 -- @signal mouse::leave
 -- @tparam table self The current object instance itself.
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.

lib/wibox/widget/calendar.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- A calendar widget.
+-- Display a monthly or yearly calendar.
 --
 -- This module defines two widgets: a month calendar and a year calendar
 --
@@ -71,7 +71,7 @@ local properties = { "date"        , "font"         , "spacing" , "week_numbers"
 -- A table representing the date {day=[number|nil], month=[number|nil], year=[number]}.
 --
 -- E.g.. {day=21, month=2, year=2005}, {month=2, year=2005}, {year=2005}
--- @tparam date table Date table.
+-- @tparam table date Date table.
 -- @tparam number date.year Date year
 -- @tparam number|nil date.month Date month
 -- @tparam number|nil date.day Date day
@@ -80,34 +80,44 @@ local properties = { "date"        , "font"         , "spacing" , "week_numbers"
 --- The calendar font.
 --
 -- Choose a monospace font for a better rendering.
+--
 --@DOC_wibox_widget_calendar_font_EXAMPLE@
--- @param[opt="Monospace 10"] string Font of the calendar
+--
+-- @tparam[opt="Monospace 10"] string font Font of the calendar
 -- @property font
+-- @usebeautiful beautiful.calendar_font
 
 --- The calendar spacing.
 --
 -- The spacing between cells in the month.
 -- The spacing between months in a year calendar is twice this value.
--- @param[opt=5] number Spacing of the grid
+-- @tparam[opt=5] number spacing Spacing of the grid
 -- @property spacing
+-- @usebeautiful beautiful.calendar_spacing
 
 --- Display the calendar week numbers.
 --
 --@DOC_wibox_widget_calendar_week_numbers_EXAMPLE@
--- @param[opt=false] boolean Display week numbers
+--
+-- @tparam[opt=false] boolean week_numbers Display week numbers
 -- @property week_numbers
+-- @usebeautiful beautiful.calendar_week_numbers
 
 --- Start the week on Sunday.
 --
 --@DOC_wibox_widget_calendar_start_sunday_EXAMPLE@
--- @param[opt=false] boolean Start the week on Sunday
+--
+-- @tparam[opt=false] boolean start_sunday Start the week on Sunday
 -- @property start_sunday
+-- @usebeautiful beautiful.calendar_start_sunday
 
 --- Format the weekdays with three characters instead of two
 --
 --@DOC_wibox_widget_calendar_long_weekdays_EXAMPLE@
--- @param[opt=false] boolean Use three characters for the weekdays instead of two
+--
+-- @tparam[opt=false] boolean long_weekdays Use three characters for the weekdays instead of two
 -- @property long_weekdays
+-- @usebeautiful beautiful.calendar_long_weekdays
 
 --- The widget encapsulating function.
 --
@@ -119,15 +129,16 @@ local properties = { "date"        , "font"         , "spacing" , "week_numbers"
 -- It is used to add a container to the grid layout and to the cells:
 --
 --@DOC_wibox_widget_calendar_fn_embed_cell_EXAMPLE@
--- @param function Function to embed the widget depending on its flag
+-- @tparam function fn_embed Function to embed the widget depending on its flag
 -- @property fn_embed
 
 --- Allow cells to have flexible height
 --
 --@DOC_wibox_widget_calendar_flex_height_EXAMPLE@
 --
--- @param[opt=false] boolean Allow flex height.
+-- @tparam[opt=false] boolean flex_height Allow flex height.
 -- @property flex_height
+-- @usebeautiful beautiful.flex_height
 
 --- Make a textbox
 -- @tparam string text Text of the textbox
@@ -257,7 +268,7 @@ end
 
 --- Create a grid layout for the year calendar
 -- @tparam table props Table of year calendar properties
--- @param date Year to display (number or string)
+-- @tparam number|string date Year to display.
 -- @treturn widget Grid layout
 local function create_year(props, date)
     -- Create a grid widget with the 12 months

lib/wibox/widget/checkbox.lua

@@ -137,7 +137,7 @@ local checkbox = {}
 -- If none is set, then the `shape` property will be used.
 --@DOC_wibox_widget_checkbox_check_shape_EXAMPLE@
 -- @property check_shape
--- @tparam gears.shape shape
+-- @tparam gears.shape check_shape
 -- @propbeautiful
 -- @propemits true false
 -- @see gears.shape
@@ -254,7 +254,7 @@ end
 
 --- If the checkbox is checked.
 -- @property checked
--- @param boolean
+-- @tparam[opt=false] boolean checked
 
 for _, prop in ipairs {"border_width", "bg", "border_color", "check_border_color",
     "check_border_width", "check_color", "shape", "check_shape", "paddings",

lib/wibox/widget/graph.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- A graph widget.
+--- Display multiple values as a stream of bars.
 --
 -- The graph goes from left to right. To change this to right to left, use
 -- a `wibox.container.mirror` widget. This can also be used to have data
@@ -84,7 +84,7 @@ local graph = { mt = {} }
 -- @DOC_wibox_widget_graph_stacked_group_disable_EXAMPLE@
 --
 -- @property group_colors
--- @tparam table colors A table with colors for data groups.
+-- @tparam table group_colors A table with colors for data groups.
 -- @see gears.color
 
 --- The maximum value the graph should handle.

lib/wibox/widget/imagebox.lua

@@ -547,7 +547,7 @@ end
 -- @DOC_wibox_widget_imagebox_vertical_fit_policy_EXAMPLE@
 --
 -- @property vertical_fit_policy
--- @tparam[opt="auto"] string horizontal_fit_policy
+-- @tparam[opt="auto"] string vertical_fit_policy
 -- @propemits true false
 -- @see horizontal_fit_policy
 -- @see resize

lib/wibox/widget/init.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+--- Utility function for working with widgets.
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @module wibox.widget

lib/wibox/widget/piechart.lua

@@ -191,7 +191,7 @@ end
 --
 --@DOC_wibox_widget_piechart_label_EXAMPLE@
 -- @property display_labels
--- @param[opt=true] boolean
+-- @tparam[opt=true] boolean display_labels
 
 --- The pie elements border width.
 --

lib/wibox/widget/progressbar.lua

@@ -54,7 +54,7 @@ local progressbar = { mt = {} }
 -- @DOC_wibox_widget_progressbar_border_color_EXAMPLE@
 --
 -- @property border_color
--- @tparam gears.color color The border color to set.
+-- @tparam gears.color border_color The border color to set.
 -- @propemits true false
 -- @propbeautiful
 -- @see gears.color
@@ -75,7 +75,7 @@ local progressbar = { mt = {} }
 -- @DOC_wibox_widget_progressbar_bar_border_color_EXAMPLE@
 --
 -- @property bar_border_color
--- @tparam gears.color color The border color to set.
+-- @tparam gears.color bar_border_color The border color to set.
 -- @propemits true false
 -- @propbeautiful
 -- @see gears.color
@@ -104,7 +104,7 @@ local progressbar = { mt = {} }
 -- @DOC_wibox_widget_progressbar_background_color_EXAMPLE@
 --
 -- @property background_color
--- @tparam gears.color color The progressbar background color.
+-- @tparam gears.color background_color The progressbar background color.
 -- @propemits true false
 -- @usebeautiful beautiful.progressbar_bg
 -- @see gears.color
@@ -114,7 +114,7 @@ local progressbar = { mt = {} }
 --@DOC_wibox_widget_progressbar_bar_shape_EXAMPLE@
 --
 -- @property bar_shape
--- @tparam[opt=gears.shape.rectangle] gears.shape shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape bar_shape
 -- @propemits true false
 -- @propbeautiful
 -- @see gears.shape
@@ -243,7 +243,7 @@ local progressbar = { mt = {} }
 -- @DOC_wibox_widget_progressbar_margins1_EXAMPLE@
 --
 -- @property margins
--- @tparam[opt=0] (table|number|nil) margins A table for each side or a number
+-- @tparam[opt=0] table|number|nil margins A table for each side or a number
 -- @tparam[opt=0] number margins.top
 -- @tparam[opt=0] number margins.bottom
 -- @tparam[opt=0] number margins.left
@@ -268,7 +268,7 @@ local progressbar = { mt = {} }
 -- @DOC_wibox_widget_progressbar_paddings1_EXAMPLE@
 --
 -- @property paddings
--- @tparam[opt=0] (table|number|nil) padding A table for each side or a number
+-- @tparam[opt=0] (table|number|nil) paddings A table for each side or a number
 -- @tparam[opt=0] number paddings.top
 -- @tparam[opt=0] number paddings.bottom
 -- @tparam[opt=0] number paddings.left
@@ -591,8 +591,24 @@ end
 --
 -- @tparam table args Standard widget() arguments. You should add width and
 --  height constructor parameters to set progressbar geometry.
--- @tparam number args.width The width.
+-- @tparam[opt] number args.width The width.
--- @tparam number args.height The height.
+-- @tparam[opt] number args.height The height.
+-- @tparam[opt] gears.color args.border_color The progressbar border color.
+-- @tparam[opt] number args.border_width The progressbar border width.
+-- @tparam[opt] gears.color args.bar_border_color The progressbar inner border color.
+-- @tparam[opt] number args.bar_border_width The progressbar inner border width.
+-- @tparam[opt] gears.color args.color The progressbar foreground color.
+-- @tparam[opt] gears.color args.background_color The progressbar background color.
+-- @tparam[opt] gears.shape args.bar_shape The progressbar inner shape.
+-- @tparam[opt] gears.shape args.shape The progressbar shape.
+-- @tparam[opt] boolean args.clip Force the inner part (the bar) to fit in the background shape.
+-- @tparam[opt] boolean args.ticks The progressbar to draw ticks.
+-- @tparam[opt] number args.ticks_gap The progressbar ticks gap.
+-- @tparam[opt] number args.ticks_size The progressbar ticks size.
+-- @tparam[opt] number args.max_value The maximum value the progressbar should handle.
+-- @tparam[opt] table|number args.margins The progressbar margins.
+-- @tparam[opt] table|number args.paddings The progressbar padding.
+-- @tparam[opt] number args.value Set the progressbar value.
 -- @treturn wibox.widget.progressbar A progressbar widget.
 -- @constructorfct wibox.widget.progressbar
 function progressbar.new(args)

lib/wibox/widget/separator.lua

@@ -68,7 +68,7 @@ local separator = {}
 --- The relative percentage covered by the bar.
 --
 -- @property span_ratio
--- @tparam[opt=1] number A number between 0 and 1.
+-- @tparam[opt=1] number span_ratio A number between 0 and 1.
 -- @propbeautiful
 -- @propemits true false
 
@@ -112,7 +112,7 @@ local separator = {}
 
 --- The relative percentage covered by the bar.
 -- @beautiful beautiful.separator_span_ratio
--- @tparam[opt=1] number A number between 0 and 1.
+-- @tparam[opt=1] number separator_span_ratio A number between 0 and 1.
 
 --- The separator's color.
 -- @beautiful beautiful.separator_color
@@ -203,6 +203,13 @@ end
 --- Create a new separator.
 -- @constructorfct wibox.widget.separator
 -- @tparam table args The arguments (all properties are available).
+-- @tparam[opt] string args.orientation The separator's orientation.
+-- @tparam[opt] number args.thickness The separator's thickness.
+-- @tparam[opt] function args.shape The separator's shape.
+-- @tparam[opt] number args.span_ratio The relative percentage covered by the bar.
+-- @tparam[opt] color args.color The separator's color.
+-- @tparam[opt] color args.border_color The separator's border color.
+-- @tparam[opt] number args.border_width The separator's border width.
 
 local function new(args)
     local ret = base.make_widget(nil, nil, {

lib/wibox/widget/slider.lua

@@ -30,7 +30,7 @@ local slider = {mt={}}
 --@DOC_wibox_widget_slider_handle_shape_EXAMPLE@
 --
 -- @property handle_shape
--- @tparam[opt=gears shape rectangle] gears.shape shape
+-- @tparam[opt=gears shape rectangle] gears.shape handle_shape
 -- @propemits true false
 -- @propbeautiful
 -- @see gears.shape
@@ -49,7 +49,7 @@ local slider = {mt={}}
 --@DOC_wibox_widget_slider_handle_margins_EXAMPLE@
 --
 -- @property handle_margins
--- @tparam[opt={}] table margins
+-- @tparam[opt={}] table handle_margins
 -- @tparam[opt=0] number margins.left
 -- @tparam[opt=0] number margins.right
 -- @tparam[opt=0] number margins.top
@@ -86,7 +86,7 @@ local slider = {mt={}}
 --@DOC_wibox_widget_slider_bar_shape_EXAMPLE@
 --
 -- @property bar_shape
--- @tparam[opt=gears shape rectangle] gears.shape shape
+-- @tparam[opt=gears shape rectangle] gears.shape bar_shape
 -- @propemits true false
 -- @propbeautiful
 -- @see gears.shape
@@ -124,7 +124,7 @@ local slider = {mt={}}
 --@DOC_wibox_widget_slider_bar_margins_EXAMPLE@
 --
 -- @property bar_margins
--- @tparam[opt={}] table margins
+-- @tparam[opt={}] table bar_margins
 -- @tparam[opt=0] number margins.left
 -- @tparam[opt=0] number margins.right
 -- @tparam[opt=0] number margins.top
@@ -136,6 +136,7 @@ local slider = {mt={}}
 -- @property bar_border_width
 -- @tparam[opt=0] number bar_border_width
 -- @propemits true false
+-- @propbeautiful
 
 --- The bar (background) border_color.
 --
@@ -148,8 +149,6 @@ local slider = {mt={}}
 
 --- The slider value.
 --
--- **Signal:** *property::value* notify the value is changed.
---
 --@DOC_wibox_widget_slider_value_EXAMPLE@
 --
 -- @property value
@@ -521,8 +520,25 @@ local function mouse_press(self, x, y, button_id, _, geo)
 end
 
 --- Create a slider widget.
--- @tparam[opt={}] table args
+--
 -- @constructorfct wibox.widget.slider
+-- @tparam[opt={}] table args
+-- @tparam[opt] gears.shape args.handle_shape The slider handle shape.
+-- @tparam[opt] color args.handle_color The slider handle color.
+-- @tparam[opt] table args.handle_margins The slider handle margins.
+-- @tparam[opt] number args.handle_width The slider handle width.
+-- @tparam[opt] color args.handle_border_color The handle border_color.
+-- @tparam[opt] number args.handle_border_width The handle border width.
+-- @tparam[opt] gears.shape args.bar_shape The bar (background) shape.
+-- @tparam[opt] number args.bar_height The bar (background) height.
+-- @tparam[opt] color args.bar_color The bar (background) color.
+-- @tparam[opt] color args.bar_active_color The bar (active) color.
+-- @tparam[opt] table args.bar_margins The bar (background) margins.
+-- @tparam[opt] number args.bar_border_width The bar (background) border width.
+-- @tparam[opt] color args.bar_border_color The bar (background) border_color.
+-- @tparam[opt] number args.value The slider value.
+-- @tparam[opt] number args.minimum The slider minimum value.
+-- @tparam[opt] number args.maximum The slider maximum value.
 local function new(args)
     local ret = base.make_widget(nil, nil, {
         enable_properties = true,

lib/wibox/widget/systray.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Container for the various system tray icons.
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @widgetmod wibox.widget.systray
@@ -27,20 +29,23 @@ local display_on_screen = "primary"
 
 --- The systray background color.
 --
+-- Please note that only solid+opaque colors are supported. It does **not**
+-- support gradients, patterns or transparent colors.
+--
 -- @beautiful beautiful.bg_systray
--- @param string The color (string like "#ff0000" only)
+-- @tparam string bg_systray The color (string like "#ff0000" only)
 
 --- The maximum number of rows for systray icons. Icons will fill the
 -- current column (orthogonally to the systray direction) before
 -- filling the next column.
 --
 -- @beautiful beautiful.systray_max_rows
--- @tparam[opt=1] integer The positive number of rows
+-- @tparam[opt=1] integer systray_max_rows The positive number of rows.
 
 --- The systray icon spacing.
 --
 -- @beautiful beautiful.systray_icon_spacing
--- @tparam[opt=0] integer The icon spacing
+-- @tparam[opt=0] integer systray_icon_spacing The icon spacing
 
 local function should_display_on(s)
     if display_on_screen == "primary" then
@@ -143,7 +148,7 @@ end
 -- available space. Otherwise, any single icon has a size of `size`x`size`.
 --
 -- @property base_size
--- @tparam integer|nil size The base size
+-- @tparam integer|nil base_size The base size
 -- @propemits true false
 
 function systray:set_base_size(size)
@@ -157,7 +162,7 @@ end
 --- Decide between horizontal or vertical display.
 --
 -- @property horizontal
--- @tparam boolean horiz Use horizontal mode?
+-- @tparam boolean horizontal Use horizontal mode?
 -- @propemits true false
 
 function systray:set_horizontal(horiz)
@@ -171,7 +176,7 @@ end
 --- Should the systray icons be displayed in reverse order?
 --
 -- @property reverse
--- @tparam boolean rev Display in reverse order.
+-- @tparam boolean reverse Display in reverse order.
 -- @propemits true false
 
 function systray:set_reverse(rev)
@@ -189,7 +194,7 @@ end
 -- visible on the primary screen. The default value is "primary".
 --
 -- @property screen
--- @tparam screen|"primary" s The screen to display on.
+-- @tparam screen|"primary" screen The screen to display on.
 -- @propemits true false
 
 function systray:set_screen(s)
@@ -204,9 +209,12 @@ end
 --
 -- Note that this widget can only exist once.
 --
--- @tparam boolean revers Show in the opposite direction
+-- @tparam boolean reverse Show in the opposite direction
 -- @treturn table The new `systray` widget
 -- @constructorfct wibox.widget.systray
+-- @usebeautiful beautiful.bg_systray
+-- @usebeautiful beautiful.systray_icon_spacing
+-- @usebeautiful beautiful.systray_max_rows
 
 local function new(revers)
     local ret = wbase.make_widget(nil, nil, {enable_properties = true})