Merge pull request #2785 from Elv13/better_doc_render

Fix a thousand documentation issues.

.travis.yml

@@ -303,6 +303,7 @@ script:
         i=$((i+1))
         travis_fold_start "test_commit_${commit}_.$i.$n"
         echo "Testing commit $commit"
+        git reset --hard # Some files are updated when compiling...
         git checkout "$commit"
         git --no-pager show --stat
 

CMakeLists.txt

@@ -286,9 +286,6 @@ if(GENERATE_DOC)
     # Copy the images to the build directory
     file(COPY ${SOURCE_DIR}/docs/images DESTINATION ${BUILD_DIR}/doc)
 
-    # Copy the aliases to the build directory
-    file(COPY ${SOURCE_DIR}/docs/aliases DESTINATION ${BUILD_DIR}/docs)
-
     # Copy ldoc files.
     configure_file(${SOURCE_DIR}/docs/ldoc.css ${BUILD_DIR}/docs COPYONLY)
     configure_file(${SOURCE_DIR}/docs/ldoc.ltp ${BUILD_DIR}/docs COPYONLY)

docs/_parser.lua

@@ -68,17 +68,37 @@ local function path_to_module(path)
     error("Cannot figure out module for " .. tostring(path))
 end
 
+local modtypes = {
+    classmod     = true,
+    widgetmod    = true,
+    containermod = true,
+    layoutmod    = true,
+    coreclassmod = true,
+    popupmod     = true,
+}
+
+local libtypes = {
+    module    = true,
+    submodule = true,
+    utillib   = true,
+    themelib  = true,
+}
+
 function module.path_to_html(path)
     local mod = path_to_module(path):gsub(".init", "")
     local f = assert(io.open(path))
     while true do
         local line = f:read()
         if not line then break end
-        if line:match("@classmod") then
+
+        local tag = line:gmatch("@([^ ]+) ")() or ""
+
+        if modtypes[tag] then
             f:close()
             return "../classes/".. mod ..".html#"
         end
-        if line:match("@module") or line:match("@submodule") then
+
+        if libtypes[tag] then
             f:close()
             return "../libraries/".. mod ..".html#"
         end

docs/aliases/awful_client.lua

@@ -1,5 +0,0 @@
----------------------------------------------------------------------------
---- This module documentation has been merged with the `client` class.
---
--- @module awful.client
----------------------------------------------------------------------------

docs/aliases/awful_mouse.lua

@@ -1,5 +0,0 @@
----------------------------------------------------------------------------
---- This module documentation has been merged with the `mouse` class.
---
--- @module awful.mouse
----------------------------------------------------------------------------

docs/aliases/awful_screen.lua

@@ -1,5 +0,0 @@
----------------------------------------------------------------------------
---- This module documentation has been merged with the `screen` class.
---
--- @module awful.screen
----------------------------------------------------------------------------

docs/aliases/awful_tag.lua

@@ -1,5 +0,0 @@
----------------------------------------------------------------------------
---- This module documentation has been merged with the `tag` class.
---
--- @module awful.tag
----------------------------------------------------------------------------

docs/common/cobject.ldoc

@@ -3,7 +3,7 @@
 /** Disconnect from a signal.
  * @tparam string name The name of the signal.
  * @tparam function func The callback that should be disconnected.
- * @function disconnect_signal
+ * @staticfct disconnect_signal
  */
 
 /** Emit a signal.
@@ -12,13 +12,13 @@
  * @param ... Extra arguments for the callback functions. Each connected
  *   function receives the object as first argument and then any extra
  *   arguments that are given to emit_signal().
- * @function emit_signal
+ * @staticfct emit_signal
  */
 
 /** Connect to a signal.
  * @tparam string name The name of the signal.
  * @tparam function func The callback to call when the signal is emitted.
- * @function connect_signal
+ * @staticfct connect_signal
  */
 
 /*

docs/common/fixed.ldoc

@@ -4,8 +4,7 @@
 -- @tparam number index A widget or a widget index
 -- @param widget2 The widget to take the place of the first one
 -- @treturn boolean If the operation is successful
--- @name set
+-- @method set
--- @class function
 
 --- Replace the first instance of `widget` in the layout with `widget2`.
 -- **Signal:** widget::replaced The argument is the new widget and the old one
@@ -14,16 +13,14 @@
 -- @param widget2 The widget to replace `widget` with
 -- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
 -- @treturn boolean If the operation is successful
--- @name replace_widget
+-- @method replace_widget
--- @class function
 
 --- Swap 2 widgets in a layout.
 -- **Signal:** widget::swapped The arguments are both widgets and both (new) indexes.
 -- @tparam number index1 The first widget index
 -- @tparam number index2 The second widget index
 -- @treturn boolean If the operation is successful
--- @name swap
+-- @method swap
--- @class function
 
 --- Swap 2 widgets in a layout.
 -- If widget1 is present multiple time, only the first instance is swapped
@@ -33,8 +30,7 @@
 -- @param widget2 The second widget
 -- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
 -- @treturn boolean If the operation is successful
--- @name swap_widgets
+-- @method swap_widgets
--- @class function
 
 --- Get all direct children of this layout.
 -- @param layout The layout you are modifying.
@@ -43,5 +39,4 @@
 --- Reset a ratio layout. This removes all widgets from the layout.
 -- **Signal:** widget::reset
 -- @param layout The layout you are modifying.
--- @name reset
+-- @method reset
--- @class function

docs/common/object.ldoc

@@ -2,7 +2,7 @@
 --- Disconnect from a signal.
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback that should be disconnected.
--- @function disconnect_signal
+-- @method disconnect_signal
 
 --- Emit a signal.
 --
@@ -10,12 +10,12 @@
 -- @param ... Extra arguments for the callback functions. Each connected
 --   function receives the object as first argument and then any extra
 --   arguments that are given to emit_signal().
--- @function emit_signal
+-- @method emit_signal
 
 --- Connect to a signal.
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback to call when the signal is emitted.
--- @function connect_signal
+-- @method connect_signal
 
 --- Connect to a signal weakly.
 --
@@ -27,4 +27,4 @@
 -- are doing.
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback to call when the signal is emitted.
--- @function weak_connect_signal
+-- @method weak_connect_signal

docs/common/rules_index.ldoc

@@ -15,8 +15,8 @@
 --   <tr><td><a href='../classes/client.html#client.callback'>callback</a></td><td>A function to call when this client is ready</td></tr>
 --   <tr><td><a href='../classes/client.html#client.marked'>marked</a></td><td>If a client is marked or not</td></tr>
 --   <tr><td><a href='../classes/client.html#client.is_fixed'>is\_fixed</a></td><td>Return if a client has a fixed size or not</td></tr>
---   <tr><td><a href='../classes/client.html#client.immobilized'>immobilized</a></td><td>Is the client immobilized horizontally?</td></tr>
+--   <tr><td><a href='../classes/client.html#client.immobilized_horizontal'>immobilized\_horizontal</a></td><td>Is the client immobilized horizontally?</td></tr>
---   <tr><td><a href='../classes/client.html#client.immobilized'>immobilized</a></td><td>Is the client immobilized vertically?</td></tr>
+--   <tr><td><a href='../classes/client.html#client.immobilized_vertical'>immobilized\_vertical</a></td><td>Is the client immobilized vertically?</td></tr>
 --   <tr><td><a href='../classes/client.html#client.floating'>floating</a></td><td>The client floating state</td></tr>
 --   <tr><td><a href='../classes/client.html#client.x'>x</a></td><td>The x coordinates</td></tr>
 --   <tr><td><a href='../classes/client.html#client.y'>y</a></td><td>The y coordinates</td></tr>

docs/common/wibox.ldoc

@@ -199,40 +199,42 @@
 --- Get or set mouse buttons bindings to a wibox.
 --
 -- @param buttons_table A table of buttons objects, or nothing.
--- @function buttons
+-- @method buttons
 
 --- Get or set wibox geometry. That's the same as accessing or setting the x,
 -- y, width or height properties of a wibox.
 --
 -- @param A table with coordinates to modify.
 -- @return A table with wibox coordinates and geometry.
--- @function geometry
+-- @method geometry
 
 --- Get or set wibox struts.
 --
 -- @param strut A table with new strut, or nothing
 -- @return The wibox strut in a table.
--- @function struts
+-- @method struts
 -- @see client.struts
 
 --- The default background color.
 -- @beautiful beautiful.bg_normal
+-- @param color
 -- @see bg
 
 --- The default foreground (text) color.
 -- @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
--- @name setup
+-- @method setup
--- @class function
 
 --- The background of the wibox.
 -- @param c The background to use. This must either be a cairo pattern object,
 --   nil or a string that gears.color() understands.
 -- @property bg
+-- @param color
 -- @see gears.color
 
 --- The background image of the drawable.
@@ -246,6 +248,7 @@
 -- @param c The foreground to use. This must either be a cairo pattern object,
 --   nil or a string that gears.color() understands.
 -- @property fg
+-- @param color
 -- @see gears.color
 
 --- Find a widget by a point.
@@ -255,5 +258,4 @@
 -- @treturn table A sorted table of widgets positions. The first element is the biggest
 -- container while the last is the topmost widget. The table contains *x*, *y*,
 -- *width*, *height* and *widget*.
--- @name find_widgets
+-- @method find_widgets
--- @class function

docs/common/widget.ldoc

@@ -6,19 +6,23 @@
 -- @return The index
 -- @return The parent layout
 -- @return The path between self and widget
--- @function index
+-- @method index
+
+--- Get or set the children elements.
+-- @property children
+-- @tparam table The children
 
 --- Get all direct and indirect children widgets.
 -- This will scan all containers recursively to find widgets
 -- Warning: This method it prone to stack overflow id the widget, or any of its
 -- children, contain (directly or indirectly) itself.
--- @treturn table The children
+-- @property all_children
--- @function get_all_children
+-- @tparam table The children
 
 --- 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
--- @function setup
+-- @method setup
 
 --- Force a widget height.
 -- @property forced_height
@@ -38,14 +42,14 @@
 
 --- Set/get a widget's buttons.
 -- @param _buttons The table of buttons that should bind to the widget.
--- @function buttons
+-- @method buttons
 
 --- Emit a signal and ensure all parent widgets in the hierarchies also
 -- forward the signal. This is useful to track signals when there is a dynamic
 -- set of containers and layouts wrapping the widget.
 -- @tparam string signal_name
 -- @param ... Other arguments
--- @function emit_signal_recursive
+-- @method emit_signal_recursive
 
 --- When the layout (size) change.
 -- This signal is emitted when the previous results of `:layout()` and `:fit()`

docs/config.ld

@@ -1,3 +1,6 @@
+local args = ...
+
+
 -- Configuration file for ldoc
 
 project='awesome'
@@ -49,30 +52,39 @@ tparam_alias('tab', 'table')
 tparam_alias('screen', 'screen')
 tparam_alias('screen_or_idx', 'screen|int')
 
--- Hack to get the functions and method on top of the signals and properties
+-- The first stereotype are the constructors.
-new_type("function", "Functions")
+new_type("constructorfct", "Constructors", false, "Parameters")
+-- Hack to get the functions on top of the signals and properties
+new_type("function", "Functions", false, "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")
 -- Documentation for objects properties
-new_type("property", "Object properties", false, "Type")
+new_type("property", "Object properties", false, "Type constraints")
 -- Documentation for objects deprecated properties
-new_type("deprecatedproperty", "Deprecated object properties", false, "Type")
+new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints")
+-- 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")
 -- New type for signals
 new_type("signal", "Signals", false, "Arguments")
 -- New type for signals connections
 new_type("signalhandler", "Request handlers", false, "Arguments")
 -- Allow objects to define a set of beautiful properties affecting them
-new_type("beautiful", "Theme variables", false, "Type")
+new_type("beautiful", "Theme variables", false, "Type constraints")
 -- Put deprecated methods in their own section
-new_type("deprecated", "Deprecated functions", false, "param")
+new_type("deprecated", "Deprecated functions", false, "Parameters")
 -- For the legacy stateless layout related functions
-new_type("legacylayout", "Layout related functions", false, "param")
+new_type("legacylayout", "Layout related functions", false, "Parameters")
 -- Have a category for the client layouts
-new_type("clientlayout", "Client layouts", false, "param")
+new_type("clientlayout", "Client layouts", false, "Parameters")
 -- Source functions for the taglist/tasklist/layoutlist
 new_type("sourcefunction", "List source functions", false)
 -- Document some callback prototypes
 new_type("callback", "Callback functions prototype", false, "Parameters")
 -- gears.matcher / awful.rules sources
-new_type("rulesources", "Rule sources", false, "param")
+new_type("rulesources", "Rule sources", false, "Parameters")
 -- gears.matcher / awful.rules rule components
 new_type("rulecomponent", "Rule components", false, "Type")
 -- Filter functions for the taglist/tasklist/layoutlist
@@ -86,6 +98,15 @@ kind_names={topic='Documentation', module='Libraries', script='Sample files'}
 -- Sort modules alphabetically
 sort_modules=true
 
+-- Add more project level (left side index) types.
+new_type("widgetmod"   , "Widgets"   , true)
+new_type("containermod", "Widget containers", true)
+new_type("layoutmod"   , "Widget layouts"   , true)
+new_type("coreclassmod", "Core components"  , true)
+new_type("popupmod"    , "Popups and bars"  , true)
+new_type("utillib"     , "Utility libraries", true)
+new_type("themelib"    , "Theme related libraries", true)
+
 file = {
     -- C parts of libraries
     '../dbus.c',
@@ -109,11 +130,6 @@ file = {
     '../lib/',
     -- Auto generated scripts
     '../script_files/',
-    -- Old APIs the user should not longer use directly
-    '../docs/aliases/awful_client.lua',
-    '../docs/aliases/awful_screen.lua',
-    '../docs/aliases/awful_tag.lua',
-    '../docs/aliases/awful_mouse.lua',
     exclude = {
         -- exclude these modules, as they do not contain any written
         -- documentation
@@ -128,6 +144,7 @@ file = {
         '../lib/wibox/container/init.lua',
         '../lib/naughty/constants.lua',
         '../lib/naughty/dbus.lua',
+        '../lib/beautiful/gtk.lua',
 
         -- Ignore some parts of the widget library
         '../lib/awful/widget/init.lua',
@@ -137,6 +154,8 @@ file = {
         -- in the index
         '../lib/awful/widget/graph.lua',
         '../lib/awful/widget/progressbar.lua',
+        '../lib/awful/widget/textclock.lua',
+        '../lib/awful/wibox.lua',
         '../lib/wibox/layout/constraint.lua',
         '../lib/wibox/layout/margin.lua',
         '../lib/wibox/layout/mirror.lua',
@@ -146,12 +165,110 @@ file = {
     }
 }
 
+-- Wrap the module name for the CSS highlight.
+local function wrap_modname(str, item)
+    if (not item.module) or str:sub(1, #item.module.name+1) ~= item.module.name.."." then return str end
+
+    return "<span class='function_modname'>"..item.module.name..".</span>"
+        .. str:sub(#item.module.name+2, 9999)
+end
+
+-- Wrap the arguments for the CSS highlight.
+local function wrap_args(item)
+    if not item.args then return "" end
+    return "<span class='function_args'>"..item.args.."</span>"
+end
+
+
+-- Mimics the ldoc built-in method style, but better.
+--
+-- This custom renderer exists because using ldoc built-in method detection
+-- turned out to be too unreliable and upstream is dead.
+local function render_methods(item)
+    local ret = item.name
+
+    -- Some methods will have it depending on the weather. Most wont.
+    if not ret:find(":") then
+        ret = ":"..ret
+    end
+
+    return ret .. " " .. wrap_args(item)
+end
+
+-- Parse the magic parameters to type concention in something the template eats.
+local function sanitize_type(item, ldoc)
+
+    for parm in ldoc.modules.iter(item.params) do
+        local t = item:type_of_param(parm)
+
+        -- Remove the value.
+        t = t:gsub("(\\[[^\\]]])","")
+        t = t:gsub("?","")
+
+        -- Add " or " between alternatives
+        t = t:gsub("|"," <i>or</i> ")
+
+        -- Fallback.
+        t = t == "" and parm or t
+        t = t == "" and "N/A" or t
+
+        item.display_type = "<span class='summary_type'>"..t.."</span>"
+
+        -- There is no value in repeating the type a second time.
+        if item.params.map[parm] == "" then
+            item.hide_params = true
+        end
+
+        if t ~= "N/A" then return end
+    end
+
+    -- It has to be set, otherwise the table will have different col count.
+    item.display_type = "<span class='summary_type'>N/A</span>"
+end
 local no_prefix = {
     property = true, signal = true, clientruleproperty = true,
     deprecatedproperty = true,
 }
 
+-- These modules merge the doc of their `awful` siblings.
+local coreclassmap = {
+    tag    = "tag<span class='listplusign'> and awful.tag</span>",
+    screen = "screen<span class='listplusign'> and awful.screen</span>",
+    client = "client<span class='listplusign'> and awful.client</span>",
+    mouse  = "mouse<span class='listplusign'> and awful.mouse</span>",
+}
+
+-- Add the full module name in front.
+local add_mod = {
+    ["function"]   = true,
+    constructorfct = true,
+    staticfct      = true,
+    deprecated     = true,
+    field          = true,
+}
+
+-- Add the arguments.
+local add_args = {
+    constructorfct = true,
+    staticfct      = true,
+}
+
+-- Add a type column to the summary and type field in the description.
+local display_type = {
+    property           = true,
+    beautiful          = true,
+    field              = true,
+    deprecatedproperty = true,
+}
+
 custom_display_name_handler = function(item, default_handler)
+    local ret = default_handler(item)
+
+    -- Edit the input so the template is notified.
+    if display_type[item.type] then
+        -- Punch a hole in the sandbox and inject the `ldoc` object.
+        item.sanitize_type = sanitize_type
+    end
 
     -- Remove the "namespace" from the signals and properties
     if no_prefix[item.type] then
@@ -159,11 +276,51 @@ custom_display_name_handler = function(item, default_handler)
         return name ~= "" and name or item.name
     end
 
-    if item.type == "deprecated" or item.type == "deprecatedproperty" then
+    -- Handle the left sidebar modules.
-        return default_handler(item) .. "</a> <i class=\"deprecated_label\">[deprecated]</i><a>"
+    if item.type == "coreclassmod" and coreclassmap[item.name] then
+        return coreclassmap[item.name]
     end
 
-    return default_handler(item)
+    -- Undocumented API to make the libraries and classmod "function" section
+    -- more consistent. Right now some have their full awful.foo.bar while other
+    -- have "just" `bar`. Given we use constructors from metatables, we have no
+    -- choice but to use the full function name. It also makes copy/paste easier.
+    if add_mod[item.type] then
+        if (not ret:find(".", 1, true)) and (not ret:find(":", 1, true))  then
+            ret = item.module.name .. "." .. ret
+        elseif item.type == "field" and ret:sub(1, #item.module.name) ~= item.module.name then
+            ret = item.module.name .. "." .. ret
+        end
+    end
+
+    if item.type == "deprecated" or item.type == "deprecatedproperty" then
+        return ret .. "<i class=\"deprecated_label\"> [deprecated]</i>"
+    end
+
+    if item.type == "method" then
+        ret = render_methods(item)
+    end
+
+
+    -- Get rid of the "module:" in front of method names. It is either wrong or
+    -- just redundant.
+    ret = ret:gsub("([^:]*)(:[^:])","%2")
+
+    -- Undocumented API to get rid of `module.rounded_rect` rather than
+    -- `gears.shape.rounded_rect`
+    if ret:sub(1, 7) == "module." and module then
+        return ret:gsub("^module", item.module.name)
+    end
+
+    -- It isn't there by default.
+    if add_args[item.type] then
+        ret = ret .. " " .. wrap_args(item)
+    end
+
+    -- Beautify.
+    ret = wrap_modname(ret, item)
+
+    return ret
 end
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

docs/ldoc.css

@@ -290,6 +290,31 @@ table.module_list td.summary, table.function_list td.summary {
     border-left-width: 0px;
 }
 
+table.function_list td.shortname {
+    background-color: white;
+    border-right-width: 0px;
+}
+
+.proptype {
+    padding-right: 20px;
+    float: right;
+}
+
+td.summarytype {
+    background-color: white;
+    color: #a4c7ff;
+    font-size: 85%;
+    border-left: none;
+    border-right: none;
+    text-align: right;
+}
+
+table.function_list .function_args /*.function_modname*/ {
+    color: #94b1ff;
+    text-decoration: underline;
+    text-decoration-color: #bbd3ff;
+}
+
 dl.function {
     margin-right: 15px;
     margin-left: 15px;
@@ -355,6 +380,12 @@ a:target + * {
   background-color: #FF9;
 }
 
+/* tag + awful.tag */
+.listplusign {
+    color: #b7c1ff;
+    text-decoration: underline;
+    text-decoration-color: white;
+}
 
 /* styles for prettification of source */
 pre .comment { color: #bbccaa; }

docs/ldoc.ltp

@@ -87,7 +87,7 @@
 # if ldoc.body then -- verbatim HTML as contents; 'non-code' entries
     $(ldoc.body)
 # elseif module then -- module documentation
-<h1>$(ldoc.module_typename(module)) <code>$(module.name)</code></h1>
+<h1>Module: <code>$(module.name)</code></h1>
 <p>$(M(module.summary,module))</p>
 <p>$(M(module.description,module))</p>
 #   if module.tags.include then
@@ -127,8 +127,15 @@
 <h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
 <table class="function_list">
 #  for item in items() do
+#   local dn = display_name(item)
+#   if item.sanitize_type then item.sanitize_type(item, ldoc) end
 	<tr>
-	<td class="name" $(nowrap)><a href="#$(item.name)">$(display_name(item))</a></td>
+#   if item.display_type then
+	<td class="shortname" $(nowrap)><a href="#$(item.name)">$(dn)</a></td>
+	<td class="summarytype" nowrap>$(item.display_type)</td>
+#   else
+	<td class="name" $(nowrap)><a href="#$(item.name)">$(dn)</a></td>
+#   end
 	<td class="summary">$(M(item.summary,item))</td>
 	</tr>
 #  end -- for items
@@ -165,6 +172,9 @@
     <dt>
     <a name = "$(item.name)"></a>
     <strong>$(display_name(item))</strong>
+#   if item.display_type then
+    <span class="proptype">($(item.display_type))</span>
+#   end
 #   if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
     <a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
 #  end
@@ -187,7 +197,7 @@
 #    end -- iter tags
 #   end
 
-#  if show_parms and item.params and #item.params > 0 then
+#  if show_parms and item.params and #item.params > 0 and not item.hide_params then
 #    local subnames = module.kinds:type_of(item).subnames
 #    if subnames then
     <h3>$(subnames):</h3>

lib/awful/client.lua

@@ -164,7 +164,7 @@ end
 --- Jump to the given client.
 -- Takes care of focussing the screen, the right tag, etc.
 --
--- @function client.jump_to
+-- @method 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
@@ -239,7 +239,7 @@ end
 --- Get a client by its relative index to another client.
 -- If no client is passed, the focused client will be used.
 --
--- @function awful.client.next
+-- @staticfct awful.client.next
 -- @tparam int i The index.  Use 1 to get the next, -1 to get the previous.
 -- @client[opt] sel The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@@ -274,7 +274,7 @@ function client.next(i, sel, stacked)
 end
 
 --- Swap a client with another client in the given direction.
--- @function awful.client.swap.bydirection
+-- @staticfct awful.client.swap.bydirection
 -- @tparam string dir The direction, can be either "up", "down", "left" or "right".
 -- @client[opt=focused] c The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@@ -295,8 +295,9 @@ function client.swap.bydirection(dir, c, stacked)
     end
 end
 
---- Swap a client with another client in the given direction. Swaps across screens.
+--- Swap a client with another client in the given direction.
--- @function awful.client.swap.global_bydirection
+-- Swaps across screens.
+-- @staticfct awful.client.swap.global_bydirection
 -- @param dir The direction, can be either "up", "down", "left" or "right".
 -- @client[opt] sel The client.
 function client.swap.global_bydirection(dir, sel)
@@ -329,7 +330,7 @@ function client.swap.global_bydirection(dir, sel)
 end
 
 --- Swap a client by its relative index.
--- @function awful.client.swap.byidx
+-- @staticfct awful.client.swap.byidx
 -- @param i The index.
 -- @client[opt] c The client, otherwise focused one is used.
 function client.swap.byidx(i, c)
@@ -342,7 +343,7 @@ end
 
 --- Cycle clients.
 --
--- @function awful.client.cycle
+-- @staticfct awful.client.cycle
 -- @param clockwise True to cycle clients clockwise.
 -- @param[opt] s The screen where to cycle clients.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@@ -409,7 +410,7 @@ function client.moveresize(x, y, w, h, c)
 end
 
 --- Move/resize a client relative to current coordinates.
--- @function client.relative_move
+-- @method relative_move
 -- @see geometry
 -- @tparam[opt=c.x] number x The relative x coordinate.
 -- @tparam[opt=c.y] number y The relative y coordinate.
@@ -435,7 +436,7 @@ function client.movetotag(target, c)
 end
 
 --- Move a client to a tag.
--- @function client.move_to_tag
+-- @method move_to_tag
 -- @tparam tag target The tag to move the client to.
 function client.object.move_to_tag(self, target)
     local s = target.screen
@@ -460,7 +461,7 @@ function client.toggletag(target, c)
 end
 
 --- Toggle a tag on a client.
--- @function client.toggle_tag
+-- @method toggle_tag
 -- @tparam tag target The tag to move the client to.
 function client.object.toggle_tag(self, target)
     -- Check that tag and client screen are identical
@@ -496,7 +497,7 @@ function client.movetoscreen(c, s)
 end
 
 --- Move a client to a screen. Default is next screen, cycling.
--- @function client.move_to_screen
+-- @method move_to_screen
 -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1.
 -- @see screen
 -- @see request::activate
@@ -524,7 +525,7 @@ function client.object.move_to_screen(self, s)
 end
 
 --- Tag a client with the set of current tags.
--- @function client.to_selected_tags
+-- @method to_selected_tags
 -- @see screen.selected_tags
 function client.object.to_selected_tags(self)
     local tags = {}
@@ -625,7 +626,7 @@ function client.togglemarked(c)
 end
 
 --- Return the marked clients and empty the marked table.
--- @function awful.client.getmarked
+-- @deprecated awful.client.getmarked
 -- @return A table with all marked clients.
 function client.getmarked()
     local copy = gtable.clone(client.data.marked, false)
@@ -886,7 +887,7 @@ end
 
 
 --- Restore (=unminimize) a random client.
--- @function awful.client.restore
+-- @staticfct awful.client.restore
 -- @param s The screen to use.
 -- @return The restored client if some client was restored, otherwise nil.
 function client.restore(s)
@@ -907,7 +908,7 @@ function client.restore(s)
     return nil
 end
 
---- Normalize a set of numbers to 1
+--- Normalize a set of numbers to 1.
 -- @param set the set of numbers to normalize
 -- @param num the number of numbers to normalize
 local function normalize(set, num)
@@ -1204,7 +1205,7 @@ end
 
 --- Set a client property to be persistent across restarts (via X properties).
 --
--- @function awful.client.property.persist
+-- @staticfct awful.client.property.persist
 -- @param prop The property name.
 -- @param kind The type (used for register_xproperty).
 --   One of "string", "number" or "boolean".
@@ -1221,16 +1222,17 @@ function client.property.persist(prop, kind)
     end
 end
 
----
+--- Returns an iterator to cycle through clients.
--- Returns an iterator to cycle through, starting from the client in focus or
+--
--- the given index, all clients that match a given criteria.
+-- Starting from the client in focus or the given index, all clients that match
+-- a given criteria.
 --
 -- @param filter a function that returns true to indicate a positive match
 -- @param start  what index to start iterating from.  Defaults to using the
 --   index of the currently focused client.
 -- @param s which screen to use.  nil means all screens.
 --
--- @function awful.client.iterate
+-- @staticfct awful.client.iterate
 -- @usage -- un-minimize all urxvt instances
 -- local urxvt = function (c)
 --   return awful.rules.match(c, {class = "URxvt"})
@@ -1300,7 +1302,7 @@ function client.get_transient_for_matching(c, matcher)
 end
 
 --- Get a matching transient_for client (if any).
--- @function client.get_transient_for_matching
+-- @method get_transient_for_matching
 -- @tparam function matcher A function that should return true, if
 --   a matching parent client is found.
 -- @treturn client.client|nil The matching parent client or nil.
@@ -1328,7 +1330,7 @@ function client.is_transient_for(c, c2)
 end
 
 --- Is a client transient for another one?
--- @function client.is_transient_for
+-- @method is_transient_for
 -- @client c2 The parent client to check.
 -- @treturn client.client|nil The parent client or nil.
 function client.object.is_transient_for(self, c2)
@@ -1387,7 +1389,7 @@ do
     -- See `awful.client.focus.history.enable_tracking` to enable it again.
     -- @treturn int The internal value of `disabled_count` (calls to this
     --   function without calling `awful.client.focus.history.enable_tracking`).
-    -- @function awful.client.focus.history.disable_tracking
+    -- @staticfct awful.client.focus.history.disable_tracking
     function client.focus.history.disable_tracking()
         disabled_count = disabled_count + 1
         if disabled_count == 1 then
@@ -1401,7 +1403,7 @@ do
     -- This is the default, but can be disabled
     -- through `awful.client.focus.history.disable_tracking`.
     -- @treturn boolean True if history tracking has been enabled.
-    -- @function awful.client.focus.history.enable_tracking
+    -- @staticfct awful.client.focus.history.enable_tracking
     function client.focus.history.enable_tracking()
         assert(disabled_count > 0)
         disabled_count = disabled_count - 1
@@ -1414,7 +1416,7 @@ do
     --- Is history tracking enabled?
     -- @treturn bool True if history tracking is enabled.
     -- @treturn int The number of times that tracking has been disabled.
-    -- @function awful.client.focus.history.is_enabled
+    -- @staticfct awful.client.focus.history.is_enabled
     function client.focus.history.is_enabled()
         return disabled_count == 0, disabled_count
     end
@@ -1432,6 +1434,8 @@ object.properties(capi.client, {
     setter_fallback = client.property.set,
 })
 
+--@DOC_object_COMMON@
+
 return client
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/completion.lua

@@ -32,6 +32,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.
+-- @staticfct awful.completion.bashcomp_load
 function completion.bashcomp_load(src)
     if src then bashcomp_src = src end
     local c, err = io.popen("/usr/bin/env bash -c 'source " .. bashcomp_src .. "; complete -p'")
@@ -70,6 +71,7 @@ completion.default_shell = nil
 -- @treturn string The new command.
 -- @treturn number The new cursor position.
 -- @treturn table The table with all matches.
+-- @staticfct awful.completion.shell
 function completion.shell(command, cur_pos, ncomp, shell)
     local wstart = 1
     local wend = 1
@@ -192,6 +194,7 @@ end
 -- @param ncomp The number of yet requested completion using current text.
 -- @param keywords The keywords table uised for completion.
 -- @return The new match, the new cursor position, 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
     if #keywords == 0 then

lib/awful/ewmh.lua

@@ -54,6 +54,7 @@ local ewmh = {
 --- Update a client's settings when its geometry changes, skipping signals
 -- resulting from calls within.
 local repair_geometry_lock = false
+
 local function repair_geometry(window)
     if repair_geometry_lock then return end
     repair_geometry_lock = true
@@ -166,6 +167,7 @@ end
 -- @see generic_activate_filters
 -- @see contextual_activate_filters
 -- @see remove_activate_filter
+-- @staticfct awful.ewmh.add_activate_filter
 function ewmh.add_activate_filter(f, context)
     if not context then
         table.insert(ewmh.generic_activate_filters, f)
@@ -185,6 +187,7 @@ end
 -- @see generic_activate_filters
 -- @see contextual_activate_filters
 -- @see add_activate_filter
+-- @staticfct awful.ewmh.remove_activate_filter
 function ewmh.remove_activate_filter(f, context)
     local tab = context and (ewmh.contextual_activate_filters[context] or {})
         or ewmh.generic_activate_filters

lib/awful/hotkeys_popup/init.lua

@@ -24,7 +24,7 @@ local hotkeys_popup = {
 -- @tparam[opt] screen s The screen.
 -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys.
 -- When set to `false` only app-specific hotkeys will be shown.
--- @function awful.hotkeys_popup.show_help
+-- @staticfct awful.hotkeys_popup.show_help
 -- @see awful.hotkeys_popup.widget.show_help
 
 hotkeys_popup.show_help = hotkeys_popup.widget.show_help

lib/awful/hotkeys_popup/widget.lua

@@ -3,7 +3,7 @@
 --
 -- @author Yauheni Kirylau <yawghen@gmail.com>
 -- @copyright 2014-2015 Yauheni Kirylau
--- @module awful.hotkeys_popup.widget
+-- @popupmod awful.hotkeys_popup.widget
 ---------------------------------------------------------------------------
 
 local capi = {
@@ -49,13 +49,16 @@ local widget = {
 }
 
 --- Don't show hotkeys without descriptions.
+-- @tfield boolean widget.hide_without_description
+-- @param boolean
 widget.hide_without_description = true
 
 --- Merge hotkey records into one if they have the same modifiers and
 -- description.
+-- @tfield boolean widget.merge_duplicates
+-- @param boolean
 widget.merge_duplicates = true
 
-
 --- Hotkeys widget background color.
 -- @beautiful beautiful.hotkeys_bg
 -- @tparam color hotkeys_bg
@@ -125,6 +128,7 @@ widget.merge_duplicates = true
 -- @tparam[opt] table args.labels Labels used for displaying human-readable keynames.
 -- @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
 function widget.new(args)
     args = args or {}
     local widget_instance = {
@@ -489,6 +493,7 @@ function widget.new(args)
     -- @tparam[opt] table show_args Additional arguments.
     -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys.
     -- When set to `false` only app-specific hotkeys will be shown.
+    -- @method show_help
     function widget_instance:show_help(c, s, show_args)
         show_args = show_args or {}
         local show_awesome_keys = show_args.show_awesome_keys ~= false
@@ -548,6 +553,7 @@ function widget.new(args)
     --- Add hotkey descriptions for third-party applications.
     -- @tparam table hotkeys Table with bindings,
     -- see `awful.hotkeys_popup.key.vim` as an example.
+    -- @method add_hotkeys
     function widget_instance:add_hotkeys(hotkeys)
         for group, bindings in pairs(hotkeys) do
             for _, binding in ipairs(bindings) do
@@ -570,6 +576,7 @@ function widget.new(args)
     -- @tparam string group hotkeys group name,
     -- @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)
         self.group_rules[group] = data
     end
@@ -590,6 +597,7 @@ end
 -- @tparam[opt] table args Additional arguments.
 -- @tparam[opt=true] boolean args.show_awesome_keys Show AwesomeWM hotkeys.
 -- When set to `false` only app-specific hotkeys will be shown.
+-- @staticfct awful.hotkeys_popup.widget.show_help
 function widget.show_help(...)
     return get_default_widget():show_help(...)
 end
@@ -598,6 +606,7 @@ end
 -- (default widget instance will be used).
 -- @tparam table hotkeys Table with bindings,
 -- see `awful.hotkeys_popup.key.vim` as an example.
+-- @staticfct awful.hotkeys_popup.widget.add_hotkeys
 function widget.add_hotkeys(...)
     return get_default_widget():add_hotkeys(...)
 end
@@ -607,6 +616,7 @@ end
 -- @tparam string group rule group name,
 -- @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)
     return get_default_widget():add_group_rules(group, data)
 end

lib/awful/key.lua

@@ -3,7 +3,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
--- @module awful.key
+-- @classmod awful.key
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -59,6 +59,7 @@ capi.awesome.connect_signal("xkb::map_changed"  , function() conversion = nil en
 -- @tparam table mod A modified table. Valid modifiers are: Any, Mod1,
 --   Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
 -- @tparam string k The key
+-- @staticfct awful.key.execute
 function key.execute(mod, k)
     local modmap = generate_conversion_map()
     local active = capi.awesome._active_modifiers
@@ -111,6 +112,7 @@ end
 -- @tparam table data User data for key,
 -- for example {description="select next tag", group="tag"}.
 -- @treturn table A table with one or several key objects.
+-- @constructorfct awful.key
 function key.new(mod, _key, press, release, data)
     if type(release)=='table' then
         data=release
@@ -145,6 +147,7 @@ end
 -- @param _key The key object.
 -- @param pressed_mod The modifiers to compare with.
 -- @param pressed_key The key to compare with.
+-- @staticfct awful.key.match
 function key.match(_key, pressed_mod, pressed_key)
     -- First, compare key.
     if pressed_key ~= _key.key then return false end

lib/awful/keygrabber.lua

@@ -60,7 +60,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2012 dodo
 -- @copyright 2017 Emmanuel Lepage Vallee
--- @classmod awful.keygrabber
+-- @coreclassmod awful.keygrabber
 ---------------------------------------------------------------------------
 
 local ipairs = ipairs
@@ -314,6 +314,7 @@ end
 -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@
 --
 -- @property timeout
+-- @param number
 -- @see gears.timer
 -- @see timeout_callback
 
@@ -393,6 +394,7 @@ end
 -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@
 --
 -- @property root_keybindings
+-- @param table
 -- @see export_keybindings
 -- @see keybindings
 
@@ -463,6 +465,7 @@ end
 -- Note that only a single keygrabber can be started at any one time. If another
 -- keygrabber (or this one) is currently running. This method returns false.
 --
+-- @method start
 -- @treturn boolean If the keygrabber was successfully started.
 function keygrabber:start()
     if self.grabber or keygrab.current_instance then
@@ -514,7 +517,7 @@ function keygrabber:start()
 end
 
 --- Stop the keygrabber.
--- @function keygrabber:stop
+-- @method stop
 function keygrabber:stop(_stop_key, _stop_mods) -- (at)function disables ldoc params
     keygrab.stop(self.grabber)
 
@@ -534,6 +537,7 @@ end
 --
 -- Those keybindings will automatically start the keygrabbing when hit.
 --
+-- @method add_keybinding
 -- @tparam table mods A table with modifier keys, such as `shift`, `mod4`, `mod1` (alt) or
 --  `control`.
 -- @tparam string key The key name, such as `left` or `f`
@@ -661,7 +665,7 @@ end
 -- @tparam[opt=false] boolean args.autostart Start the grabbing immediately
 -- @tparam[opt=false] boolean args.mask_modkeys Do not call the callbacks on
 --  modifier keys (like `Control` or `Mod4`) events.
--- @function awful.keygrabber
+-- @constructorfct awful.keygrabber
 function keygrab.run_with_keybindings(args)
     args = args or {}
 
@@ -722,17 +726,6 @@ function keygrab.run_with_keybindings(args)
     return ret
 end
 
---- Run a grabbing function.
---
--- Calling this is equivalent to `keygrabber.run`.
---
--- @param g The key grabber callback that will get the key events until it
---   will be deleted or a new grabber is added.
--- @return the given callback `g`.
---
--- @deprecated awful.keygrabber.run
--- @see keygrabber.run
-
 --- A lower level API to interact with the keygrabber directly.
 --
 -- Grab keyboard input and read pressed keys, calling the least callback
@@ -749,7 +742,7 @@ end
 --
 -- Here is the content of the modifier table:
 --
--- <table>
+-- <table class='widget_list' border=1>
 --  <tr style='font-weight: bold;'>
 --   <th align='center'>Modifier name </th>
 --   <th align='center'>Key name</th>
@@ -784,7 +777,7 @@ end
 --     end
 --   end)
 -- end
--- @function awful.keygrabber.run
+-- @deprecated awful.keygrabber.run
 function keygrab.run(g)
     -- Remove the grabber if it is in the stack.
     keygrab.stop(g)
@@ -806,7 +799,7 @@ end
 local signals = {}
 
 --- Connect to a signal for all keygrabbers at once.
--- @function awful.keygrabber.connect_signal
+-- @staticfct awful.keygrabber.connect_signal
 -- @tparam string name The signal name.
 -- @tparam function callback The callback.
 function keygrab.connect_signal(name, callback)
@@ -819,7 +812,7 @@ function keygrab.connect_signal(name, callback)
 end
 
 --- Disconnect to a signal for all keygrabbers at once.
--- @function awful.keygrabber.disconnect_signal
+-- @staticfct awful.keygrabber.disconnect_signal
 -- @tparam string name The signal name.
 -- @tparam function callback The callback.
 function keygrab.disconnect_signal(name, callback)
@@ -839,7 +832,7 @@ end
 -- `my_keygrabber:emit_signal(name, ...)`. This function works on the whole
 -- keygrabber module, not one of its instance.
 --
--- @function awful.keygrabber.emit_signal
+-- @staticfct awful.keygrabber.emit_signal
 -- @tparam string name The signal name.
 -- @param ... Other arguments for the callbacks.
 function keygrab.emit_signal(name, ...)

lib/awful/layout/init.lua

@@ -73,7 +73,7 @@ layout.layouts = {
 --    awful.layout.suit.corner.sw,
 --    awful.layout.suit.corner.se,
 --
--- @field layout.layouts
+-- @field awful.layout.layouts
 
 --- Return the tag layout index (from `awful.layout.layouts`).
 --
@@ -82,6 +82,7 @@ layout.layouts = {
 --
 -- @tparam tag t The tag.
 -- @treturn nil|number The layout index.
+-- @staticfct awful.layout.get_tag_layout_index
 function layout.get_tag_layout_index(t)
     return gtable.hasitem(layout.layouts, t.layout)
 end
@@ -95,6 +96,7 @@ local delayed_arrange = {}
 --- Get the current layout.
 -- @param screen The screen.
 -- @return The layout function.
+-- @staticfct awful.layout.get
 function layout.get(screen)
     screen = screen or capi.mouse.screen
     local t = get_screen(screen).selected_tag
@@ -105,6 +107,7 @@ end
 -- @param i Relative index.
 -- @param s The screen.
 -- @param[opt] layouts A table of layouts.
+-- @staticfct awful.layout.inc
 function layout.inc(i, s, layouts)
     if type(i) == "table" then
         -- Older versions of this function had arguments (layouts, i, s), but
@@ -150,6 +153,7 @@ end
 --- Set the layout function of the current tag.
 -- @param _layout Layout name.
 -- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify.
+-- @staticfct awful.layout.set
 function layout.set(_layout, t)
     t = t or capi.mouse.screen.selected_tag
     t.layout = _layout
@@ -168,6 +172,7 @@ end
 -- @treturn table A table with the workarea (x, y, width, height), the screen
 --   geometry (x, y, width, height), the clients, the screen and sometime, a
 --   "geometries" table with client as keys and geometry as value
+-- @staticfct awful.layout.parameters
 function layout.parameters(t, screen)
     screen = get_screen(screen)
     t = t or screen.selected_tag
@@ -210,6 +215,7 @@ end
 
 --- Arrange a screen using its current layout.
 -- @param screen The screen to arrange.
+-- @staticfct awful.layout.arrange
 function layout.arrange(screen)
     screen = get_screen(screen)
     if not screen or delayed_arrange[screen] then return end
@@ -250,6 +256,7 @@ end
 --- Get the current layout name.
 -- @param _layout The layout.
 -- @return The layout name.
+-- @staticfct awful.layout.getname
 function layout.getname(_layout)
     _layout = _layout or layout.get()
     return _layout.name
@@ -318,6 +325,7 @@ capi.client.connect_signal("list", function()
 -- @tparam client c The client
 -- @tparam string context The context
 -- @tparam table hints Additional hints
+-- @signalhandler awful.layout.move_handler
 function layout.move_handler(c, context, hints) --luacheck: no unused args
     -- Quit if it isn't a mouse.move on a tiled layout, that's handled elsewhere
     if c.floating then return end

lib/awful/layout/suit/fair.lua

@@ -88,21 +88,30 @@ local function do_fair(p, orientation)
     end
 end
 
---- Horizontal fair layout.
+-- Horizontal fair layout.
 -- @param screen The screen to arrange.
 fair.horizontal = {}
 fair.horizontal.name = "fairh"
+
 function fair.horizontal.arrange(p)
     return do_fair(p, "east")
 end
 
---- Vertical fair layout.
+-- Vertical fair layout.
 -- @param screen The screen to arrange.
 fair.name = "fairv"
 function fair.arrange(p)
     return do_fair(p, "south")
 end
 
+--- The fair layout.
+-- Try to give all clients the same size.
+-- @clientlayout awful.layout.suit.fair
+
+--- The horizontal fair layout.
+-- Try to give all clients the same size.
+-- @clientlayout awful.layout.suit.fair.horizontal
+
 return fair
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/layout/suit/floating.lua

@@ -22,6 +22,7 @@ local capi =
 local floating = {}
 
 --- Jump mouse cursor to the client's corner when resizing it.
+-- @field awful.layout.suit.floating.resize_jump_to_corner
 floating.resize_jump_to_corner = true
 
 function floating.mouse_resize_handler(c, corner, x, y)
@@ -103,7 +104,7 @@ function floating.arrange()
 end
 
 --- The floating layout.
--- @clientlayout awful.layout.suit.
+-- @clientlayout awful.layout.suit.floating
 
 floating.name = "floating"
 

lib/awful/layout/suit/tile.lua

@@ -43,6 +43,7 @@ local tile = {}
 -- @see gears.surface
 
 --- Jump mouse cursor to the client's corner when resizing it.
+-- @field awful.layout.suit.tile.resize_jump_to_corner
 tile.resize_jump_to_corner = true
 
 local function mouse_resize_handler(c, _, _, _, orientation)

lib/awful/menu.lua

@@ -5,7 +5,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @author dodo
 -- @copyright 2008, 2011 Damien Leone, Julien Danjou, dodo
--- @module awful.menu
+-- @popupmod awful.menu
 --------------------------------------------------------------------------------
 
 local wibox = require("wibox")
@@ -50,6 +50,7 @@ end
 
 --- The icon used for sub-menus.
 -- @beautiful beautiful.menu_submenu_icon
+-- @tparam string|gears.surface menu_submenu_icon
 
 --- The menu text font.
 -- @beautiful beautiful.menu_font
@@ -358,6 +359,7 @@ end
 --- Show a menu.
 -- @param args The arguments
 -- @param args.coords Menu position defaulting to mouse.coords()
+-- @method show
 function menu:show(args)
     args = args or {}
     local coords = args.coords or nil
@@ -371,6 +373,7 @@ function menu:show(args)
 end
 
 --- Hide a menu popup.
+-- @method hide
 function menu:hide()
     -- Remove items from screen
     for i = 1, #self.items do
@@ -389,6 +392,7 @@ end
 --- Toggle menu visibility.
 -- @param args The arguments
 -- @param args.coords Menu position {x,y}
+-- @method toggle
 function menu:toggle(args)
     if self.wibox.visible then
         self:hide()
@@ -397,7 +401,8 @@ function menu:toggle(args)
     end
 end
 
---- Update menu content
+--- Update menu content.
+-- @method update
 function menu:update()
     if self.wibox.visible then
         self:show({ coords = { x = self.x, y = self.y } })
@@ -407,6 +412,7 @@ end
 
 --- Get the elder parent so for example when you kill
 -- it, it will destroy the whole family.
+-- @method get_root
 function menu:get_root()
     return self.parent and menu.get_root(self.parent) or self
 end
@@ -417,6 +423,7 @@ end
 -- @param args.new (Default: awful.menu.entry) The menu entry constructor.
 -- @param[opt] args.theme The menu entry theme.
 -- @param[opt] index The index where the new entry will inserted.
+-- @method add
 function menu:add(args, index)
     if not args then return end
     local theme = load_theme(args.theme or {}, self.theme)
@@ -470,8 +477,9 @@ function menu:add(args, index)
     return item
 end
 
---- Delete menu entry at given position
+--- 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
+-- @param num The position 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
         num = gtable.hasitem(self.items, num)
@@ -511,6 +519,7 @@ end
 --   returning `true` or `false` to indicate whether the client should be
 --   included in the menu.
 -- @return The menu.
+-- @constructorfct awful.menu.clients
 function menu.clients(args, item_args, filter)
     local cls_t = {}
     for c in client_iterate(filter or function() return true end) do
@@ -553,6 +562,7 @@ local clients_menu = nil
 --   returning `true` or `false` to indicate whether the client should be
 --   included in the menu.
 -- @return The menu.
+-- @constructorfct awful.menu.client_list
 function menu.client_list(args, item_args, filter)
     if clients_menu and clients_menu.wibox.visible then
         clients_menu:hide()
@@ -565,10 +575,11 @@ end
 
 --------------------------------------------------------------------------------
 
---- Default awful.menu.entry constructor
+--- Default awful.menu.entry constructor.
 -- @param parent The parent menu (TODO: This is apparently unused)
 -- @param args the item params
 -- @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 {}
     args.text = args[1] or args.text or ""
@@ -668,6 +679,7 @@ end
 -- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false.
 --
 -- @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
 -- -- a particular rule.
 -- -- Bound to a key, it can be used to select from dozens of terminals open on

lib/awful/mouse/init.lua

@@ -72,7 +72,7 @@ function mouse.client_under_pointer()
 end
 
 --- Move a client.
--- @function awful.mouse.client.move
+-- @staticfct awful.mouse.client.move
 -- @param c The client to move, or the focused one if nil.
 -- @param snap The pixel to snap clients.
 -- @param finished_cb Deprecated, do not use
@@ -125,7 +125,7 @@ function mouse.client.dragtotag.border(c)
 end
 
 --- Move the wibox under the cursor.
--- @function awful.mouse.wibox.move
+-- @staticfct awful.mouse.wibox.move
 --@tparam wibox w The wibox to move, or none to use that under the pointer
 function mouse.wibox.move(w)
     w = w or mouse.current_wibox
@@ -183,7 +183,7 @@ function mouse.client.corner(c, corner)
 end
 
 --- Resize a client.
--- @function awful.mouse.client.resize
+-- @staticfct awful.mouse.client.resize
 -- @param c The client to resize, or the focused one by default.
 -- @tparam string corner The corner to grab on resize. Auto detected by default.
 -- @tparam[opt={}] table args A set of `awful.placement` arguments
@@ -417,7 +417,7 @@ end)
 -- @treturn integer table.y The vertical position
 -- @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true
 --  when button 1 is pressed.
--- @function mouse.coords
+-- @staticfct mouse.coords
 
 
 return mouse

lib/awful/placement.lua

@@ -811,7 +811,8 @@ end
 --   or `wibox`)
 -- @tparam[opt={}] table args The arguments
 -- @treturn table The new geometry
--- @treturn string The corner name
+-- @treturn string The corner name.
+-- @staticfct awful.placement.closest_corner
 function placement.closest_corner(d, args)
     args = add_context(args, "closest_corner")
     d = d or capi.client.focus
@@ -855,6 +856,7 @@ end
 -- @tparam[opt={}] table args The arguments
 -- @tparam[opt=client's screen] integer args.screen The screen.
 -- @treturn table The new client geometry.
+-- @staticfct awful.placement.no_offscreen
 function placement.no_offscreen(c, args)
 
     --compatibility with the old API
@@ -897,6 +899,7 @@ end
 -- @param c The client.
 -- @tparam[opt={}] table args Other arguments
 -- @treturn table The new geometry
+-- @staticfct awful.placement.no_overlap
 function placement.no_overlap(c, args)
     c = c or capi.client.focus
     args = add_context(args, "no_overlap")
@@ -969,6 +972,7 @@ end
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
 -- @tparam[opt={}] table args Other arguments
 -- @treturn table The new geometry
+-- @staticfct awful.placement.under_mouse
 function placement.under_mouse(d, args)
     args = add_context(args, "under_mouse")
     d = d or capi.client.focus
@@ -993,6 +997,7 @@ end
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
 -- @tparam[opt={}] table args Other arguments
 -- @treturn table The new geometry
+-- @staticfct awful.placement.next_to_mouse
 function placement.next_to_mouse(d, args)
     if type(args) == "number" then
         gdebug.deprecate(
@@ -1042,6 +1047,7 @@ end
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
 -- @tparam[opt={}] table args Other arguments
 -- @treturn table The new geometry
+-- @staticfct awful.placement.resize_to_mouse
 function placement.resize_to_mouse(d, args)
     d    = d or capi.client.focus
     args = add_context(args, "resize_to_mouse")
@@ -1119,6 +1125,7 @@ end
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
 -- @tparam[opt={}] table args Other arguments
 -- @treturn table The new geometry
+-- @staticfct awful.placement.align
 function placement.align(d, args)
     args = add_context(args, "align")
     d    = d or capi.client.focus
@@ -1193,6 +1200,7 @@ end
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
 -- @tparam[opt={}] table args The arguments
 -- @treturn table The new geometry
+-- @staticfct awful.placement.stretch
 function placement.stretch(d, args)
     args = add_context(args, "stretch")
 
@@ -1265,6 +1273,7 @@ end
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
 -- @tparam[opt={}] table args The arguments
 -- @treturn table The new geometry
+-- @staticfct awful.placement.maximize
 function placement.maximize(d, args)
     args = add_context(args, "maximize")
     d    = d or capi.client.focus
@@ -1318,6 +1327,7 @@ end
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
 -- @tparam[opt={}] table args The arguments
 -- @treturn table The new geometry
+-- @staticfct awful.placement.scale
 function placement.scale(d, args)
     args = add_context(args, "scale_to_percent")
     d    = d or capi.client.focus
@@ -1400,6 +1410,7 @@ end
 -- @treturn table The new geometry
 -- @treturn string The choosen position ("left", "right", "top" or "bottom")
 -- @treturn string The choosen anchor ("front", "middle" or "back")
+-- @staticfct awful.placement.next_to
 function placement.next_to(d, args)
     args = add_context(args, "next_to")
     d    = d or capi.client.focus
@@ -1527,6 +1538,7 @@ end
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
 -- @tparam[opt={}] table args The arguments
 -- @treturn boolean If the geometry was restored
+-- @staticfct awful.placement.restore
 function placement.restore(d, args)
     if not args or not args.context then return false end
     d = d or capi.client.focus

lib/awful/popup.lua

@@ -18,7 +18,7 @@
 --
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
--- @classmod awful.popup
+-- @popupmod awful.popup
 ---------------------------------------------------------------------------
 local wibox     = require( "wibox"           )
 local util      = require( "awful.util"      )
@@ -234,6 +234,7 @@ end
 -- @see awful.popup.preferred_positions
 -- @see awful.popup.preferred_anchors
 -- @treturn table The new geometry
+-- @method move_next_to
 function popup:move_next_to(obj)
     if self._private.is_relative == false then return end
 
@@ -256,6 +257,7 @@ end
 --
 -- @tparam widget widget The widget
 -- @tparam[opt=1] number button The button index
+-- @method bind_to_widget
 function popup:bind_to_widget(widget, button)
     if not self._private.button_for_widget then
         self._private.button_for_widget = {}
@@ -267,6 +269,7 @@ end
 
 --- Unbind the popup from a widget button.
 -- @tparam widget widget The widget
+-- @method unbind_to_widget
 function popup:unbind_to_widget(widget)
     widget:disconnect_signal("button::press", self._private.show_fct)
 end
@@ -394,7 +397,7 @@ end
 -- @tparam table|number args.offset The X and Y offset compared to the parent object
 -- @tparam boolean args.hide_on_right_click Whether or not to hide the popup on
 --  right clicks.
--- @function awful.popup
+-- @constructorfct awful.popup
 local function create_popup(_, args)
     assert(args)
 

lib/awful/prompt.lua

@@ -454,6 +454,7 @@ end
 --   with mod table, key and command as arguments when a key was pressed.
 --   [**DEPRECATED**]
 -- @see gears.color
+-- @staticfct awful.prompt.run
 function prompt.run(args, textbox, exe_callback, completion_callback,
                     history_path, history_max, done_callback,
                     changed_callback, keypressed_callback)

lib/awful/rules.lua

@@ -134,6 +134,7 @@ local crules = gmatcher()
 -- @client c The client.
 -- @tab rule The rule to check.
 -- @treturn bool True if it matches, false otherwise.
+-- @staticfct awful.rules.match
 function rules.match(c, rule)
     return crules:_match(c, rule)
 end
@@ -142,6 +143,7 @@ end
 -- @client c The client.
 -- @tab rule The rule to check.
 -- @treturn bool True if at least one rule is matched, false otherwise.
+-- @staticfct awful.rules.match_any
 function rules.match_any(c, rule)
     return crules:_match_any(c, rule)
 end
@@ -151,6 +153,7 @@ end
 -- @tab entry Rule entry (with keys `rule`, `rule_any`, `except` and/or
 --   `except_any`).
 -- @treturn bool
+-- @staticfct awful.rules.matches
 function rules.matches(c, entry)
     return crules:matches_rule(c, entry)
 end
@@ -160,6 +163,7 @@ end
 -- @tab _rules The rules to check. List with "rule", "rule_any", "except" and
 --   "except_any" keys.
 -- @treturn table The list of matched rules.
+-- @staticfct awful.rules.matching_rules
 function rules.matching_rules(c, _rules)
     return crules:matching_rules(c, _rules)
 end
@@ -169,13 +173,15 @@ end
 -- @tab _rules The rules to check. List of tables with `rule`, `rule_any`,
 --   `except` and `except_any` keys.
 -- @treturn bool True if at least one rule is matched, false otherwise.
+-- @staticfct awful.rules.matches_list
 function rules.matches_list(c, _rules)
     return crules:matches_rules(c, _rules)
 end
 
 --- Remove a source.
 -- @tparam string name The source name.
--- @treturn boolean If the source was removed,
+-- @treturn boolean If the source was removed.
+-- @staticfct awful.rules.remove_rule_source
 function rules.remove_rule_source(name)
     return crules:remove_matching_source(name)
 end
@@ -183,6 +189,7 @@ end
 
 --- Apply awful.rules.rules to a client.
 -- @client c The client.
+-- @staticfct awful.rules.apply
 function rules.apply(c)
     return crules:apply(c)
 end
@@ -226,7 +233,7 @@ end
 -- @tparam[opt={}] table precede A list of names of sources this source have a
 --  priority over.
 -- @treturn boolean Returns false if a dependency conflict was found.
--- @function awful.rules.add_rule_source
+-- @staticfct awful.rules.add_rule_source
 
 function rules.add_rule_source(name, cb, ...)
     local function callback(_, ...)
@@ -519,7 +526,7 @@ end
 -- @client c The client.
 -- @tab props Properties to apply.
 -- @tab[opt] callbacks Callbacks to apply.
--- @function awful.rules.execute
+-- @staticfct awful.rules.execute
 
 crules._execute = function(_, c, props, callbacks)
     -- This has to be done first, as it will impact geometry related props.

lib/awful/screen.lua

@@ -57,7 +57,7 @@ function screen.getdistance_sq(s, x, y)
 end
 
 --- Get the square distance between a `screen` and a point.
--- @function screen.get_square_distance
+-- @method get_square_distance
 -- @tparam number x X coordinate of point
 -- @tparam number y Y coordinate of point
 -- @treturn number The squared distance of the screen to the provided point.
@@ -69,7 +69,7 @@ end
 --
 -- The number returned can be used as an index into the global
 -- `screen` table/object.
--- @function awful.screen.getbycoord
+-- @staticfct awful.screen.getbycoord
 -- @tparam number x The x coordinate
 -- @tparam number y The y coordinate
 -- @treturn ?number The screen index
@@ -86,7 +86,7 @@ end
 --
 -- This moves the mouse pointer to the last known position on the new screen,
 -- or keeps its position relative to the current focused screen.
--- @function awful.screen.focus
+-- @staticfct awful.screen.focus
 -- @screen _screen Screen number (defaults / falls back to mouse.screen).
 function screen.focus(_screen)
     client = client or require("awful.client")
@@ -128,7 +128,7 @@ end
 -- This gets the next screen relative to this one in
 -- the specified direction.
 --
--- @function screen:get_next_in_direction
+-- @method get_next_in_direction
 -- @param self Screen.
 -- @param dir The direction, can be either "up", "down", "left" or "right".
 function screen.object.get_next_in_direction(self, dir)
@@ -149,7 +149,7 @@ end
 --
 -- This moves the mouse pointer to the last known position on the new screen,
 -- or keeps its position relative to the current focused screen.
--- @function awful.screen.focus_bydirection
+-- @staticfct awful.screen.focus_bydirection
 -- @param dir The direction, can be either "up", "down", "left" or "right".
 -- @param _screen Screen.
 function screen.focus_bydirection(dir, _screen)
@@ -166,7 +166,7 @@ end
 -- This moves the mouse pointer to the last known position on the new screen,
 -- or keeps its position relative to the current focused screen.
 --
--- @function awful.screen.focus_relative
+-- @staticfct awful.screen.focus_relative
 -- @tparam int offset Value to add to the current focused screen index. 1 to
 --   focus the next one, -1 to focus the previous one.
 function screen.focus_relative(offset)
@@ -242,19 +242,20 @@ end
 -- focused screen by default.
 -- @tparam client c A client.
 -- @treturn screen The preferred screen.
+-- @staticfct awful.screen.preferred
 function screen.preferred(c)
     return capi.awesome.startup and c.screen or screen.focused()
 end
 
 --- The defaults arguments for `awful.screen.focused`.
--- @tfield[opt=nil] table awful.screen.default_focused_args
+-- @tfield[opt={}] table awful.screen.default_focused_args
 
 --- Get the focused screen.
 --
 -- It is possible to set `awful.screen.default_focused_args` to override the
 -- default settings.
 --
--- @function awful.screen.focused
+-- @staticfct awful.screen.focused
 -- @tparam[opt] table args
 -- @tparam[opt=false] boolean args.client Use the client screen instead of the
 --   mouse screen.
@@ -272,7 +273,7 @@ end
 --
 -- This method computes the different variants of the "usable" screen geometry.
 --
--- @function screen.get_bounding_geometry
+-- @staticfct 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.
@@ -341,7 +342,7 @@ end
 --
 -- This is used by `screen.clients` internally (with `stacked=true`).
 --
--- @function screen:get_clients
+-- @method get_clients
 -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table The clients list.
 function screen.object.get_clients(s, stacked)
@@ -388,7 +389,7 @@ end
 --
 -- This is used by `all_clients` internally (with `stacked=true`).
 --
--- @function screen:get_all_clients
+-- @method get_all_clients
 -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table The clients list.
 function screen.object.get_all_clients(s, stacked)
@@ -410,7 +411,7 @@ end
 --
 -- This is used by `tiles_clients` internally (with `stacked=true`).
 --
--- @function screen:get_tiled_clients
+-- @method get_tiled_clients
 -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table The clients list.
 function screen.object.get_tiled_clients(s, stacked)
@@ -430,7 +431,7 @@ end
 
 --- Call a function for each existing and created-in-the-future screen.
 --
--- @function awful.screen.connect_for_each_screen
+-- @staticfct awful.screen.connect_for_each_screen
 -- @tparam function func The function to call.
 -- @screen func.screen The screen.
 function screen.connect_for_each_screen(func)
@@ -441,7 +442,7 @@ function screen.connect_for_each_screen(func)
 end
 
 --- Undo the effect of connect_for_each_screen.
--- @function awful.screen.disconnect_for_each_screen
+-- @staticfct awful.screen.disconnect_for_each_screen
 -- @tparam function func The function that should no longer be called.
 function screen.disconnect_for_each_screen(func)
     capi.screen.disconnect_signal("added", func)
@@ -525,6 +526,7 @@ end
 -- defaulting to 96.
 --
 -- @tparam boolean enabled Enable or disable automatic DPI support.
+-- @staticfct awful.screen.set_auto_dpi_enabled
 function screen.set_auto_dpi_enabled(enabled)
     for s in capi.screen do
         s.data.dpi_cache = nil
@@ -535,7 +537,7 @@ end
 
 --- The number of pixels per inch of the screen.
 -- @property dpi
--- @treturn number the DPI value.
+-- @param number the DPI value.
 
 local xft_dpi, fallback_dpi
 
@@ -661,6 +663,8 @@ object.properties(capi.screen, {
     auto_emit    = true,
 })
 
+--@DOC_object_COMMON@
+
 return screen
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/spawn.lua

@@ -344,6 +344,7 @@ end
 -- @treturn[1] ?string The startup notification ID, if `sn` is not false, or
 --   a `callback` is provided.
 -- @treturn[2] string Error message.
+-- @staticfct awful.spawn
 function spawn.spawn(cmd, sn_rules, callback)
     if cmd and cmd ~= "" then
         local enable_sn = (sn_rules ~= false or callback)
@@ -363,6 +364,7 @@ end
 --- Spawn a program using the shell.
 -- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`).
 -- @tparam string cmd The command.
+-- @staticfct awful.spawn.with_shell
 function spawn.with_shell(cmd)
     if cmd and cmd ~= "" then
         cmd = { util.shell, "-c", cmd }
@@ -389,6 +391,7 @@ end
 --   termination.
 -- @treturn[1] Integer the PID of the forked process.
 -- @treturn[2] string Error message.
+-- @staticfct awful.spawn.with_line_callback
 function spawn.with_line_callback(cmd, callbacks)
     local stdout_callback, stderr_callback, done_callback, exit_callback =
         callbacks.stdout, callbacks.stderr, callbacks.output_done, callbacks.exit
@@ -434,6 +437,7 @@ end
 -- @treturn[1] Integer the PID of the forked process.
 -- @treturn[2] string Error message.
 -- @see spawn.with_line_callback
+-- @staticfct awful.spawn.easy_async
 function spawn.easy_async(cmd, callback)
     local stdout = ''
     local stderr = ''
@@ -484,6 +488,7 @@ end
 -- @treturn[1] Integer the PID of the forked process.
 -- @treturn[2] string Error message.
 -- @see spawn.with_line_callback
+-- @staticfct awful.spawn.easy_async_with_shell
 function spawn.easy_async_with_shell(cmd, callback)
     return spawn.easy_async({ util.shell, "-c", cmd or "" }, callback)
 end
@@ -495,6 +500,7 @@ end
 -- @tparam[opt] function done_callback Function that is called when the
 --   operation finishes (e.g. due to end of file).
 -- @tparam[opt=false] boolean close Should the stream be closed after end-of-file?
+-- @staticfct awful.spawn.read_lines
 function spawn.read_lines(input_stream, line_callback, done_callback, close)
     local stream = Gio.DataInputStream.new(input_stream)
     local function done()
@@ -644,6 +650,7 @@ end
 --  multiple time.
 -- @tparam[opt] function callback A callback function when the client is created.
 -- @see awful.rules
+-- @staticfct awful.spawn.once
 function spawn.once(cmd, rules, matcher, unique_id, callback)
     local hash = unique_id or hash_command(cmd, rules)
     local status = register_common(hash, rules, matcher, callback)
@@ -676,6 +683,7 @@ end
 --  multiple time.
 -- @tparam[opt] function callback A callback function when the client is created.
 -- @see awful.rules
+-- @staticfct awful.spawn.single_instance
 function spawn.single_instance(cmd, rules, matcher, unique_id, callback)
     local hash = unique_id or hash_command(cmd, rules)
     register_common(hash, rules, matcher, callback)
@@ -703,6 +711,7 @@ local raise_rules = {focus = true, switch_to_tags = true, raise = true}
 -- @tparam[opt] function callback A callback function when the client is created.
 -- @see awful.rules
 -- @treturn client The client if it already exists.
+-- @staticfct awful.spawn.raise_or_spawn
 function spawn.raise_or_spawn(cmd, rules, matcher, unique_id, callback)
     local hash = unique_id or hash_command(cmd, rules)
 

lib/awful/tag.lua

@@ -218,8 +218,8 @@ function tag.move(new_index, target_tag)
     tag.object.set_index(target_tag, new_index)
 end
 
---- Swap 2 tags
+--- Swap 2 tags.
--- @function tag.swap
+-- @method swap
 -- @param tag2 The second tag
 -- @see client.swap
 function tag.object.swap(self, tag2)
@@ -259,7 +259,7 @@ end
 --        layout = awful.layout.suit.max,
 --    })
 --
--- @function awful.tag.add
+-- @constructorfct awful.tag.add
 -- @param name The tag name, a string
 -- @param props The tags inital properties, a table
 -- @return The created tag
@@ -296,7 +296,7 @@ function tag.add(name, props)
 end
 
 --- Create a set of tags and attach it to a screen.
--- @function awful.tag.new
+-- @staticfct awful.tag.new
 -- @param names The tag name, in a table
 -- @param screen The tag screen, or 1 if not set.
 -- @param layout The layout or layout table to set for this tags by default.
@@ -322,7 +322,7 @@ function tag.new(names, screen, layout)
 end
 
 --- Find a suitable fallback tag.
--- @function awful.tag.find_fallback
+-- @staticfct awful.tag.find_fallback
 -- @param screen The screen to look for a tag on. [awful.screen.focused()]
 -- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)]
 function tag.find_fallback(screen, invalids)
@@ -340,7 +340,7 @@ end
 --
 --    mouse.screen.selected_tag:delete()
 --
--- @function tag.delete
+-- @method delete
 -- @see awful.tag.add
 -- @see awful.tag.find_fallback
 -- @tparam[opt=awful.tag.find_fallback()] tag fallback_tag Tag to assign
@@ -429,7 +429,7 @@ function tag.delete(target_tag, fallback_tag)
 end
 
 --- Update the tag history.
--- @function awful.tag.history.update
+-- @staticfct awful.tag.history.update
 -- @param obj Screen object.
 function tag.history.update(obj)
     local s = get_screen(obj)
@@ -470,7 +470,7 @@ function tag.history.update(obj)
 end
 
 --- Revert tag history.
--- @function awful.tag.history.restore
+-- @staticfct awful.tag.history.restore
 -- @param screen The screen.
 -- @param idx Index in history. Defaults to "previous" which is a special index
 -- toggling between last two selected sets of tags. Number (eg 1) will go back
@@ -522,6 +522,7 @@ end
 -- @tparam screen s The screen of the tag
 -- @tparam string name The name of the tag
 -- @return The tag found, or `nil`
+-- @staticfct awful.tag.find_by_name
 -- @usage -- For the current screen
 -- local t = awful.tag.find_by_name(awful.screen.focused(), "name")
 --
@@ -696,7 +697,7 @@ function tag.setmwfact(mwfact, t)
 end
 
 --- Increase master width factor.
--- @function awful.tag.incmwfact
+-- @staticfct awful.tag.incmwfact
 -- @see master_width_factor
 -- @param add Value to add to master width factor.
 -- @param t The tag to modify, if null tag.selected() is used.
@@ -741,7 +742,7 @@ end
 --         -- awful.layout.suit.corner.se,
 --     }
 --
--- @field awful.tag.layouts
+-- @tfield table awful.tag.layouts
 
 --- The tag client layout.
 --
@@ -972,7 +973,7 @@ function tag.setgap(useless_gap, t)
 end
 
 --- Increase the spacing between clients
--- @function awful.tag.incgap
+-- @staticfct awful.tag.incgap
 -- @see gap
 -- @param add Value to add to the spacing between clients
 -- @param t The tag to modify, if null tag.selected() is used.
@@ -1079,7 +1080,7 @@ end
 
 --- Toggle size fill policy for the master client(s)
 -- between "expand" and "master_width_factor".
--- @function awful.tag.togglemfpol
+-- @staticfct awful.tag.togglemfpol
 -- @see master_fill_policy
 -- @tparam tag t The tag to modify, if null tag.selected() is used.
 function tag.togglemfpol(t)
@@ -1160,7 +1161,7 @@ function tag.getnmaster(t)
 end
 
 --- Increase the number of master windows.
--- @function awful.tag.incnmaster
+-- @staticfct awful.tag.incnmaster
 -- @see master_count
 -- @param add Value to add to number of master windows.
 -- @param[opt] t The tag to modify, if null tag.selected() is used.
@@ -1278,7 +1279,7 @@ function tag.getncol(t)
 end
 
 --- Increase number of column windows.
--- @function awful.tag.incncol
+-- @staticfct awful.tag.incncol
 -- @param add Value to add to number of column windows.
 -- @param[opt] t The tag to modify, if null tag.selected() is used.
 -- @tparam[opt=false] boolean sensible Limit column_count based on the number
@@ -1309,7 +1310,7 @@ function tag.incncol(add, t, sensible)
 end
 
 --- View no tag.
--- @function awful.tag.viewnone
+-- @staticfct awful.tag.viewnone
 -- @tparam[opt] int|screen screen The screen.
 function tag.viewnone(screen)
     screen = screen or ascreen.focused()
@@ -1322,7 +1323,7 @@ end
 --- View a tag by its taglist index.
 --
 -- This is equivalent to `screen.tags[i]:view_only()`
--- @function awful.tag.viewidx
+-- @staticfct awful.tag.viewidx
 -- @see screen.tags
 -- @param i The **relative** index to see.
 -- @param[opt] screen The screen.
@@ -1357,21 +1358,21 @@ function tag.getidx(query_tag)
 end
 
 --- View next tag. This is the same as tag.viewidx(1).
--- @function awful.tag.viewnext
+-- @staticfct awful.tag.viewnext
 -- @param screen The screen.
 function tag.viewnext(screen)
     return tag.viewidx(1, screen)
 end
 
 --- View previous tag. This is the same a tag.viewidx(-1).
--- @function awful.tag.viewprev
+-- @staticfct awful.tag.viewprev
 -- @param screen The screen.
 function tag.viewprev(screen)
     return tag.viewidx(-1, screen)
 end
 
 --- View only a tag.
--- @function tag.view_only
+-- @method view_only
 -- @see selected
 function tag.object.view_only(self)
     local tags = self.screen.tags
@@ -1404,7 +1405,7 @@ end
 -- selected. The tags already selected do not count. To do nothing if one or
 -- more of the tags are already selected, set `maximum` to zero.
 --
--- @function awful.tag.viewmore
+-- @staticfct awful.tag.viewmore
 -- @param tags A table with tags to view only.
 -- @param[opt] screen The screen of the tags.
 -- @tparam[opt=#tags] number maximum The maximum number of tags to select.
@@ -1437,7 +1438,7 @@ function tag.viewmore(tags, screen, maximum)
 end
 
 --- Toggle selection of a tag
--- @function awful.tag.viewtoggle
+-- @staticfct awful.tag.viewtoggle
 -- @see selected
 -- @tparam tag t Tag to be toggled
 function tag.viewtoggle(t)
@@ -1530,7 +1531,7 @@ end
 --- Add a signal to all attached tags and all tags that will be attached in the
 -- future. When a tag is detached from the screen, its signal is removed.
 --
--- @function awful.tag.attached_connect_signal
+-- @staticfct awful.tag.attached_connect_signal
 -- @screen screen The screen concerned, or all if nil.
 -- @tparam[opt] string signal The signal name.
 -- @tparam[opt] function Callback
@@ -1685,6 +1686,8 @@ object.properties(capi.tag, {
     setter_fallback = tag.setproperty,
 })
 
+--@DOC_object_COMMON@
+
 return setmetatable(tag, tag.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/titlebar.lua

@@ -9,7 +9,7 @@
 --
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
--- @classmod awful.titlebar
+-- @popupmod awful.titlebar
 ---------------------------------------------------------------------------
 
 local error = error
@@ -38,9 +38,11 @@ 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.
@@ -55,7 +57,7 @@ local titlebar = {
 
 --- The titlebar background image image.
 -- @beautiful beautiful.titlebar_bgimage_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The titlebar foreground (text) color.
@@ -70,7 +72,7 @@ local titlebar = {
 
 --- The titlebar background image image.
 -- @beautiful beautiful.titlebar_bgimage
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The focused titlebar foreground (text) color.
@@ -85,354 +87,353 @@ local titlebar = {
 
 --- The focused titlebar background image image.
 -- @beautiful beautiful.titlebar_bgimage_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal.
 -- @beautiful beautiful.titlebar_floating_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal.
 -- @beautiful beautiful.titlebar_maximized_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_normal.
 -- @beautiful beautiful.titlebar_minimize_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_normal_hover.
 -- @beautiful beautiful.titlebar_minimize_button_normal_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_normal_press.
 -- @beautiful beautiful.titlebar_minimize_button_normal_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_normal.
 -- @beautiful beautiful.titlebar_close_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_normal_hover.
 -- @beautiful beautiful.titlebar_close_button_normal_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_normal_press.
 -- @beautiful beautiful.titlebar_close_button_normal_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal.
 -- @beautiful beautiful.titlebar_ontop_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal.
 -- @beautiful beautiful.titlebar_sticky_button_normal
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus.
 -- @beautiful beautiful.titlebar_floating_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus.
 -- @beautiful beautiful.titlebar_maximized_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_focus.
 -- @beautiful beautiful.titlebar_minimize_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_focus_hover.
 -- @beautiful beautiful.titlebar_minimize_button_focus_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- minimize_button_focus_press.
 -- @beautiful beautiful.titlebar_minimize_button_focus_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_focus.
 -- @beautiful beautiful.titlebar_close_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_focus_hover.
 -- @beautiful beautiful.titlebar_close_button_focus_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- close_button_focus_press.
 -- @beautiful beautiful.titlebar_close_button_focus_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus.
 -- @beautiful beautiful.titlebar_ontop_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus.
 -- @beautiful beautiful.titlebar_sticky_button_focus
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_active.
 -- @beautiful beautiful.titlebar_floating_button_normal_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_active_hover.
 -- @beautiful beautiful.titlebar_floating_button_normal_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_active_press.
 -- @beautiful beautiful.titlebar_floating_button_normal_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_active.
 -- @beautiful beautiful.titlebar_maximized_button_normal_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_active_hover.
 -- @beautiful beautiful.titlebar_maximized_button_normal_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_active_press.
 -- @beautiful beautiful.titlebar_maximized_button_normal_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_active.
 -- @beautiful beautiful.titlebar_ontop_button_normal_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_active_hover.
 -- @beautiful beautiful.titlebar_ontop_button_normal_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_active_press.
 -- @beautiful beautiful.titlebar_ontop_button_normal_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_active.
 -- @beautiful beautiful.titlebar_sticky_button_normal_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_active_hover.
 -- @beautiful beautiful.titlebar_sticky_button_normal_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_active_press.
 -- @beautiful beautiful.titlebar_sticky_button_normal_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_active.
 -- @beautiful beautiful.titlebar_floating_button_focus_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_active_hover.
 -- @beautiful beautiful.titlebar_floating_button_focus_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_active_press.
 -- @beautiful beautiful.titlebar_floating_button_focus_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_active.
 -- @beautiful beautiful.titlebar_maximized_button_focus_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_active_hover.
 -- @beautiful beautiful.titlebar_maximized_button_focus_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_active_press.
 -- @beautiful beautiful.titlebar_maximized_button_focus_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_active.
 -- @beautiful beautiful.titlebar_ontop_button_focus_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_active_hover.
 -- @beautiful beautiful.titlebar_ontop_button_focus_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_active_press.
 -- @beautiful beautiful.titlebar_ontop_button_focus_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_active.
 -- @beautiful beautiful.titlebar_sticky_button_focus_active
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_active_hover.
 -- @beautiful beautiful.titlebar_sticky_button_focus_active_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_active_press.
 -- @beautiful beautiful.titlebar_sticky_button_focus_active_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_inactive.
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_inactive_hover.
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_normal_inactive_press.
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_inactive.
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_inactive_hover.
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_normal_inactive_press.
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_inactive.
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_inactive_hover.
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_normal_inactive_press.
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_inactive.
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_inactive_hover.
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_normal_inactive_press.
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_inactive.
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_inactive_hover.
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- floating_button_focus_inactive_press.
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_inactive.
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_inactive_hover.
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- maximized_button_focus_inactive_press.
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_inactive.
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_inactive_hover.
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- ontop_button_focus_inactive_press.
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_inactive.
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_inactive_hover.
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover
--- @param surface
+-- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- sticky_button_focus_inactive_press.
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press
--- @param surface
+-- @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
--- @name setup
+-- @method setup
--- @class function
 
 
 local all_titlebars = setmetatable({}, { __mode = 'k' })
@@ -502,7 +503,7 @@ end
 -- @tparam[opt=top] string args.fg_normal
 -- @tparam[opt=top] string args.fg_focus
 -- @tparam[opt=top] string args.font
--- @function awful.titlebar
+-- @constructorfct awful.titlebar
 local function new(c, args)
     args = args or {}
     local position = args.position or "top"
@@ -564,6 +565,7 @@ end
 -- @param c The client whose titlebar is modified
 -- @param[opt] position The position of the titlebar. Must be one of "left",
 --   "right", "top", "bottom". Default is "top".
+-- @staticfct awful.titlebar.show
 function titlebar.show(c, position)
     position = position or "top"
     if load_titlebars(c, true, position) then return end
@@ -577,6 +579,7 @@ end
 -- @param c The client whose titlebar is modified
 -- @param[opt] position The position of the titlebar. Must be one of "left",
 --   "right", "top", "bottom". Default is "top".
+-- @staticfct awful.titlebar.hide
 function titlebar.hide(c, position)
     position = position or "top"
     get_titlebar_function(c, position)(c, 0)
@@ -586,6 +589,7 @@ end
 -- @param c The client whose titlebar is modified
 -- @param[opt] position The position of the titlebar. Must be one of "left",
 --   "right", "top", "bottom". Default is "top".
+-- @staticfct awful.titlebar.toggle
 function titlebar.toggle(c, position)
     position = position or "top"
     if load_titlebars(c, true, position) then return end
@@ -602,6 +606,7 @@ end
 -- This way, you can e.g. modify the font that is used.
 -- @param c The client for which a titlewidget should be created.
 -- @return The title widget.
+-- @staticfct awful.titlebar.widget.titlewidget
 function titlebar.widget.titlewidget(c)
     local ret = textbox()
     local function update()
@@ -618,6 +623,7 @@ end
 -- available. This way, you can e.g. disallow resizes.
 -- @param c The client for which an icon widget should be created.
 -- @return The icon widget.
+-- @staticfct awful.titlebar.widget.iconwidget
 function titlebar.widget.iconwidget(c)
     return clienticon(c)
 end
@@ -635,6 +641,7 @@ end
 -- @param selector A function that selects the image that should be displayed.
 -- @param action Function that is called when the button is clicked.
 -- @return The widget
+-- @staticfct awful.titlebar.widget.button
 function titlebar.widget.button(c, name, selector, action)
     local ret = imagebox()
 
@@ -718,6 +725,7 @@ end
 
 --- Create a new float button for a client.
 -- @param c The client for which the button is wanted.
+-- @staticfct awful.titlebar.widget.floatingbutton
 function titlebar.widget.floatingbutton(c)
     local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle)
     c:connect_signal("property::floating", widget.update)
@@ -726,6 +734,7 @@ end
 
 --- Create a new maximize button for a client.
 -- @param c The client for which the button is wanted.
+-- @staticfct awful.titlebar.widget.maximizedbutton
 function titlebar.widget.maximizedbutton(c)
     local widget = titlebar.widget.button(c, "maximized", function(cl)
         return cl.maximized
@@ -738,6 +747,7 @@ end
 
 --- Create a new minimize button for a client.
 -- @param c The client for which the button is wanted.
+-- @staticfct awful.titlebar.widget.minimizebutton
 function titlebar.widget.minimizebutton(c)
     local widget = titlebar.widget.button(c, "minimize",
                                           function() return "" end,
@@ -748,12 +758,14 @@ end
 
 --- Create a new closing button for a client.
 -- @param c The client for which the button is wanted.
+-- @staticfct awful.titlebar.widget.closebutton
 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.
+-- @staticfct awful.titlebar.widget.ontopbutton
 function titlebar.widget.ontopbutton(c)
     local widget = titlebar.widget.button(c, "ontop",
                                           function(cl) return cl.ontop end,
@@ -764,6 +776,7 @@ end
 
 --- Create a new sticky button for a client.
 -- @param c The client for which the button is wanted.
+-- @staticfct awful.titlebar.widget.stickybutton
 function titlebar.widget.stickybutton(c)
     local widget = titlebar.widget.button(c, "sticky",
                                           function(cl) return cl.sticky end,

lib/awful/tooltip.lua

@@ -39,7 +39,7 @@
 --
 -- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org>
 -- @copyright 2009 Sébastien Gross
--- @classmod awful.tooltip
+-- @popupmod awful.tooltip
 -------------------------------------------------------------------------
 
 local timer = require("gears.timer")
@@ -86,27 +86,34 @@ local offset = {
 
 --- The tooltip border color.
 -- @beautiful beautiful.tooltip_border_color
+-- @param color
 
 --- The tooltip background color.
 -- @beautiful beautiful.tooltip_bg
+-- @param color
 
 --- The tooltip foregound (text) color.
 -- @beautiful beautiful.tooltip_fg
+-- @param color
 
 --- The tooltip font.
 -- @beautiful beautiful.tooltip_font
+-- @param string
 
 --- The tooltip border width.
 -- @beautiful beautiful.tooltip_border_width
+-- @param number
 
 --- The tooltip opacity.
 -- @beautiful beautiful.tooltip_opacity
+-- @param number opacity Between 0 and 1
 
 --- The default tooltip shape.
--- The default shape for all tooltips is a rectangle. However, by setting this variable
+-- The default shape for all tooltips is a rectangle. However, by setting
--- they can default to rounded rectangle or stretched octogons.
+-- this variable they can default to rounded rectangle or stretched octogons.
 -- @beautiful beautiful.tooltip_shape
--- @tparam[opt=gears.shape.rectangle] function shape A `gears.shape` compatible function
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape A `gears.shape`
+--  compatible function
 -- @see shape
 -- @see gears.shape
 
@@ -251,6 +258,7 @@ end
 -- * top
 --
 -- @property align
+-- @param string
 -- @see beautiful.tooltip_align
 -- @see mode
 -- @see preferred_positions
@@ -276,20 +284,14 @@ function tooltip:set_align(value)
 end
 
 --- The shape of the tooltip window.
--- If the shape require some parameters, use `set_shape`.
 --
 -- @DOC_awful_tooltip_shape_EXAMPLE@
 --
 -- @property shape
+-- @tparam gears.shape shape
 -- @see gears.shape
--- @see set_shape
 -- @see beautiful.tooltip_shape
 
---- Set the tooltip shape.
--- All other arguments will be passed to the shape function.
--- @tparam gears.shape s The shape
--- @see shape
--- @see gears.shape
 function tooltip:set_shape(s)
     self.backgroundbox:set_shape(s)
 end
@@ -473,6 +475,7 @@ end
 -- @DOC_awful_tooltip_border_color_EXAMPLE@
 --
 -- @property border_color
+-- @param color
 -- @param gears.color
 
 function tooltip:set_border_color(val)
@@ -520,7 +523,7 @@ end
 -- @tparam tooltip self The tooltip.
 -- @tparam gears.object obj An object with `mouse::enter` and
 --   `mouse::leave` signals.
--- @function add_to_object
+-- @method add_to_object
 function tooltip:add_to_object(obj)
     if not obj then return end
 
@@ -533,7 +536,7 @@ end
 -- @tparam tooltip self The tooltip.
 -- @tparam gears.object obj An object with `mouse::enter` and
 --   `mouse::leave` signals.
--- @function remove_from_object
+-- @method remove_from_object
 function tooltip:remove_from_object(obj)
     obj:disconnect_signal("mouse::enter", self.show)
     obj:disconnect_signal("mouse::leave", self.hide)
@@ -577,7 +580,7 @@ end
 -- @see text
 -- @see markup
 -- @see align
--- @function awful.tooltip
+-- @constructorfct awful.tooltip
 function tooltip.new(args)
     -- gears.object, properties are linked to set_/get_ functions
     local self = object {

lib/awful/util.lua

@@ -31,6 +31,7 @@ local util = {}
 util.table = {}
 
 --- The default shell used when spawing processes.
+-- @param string
 util.shell = os.getenv("SHELL") or "/bin/sh"
 
 --- Execute a system command and road the output.
@@ -99,6 +100,7 @@ end
 
 --- Eval Lua code.
 -- @return The return value of Lua code.
+-- @staticfct awful.util.eval
 function util.eval(s)
     return assert(load(s))()
 end
@@ -129,6 +131,7 @@ end
 -- @param path The file path.
 -- @return A function if everything is alright, a string with the error
 -- otherwise.
+-- @staticfct awful.util.checkfile
 function util.checkfile(path)
     local f, e = loadfile(path)
     -- Return function if function, otherwise return error.
@@ -140,6 +143,7 @@ end
 -- It checks if the configuration file is valid, and then restart if it's ok.
 -- If it's not ok, the error will be returned.
 -- @return Never return if awesome restart, or return a string error.
+-- @staticfct awful.util.restart
 function util.restart()
     local c = util.checkfile(capi.awesome.conffile)
 
@@ -225,6 +229,7 @@ end
 -- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' }
 -- @tparam[opt] string size The size. If this is specified, subdirectories `x`
 --   of the dirs are searched first.
+-- @staticfct awful.util.geticonpath
 function util.geticonpath(iconname, exts, dirs, size)
     exts = exts or { 'png', 'gif' }
     dirs = dirs or { '/usr/share/pixmaps/', '/usr/share/icons/hicolor/' }

lib/awful/wibar.lua

@@ -5,7 +5,7 @@
 --
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee
--- @classmod awful.wibar
+-- @popupmod awful.wibar
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -217,11 +217,6 @@ local function set_position(wb, position, skip_reattach)
     end
 end
 
---- Stretch the wibar.
---
--- @property stretch
--- @param[opt=true] boolean
-
 local function get_stretch(w)
     return w._stretch
 end
@@ -233,7 +228,8 @@ local function set_stretch(w, value)
 end
 
 --- Remove a wibar.
--- @function remove
+-- @method remove
+
 local function remove(self)
     self.visible = false
 
@@ -344,7 +340,7 @@ end
 -- @tparam string args.stretch If the wibar need to be stretched to fill the screen.
 --@DOC_wibox_constructor_COMMON@
 -- @return The new wibar
--- @function awful.wibar
+-- @constructorfct awful.wibar
 function awfulwibar.new(args)
     args = args or {}
     local position = args.position or "top"

lib/awful/widget/button.lua

@@ -9,7 +9,7 @@
 -- ))
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
--- @classmod awful.widget.button
+-- @widgetmod awful.widget.button
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -24,6 +24,7 @@ local button = { mt = {} }
 --- Create a button widget. When clicked, the image is deplaced to make it like
 -- a real button.
 --
+-- @constructorfct awful.widget.button
 -- @param args Widget arguments. "image" is the image to display.
 -- @return A textbox widget configured as a button.
 function button.new(args)

lib/awful/widget/calendar_popup.lua

@@ -22,7 +22,7 @@
 --
 -- @author getzze
 -- @copyright 2017 getzze
--- @classmod awful.widget.calendar_popup
+-- @popupmod awful.widget.calendar_popup
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -203,6 +203,7 @@ end
 -- @tparam string position Two-character position of the calendar in the screen
 -- @tparam screen screen Screen where to display the calendar
 -- @treturn wibox The wibox calendar
+-- @method call_calendar
 function calendar_popup:call_calendar(offset, position, screen)
     local inc_offset = offset or 0
     local pos = position or self.position
@@ -230,7 +231,8 @@ function calendar_popup:call_calendar(offset, position, screen)
     return self
 end
 
---- Toggle calendar visibility
+--- Toggle calendar visibility.
+-- @method toggle
 function calendar_popup:toggle()
     self:call_calendar(0)
     self.visible = not self.visible
@@ -247,6 +249,7 @@ end
 -- @tparam[opt={}] table args Additional options
 -- @tparam[opt=true] bool args.on_hover Show popup during mouse hover
 -- @treturn wibox The wibox calendar
+-- @method attach
 function calendar_popup:attach(widget, position, args)
     position = position or "tr"
     args = args or {}
@@ -371,7 +374,7 @@ end
 -- @tparam table args.style_normal Cell style for the normal day cells (see `cell_properties`)
 -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`)
 -- @treturn wibox A wibox containing the calendar
--- @function awful.widget.calendar_popup.month
+-- @constructorfct awful.widget.calendar_popup.month
 function calendar_popup.month(args)
     return get_cal_wibox("month", args)
 end
@@ -407,7 +410,7 @@ end
 -- @tparam table args.style_normal Cell style for the normal day cells (see `cell_properties`)
 -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`)
 -- @treturn wibox A wibox containing the calendar
--- @function awful.widget.calendar_popup.year
+-- @constructorfct awful.widget.calendar_popup.year
 function calendar_popup.year(args)
     return get_cal_wibox("year", args)
 end

lib/awful/widget/clienticon.lua

@@ -1,7 +1,7 @@
 --- Container showing the icon of a client.
 -- @author Uli Schlachter
 -- @copyright 2017 Uli Schlachter
--- @classmod awful.widget.clienticon
+-- @widgetmod awful.widget.clienticon
 
 local base = require("wibox.widget.base")
 local surface = require("gears.surface")
@@ -99,7 +99,7 @@ end
 --- Returns a new clienticon.
 -- @tparam client c The client whose icon should be displayed.
 -- @treturn widget A new `widget`
--- @function awful.widget.clienticon
+-- @constructorfct awful.widget.clienticon
 local function new(c)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 

lib/awful/widget/keyboardlayout.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 -- @author Aleksey Fedotov <lexa@cfotr.com>
 -- @copyright 2015 Aleksey Fedotov
--- @classmod awful.widget.keyboardlayout
+-- @widgetmod awful.widget.keyboardlayout
 ---------------------------------------------------------------------------
 
 local capi = {awesome = awesome}
@@ -135,6 +135,7 @@ end
 -- xkb_symbols pattern "vendor/file(section):group_idx".
 -- @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)
     if group_names == nil then
         return nil
@@ -252,7 +253,11 @@ local function update_layout(self)
     update_status(self)
 end
 
---- Create a keyboard layout widget. It shows current keyboard layout name in a textbox.
+--- Create a keyboard layout widget.
+--
+-- It shows current keyboard layout name in a textbox.
+--
+-- @constructorfct awful.widget.keyboardlayout
 -- @return A keyboard layout widget.
 function keyboardlayout.new()
     local widget = textbox()

lib/awful/widget/launcher.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
--- @classmod awful.widget.launcher
+-- @widgetmod awful.widget.launcher
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -16,6 +16,7 @@ local launcher = { mt = {} }
 -- @param args Standard widget table arguments, plus image for the image path
 -- and command for the command to run on click, or either menu to create menu.
 -- @return A launcher widget.
+-- @constructorfct awful.widget.launcher
 function launcher.new(args)
     if not args.command and not args.menu then return end
     local w = wbutton(args)

lib/awful/widget/layoutbox.lua

@@ -3,7 +3,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
--- @classmod awful.widget.layoutbox
+-- @widgetmod awful.widget.layoutbox
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -44,6 +44,7 @@ end
 -- symbol of the current tag.
 -- @param screen The screen number that the layout will be represented for.
 -- @return An imagebox widget configured as a layoutbox.
+-- @constructorfct awful.widget.layoutbox
 function layoutbox.new(screen)
     screen = get_screen(screen or 1)
 

lib/awful/widget/layoutlist.lua

@@ -20,7 +20,7 @@
 --
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2010, 2018 Emmanuel Lepage Vallee
--- @classmod awful.widget.layoutlist
+-- @widgetmod awful.widget.layoutlist
 ----------------------------------------------------------------------------
 
 local capi     = {screen = screen, tag = tag}
@@ -382,7 +382,7 @@ end
 -- @tparam string|pattern args.style.shape_border_width_selected
 -- @tparam string|pattern args.style.shape_border_color_selected
 -- @treturn widget The action widget.
--- @function awful.widget.layoutlist
+-- @constructorfct awful.widget.layoutlist
 
 local is_connected, instances = false, setmetatable({}, {__mode = "v"})
 

lib/awful/widget/only_on_screen.lua

@@ -4,7 +4,7 @@
 --
 -- @author Uli Schlachter
 -- @copyright 2017 Uli Schlachter
--- @classmod awful.widget.only_on_screen
+-- @containermod awful.widget.only_on_screen
 ---------------------------------------------------------------------------
 
 local type = type
@@ -63,15 +63,10 @@ function only_on_screen:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function only_on_screen:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function only_on_screen:set_children(children)
     self:set_widget(children[1])
 end
@@ -96,7 +91,7 @@ end
 -- @param[opt] widget The widget to display.
 -- @param[opt] s The screen to display on.
 -- @treturn table A new only_on_screen container
--- @function wibox.container.only_on_screen
+-- @constructorfct awful.widget.only_on_screen
 local function new(widget, s)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 

lib/awful/widget/prompt.lua

@@ -6,7 +6,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @copyright 2018 Aire-One
--- @classmod awful.widget.prompt
+-- @widgetmod awful.widget.prompt
 ---------------------------------------------------------------------------
 
 --- The prompt foreground color.
@@ -113,7 +113,7 @@ end
 --   for the matching modifiers + key. See @{awful.prompt.run} for details.
 -- @return An instance of prompt widget, inherits from
 --   `wibox.container.background`.
--- @function awful.widget.prompt
+-- @constructorfct awful.widget.prompt
 function widgetprompt.new(args)
     args = args or {}
     local promptbox = background()

lib/awful/widget/taglist.lua

@@ -34,7 +34,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
--- @classmod awful.widget.taglist
+-- @widgetmod awful.widget.taglist
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -153,7 +153,7 @@ taglist.filter, taglist.source = {}, {}
 -- This will be the fallback for state specific shapes.
 -- To get a shape for the whole taglist, use `wibox.container.background`.
 -- @beautiful beautiful.taglist_shape
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 -- @see beautiful.taglist_shape_empty
 -- @see beautiful.taglist_shape_focus
@@ -172,7 +172,7 @@ taglist.filter, taglist.source = {}, {}
 
 --- The shape used for the empty elements.
 -- @beautiful beautiful.taglist_shape_empty
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The shape used for the empty elements border width.
@@ -187,7 +187,7 @@ taglist.filter, taglist.source = {}, {}
 
 --- The shape used for the selected elements.
 -- @beautiful beautiful.taglist_shape_focus
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The shape used for the selected elements border width.
@@ -202,7 +202,7 @@ taglist.filter, taglist.source = {}, {}
 
 --- The shape used for the urgent elements.
 -- @beautiful beautiful.taglist_shape_urgent
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The shape used for the urgent elements border width.
@@ -217,7 +217,7 @@ taglist.filter, taglist.source = {}, {}
 
 --- The shape used for the volatile elements.
 -- @beautiful beautiful.taglist_shape_volatile
--- @param[opt=rectangle] gears.shape
+-- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
 --- The shape used for the volatile elements border width.
@@ -462,7 +462,7 @@ end
 -- @param style **DEPRECATED** use args.style
 -- @param update_function **DEPRECATED** use args.update_function
 -- @param base_widget **DEPRECATED** use args.base_widget
--- @function awful.widget.taglist
+-- @constructorfct awful.widget.taglist
 function taglist.new(args, filter, buttons, style, update_function, base_widget)
 
     local screen = nil

lib/awful/widget/tasklist.lua

@@ -70,7 +70,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
--- @classmod awful.widget.tasklist
+-- @widgetmod awful.widget.tasklist
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -518,7 +518,7 @@ end
 -- @param style **DEPRECATED** use args.style
 -- @param update_function **DEPRECATED** use args.update_function
 -- @param base_widget **DEPRECATED** use args.base_widget
--- @function awful.tasklist
+-- @constructorfct awful.widget.tasklist
 function tasklist.new(args, filter, buttons, style, update_function, base_widget)
     local screen = nil
 

lib/awful/widget/watch.lua

@@ -27,7 +27,7 @@
 -- @author Benjamin Petrenko
 -- @author Yauheni Kirylau
 -- @copyright 2015, 2016 Benjamin Petrenko, Yauheni Kirylau
--- @classmod awful.widget.watch
+-- @widgetmod awful.widget.watch
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -64,6 +64,7 @@ local watch = { mt = {} }
 --
 -- @return The widget used by this watch.
 -- @return Its gears.timer.
+-- @constructorfct awful.widget.watch
 function watch.new(command, timeout, callback, base_widget)
     timeout = timeout or 5
     base_widget = base_widget or textbox()

lib/beautiful/gtk.lua

@@ -3,7 +3,7 @@
 --
 -- @author Yauheni Kirylau <yawghen@gmail.com>
 -- @copyright 2016-2017 Yauheni Kirylau
--- @module beautiful.gtk
+-- @themelib beautiful.gtk
 ---------------------------------------------------------------------------
 local get_dpi = require("beautiful.xresources").get_dpi
 local gears_debug = require("gears.debug")
@@ -63,54 +63,6 @@ local function read_gtk_color_properties_from_widget(gtk_widget, properties)
     return result
 end
 
-
--- luacheck: max comment line length 300
-
---- Get GTK+3 theme variables from GtkStyleContext
--- @treturn table Key-value table with the following structure:
--- <table class='widget_list' border=1>
--- <tr style='font-weight: bold;'> <th align='center'>Result key</th> <th align='center'>StyleContext key</th> <th align='center'>StyleContext fallback #1</th> <th align='center'>StyleContext fallback #2</th> <th align='center'>GTK Widget fallback</th> </tr>
--- <tr> <td>`font_size`</td> <td></td> <td></td> <td></td> <td>Label font-size</td> </tr>
--- <tr> <td>`font_family`</td> <td></td> <td></td> <td></td> <td>Label font-family</td> </tr>
--- <tr> <td>`bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> <td>Window bg</td> </tr>
--- <tr> <td>`fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> <td>Window fg</td> </tr>
--- <tr> <td>`base_color`</td> <td>`theme_base_color`</td> <td></td> <td></td> <td>Entry bg</td> </tr>
--- <tr> <td>`text_color`</td> <td>`theme_text_color`</td> <td></td> <td></td> <td>Entry fg</td> </tr>
--- <tr> <td>`button_bg_color`</td> <td>`theme_button_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>Button bg</td> </tr>
--- <tr> <td>`button_fg_color`</td> <td>`theme_button_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>Button fg</td> </tr>
--- <tr> <td>`button_border_color`</td> <td></td> <td></td> <td></td> <td>Button border-color</td> </tr>
--- <tr> <td>`button_border_radius`</td> <td></td> <td></td> <td></td> <td>Button border-radius</td> </tr>
--- <tr> <td>`button_border_width`</td> <td></td> <td></td> <td></td> <td>Button border-top-width</td> </tr>
--- <tr> <td>`selected_bg_color`</td> <td>`theme_selected_bg_color`</td> <td></td> <td></td> <td>ToggleButton bg</td> </tr>
--- <tr> <td>`selected_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> <td>ToggleButton fg</td> </tr>
--- <tr> <td>`menubar_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>HeaderBar bg</td> </tr>
--- <tr> <td>`menubar_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>HeaderBar fg</td> </tr>
--- <tr> <td>`header_button_bg_color`</td> <td>`header_button_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar > Button bg</td> </tr>
--- <tr> <td>`header_button_fg_color`</td> <td>`header_button_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td>HeaderBar > Button fg</td> </tr>
--- <tr> <td>`header_button_border_color`</td> <td></td> <td></td> <td></td> <td>HeaderBar > Button border-color</td> </tr>
--- <tr> <td>`error_color`</td> <td>`error_color`</td> <td>`error_bg_color`</td> <td></td> <td>destructive Button bg</td> </tr>
--- <tr> <td>`error_bg_color`</td> <td>`error_bg_color`</td> <td>`error_color`</td> <td></td> <td>destructive Button bg</td> </tr>
--- <tr> <td>`error_fg_color`</td> <td>`error_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td>destructive Button fg</td> </tr>
--- <tr> <td>`warning_color`</td> <td>`warning_color`</td> <td>`warning_bg_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`warning_bg_color`</td> <td>`warning_bg_color`</td> <td>`warning_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`warning_fg_color`</td> <td>`warning_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`success_color`</td> <td>`success_color`</td> <td>`success_bg_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`success_bg_color`</td> <td>`success_bg_color`</td> <td>`success_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`success_fg_color`</td> <td>`success_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`tooltip_bg_color`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`tooltip_fg_color`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`osd_bg_color`</td> <td>`osd_bg`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> </tr>
--- <tr> <td>`osd_fg_color`</td> <td>`osd_fg`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> </tr>
--- <tr> <td>`osd_border_color`</td> <td>`osd_borders_color`</td> <td>`osd_fg_color`</td> <td></td> <td></td> </tr>
--- <tr> <td>`wm_bg_color`</td> <td>`wm_bg`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar bg</td> </tr>
--- <tr> <td>`wm_border_focused_color`</td> <td>`wm_border_focused`</td> <td>`theme_selected_bg_color`</td> <td></td> <td>ToggleButton bg</td> </tr>
--- <tr> <td>`wm_border_unfocused_color`</td> <td>`wm_border_unfocused`</td> <td>`wm_border`</td> <td>`menubar_bg_color`</td> <!--<td>`theme_bg_color`</td>--> <td>HeaderBar bg</td> </tr>
--- <tr> <td>`wm_title_focused_color`</td> <td>`wm_title_focused`</td> <td>`wm_title`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
--- <tr> <td>`wm_title_unfocused_color`</td> <td>`wm_title_unfocused`</td> <td>`wm_unfocused_title`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
--- <tr> <td>`wm_icons_focused_color`</td> <td>`wm_icons_focused`</td> <td>`wm_title_focused`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
--- <tr> <td>`wm_icons_unfocused_color`</td> <td>`wm_icons_unfocused`</td> <td>`wm_title_unfocused`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
--- </table>
---
 function gtk.get_theme_variables()
     if gtk.cached_theme_variables then
         return gtk.cached_theme_variables

lib/beautiful/init.lua

@@ -4,7 +4,7 @@
 -- @author Damien Leone <damien.leone@gmail.com>
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Damien Leone, Julien Danjou
--- @module beautiful
+-- @themelib beautiful
 ----------------------------------------------------------------------------
 
 -- Grab environment
@@ -37,36 +37,96 @@ local descs = setmetatable({}, { __mode = 'k' })
 local fonts = setmetatable({}, { __mode = 'v' })
 local active_font
 
+
+-- luacheck: max comment line length 300
+
+--- Get GTK+3 theme variables from GtkStyleContext
+-- @treturn table Key-value table with the following structure:
+-- <table class='widget_list' border=1>
+-- <tr style='font-weight: bold;'> <th align='center'>Result key</th> <th align='center'>StyleContext key</th> <th align='center'>StyleContext fallback #1</th> <th align='center'>StyleContext fallback #2</th> <th align='center'>GTK Widget fallback</th> </tr>
+-- <tr> <td>`font_size`</td> <td></td> <td></td> <td></td> <td>Label font-size</td> </tr>
+-- <tr> <td>`font_family`</td> <td></td> <td></td> <td></td> <td>Label font-family</td> </tr>
+-- <tr> <td>`bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> <td>Window bg</td> </tr>
+-- <tr> <td>`fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> <td>Window fg</td> </tr>
+-- <tr> <td>`base_color`</td> <td>`theme_base_color`</td> <td></td> <td></td> <td>Entry bg</td> </tr>
+-- <tr> <td>`text_color`</td> <td>`theme_text_color`</td> <td></td> <td></td> <td>Entry fg</td> </tr>
+-- <tr> <td>`button_bg_color`</td> <td>`theme_button_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>Button bg</td> </tr>
+-- <tr> <td>`button_fg_color`</td> <td>`theme_button_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>Button fg</td> </tr>
+-- <tr> <td>`button_border_color`</td> <td></td> <td></td> <td></td> <td>Button border-color</td> </tr>
+-- <tr> <td>`button_border_radius`</td> <td></td> <td></td> <td></td> <td>Button border-radius</td> </tr>
+-- <tr> <td>`button_border_width`</td> <td></td> <td></td> <td></td> <td>Button border-top-width</td> </tr>
+-- <tr> <td>`selected_bg_color`</td> <td>`theme_selected_bg_color`</td> <td></td> <td></td> <td>ToggleButton bg</td> </tr>
+-- <tr> <td>`selected_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> <td>ToggleButton fg</td> </tr>
+-- <tr> <td>`menubar_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>HeaderBar bg</td> </tr>
+-- <tr> <td>`menubar_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>HeaderBar fg</td> </tr>
+-- <tr> <td>`header_button_bg_color`</td> <td>`header_button_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar > Button bg</td> </tr>
+-- <tr> <td>`header_button_fg_color`</td> <td>`header_button_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td>HeaderBar > Button fg</td> </tr>
+-- <tr> <td>`header_button_border_color`</td> <td></td> <td></td> <td></td> <td>HeaderBar > Button border-color</td> </tr>
+-- <tr> <td>`error_color`</td> <td>`error_color`</td> <td>`error_bg_color`</td> <td></td> <td>destructive Button bg</td> </tr>
+-- <tr> <td>`error_bg_color`</td> <td>`error_bg_color`</td> <td>`error_color`</td> <td></td> <td>destructive Button bg</td> </tr>
+-- <tr> <td>`error_fg_color`</td> <td>`error_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td>destructive Button fg</td> </tr>
+-- <tr> <td>`warning_color`</td> <td>`warning_color`</td> <td>`warning_bg_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`warning_bg_color`</td> <td>`warning_bg_color`</td> <td>`warning_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`warning_fg_color`</td> <td>`warning_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`success_color`</td> <td>`success_color`</td> <td>`success_bg_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`success_bg_color`</td> <td>`success_bg_color`</td> <td>`success_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`success_fg_color`</td> <td>`success_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`tooltip_bg_color`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`tooltip_fg_color`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`osd_bg_color`</td> <td>`osd_bg`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> </tr>
+-- <tr> <td>`osd_fg_color`</td> <td>`osd_fg`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> </tr>
+-- <tr> <td>`osd_border_color`</td> <td>`osd_borders_color`</td> <td>`osd_fg_color`</td> <td></td> <td></td> </tr>
+-- <tr> <td>`wm_bg_color`</td> <td>`wm_bg`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar bg</td> </tr>
+-- <tr> <td>`wm_border_focused_color`</td> <td>`wm_border_focused`</td> <td>`theme_selected_bg_color`</td> <td></td> <td>ToggleButton bg</td> </tr>
+-- <tr> <td>`wm_border_unfocused_color`</td> <td>`wm_border_unfocused`</td> <td>`wm_border`</td> <td>`menubar_bg_color`</td> <!--<td>`theme_bg_color`</td>--> <td>HeaderBar bg</td> </tr>
+-- <tr> <td>`wm_title_focused_color`</td> <td>`wm_title_focused`</td> <td>`wm_title`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
+-- <tr> <td>`wm_title_unfocused_color`</td> <td>`wm_title_unfocused`</td> <td>`wm_unfocused_title`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
+-- <tr> <td>`wm_icons_focused_color`</td> <td>`wm_icons_focused`</td> <td>`wm_title_focused`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
+-- <tr> <td>`wm_icons_unfocused_color`</td> <td>`wm_icons_unfocused`</td> <td>`wm_title_unfocused`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
+-- </table>
+--
+-- @staticfct beautiful.gtk.get_theme_variables
+
 --- The default font.
 -- @beautiful beautiful.font
+-- @param string
 
 -- The default background color.
 -- @beautiful beautiful.bg_normal
+-- @param color
 
 -- The default focused element background color.
 -- @beautiful beautiful.bg_focus
+-- @param color
 
 -- The default urgent element background color.
 -- @beautiful beautiful.bg_urgent
+-- @param color
 
 -- The default minimized element background color.
 -- @beautiful beautiful.bg_minimize
+-- @param color
 
 -- The system tray background 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.
 -- @beautiful beautiful.fg_focus
+-- @param color
 
 -- The default urgent element foreground (text) color.
 -- @beautiful beautiful.fg_urgent
+-- @param color
 
 -- The default minimized element foreground (text) color.
 -- @beautiful beautiful.fg_minimize
+-- @param color
 
 --- The gap between clients.
 -- @beautiful beautiful.useless_gap
@@ -74,31 +134,39 @@ local active_font
 
 --- The client border width.
 -- @beautiful beautiful.border_width
+-- @param number
 
 --- The default clients border color.
 -- Note that only solid colors are supported.
 -- @beautiful beautiful.border_normal
+-- @param color
 
 --- The focused client border color.
 -- Note that only solid colors are supported.
 -- @beautiful beautiful.border_focus
+-- @param color
 
 --- The marked clients border color.
 -- Note that only solid colors are supported.
 -- @beautiful beautiful.border_marked
+-- @param color
 
 --- The wallpaper path.
 -- @beautiful beautiful.wallpaper
+-- @tparam string|gears.surface wallpaper
 
 -- 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
 
 --- The Awesome icon path.
 -- @beautiful beautiful.awesome_icon
+-- @tparam string|gears.surface icon
 
 --- The current theme path (if any)
 -- @tfield string beautiful.theme_path
+-- @param string
 
 --- Load a font from a string or a font description.
 --
@@ -155,6 +223,7 @@ end
 -- See https://developer.gnome.org/pango/stable/pango-Fonts.html#PangoFontDescription.
 -- @tparam string|lgi.Pango.FontDescription name The name of the font.
 -- @treturn lgi.Pango.FontDescription
+-- @staticfct beautiful.get_font
 function beautiful.get_font(name)
     return load_font(name).description
 end
@@ -165,6 +234,7 @@ end
 -- @tparam string|Pango.FontDescription name The base font.
 -- @tparam string merge Attributes that should be merged, e.g. "bold".
 -- @treturn lgi.Pango.FontDescription
+-- @staticfct beautiful.get_merged_font
 function beautiful.get_merged_font(name, merge)
     local font = beautiful.get_font(name)
     merge = Pango.FontDescription.from_string(merge)
@@ -175,7 +245,8 @@ end
 
 --- Get the height of a font.
 --
--- @param name Name of the font
+-- @param name Name of the font.
+-- @staticfct beautiful.get_font_height
 function beautiful.get_font_height(name)
     return load_font(name).height
 end
@@ -208,6 +279,7 @@ end
 --   the theme file (which should return a table) or directly a table
 --   containing all the theme values.
 -- @treturn true|nil True if successful, nil in case of error.
+-- @staticfct beautiful.init
 function beautiful.init(config)
     if config then
         local state, t_theme = nil, nil
@@ -258,6 +330,7 @@ end
 --- Get the current theme.
 --
 -- @treturn table The current theme table.
+-- @staticfct beautiful.get
 function beautiful.get()
     return theme
 end

lib/beautiful/theme_assets.lua

@@ -3,7 +3,7 @@
 --
 -- @author Yauhen Kirylau <yawghen@gmail.com>
 -- @copyright 2015 Yauhen Kirylau
--- @submodule beautiful
+-- @module beautiful
 ----------------------------------------------------------------------------
 
 local cairo = require("lgi").cairo
@@ -19,6 +19,7 @@ local theme_assets = {}
 -- @tparam number size Size.
 -- @tparam color fg Background color.
 -- @return Image with the square.
+-- @staticfct beautiful.theme_assets.taglist_squares_sel
 function theme_assets.taglist_squares_sel(size, fg)
     local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
     local cr = cairo.Context(img)
@@ -31,6 +32,7 @@ end
 -- @tparam number size Size.
 -- @tparam color fg Background color.
 -- @return Image with the square.
+-- @staticfct beautiful.theme_assets.taglist_squares_unsel
 function theme_assets.taglist_squares_unsel(size, fg)
     local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
     local cr = cairo.Context(img)
@@ -84,6 +86,7 @@ end
 -- @tparam color bg Background color.
 -- @tparam color fg Main foreground color.
 -- @tparam color alt_fg Accent foreground color.
+-- @staticfct beautiful.theme_assets.gen_awesome_name
 function theme_assets.gen_awesome_name(cr, height, bg, fg, alt_fg)
     local ls = height/10 -- letter_size
     local letter_line = ls/18
@@ -152,6 +155,7 @@ end
 -- @tparam number height Height.
 -- @tparam color bg Background color.
 -- @tparam color fg Foreground color.
+-- @staticfct beautiful.theme_assets.gen_logo
 function theme_assets.gen_logo(cr, width, height, bg, fg)
     local ls = math.min(width, height)
 
@@ -174,6 +178,7 @@ end
 -- @tparam color bg Background color.
 -- @tparam color fg Background color.
 -- @return Image with the logo.
+-- @staticfct beautiful.theme_assets.awesome_icon
 function theme_assets.awesome_icon(size, bg, fg)
     local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
     local cr = cairo.Context(img)
@@ -187,6 +192,7 @@ end
 -- @tparam color alt_fg Accent foreground color.
 -- @tparam screen s Screen (to get wallpaper size).
 -- @return Wallpaper image.
+-- @staticfct beautiful.theme_assets.wallpaper
 function theme_assets.wallpaper(bg, fg, alt_fg, s)
     s = s or screen.primary
     local height = s.geometry.height
@@ -215,6 +221,7 @@ end
 -- @tparam string postfix `nil`, `"hover"` or `"press"`.
 -- @tparam string toggle_state `nil`, `"active"` or `"inactive"`.
 -- @treturn table Beautiful theme table with the images recolored.
+-- @staticfct beautiful.theme_assets.recolor_titlebar
 function theme_assets.recolor_titlebar(theme, color, state, postfix, toggle_state)
     if postfix then postfix='_'..postfix end
     if toggle_state then toggle_state='_'..toggle_state end
@@ -266,6 +273,7 @@ end
 -- @tparam table theme Beautiful theme table
 -- @tparam color color Icons' color.
 -- @treturn table Beautiful theme table with the images recolored.
+-- @staticfct beautiful.theme_assets.recolor_layout
 function theme_assets.recolor_layout(theme, color)
     for _, layout_name in ipairs({
         'layout_fairh',

lib/beautiful/xresources.lua

@@ -3,7 +3,7 @@
 --
 -- @author Yauhen Kirylau <yawghen@gmail.com>
 -- @copyright 2015 Yauhen Kirylau
--- @submodule beautiful
+-- @module beautiful
 ----------------------------------------------------------------------------
 
 -- Grab environment
@@ -45,7 +45,8 @@ local fallback = {
 }
 
 --- Get current base colorscheme from xrdb.
--- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15'
+-- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15'.
+-- @staticfct beautiful.xresources.get_current_theme
 function xresources.get_current_theme()
     local keys = { 'background', 'foreground' }
     for i=0,15 do table.insert(keys, "color"..i) end
@@ -77,7 +78,7 @@ end
 -- This function is deprecated. Use `s.dpi` and avoid getting the DPI without
 -- a screen.
 --
--- @deprecated xresources.get_dpi
+-- @deprecated beautiful.xresources.get_dpi
 -- @tparam[opt] integer|screen s The screen.
 -- @treturn number DPI value.
 
@@ -118,6 +119,7 @@ end
 --- Set DPI for a given screen (defaults to global).
 -- @tparam number dpi DPI value.
 -- @tparam[opt] integer s Screen.
+-- @staticfct beautiful.xresources.set_dpi
 function xresources.set_dpi(dpi, s)
     s = get_screen(s)
     if not s then
@@ -132,6 +134,7 @@ end
 -- @tparam number size Size
 -- @tparam[opt] integer|screen s The screen.
 -- @treturn integer Resulting size (rounded to integer).
+-- @staticfct beautiful.xresources.apply_dpi
 function xresources.apply_dpi(size, s)
     return round(size / 96 * xresources.get_dpi(s))
 end

lib/gears/cache.lua

@@ -37,6 +37,7 @@ end
 -- garbage-collected at any time, but might be useful to keep.
 -- @param creation_cb Callback that is used for creating missing cache entries.
 -- @return A new cache object.
+-- @constructorfct gears.cache
 function cache.new(creation_cb)
     return setmetatable({
         _cache = setmetatable({}, { __mode = "v" }),

lib/gears/color.lua

@@ -32,14 +32,10 @@
 -- calling :set_matrix() on it, because this function uses a cache and your
 -- changes could thus have unintended side effects. Use @{create_pattern_uncached}
 -- if you need to modify the returned pattern.
--- @see create_pattern_uncached, create_solid_pattern, create_png_pattern,
---   create_linear_pattern, create_radial_pattern
--- @tparam string col The string describing the pattern.
--- @return a cairo pattern object
 --
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @module gears.color
+-- @themelib gears.color
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -65,6 +61,7 @@ local pattern_cache
 -- @param col The color to parse
 -- @treturn table 4 values representing color in RGBA format (each of them in
 -- [0, 1] range) or nil if input is incorrect.
+-- @staticfct gears.color.parse_color
 -- @usage -- This will return 0, 1, 0, 1
 -- gears.color.parse_color("#00ff00ff")
 function color.parse_color(col)
@@ -123,6 +120,7 @@ end
 --
 -- @param col The color for the pattern
 -- @return A cairo pattern object
+-- @staticfct gears.color.create_solid_pattern
 function color.create_solid_pattern(col)
     if col == nil then
         col = "#000000"
@@ -136,6 +134,7 @@ end
 --
 -- @param file The filename of the file
 -- @return a cairo pattern object
+-- @staticfct gears.color.create_png_pattern
 function color.create_png_pattern(file)
     if type(file) == "table" then
         file = file.file
@@ -192,6 +191,7 @@ end
 -- For the explanation of `<stops>`, see `color.create_pattern`.
 -- @tparam string|table arg The argument describing the pattern.
 -- @return a cairo pattern object
+-- @staticfct gears.color.create_linear_pattern
 function color.create_linear_pattern(arg)
     local pat
 
@@ -217,6 +217,7 @@ end
 -- For the explanation of `<stops>`, see `color.create_pattern`.
 -- @tparam string|table arg The argument describing the pattern
 -- @return a cairo pattern object
+-- @staticfct gears.color.create_radial_pattern
 function color.create_radial_pattern(arg)
     local pat
 
@@ -249,6 +250,7 @@ color.types = {
 -- @see create_pattern
 -- @param col The string describing the pattern.
 -- @return a cairo pattern object
+-- @staticfct gears.color.create_pattern_uncached
 function color.create_pattern_uncached(col)
     -- If it already is a cairo pattern, just leave it as that
     if cairo.Pattern:is_type_of(col) then
@@ -273,6 +275,7 @@ end
 
 --- Create a pattern from a given string, same as @{gears.color}.
 -- @see gears.color
+-- @staticfct gears.color.create_pattern
 function color.create_pattern(col)
     if cairo.Pattern:is_type_of(col) then
         return col
@@ -285,6 +288,7 @@ end
 -- operator OVER) doesn't influence the visual result.
 -- @param col An argument that `create_pattern` accepts.
 -- @return The pattern if it is surely opaque, else nil
+-- @staticfct gears.color.create_opaque_pattern
 function color.create_opaque_pattern(col)
     local pattern = color.create_pattern(col)
     local kind = pattern:get_type()
@@ -335,6 +339,7 @@ end
 -- @param image Image or path to it.
 -- @param new_color New color.
 -- @return Recolored image.
+-- @staticfct gears.color.recolor_image
 function color.recolor_image(image, new_color)
     if type(image) == 'string' then
         image = surface.duplicate_surface(image)
@@ -349,6 +354,7 @@ end
 -- @param check_color The color to check.
 -- @tparam string fallback The color to return if the first is invalid. (default: black)
 -- @treturn string color if it is valid, else fallback.
+-- @staticfct gears.color.ensure_pango_color
 function color.ensure_pango_color(check_color, fallback)
     check_color = tostring(check_color)
     -- Pango markup supports alpha, PangoColor does not. Thus, check for this.

lib/gears/debug.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @module gears.debug
+-- @utillib gears.debug
 ---------------------------------------------------------------------------
 
 local tostring = tostring
@@ -49,6 +49,7 @@ end
 -- @param tag The name of the value.
 -- @tparam[opt] int depth Depth of recursion.
 -- @return string A string that contains the expanded value of data.
+-- @staticfct gears.debug.dump_return
 function debug.dump_return(data, tag, depth)
     return dump_raw(data, nil, tag, depth)
 end
@@ -57,23 +58,27 @@ end
 -- @param data Table to print.
 -- @param tag The name of the table.
 -- @tparam[opt] int depth Depth of recursion.
+-- @staticfct gears.debug.dump
 function debug.dump(data, tag, depth)
     print(debug.dump_return(data, tag, depth))
 end
 
 --- Print an warning message
--- @tparam string message The warning message to print
+-- @tparam string message The warning message to print.
+-- @staticfct gears.debug.print_warning
 function debug.print_warning(message)
     io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n")
 end
 
 --- Print an error message
--- @tparam string message The error message to print
+-- @tparam string message The error message to print.
+-- @staticfct gears.debug.print_error
 function debug.print_error(message)
     io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n")
 end
 
 local displayed_deprecations = {}
+
 --- Display a deprecation notice, but only once per traceback.
 --
 -- This function also emits the `debug::deprecate` signal on the `awesome`
@@ -84,6 +89,7 @@ local displayed_deprecations = {}
 -- @tparam boolean args.raw Print the message as-is without the automatic context
 -- @tparam integer args.deprecated_in Print the message only when Awesome's
 --   version is equal to or greater than deprecated_in.
+-- @staticfct gears.debug.deprecate
 function debug.deprecate(see, args)
     args = args or {}
     if args.deprecated_in then
@@ -124,6 +130,7 @@ end
 -- @tparam string old_name The old class name
 -- @tparam string new_name The new class name
 -- @treturn table A proxy class.
+-- @staticfct gears.debug.deprecate_class
 function debug.deprecate_class(fallback, old_name, new_name)
     local message = old_name.." has been renamed to "..new_name
 

lib/gears/filesystem.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 --- Filesystem module for gears
 --
--- @module gears.filesystem
+-- @utillib gears.filesystem
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -26,6 +26,7 @@ end
 --- Create a directory, including all missing parent directories.
 -- @tparam string dir The directory.
 -- @return (true, nil) on success, (false, err) on failure
+-- @staticfct gears.filesystem.make_directories
 function filesystem.make_directories(dir)
     return make_directory(Gio.File.new_for_path(dir))
 end
@@ -37,7 +38,8 @@ end
 
 --- Create all parent directories for a given path.
 -- @tparam string path The path whose parents should be created.
--- @return (true, nil) on success, (false, err) on failure
+-- @return (true, nil) on success, (false, err) on failure.
+-- @staticfct gears.filesystem.make_parent_directories
 function filesystem.make_parent_directories(path)
     return make_directory(Gio.File.new_for_path(path):get_parent())
 end
@@ -45,6 +47,7 @@ end
 --- Check if a file exists, is readable and not a directory.
 -- @tparam string filename The file path.
 -- @treturn boolean True if file exists and is readable.
+-- @staticfct gears.filesystem.file_readable
 function filesystem.file_readable(filename)
     local gfile = Gio.File.new_for_path(filename)
     local gfileinfo = gfile:query_info("standard::type,access::can-read",
@@ -56,6 +59,7 @@ end
 --- Check if a file exists, is executable and not a directory.
 -- @tparam string filename The file path.
 -- @treturn boolean True if file exists and is executable.
+-- @staticfct gears.filesystem.file_executable
 function filesystem.file_executable(filename)
     local gfile = Gio.File.new_for_path(filename)
     local gfileinfo = gfile:query_info("standard::type,access::can-execute",
@@ -67,6 +71,7 @@ end
 --- Check if a path exists, is readable and a directory.
 -- @tparam string path The directory path.
 -- @treturn boolean True if path exists and is readable.
+-- @staticfct gears.filesystem.dir_readable
 function filesystem.dir_readable(path)
     local gfile = Gio.File.new_for_path(path)
     local gfileinfo = gfile:query_info("standard::type,access::can-read",
@@ -78,30 +83,35 @@ end
 --- Check if a path is a directory.
 -- @tparam string path The directory path
 -- @treturn boolean True if path exists and is a directory.
+-- @staticfct gears.filesystem.is_dir
 function filesystem.is_dir(path)
     return Gio.File.new_for_path(path):query_file_type({}) == "DIRECTORY"
 end
 
 --- Get the config home according to the XDG basedir specification.
 -- @return the config home (XDG_CONFIG_HOME) with a slash at the end.
+-- @staticfct gears.filesystem.get_xdg_config_home
 function filesystem.get_xdg_config_home()
     return (os.getenv("XDG_CONFIG_HOME") or os.getenv("HOME") .. "/.config") .. "/"
 end
 
 --- Get the cache home according to the XDG basedir specification.
 -- @return the cache home (XDG_CACHE_HOME) with a slash at the end.
+-- @staticfct gears.filesystem.get_xdg_cache_home
 function filesystem.get_xdg_cache_home()
     return (os.getenv("XDG_CACHE_HOME") or os.getenv("HOME") .. "/.cache") .. "/"
 end
 
 --- Get the data home according to the XDG basedir specification.
 -- @treturn string the data home (XDG_DATA_HOME) with a slash at the end.
+-- @staticfct gears.filesystem.get_xdg_data_home
 function filesystem.get_xdg_data_home()
     return (os.getenv("XDG_DATA_HOME") or os.getenv("HOME") .. "/.local/share") .. "/"
 end
 
 --- Get the data dirs according to the XDG basedir specification.
 -- @treturn table the data dirs (XDG_DATA_DIRS) with a slash at the end of each entry.
+-- @staticfct gears.filesystem.get_xdg_data_dirs
 function filesystem.get_xdg_data_dirs()
     local xdg_data_dirs = os.getenv("XDG_DATA_DIRS") or "/usr/share:/usr/local/share"
     return gtable.map(
@@ -112,12 +122,14 @@ end
 --- Get the path to the user's config dir.
 -- This is the directory containing the configuration file ("rc.lua").
 -- @return A string with the requested path with a slash at the end.
+-- @staticfct gears.filesystem.get_configuration_dir
 function filesystem.get_configuration_dir()
     return awesome.conffile:match(".*/") or "./"
 end
 
 --- Get the path to a directory that should be used for caching data.
 -- @return A string with the requested path with a slash at the end.
+-- @staticfct gears.filesystem.get_cache_dir
 function filesystem.get_cache_dir()
     local result = filesystem.get_xdg_cache_home() .. "awesome/"
     filesystem.make_directories(result)
@@ -126,12 +138,14 @@ end
 
 --- Get the path to the directory where themes are installed.
 -- @return A string with the requested path with a slash at the end.
+-- @staticfct gears.filesystem.get_themes_dir
 function filesystem.get_themes_dir()
     return (os.getenv('AWESOME_THEMES_PATH') or awesome.themes_path) .. "/"
 end
 
 --- Get the path to the directory where our icons are installed.
 -- @return A string with the requested path with a slash at the end.
+-- @staticfct gears.filesystem.get_awesome_icon_dir
 function filesystem.get_awesome_icon_dir()
     return (os.getenv('AWESOME_ICON_PATH') or awesome.icon_path) .. "/"
 end
@@ -141,6 +155,7 @@ end
 -- default paths.
 -- @param d The directory to get (either "config" or "cache").
 -- @return A string containing the requested path.
+-- @staticfct gears.filesystem.get_dir
 function filesystem.get_dir(d)
     if d == "config" then
         -- No idea why this is what is returned, I recommend everyone to use
@@ -159,6 +174,7 @@ end
 --   If ommited, all files are considered.
 -- @treturn string|nil A randomly selected filename from the specified path (with
 --   a specified extension if required) or nil if no suitable file is found.
+-- @staticfct gears.filesystem.get_random_file_from_dir
 function filesystem.get_random_file_from_dir(path, exts)
     local files, valid_exts = {}, {}
 

lib/gears/geometry.lua

@@ -7,7 +7,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
--- @module gears.geometry
+-- @utillib gears.geometry
 ---------------------------------------------------------------------------
 local math = math
 
@@ -21,7 +21,8 @@ local gears = {geometry = {rectangle = {} } }
 -- @tparam number geom.height The rectangle height
 -- @tparam number x X coordinate of point
 -- @tparam number y Y coordinate of point
--- @treturn number The squared distance of the rectangle to the provided point
+-- @treturn number The squared distance of the rectangle to the provided point.
+-- @staticfct gears.geometry.rectangle.get_square_distance
 function gears.geometry.rectangle.get_square_distance(geom, x, y)
     local dist_x, dist_y = 0, 0
     if x < geom.x then
@@ -42,6 +43,7 @@ end
 -- @tparam number x The x coordinate
 -- @tparam number y The y coordinate
 -- @return The key from the closest geometry.
+-- @staticfct gears.geometry.rectangle.get_closest_by_coord
 function gears.geometry.rectangle.get_closest_by_coord(list, x, y)
     local dist = math.huge
     local ret = nil
@@ -66,6 +68,7 @@ end
 -- @tparam number y The y coordinate
 -- @return The key from the closest geometry. In case no result is found, *nil*
 --  is returned.
+-- @staticfct gears.geometry.rectangle.get_by_coord
 function gears.geometry.rectangle.get_by_coord(list, x, y)
     for k, geometry in pairs(list) do
         if x >= geometry.x and x < geometry.x + geometry.width
@@ -126,6 +129,7 @@ end
 -- @tparam table recttbl A table of rectangle specifications.
 -- @tparam table cur The current rectangle.
 -- @return The index for the rectangle in recttbl closer to cur in the given direction. nil if none found.
+-- @staticfct gears.geometry.rectangle.get_in_direction
 function gears.geometry.rectangle.get_in_direction(dir, recttbl, cur)
     local dist, dist_min
     local target = nil
@@ -151,6 +155,7 @@ end
 -- @param a The area.
 -- @param b The other area.
 -- @return True if they intersect, false otherwise.
+-- @staticfct gears.geometry.rectangle.area_intersect_area
 function gears.geometry.rectangle.area_intersect_area(a, b)
     return (b.x < a.x + a.width
             and b.x + b.width > a.x
@@ -170,6 +175,7 @@ end
 -- @tparam number b.width The rectangle width
 -- @tparam number b.height The rectangle height
 -- @treturn table The intersect area.
+-- @staticfct gears.geometry.rectangle.get_intersection
 function gears.geometry.rectangle.get_intersection(a, b)
     local g = {}
     g.x = math.max(a.x, b.x)
@@ -191,6 +197,7 @@ end
 -- @tparam number elem.width The rectangle width
 -- @tparam number elem.height The rectangle height
 -- @return The new area list.
+-- @staticfct gears.geometry.rectangle.area_remove
 function gears.geometry.rectangle.area_remove(areas, elem)
     for i = #areas, 1, -1 do
         -- Check if the 'elem' intersect

lib/gears/math.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 --- Math module for gears
 --
--- @module gears.math
+-- @utillib gears.math
 ---------------------------------------------------------------------------
 
 local rtable = table
@@ -37,10 +37,9 @@ end
 -- For example, if we consider a set with value { 10, 15, 34 },
 -- it will return a table containing 2^n set:
 -- { }, { 10 }, { 15 }, { 34 }, { 10, 15 }, { 10, 34 }, etc.
--- @class function
--- @name subsets
 -- @param set A set.
 -- @return A table with all subset.
+-- @staticfct gears.math.subsets
 function gmath.subsets(set)
     local mask = {}
     local ret = {}
@@ -56,11 +55,10 @@ function gmath.subsets(set)
 end
 
 --- Make i cycle.
--- @class function
--- @name cycle
 -- @param t A length. Must be greater than zero.
 -- @param i An absolute index to fit into #t.
 -- @return An integer in (1, t) or nil if t is less than or equal to zero.
+-- @staticfct gears.math.cycle
 function gmath.cycle(t, i)
     if t < 1 then return end
     i = i % t
@@ -71,10 +69,9 @@ function gmath.cycle(t, i)
 end
 
 --- Round a number to an integer.
--- @class function
--- @name round
 -- @tparam number x
 -- @treturn integer
+-- @staticfct gears.math.round
 function gmath.round(x)
     return math.floor(x + 0.5)
 end

lib/gears/matrix.lua

@@ -20,6 +20,7 @@ local matrix_mt = {}
 -- @tparam number x0 The x0 transformation part.
 -- @tparam number y0 The y0 transformation part.
 -- @return A new matrix describing the given transformation.
+-- @constructorfct create
 function matrix.create(xx, yx, xy, yy, x0, y0)
     return setmetatable({
         xx = xx, xy = xy, x0 = x0,
@@ -31,6 +32,7 @@ end
 -- @tparam number x The translation in x direction.
 -- @tparam number y The translation in y direction.
 -- @return A new matrix describing the given transformation.
+-- @constructorfct create_translate
 function matrix.create_translate(x, y)
     return matrix.create(1, 0, 0, 1, x, y)
 end
@@ -39,6 +41,7 @@ end
 -- @tparam number sx The scaling in x direction.
 -- @tparam number sy The scaling in y direction.
 -- @return A new matrix describing the given transformation.
+-- @constructorfct create_scale
 function matrix.create_scale(sx, sy)
     return matrix.create(sx, 0, 0, sy, 0, 0)
 end
@@ -46,6 +49,7 @@ end
 --- Create a new rotation matrix
 -- @tparam number angle The angle of the rotation in radians.
 -- @return A new matrix describing the given transformation.
+-- @constructorfct create_rotate
 function matrix.create_rotate(angle)
     local c, s = math.cos(angle), math.sin(angle)
     return matrix.create(c, s, -s, c, 0, 0)
@@ -56,6 +60,7 @@ end
 -- @tparam number y The vertical rotation point
 -- @tparam number angle The angle of the rotation in radians.
 -- @return A new matrix describing the given transformation.
+-- @constructorfct create_rotate_at
 function matrix.create_rotate_at(x, y, angle)
     return   matrix.create_translate( -x, -y )
            * matrix.create_rotate   ( angle  )
@@ -212,6 +217,7 @@ matrix_mt.__mul = matrix.multiply
 matrix_mt.__tostring = matrix.tostring
 
 --- A constant for the identity matrix.
+-- @param matrix
 matrix.identity = matrix.create(1, 0, 0, 1, 0, 0)
 
 return matrix

lib/gears/object.lua

@@ -6,7 +6,7 @@
 --
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @classmod gears.object
+-- @utillib gears.object
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -49,6 +49,7 @@ end
 --@DOC_text_gears_object_signal_EXAMPLE@
 -- @tparam string name The name of the signal
 -- @tparam function func The callback to call when the signal is emitted
+-- @method connect_signal
 function object:connect_signal(name, func)
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
     local sig = find_signal(self, name)
@@ -95,6 +96,7 @@ end
 -- collected and automatically disconnects the signal when that happens.
 -- @tparam string name The name of the signal
 -- @tparam function func The callback to call when the signal is emitted
+-- @method weak_connect_signal
 function object:weak_connect_signal(name, func)
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
     local sig = find_signal(self, name)
@@ -105,6 +107,7 @@ end
 --- Disonnect to a signal.
 -- @tparam string name The name of the signal
 -- @tparam function func The callback that should be disconnected
+-- @method disconnect_signal
 function object:disconnect_signal(name, func)
     local sig = find_signal(self, name)
     sig.weak[func] = nil
@@ -117,6 +120,7 @@ end
 -- @param ... Extra arguments for the callback functions. Each connected
 --   function receives the object as first argument and then any extra arguments
 --   that are given to emit_signal()
+-- @method emit_signal
 function object:emit_signal(name, ...)
     local sig = find_signal(self, name)
     for func in pairs(sig.strong) do
@@ -179,7 +183,8 @@ end
 --   when an unknown property is set.
 -- @tparam[opt=nil] table args.class
 -- @treturn table A new object
--- @function gears.object
+-- @constructorfct gears.object
+
 local function new(args)
     args = args or {}
     local ret = {}
@@ -236,6 +241,7 @@ end
 -- @tparam[opt=2] integer level Level for `debug.getinfo(level, "S")`.
 --   Typically 2 or 3.
 -- @treturn string The module name, e.g. "wibox.container.background".
+-- @staticfct gears.object.modulename
 function object.modulename(level)
     return debug.getinfo(level, "S").source:gsub(".*/lib/", ""):gsub("/", "."):gsub("%.lua", "")
 end

lib/gears/protected_call.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 -- @author Uli Schlachter
 -- @copyright 2016 Uli Schlachter
--- @module gears.protected_call
+-- @utillib gears.protected_call
 ---------------------------------------------------------------------------
 
 local gdebug = require("gears.debug")
@@ -43,6 +43,7 @@ end
 -- @tparam function func The function to call
 -- @param ... Arguments to the function
 -- @return The result of the given function, or nothing if an error occurred.
+-- @staticfct gears.protected_call
 function protected_call.call(func, ...)
     return do_pcall(func, ...)
 end

lib/gears/shape.lua

@@ -38,7 +38,7 @@
 --
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2011-2016 Emmanuel Lepage Vallee
--- @module gears.shape
+-- @themelib gears.shape
 ---------------------------------------------------------------------------
 local g_matrix = require( "gears.matrix" )
 local unpack   = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1)
@@ -55,6 +55,7 @@ local module = {}
 -- @tparam number width The rectangle width
 -- @tparam number height The rectangle height
 -- @tparam number radius the corner radius
+-- @staticfct gears.shape.rounded_rect
 function module.rounded_rect(cr, width, height, radius)
 
     radius = radius or 10
@@ -83,7 +84,8 @@ end
 --
 -- @param cr A cairo content
 -- @param width The rectangle width
--- @param height The rectangle height
+-- @param height The rectangle height.
+-- @staticfct gears.shape.rounded_bar
 function module.rounded_bar(cr, width, height)
     module.rounded_rect(cr, width, height, height / 2)
 end
@@ -100,6 +102,7 @@ end
 -- @tparam boolean br If the bottom right corner is rounded
 -- @tparam boolean bl If the bottom left corner is rounded
 -- @tparam number rad The corner radius
+-- @staticfct gears.shape.partially_rounded_rect
 function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad)
     rad = rad or 10
     if width / 2 < rad then
@@ -151,6 +154,7 @@ end
 -- @tparam[opt=5] number corner_radius The corner radius
 -- @tparam[opt=10] number arrow_size The width and height of the arrow
 -- @tparam[opt=width/2 - arrow_size/2] number arrow_position The position of the arrow
+-- @staticfct gears.shape.infobubble
 function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position)
     arrow_size     = arrow_size     or 10
     corner_radius  = math.min((height-arrow_size)/2, corner_radius or 5)
@@ -184,6 +188,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=height/2] number arrow_length The length of the arrow part
+-- @staticfct gears.shape.rectangular_tag
 function module.rectangular_tag(cr, width, height, arrow_length)
     arrow_length = arrow_length or height/2
     if arrow_length > 0 then
@@ -213,6 +218,7 @@ end
 -- @tparam[opt=head_width] number head_width The width of the head (/\) of the arrow
 -- @tparam[opt=width /2] number shaft_width The width of the shaft of the arrow
 -- @tparam[opt=height/2] number shaft_length The head_length of the shaft (the rest is the head)
+-- @staticfct gears.shape.arrow
 function module.arrow(cr, width, height, head_width, shaft_width, shaft_length)
     shaft_length = shaft_length or height / 2
     shaft_width  = shaft_width  or width  / 2
@@ -237,6 +243,7 @@ end
 -- @param cr A cairo context
 -- @tparam number width The shape width
 -- @tparam number height The shape height
+-- @staticfct gears.shape.hexagon
 function module.hexagon(cr, width, height)
     cr:move_to(height/2,0)
     cr:line_to(width-height/2,0)
@@ -256,6 +263,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=height/2] number arrow_depth The width of the arrow part of the shape
+-- @staticfct gears.shape.powerline
 function module.powerline(cr, width, height, arrow_depth)
     arrow_depth = arrow_depth or height/2
     local offset = 0
@@ -283,6 +291,7 @@ end
 -- @param cr A cairo context
 -- @tparam number width The shape width
 -- @tparam number height The shape height
+-- @staticfct gears.shape.isosceles_triangle
 function module.isosceles_triangle(cr, width, height)
     cr:move_to( width/2, 0      )
     cr:line_to( width  , height )
@@ -298,6 +307,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=width/3] number thickness The cross section thickness
+-- @staticfct gears.shape.cross
 function module.cross(cr, width, height, thickness)
     thickness = thickness or width/3
     local xpadding   = (width  - thickness) / 2
@@ -325,6 +335,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam number corner_radius
+-- @staticfct gears.shape.octogon
 function module.octogon(cr, width, height, corner_radius)
     corner_radius = corner_radius or math.min(10, math.min(width, height)/4)
     local offset = math.sqrt( (corner_radius*corner_radius) / 2 )
@@ -348,6 +359,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=math.min(width  height) / 2)] number radius The radius
+-- @staticfct gears.shape.circle
 function module.circle(cr, width, height, radius)
     radius = radius or math.min(width, height) / 2
     cr:move_to(width/2+radius, height/2)
@@ -362,6 +374,7 @@ end
 -- @param cr A cairo context
 -- @tparam number width The shape width
 -- @tparam number height The shape height
+-- @staticfct gears.shape.rectangle
 function module.rectangle(cr, width, height)
     cr:rectangle(0, 0, width, height)
 end
@@ -375,6 +388,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=width/3] number base_width The parallelogram base width
+-- @staticfct gears.shape.parallelogram
 function module.parallelogram(cr, width, height, base_width)
     base_width = base_width or width/3
     cr:move_to(width-base_width, 0      )
@@ -391,6 +405,7 @@ end
 -- @param cr A cairo context
 -- @tparam number width The shape width
 -- @tparam number height The shape height
+-- @staticfct gears.shape.losange
 function module.losange(cr, width, height)
     cr:move_to(width/2 , 0        )
     cr:line_to(width   , height/2 )
@@ -411,6 +426,7 @@ end
 -- @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=math.min(width height)/2] number radius The shape height
+-- @staticfct gears.shape.pie
 function module.pie(cr, width, height, start_angle, end_angle, radius)
     radius = radius or math.floor(math.min(width, height)/2)
     start_angle, end_angle = start_angle or 0, end_angle or math.pi/2
@@ -444,6 +460,7 @@ end
 -- @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 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
     end_angle   = end_angle   or math.pi/2
@@ -562,6 +579,7 @@ end
 -- @tparam number h The shape height
 -- @tparam number percent The progressbar percent
 -- @tparam boolean hide_left Do not draw the left side of the shape
+-- @staticfct gears.shape.radial_progress
 function module.radial_progress(cr, w, h, percent, hide_left)
     percent = percent or 1
     local total_length = (2*(w-h))+2*((h/2)*math.pi)
@@ -628,6 +646,7 @@ end
 --
 -- @param shape A shape function
 -- @return A transformation handle, also act as a shape function
+-- @staticfct gears.shape.transform
 function module.transform(shape)
 
     -- Apply the transformation matrix and apply the shape, then restore

lib/gears/sort/init.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 --- Extra sorting algorithms.
 --
--- @module gears.sort
+-- @utillib gears.sort
 ---------------------------------------------------------------------------
 
 return {

lib/gears/sort/topological.lua

@@ -18,6 +18,7 @@ end
 --- Ensure that `node` appears after all `dependencies`.
 -- @param node The node that edges are added to.
 -- @tparam table dependencies List of nodes that have to appear before `node`.
+-- @method append
 function tsort:append(node, dependencies)
     add_node(self, node)
     for _, dep in ipairs(dependencies) do
@@ -29,6 +30,7 @@ end
 --- Ensure that `node` appears before all `subordinates`.
 -- @param node The node that edges are added to.
 -- @tparam table subordinates List of nodes that have to appear after `node`.
+-- @method prepend
 function tsort:prepend(node, subordinates)
     for _, dep in ipairs(subordinates) do
         self:append(dep, { node })
@@ -63,6 +65,7 @@ end
 --- Create a copy of this topological sort.
 -- This is useful to backup it before adding elements that can potentially
 -- have circular dependencies and thus render the original useless.
+-- @method clone
 function tsort:clone()
     local new = tsort.topological()
 
@@ -75,6 +78,7 @@ end
 --- Remove a node from the topological map.
 --
 -- @param node The node
+-- @method remove
 function tsort:remove(node)
     self._edges[node] = nil
     for _, deps in pairs(self._edges) do
@@ -86,6 +90,7 @@ end
 -- @treturn[1] table A sorted list of nodes
 -- @treturn[2] nil
 -- @return[2] A node around which a loop exists
+-- @method sort
 function tsort:sort()
     local result, state = {}, {}
     for node in pairs(self._edges) do
@@ -104,7 +109,7 @@ end
 --
 --@DOC_text_gears_sort_topological_EXAMPLE@
 --
--- @function gears.sort.topological
+-- @constructorfct gears.sort.topological
 
 function tsort.topological()
     return setmetatable({

lib/gears/string.lua

@@ -1,49 +1,47 @@
 ---------------------------------------------------------------------------
 --- String module for gears
 --
--- @module gears.string
+-- @utillib gears.string
 ---------------------------------------------------------------------------
 
 local gstring = {}
 
 local xml_entity_names = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;", [">"] = "&gt;", ["&"] = "&amp;" };
+
 --- Escape a string from XML char.
 -- Useful to set raw text in textbox.
--- @class function
--- @name xml_escape
 -- @param text Text to escape.
 -- @return Escape text.
+-- @staticfct gears.string.xml_escape
 function gstring.xml_escape(text)
     return text and text:gsub("['&<>\"]", xml_entity_names) or nil
 end
 
 local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "'", ndash = "-", mdash = "-",
                            amp = "&" };
+
 --- Unescape a string from entities.
--- @class function
--- @name xml_unescape
 -- @param text Text to unescape.
 -- @return Unescaped text.
+-- @staticfct gears.string.xml_unescape
 function gstring.xml_unescape(text)
     return text and text:gsub("&(%a+);", xml_entity_chars) or nil
 end
 
 --- Count number of lines in a string
--- @class function
--- @name linecount
 -- @tparam string text Input string.
 -- @treturn int Number of lines.
+-- @staticfct gears.string.linecount
 function gstring.linecount(text)
     return select(2, text:gsub('\n', '\n')) + 1
 end
 
---- Split a string into multiple lines
+--- Split a string into multiple lines.
--- @class function
--- @name linewrap
 -- @param text String to wrap.
 -- @param width Maximum length of each line. Default: 72.
 -- @param indent Number of spaces added before each wrapped line. Default: 0.
 -- @return The string with lines wrapped to width.
+-- @staticfct gears.string.linewrap
 function gstring.linewrap(text, width, indent)
     text = text or ""
     width = width or 72
@@ -62,8 +60,7 @@ end
 --- Escape all special pattern-matching characters so that lua interprets them
 -- literally instead of as a character class.
 -- Source: http://stackoverflow.com/a/20778724/15690
--- @class function
+-- @staticfct gears.string.quote_pattern
--- @name quote_pattern
 function gstring.quote_pattern(s)
     -- All special characters escaped in a string: %%, %^, %$, ...
     local patternchars = '['..("%^$().[]*+-?"):gsub("(.)", "%%%1")..']'
@@ -72,8 +69,7 @@ end
 
 --- Generate a pattern matching expression that ignores case.
 -- @param s Original pattern matching expression.
--- @class function
+-- @staticfct gears.string.query_to_pattern
--- @name query_to_pattern
 function gstring.query_to_pattern(q)
     local s = gstring.quote_pattern(q)
     -- Poor man's case-insensitive character matching.
@@ -87,11 +83,10 @@ end
 
 --- Split separates a string containing a delimiter into the list of
 -- substrings between that delimiter.
--- @class function
--- @name split
 -- @tparam string str String to be splitted
 -- @tparam string delimiter Character where the string will be splitted
 -- @treturn table list of the substrings
+-- @staticfct gears.string.split
 function gstring.split(str, delimiter)
     local pattern = "(.-)" .. delimiter .. "()"
     local result = {}
@@ -106,20 +101,18 @@ function gstring.split(str, delimiter)
     return result
 end
 
---- Check if a string starts with another string
+--- Check if a string starts with another string.
--- @class function
--- @name startswith
 -- @tparam string str String to search
--- @tparam string sub String to check for
+-- @tparam string sub String to check for.
+-- @staticfct gears.string.startswith
 function gstring.startswith(str, sub)
     return string.sub(str, 1, string.len(sub)) == sub
 end
 
---- Check if a string ends with another string
+--- Check if a string ends with another string.
--- @class function
--- @name endswith
 -- @tparam string str String to search
--- @tparam string sub String to check for
+-- @tparam string sub String to check for.
+-- @staticfct gears.string.endswith
 function gstring.endswith(str, sub)
     return sub == "" or string.sub(str,-string.len(sub)) == sub
 end

lib/gears/surface.lua

@@ -35,7 +35,8 @@ end
 -- @param default The default value to return on error; when nil, then a surface
 -- in an error state is returned.
 -- @return The loaded surface, or the replacement default
--- @return An error message, or nil on success
+-- @return An error message, or nil on success.
+-- @staticfct load_uncached_silently
 function surface.load_uncached_silently(_surface, default)
     -- On nil, return some sane default
     if not _surface then
@@ -71,7 +72,8 @@ end
 -- in an error state is returned.
 -- @return The loaded surface, or the replacement default, or nil if called with
 -- nil.
--- @return An error message, or nil on success
+-- @return An error message, or nil on success.
+-- @staticfct load_silently
 function surface.load_silently(_surface, default)
     if type(_surface) == "string" then
         local cache = surface_cache[_surface]
@@ -106,6 +108,7 @@ end
 -- via `gears.debug.print_error`.
 -- @param _surface The surface to load or nil
 -- @return The loaded surface, or nil
+-- @staticfct load_uncached
 function surface.load_uncached(_surface)
     return do_load_and_handle_errors(_surface, surface.load_uncached_silently)
 end
@@ -114,7 +117,8 @@ end
 -- This is usually needed for loading images by file name. Errors are handled
 -- via `gears.debug.print_error`.
 -- @param _surface The surface to load or nil
--- @return The loaded surface, or nil
+-- @return The loaded surface, or nil.
+-- @staticfct gears.surface
 function surface.load(_surface)
     return do_load_and_handle_errors(_surface, surface.load_silently)
 end
@@ -125,7 +129,8 @@ end
 
 --- Get the size of a cairo surface
 -- @param surf The surface you are interested in
--- @return The surface's width and height
+-- @return The surface's width and height.
+-- @staticfct get_size
 function surface.get_size(surf)
     local cr = cairo.Context(surf)
     local x, y, w, h = cr:clip_extents()
@@ -142,6 +147,7 @@ end
 -- surface.
 -- @param s Source surface.
 -- @return The surface's duplicate.
+-- @staticfct duplicate_surface
 function surface.duplicate_surface(s)
     s = surface.load(s)
 
@@ -166,6 +172,7 @@ end
 -- @param[opt=white] shape_color The shape color or pattern
 -- @param[opt=transparent] bg_color The surface background color
 -- @treturn cairo.surface the new surface
+-- @staticfct load_from_shape
 function surface.load_from_shape(width, height, shape, shape_color, bg_color, ...)
     color = color or require("gears.color")
 
@@ -191,7 +198,8 @@ end
 -- @param draw A wibox or a client
 -- @param shape or gears.shape function or a custom function with a context,
 --   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()
 
@@ -224,13 +232,15 @@ end
 --- Create an SVG file with this widget content.
 -- This is dynamic, so the SVG will be updated along with the widget content.
 -- because of this, the painting may happen hover multiple event loop cycles.
--- @deprecated wibox.widget.draw_to_svg_file
+-- @deprecated draw_to_svg_file
 -- @tparam widget widget A widget
 -- @tparam string path The output file path
 -- @tparam number width The surface width
 -- @tparam number height The surface height
 -- @return The cairo surface
--- @return The hierarchy
+-- @return The hierarchy.
+-- @see wibox.widget.draw_to_svg_file
+-- @see wibox.widget.draw_to_image_surface
 function surface.widget_to_svg(widget, path, width, height)
     gdebug.deprecate("Use wibox.widget.draw_to_svg_file instead of "..
         "gears.surface.render_to_svg", {deprecated_in=5})
@@ -243,13 +253,15 @@ end
 --- Create a cairo surface with this widget content.
 -- This is dynamic, so the SVG will be updated along with the widget content.
 -- because of this, the painting may happen hover multiple event loop cycles.
--- @deprecated wibox.widget.draw_to_image_surface
+-- @deprecated draw_to_image_surface
 -- @tparam widget widget A widget
 -- @tparam number width The surface width
 -- @tparam number height The surface height
 -- @param[opt=cairo.Format.ARGB32] format The surface format
 -- @return The cairo surface
--- @return The hierarchy
+-- @return The hierarchy.
+-- @see wibox.widget.draw_to_svg_file
+-- @see wibox.widget.draw_to_image_surface
 function surface.widget_to_surface(widget, width, height, format)
     gdebug.deprecate("Use wibox.widget.draw_to_image_surface instead of "..
         "gears.surface.render_to_surface", {deprecated_in=5})

lib/gears/table.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 --- Table module for gears
 --
--- @module gears.table
+-- @utillib gears.table
 ---------------------------------------------------------------------------
 
 
@@ -12,10 +12,9 @@ local gtable = {}
 
 --- Join all tables given as arguments.
 -- This will iterate over all tables and insert their entries into a new table.
--- @class function
--- @name join
 -- @tparam table ... Tables to join.
 -- @treturn table A new table containing all entries from the arguments.
+-- @staticfct gears.table.join
 function gtable.join(...)
     local ret = {}
     for i = 1, select("#", ...) do
@@ -36,12 +35,12 @@ end
 --- Override elements in the first table by the one in the second.
 --
 -- Note that this method doesn't copy entries found in `__index`.
--- @class function
+--
--- @name crush
 -- @tparam table t the table to be overriden
 -- @tparam table set the table used to override members of `t`
 -- @tparam[opt=false] bool raw Use rawset (avoid the metatable)
 -- @treturn table t (for convenience)
+-- @staticfct gears.table.crush
 function gtable.crush(t, set, raw)
     if raw then
         for k, v in pairs(set) do
@@ -63,10 +62,9 @@ end
 --
 -- This function removes any entries with non-numeric keys.
 --
--- @class function
--- @name from_sparse
 -- @tparam table t A potentially sparse table.
 -- @treturn table A packed table with only numeric keys.
+-- @staticfct gears.table.from_sparse
 function gtable.from_sparse(t)
     local keys= {}
     for k in pairs(t) do
@@ -86,12 +84,12 @@ function gtable.from_sparse(t)
 end
 
 --- Check if a table has an item and return its key.
--- @class function
+--
--- @name hasitem
 -- @tparam table t The table.
 -- @param item The item to look for in values of the table.
 -- @treturn[1] string|number The key of the item.
 -- @treturn[2] nil
+-- @staticfct gears.table.hasitem
 function gtable.hasitem(t, item)
     for k, v in pairs(t) do
         if v == item then
@@ -110,6 +108,7 @@ end
 -- @tparam[opt=nil] number max The maximum number of entries to find.
 -- @treturn table|nil An ordered table with all the keys or `nil` if none were
 --   found.
+-- @staticfct gears.table.find_keys
 function gtable.find_keys(t, matcher, ordered, max)
     if max == 0 then return nil end
 
@@ -134,7 +133,8 @@ end
 --   returning a boolean.
 -- @tparam[opt=false] boolean ordered If true, only look for continuous
 --   numeric keys.
--- @return The table key or nil
+-- @return The table key or nil.
+-- @staticfct gears.table.find_first_key
 function gtable.find_first_key(t, matcher, ordered)
     local ret = gtable.find_keys(t, matcher, ordered, 1)
 
@@ -143,10 +143,10 @@ end
 
 
 --- Get a sorted table with all integer keys from a table.
--- @class function
+--
--- @name keys
 -- @tparam table t The table for which the keys to get.
--- @treturn table A table with keys
+-- @treturn table A table with keys.
+-- @staticfct gears.table.keys
 function gtable.keys(t)
     local keys = { }
     for k, _ in pairs(t) do
@@ -159,11 +159,11 @@ function gtable.keys(t)
 end
 
 --- Filter a table's keys for certain content type.
--- @class function
+--
--- @name keys_filter
 -- @tparam table t The table to retrieve the keys for.
 -- @tparam string ... The types to look for.
 -- @treturn table A filtered table.
+-- @staticfct gears.table.keys_filter
 function gtable.keys_filter(t, ...)
     local keys = gtable.keys(t)
     local keys_filtered = { }
@@ -179,10 +179,10 @@ function gtable.keys_filter(t, ...)
 end
 
 --- Reverse a table.
--- @class function
+--
--- @name reverse
 -- @tparam table t The table to reverse.
 -- @treturn table A reversed table.
+-- @staticfct gears.table.reverse
 function gtable.reverse(t)
     local tr = { }
     -- Reverse all elements with integer keys.
@@ -199,11 +199,11 @@ function gtable.reverse(t)
 end
 
 --- Clone a table.
--- @class function
+--
--- @name clone
 -- @tparam table t The table to clone.
 -- @tparam[opt=true] bool deep Create a deep clone?
 -- @treturn table A clone of `t`.
+-- @staticfct gears.table.clone
 function gtable.clone(t, deep)
     deep = deep == nil and true or deep
     local c = { }
@@ -218,11 +218,10 @@ function gtable.clone(t, deep)
 end
 
 --- Iterate over a table.
+--
 -- Returns an iterator to cycle through all elements of a table that match a
 -- given criteria, starting from the first element or the given index.
 --
--- @class function
--- @name iterate
 -- @tparam table t The table to iterate.
 -- @tparam func  filter A function that returns true to indicate a positive
 --   match.
@@ -230,6 +229,7 @@ end
 -- @tparam[opt=1] int start Index to start iterating from.
 --   Default is 1 (=> start of the table).
 -- @treturn func
+-- @staticfct gears.table.iterate
 function gtable.iterate(t, filter, start)
     local count  = 0
     local index  = start or 1
@@ -246,11 +246,11 @@ function gtable.iterate(t, filter, start)
 end
 
 --- Merge items from one table to another one.
--- @class function
+--
--- @name merge
 -- @tparam table t The container table
 -- @tparam table set The mixin table.
--- @treturn table (for convenience)
+-- @treturn table (for convenience).
+-- @staticfct gears.table.merge
 function gtable.merge(t, set)
     for _, v in ipairs(set) do
         table.insert(t, v)
@@ -259,13 +259,14 @@ function gtable.merge(t, set)
 end
 
 --- Map a function to a table.
+--
 -- The function is applied to each value on the table, returning a modified
 -- table.
--- @class function
+--
--- @name map
 -- @tparam function f The function to be applied to each value in the table.
 -- @tparam table tbl The container table whose values will be operated on.
 -- @treturn table
+-- @staticfct gears.table.map
 function gtable.map(f, tbl)
     local t = {}
     for k,v in pairs(tbl) do

lib/gears/timer.lua

@@ -46,7 +46,7 @@
 --
 -- @author Uli Schlachter
 -- @copyright 2014 Uli Schlachter
--- @classmod gears.timer
+-- @coreclassmod gears.timer
 ---------------------------------------------------------------------------
 
 local capi = { awesome = awesome }
@@ -84,6 +84,7 @@ local gdebug = require("gears.debug")
 local timer = { mt = {} }
 
 --- Start the timer.
+-- @method start
 function timer:start()
     if self.data.source_id ~= nil then
         gdebug.print_error(traceback("timer already started"))
@@ -97,6 +98,7 @@ function timer:start()
 end
 
 --- Stop the timer.
+-- @method stop
 function timer:stop()
     if self.data.source_id == nil then
         gdebug.print_error(traceback("timer not started"))
@@ -110,6 +112,7 @@ end
 --- Restart the timer.
 -- This is equivalent to stopping the timer if it is running and then starting
 -- it.
+-- @method again
 function timer:again()
     if self.data.source_id ~= nil then
         self:stop()
@@ -154,7 +157,7 @@ local timer_instance_mt = {
 --  "timeout" signal.
 -- @tparam[opt=false] boolean args.single_shot Run only once then stop.
 -- @treturn timer
--- @function gears.timer
+-- @constructorfct gears.timer
 function timer.new(args)
     args = args or {}
     local ret = object()
@@ -191,7 +194,7 @@ end
 -- @tparam number timeout Timeout in seconds (e.g. 1.5).
 -- @tparam function callback Function to run.
 -- @treturn timer The timer object that was set up.
--- @function gears.timer.start_new
+-- @staticfct gears.timer.start_new
 -- @see gears.timer.weak_start_new
 function timer.start_new(timeout, callback)
     local t = timer.new({ timeout = timeout })
@@ -213,7 +216,7 @@ end
 -- @tparam number timeout Timeout in seconds (e.g. 1.5).
 -- @tparam function callback Function to start.
 -- @treturn timer The timer object that was set up.
--- @function gears.timer.weak_start_new
+-- @staticfct gears.timer.weak_start_new
 -- @see gears.timer.start_new
 function timer.weak_start_new(timeout, callback)
     local indirection = setmetatable({}, { __mode = "v" })
@@ -231,7 +234,7 @@ local delayed_calls = {}
 --- Run all pending delayed calls now. This function should best not be used at
 -- all, because it means that less batching happens and the delayed calls run
 -- prematurely.
--- @function gears.timer.run_delayed_calls_now
+-- @staticfct gears.timer.run_delayed_calls_now
 function timer.run_delayed_calls_now()
     for _, callback in ipairs(delayed_calls) do
         protected_call(unpack(callback))
@@ -242,7 +245,7 @@ end
 --- Call the given function at the end of the current main loop iteration
 -- @tparam function callback The function that should be called
 -- @param ... Arguments to the callback function
--- @function gears.timer.delayed_call
+-- @staticfct gears.timer.delayed_call
 function timer.delayed_call(callback, ...)
     assert(type(callback) == "function", "callback must be a function, got: " .. type(callback))
     table.insert(delayed_calls, { callback, ... })
@@ -254,6 +257,8 @@ function timer.mt.__call(_, ...)
     return timer.new(...)
 end
 
+--@DOC_object_COMMON@
+
 return setmetatable(timer, timer.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/gears/wallpaper.lua

@@ -20,7 +20,7 @@
 --
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
--- @module gears.wallpaper
+-- @utillib gears.wallpaper
 ---------------------------------------------------------------------------
 
 local cairo = require("lgi").cairo
@@ -50,7 +50,8 @@ end
 -- global variable.
 -- @param s The screen to set the wallpaper on or nil for all screens
 -- @return[1] The available geometry (table with entries width and height)
--- @return[1] A cairo context that the wallpaper should be drawn to
+-- @return[1] A cairo context that the wallpaper should be drawn to.
+-- @staticfct gears.wallpaper.prepare_context
 function wallpaper.prepare_context(s)
     s = get_screen(s)
 
@@ -109,6 +110,7 @@ end
 -- @param pattern The wallpaper that should be set. This can be a cairo surface,
 --   a description for gears.color or a cairo pattern.
 -- @see gears.color
+-- @staticfct gears.wallpaper.set
 function wallpaper.set(pattern)
     if cairo.Surface:is_type_of(pattern) then
         pattern = cairo.Pattern.create_for_surface(pattern)
@@ -130,6 +132,7 @@ end
 --   gears.color. The default is black.
 -- @param scale The scale factor for the wallpaper. Default is 1 (original size).
 -- @see gears.color
+-- @staticfct gears.wallpaper.centered
 function wallpaper.centered(surf, s, background, scale)
     local geom, cr = wallpaper.prepare_context(s)
     local original_surf = surf
@@ -169,6 +172,7 @@ end
 -- @param s The screen whose wallpaper should be set. Can be nil, in which case
 --   all screens are set.
 -- @param offset This can be set to a table with entries x and y.
+-- @staticfct gears.wallpaper.tiled
 function wallpaper.tiled(surf, s, offset)
     local _, cr = wallpaper.prepare_context(s)
 
@@ -198,6 +202,7 @@ end
 -- @param ignore_aspect If this is true, the image's aspect ratio is ignored.
 --   The default is to honor the aspect ratio.
 -- @param offset This can be set to a table with entries x and y.
+-- @staticfct gears.wallpaper.maximized
 function wallpaper.maximized(surf, s, ignore_aspect, offset)
     local geom, cr = wallpaper.prepare_context(s)
     local original_surf = surf
@@ -238,6 +243,7 @@ end
 -- @param background The background color that should be used. Gets handled via
 --   gears.color. The default is black.
 -- @see gears.color
+-- @staticfct gears.wallpaper.fit
 function wallpaper.fit(surf, s, background)
     local geom, cr = wallpaper.prepare_context(s)
     local original_surf = surf

lib/menubar/init.lua

@@ -4,19 +4,25 @@
 -- List of menubar keybindings:
 -- ---
 --
---  *  "Left"  | "C-j" select an item on the left
+-- <table class='widget_list' border=1>
---  *  "Right" | "C-k" select an item on the right
+-- <tr style='font-weight: bold;'>
---  *  "Backspace"     exit the current category if we are in any
+--  <th align='center'>Keybinding</th>
---  *  "Escape"        exit the current directory or exit menubar
+--  <th align='center'>Description</th>
---  *  "Home"          select the first item
+-- </tr>                                                                                    </td></tr>
---  *  "End"           select the last
+--  <tr><td><kbd>Left</kbd><kbd>C-j</kbd></td><td> select an item on the left                 </td></tr>
---  *  "Return"        execute the entry
+--  <tr><td><kbd>Right</kbd><kbd>C-k</kbd></td><td> select an item on the right                </td></tr>
---  *  "C-Return"      execute the command with awful.spawn
+--  <tr><td><kbd>Backspace    </kbd></td><td> exit the current category if we are in any </td></tr>
---  *  "C-M-Return"    execute the command in a terminal
+--  <tr><td><kbd>Escape       </kbd></td><td> exit the current directory or exit menubar </td></tr>
+--  <tr><td><kbd>Home         </kbd></td><td> select the first item                      </td></tr>
+--  <tr><td><kbd>End          </kbd></td><td> select the last                            </td></tr>
+--  <tr><td><kbd>Return       </kbd></td><td> execute the entry                          </td></tr>
+--  <tr><td><kbd>C-Return     </kbd></td><td> execute the command with awful.spawn       </td></tr>
+--  <tr><td><kbd>C-M-Return   </kbd></td><td> execute the command in a terminal          </td></tr>
+-- </table>
 --
 -- @author Alexander Yakushev &lt;yakushev.alex@gmail.com&gt;
 -- @copyright 2011-2012 Alexander Yakushev
--- @module menubar
+-- @popupmod menubar
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -42,9 +48,11 @@ end
 
 --- Menubar normal text color.
 -- @beautiful beautiful.menubar_fg_normal
+-- @param color
 
 --- Menubar normal background color.
 -- @beautiful beautiful.menubar_bg_normal
+-- @param color
 
 --- Menubar border width.
 -- @beautiful beautiful.menubar_border_width
@@ -52,12 +60,15 @@ end
 
 --- Menubar border color.
 -- @beautiful beautiful.menubar_border_color
+-- @param color
 
 --- Menubar selected item text color.
 -- @beautiful beautiful.menubar_fg_normal
+-- @param color
 
 --- Menubar selected item background color.
 -- @beautiful beautiful.menubar_bg_normal
+-- @param color
 
 
 -- menubar
@@ -362,6 +373,7 @@ end
 
 --- Refresh menubar's cache by reloading .desktop files.
 -- @tparam[opt] screen scr Screen.
+-- @staticfct menubar.refresh
 function menubar.refresh(scr)
     scr = get_screen(scr or awful.screen.focused() or 1)
     menubar.menu_gen.generate(function(entries)
@@ -418,6 +430,7 @@ end
 
 --- Show the menubar on the given screen.
 -- @param[opt] scr Screen.
+-- @staticfct menubar.show
 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
@@ -492,6 +505,7 @@ function menubar.show(scr)
 end
 
 --- Hide the menubar.
+-- @staticfct menubar.hide
 function menubar.hide()
     if instance then
         instance.wibox.visible = false

lib/menubar/menu_gen.lua

@@ -58,6 +58,7 @@ menu_gen.all_categories = {
 }
 
 --- Find icons for category entries.
+-- @staticfct menubar.menu_gen.lookup_category_icons
 function menu_gen.lookup_category_icons()
     for _, v in pairs(menu_gen.all_categories) do
         v.icon = utils.lookup_icon(v.icon_name)
@@ -79,6 +80,7 @@ end
 -- @tparam function callback Will be fired when all menu entries were parsed
 -- with the resulting list of menu entries as argument.
 -- @tparam table callback.entries All menu entries.
+-- @staticfct menubar.menu_gen.generate
 function menu_gen.generate(callback)
     -- Update icons for category entries
     menu_gen.lookup_category_icons()

lib/menubar/utils.lua

@@ -32,6 +32,7 @@ local utils = {}
 -- Options section
 
 --- Terminal which applications that need terminal would open in.
+-- @param[opt="xterm"] string
 utils.terminal = 'xterm'
 
 --- The default icon for applications that don't provide any icon in
@@ -39,6 +40,7 @@ utils.terminal = 'xterm'
 local default_icon = nil
 
 --- Name of the WM for the OnlyShowIn entry in the .desktop file.
+-- @param[opt="awesome"] string
 utils.wm_name = "awesome"
 
 -- Maps keys in desktop entries to suitable getter function.
@@ -131,6 +133,7 @@ local all_icon_sizes = {
 local supported_icon_file_exts = { png = 1, xpm = 2, svg = 3 }
 
 local icon_lookup_path = nil
+
 --- Get a list of icon lookup paths.
 -- @treturn table A list of directories, without trailing slash.
 local function get_icon_lookup_path()
@@ -198,6 +201,7 @@ end
 
 --- Remove CR newline from the end of the string.
 -- @param s string to trim
+-- @staticfct menubar.utils.rtrim
 function utils.rtrim(s)
     if not s then return end
     if string.byte(s, #s) == 13 then
@@ -209,6 +213,7 @@ end
 --- Lookup an icon in different folders of the filesystem.
 -- @tparam string icon_file Short or full name of the icon.
 -- @treturn string|boolean Full name of the icon, or false on failure.
+-- @staticfct menubar.utils.lookup_icon_uncached
 function utils.lookup_icon_uncached(icon_file)
     if not icon_file or icon_file == "" then
         return false
@@ -244,6 +249,7 @@ local lookup_icon_cache = {}
 --- Lookup an icon in different folders of the filesystem (cached).
 -- @param icon Short or full name of the icon.
 -- @return full name of the icon.
+-- @staticfct menubar.utils.lookup_icon
 function utils.lookup_icon(icon)
     if not lookup_icon_cache[icon] and lookup_icon_cache[icon] ~= false then
         lookup_icon_cache[icon] = utils.lookup_icon_uncached(icon)
@@ -254,6 +260,7 @@ end
 --- Parse a .desktop file.
 -- @param file The .desktop file.
 -- @return A table with file entries.
+-- @staticfct menubar.utils.parse_desktop_file
 function utils.parse_desktop_file(file)
     local program = { show = true, file = file }
 
@@ -350,6 +357,7 @@ end
 -- @tparam function callback Will be fired when all the files were parsed
 -- with the resulting list of menu entries as argument.
 -- @tparam table callback.programs Paths of found .desktop files.
+-- @staticfct menubar.utils.parse_dir
 function utils.parse_dir(dir_path, callback)
 
     local function get_readable_path(file)
@@ -413,6 +421,7 @@ end
 -- @tparam str text Text.
 -- @tparam number|screen s Screen
 -- @treturn int Text width.
+-- @staticfct menubar.utils.compute_text_width
 function utils.compute_text_width(text, s)
     local w, _ = w_textbox(gstring.xml_escape(text)):get_preferred_size(s)
     return w

lib/naughty/action.lua

@@ -14,7 +14,7 @@ local gobject = require("gears.object")
 local action = {}
 
 --- Create a new action.
--- @function naughty.action
+-- @constructorfct naughty.action
 -- @tparam table args The arguments.
 -- @tparam string args.name The name.
 -- @tparam string args.position The position.
@@ -41,7 +41,7 @@ local action = {}
 
 --- The action icon.
 -- @property icon
--- @param gears.surface
+-- @tparam gears.surface|string icon
 
 --- The notification.
 -- @property notification
@@ -124,4 +124,6 @@ local function new(_, args)
     return ret
 end
 
+--@DOC_object_COMMON@
+
 return setmetatable(action, {__call = new})

lib/naughty/core.lua

@@ -196,6 +196,7 @@ local conns = {}
 -- @usage naughty.connect_signal("added", function(notif)
 --    -- do something
 -- end)
+-- @staticfct naughty.connect_signal
 function naughty.connect_signal(name, func)
     assert(name)
     conns[name] = conns[name] or {}
@@ -205,6 +206,7 @@ end
 --- Emit a notification signal.
 -- @tparam string name The signal name.
 -- @param ... The signal callback arguments
+-- @staticfct naughty.emit_signal
 function naughty.emit_signal(name, ...)
     assert(name)
     for _, func in pairs(conns[name] or {}) do
@@ -216,6 +218,7 @@ end
 -- @tparam string name The name of the signal
 -- @tparam function func The attached function
 -- @treturn boolean If the disconnection was successful
+-- @staticfct naughty.disconnect_signal
 function naughty.disconnect_signal(name, func)
     for k, v in ipairs(conns[name] or {}) do
         if v == func then
@@ -291,6 +294,7 @@ end
 -- @treturn true|nil True if all notifications were successfully destroyed, nil
 -- otherwise.
 -- @see notification_closed_reason
+-- @staticfct naughty.destroy_all_notifications
 function naughty.destroy_all_notifications(screens, reason)
     if not screens then
         screens = {}
@@ -323,6 +327,7 @@ end
 --
 -- @param id ID of the notification
 -- @return notification object if it was found, nil otherwise
+-- @staticfct naughty.get_by_id
 function naughty.get_by_id(id)
     -- iterate the notifications to get the notfications with the correct ID
     for s in pairs(naughty.notifications) do

lib/naughty/layout/legacy.lua

@@ -17,7 +17,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2008 koniu
 -- @copyright 2017 Emmanuel Lepage Vallee
--- @classmod naughty.layout.legacy
+-- @popupmod naughty.layout.legacy
 ----------------------------------------------------------------------------
 
 local capi      = { screen = screen, awesome = awesome }

lib/naughty/notification.lua

@@ -13,7 +13,7 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2008 koniu
 -- @copyright 2017 Emmanuel Lepage Vallee
--- @classmod naughty.notification
+-- @coreclassmod naughty.notification
 ---------------------------------------------------------------------------
 local gobject = require("gears.object")
 local gtable  = require("gears.table")
@@ -163,6 +163,7 @@ local notification = {}
 --- Widget shape.
 --@DOC_naughty_shape_EXAMPLE@
 -- @property shape
+-- @param gears.shape
 
 --- Widget opacity.
 -- @property opacity
@@ -240,6 +241,7 @@ local notification = {}
 
 --- Destroy notification by notification object.
 --
+-- @method destroy
 -- @tparam string reason One of the reasons from `notification_closed_reason`
 -- @tparam[opt=false] boolean keep_visible If true, keep the notification visible
 -- @return True if the popup was successfully destroyed, false otherwise
@@ -261,6 +263,7 @@ function notification:destroy(reason, keep_visible)
 end
 
 --- Set new notification timeout.
+-- @method reset_timeout
 -- @tparam number new_timeout Time in seconds after which notification disappears.
 function notification:reset_timeout(new_timeout)
     if self.timer then self.timer:stop() end
@@ -449,7 +452,7 @@ end
 -- @usage naughty.notify({ title = "Achtung!", message = "You're idling", timeout = 0 })
 -- @treturn ?table The notification object, or nil in case a notification was
 --   not displayed.
--- @function naughty.notification
+-- @constructorfct naughty.notification
 local function create(args)
     if cst.config.notify_callback then
         args = cst.config.notify_callback(args)
@@ -543,4 +546,6 @@ function notification._gen_next_id()
     return counter
 end
 
+--@DOC_object_COMMON@
+
 return setmetatable(notification, {__call = function(_, ...) return create(...) end})

lib/wibox/container/arcchart.lua

@@ -7,7 +7,7 @@
 --@DOC_wibox_container_defaults_arcchart_EXAMPLE@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2013 Emmanuel Lepage Vallee
--- @classmod wibox.container.arcchart
+-- @containermod wibox.container.arcchart
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -22,12 +22,15 @@ local arcchart = { mt = {} }
 
 --- The progressbar border background color.
 -- @beautiful beautiful.arcchart_border_color
+-- @param color
 
 --- The progressbar foreground color.
 -- @beautiful beautiful.arcchart_color
+-- @param color
 
 --- The progressbar border width.
 -- @beautiful beautiful.arcchart_border_width
+-- @param number
 
 --- The padding between the outline and the progressbar.
 -- @beautiful beautiful.arcchart_paddings
@@ -197,21 +200,17 @@ function arcchart:set_widget(widget)
     self:emit_signal("widget::layout_changed")
 end
 
---- Get the children elements.
--- @treturn table The children
 function arcchart:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function arcchart:set_children(children)
     self._private.widget = children and children[1]
     self:emit_signal("widget::layout_changed")
 end
 
 --- Reset this layout. The widget will be removed and the rotation reset.
+-- @method reset
 function arcchart:reset()
     self:set_widget(nil)
 end
@@ -237,6 +236,7 @@ end
 --- The border background color.
 --@DOC_wibox_container_arcchart_border_color_EXAMPLE@
 -- @property border_color
+-- @param color
 
 --- The arcchart values foreground colors.
 --@DOC_wibox_container_arcchart_color_EXAMPLE@
@@ -250,9 +250,11 @@ end
 
 --- The minimum value.
 -- @property min_value
+-- @param number
 
 --- The maximum value.
 -- @property max_value
+-- @param number
 
 --- The radial background.
 --@DOC_wibox_container_arcchart_bg_EXAMPLE@
@@ -320,7 +322,7 @@ end
 
 --- Returns a new arcchart layout.
 -- @param[opt] widget The widget to display.
--- @function wibox.container.arcchart
+-- @constructorfct wibox.container.arcchart
 local function new(widget)
     local ret = base.make_widget(nil, nil, {
         enable_properties = true,

lib/wibox/container/background.lua

@@ -5,7 +5,7 @@
 --@DOC_wibox_container_defaults_background_EXAMPLE@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @classmod wibox.container.background
+-- @containermod wibox.container.background
 ---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
@@ -175,15 +175,10 @@ function background:get_widget()
     return self._private.widget
 end
 
--- Get children element
--- @treturn table The children
 function background:get_children()
     return {self._private.widget}
 end
 
--- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function background:set_children(children)
     self:set_widget(children[1])
 end
@@ -239,6 +234,7 @@ end
 --- Set the background shape.
 --
 -- Any other arguments will be passed to the shape function
+-- @method set_shape
 -- @param shape A function taking a context, width and height as arguments
 -- @see gears.shape
 -- @see shape
@@ -389,7 +385,7 @@ end
 -- @param[opt] widget The widget to display.
 -- @param[opt] bg The background to use for that widget.
 -- @param[opt] shape A `gears.shape` compatible shape function
--- @function wibox.container.background
+-- @constructorfct wibox.container.background
 local function new(widget, bg, shape)
     local ret = base.make_widget(nil, nil, {
         enable_properties = true,

lib/wibox/container/constraint.lua

@@ -3,7 +3,7 @@
 --@DOC_wibox_container_defaults_constraint_EXAMPLE@
 -- @author Lukáš Hrázký
 -- @copyright 2012 Lukáš Hrázký
--- @classmod wibox.container.constraint
+-- @containermod wibox.container.constraint
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -51,15 +51,10 @@ function constraint:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function constraint:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function constraint:set_children(children)
     self:set_widget(children[1])
 end
@@ -67,6 +62,7 @@ end
 --- Set the strategy to use for the constraining. Valid values are 'max',
 -- 'min' or 'exact'. Throws an error on invalid values.
 -- @property strategy
+-- @tparam string strategy Either 'max', 'min' or 'exact'
 
 function constraint:set_strategy(val)
     local func = {
@@ -121,6 +117,7 @@ end
 
 --- Reset this layout. The widget will be unreferenced, strategy set to "max"
 -- and the constraints set to nil.
+-- @method reset
 function constraint:reset()
     self._private.width = nil
     self._private.height = nil
@@ -140,7 +137,7 @@ end
 -- @param[opt] width The maximum width of the widget. nil for no limit.
 -- @param[opt] height The maximum height of the widget. nil for no limit.
 -- @treturn table A new constraint container
--- @function wibox.container.constraint
+-- @constructorfct wibox.container.constraint
 local function new(widget, strategy, width, height)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 

lib/wibox/container/margin.lua

@@ -3,7 +3,7 @@
 --@DOC_wibox_container_defaults_margin_EXAMPLE@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @classmod wibox.container.margin
+-- @containermod wibox.container.margin
 ---------------------------------------------------------------------------
 
 local pairs = pairs
@@ -80,15 +80,10 @@ function margin:get_widget()
     return self._private.widget
 end
 
--- Get the number of children element
--- @treturn table The children
 function margin:get_children()
     return {self._private.widget}
 end
 
--- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function margin:set_children(children)
     self:set_widget(children[1])
 end
@@ -136,7 +131,7 @@ function margin:get_color()
 end
 
 --- Draw the margin even if the content size is 0x0 (default: true)
--- @function draw_empty
+-- @method draw_empty
 -- @tparam boolean draw_empty Draw nothing is content is 0x0 or draw the margin anyway
 
 function margin:set_draw_empty(draw_empty)
@@ -150,6 +145,7 @@ end
 
 --- Reset this layout. The widget will be unreferenced, the margins set to 0
 -- and the color erased
+-- @method reset
 function margin:reset()
     self:set_widget(nil)
     self:set_margins(0)
@@ -194,7 +190,7 @@ end
 -- @param[opt] color A color for the margins.
 -- @param[opt] draw_empty whether or not to draw the margin when the content is empty
 -- @treturn table A new margin container
--- @function wibox.container.margin
+-- @constructorfct wibox.container.margin
 local function new(widget, left, right, top, bottom, color, draw_empty)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 

lib/wibox/container/mirror.lua

@@ -3,7 +3,7 @@
 --@DOC_wibox_container_defaults_mirror_EXAMPLE@
 -- @author dodo
 -- @copyright 2012 dodo
--- @classmod wibox.container.mirror
+-- @containermod wibox.container.mirror
 ---------------------------------------------------------------------------
 
 local type = type
@@ -61,20 +61,16 @@ function mirror:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function mirror:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function mirror:set_children(children)
     self:set_widget(children[1])
 end
 
 --- Reset this layout. The widget will be removed and the axes reset.
+-- @method reset
 function mirror:reset()
     self._private.horizontal = false
     self._private.vertical = false
@@ -112,7 +108,7 @@ end
 -- @param[opt] widget The widget to display.
 -- @param[opt] reflection A table describing the reflection to apply.
 -- @treturn table A new mirror container
--- @function wibox.container.mirror
+-- @constructorfct wibox.container.mirror
 local function new(widget, reflection)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
     ret._private.horizontal = false

lib/wibox/container/place.lua

@@ -4,8 +4,7 @@
 --@DOC_wibox_container_defaults_place_EXAMPLE@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee
--- @release @AWESOME_VERSION@
+-- @containermod wibox.container.place
--- @classmod wibox.container.place
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -62,10 +61,6 @@ function place:fit(context, width, height)
         and height or h
 end
 
---- The widget to be placed.
--- @property widget
--- @tparam widget widget The widget
-
 function place:set_widget(widget)
     if widget then
         base.check_widget(widget)
@@ -78,20 +73,20 @@ function place:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
+--- Get or set the children elements.
--- @treturn table The children
+-- @property children
+-- @tparam table The children
+
 function place:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function place:set_children(children)
     self:set_widget(children[1])
 end
 
 --- Reset this layout. The widget will be removed and the rotation reset.
+-- @method reset
 function place:reset()
     self:set_widget(nil)
 end
@@ -177,7 +172,7 @@ end
 -- @tparam[opt="center"] string halign The horizontal alignment
 -- @tparam[opt="center"] string valign The vertical alignment
 -- @treturn table A new place container.
--- @function wibox.container.place
+-- @constructorfct wibox.container.place
 local function new(widget, halign, valign)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 

lib/wibox/container/radialprogressbar.lua

@@ -8,7 +8,7 @@
 --@DOC_wibox_container_defaults_radialprogressbar_EXAMPLE@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2013 Emmanuel Lepage Vallee
--- @classmod wibox.container.radialprogressbar
+-- @containermod wibox.container.radialprogressbar
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -24,12 +24,15 @@ local radialprogressbar = { mt = {} }
 
 --- The progressbar border background color.
 -- @beautiful beautiful.radialprogressbar_border_color
+-- @param color
 
 --- The progressbar foreground color.
 -- @beautiful beautiful.radialprogressbar_color
+-- @param color
 
 --- The progressbar border width.
 -- @beautiful beautiful.radialprogressbar_border_width
+-- @param number
 
 --- The padding between the outline and the progressbar.
 -- @beautiful beautiful.radialprogressbar_paddings
@@ -134,21 +137,17 @@ function radialprogressbar:set_widget(widget)
     self:emit_signal("widget::layout_changed")
 end
 
---- Get the children elements
--- @treturn table The children
 function radialprogressbar:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function radialprogressbar:set_children(children)
     self._private.widget = children and children[1]
     self:emit_signal("widget::layout_changed")
 end
 
 --- Reset this container.
+-- @method reset
 function radialprogressbar:reset()
     self:set_widget(nil)
 end
@@ -194,10 +193,12 @@ end
 --- The border background color.
 --@DOC_wibox_container_radialprogressbar_border_color_EXAMPLE@
 -- @property border_color
+-- @param color
 
 --- The border foreground color.
 --@DOC_wibox_container_radialprogressbar_color_EXAMPLE@
 -- @property color
+-- @param color
 
 --- The border width.
 --@DOC_wibox_container_radialprogressbar_border_width_EXAMPLE@
@@ -206,9 +207,11 @@ end
 
 --- The minimum value.
 -- @property min_value
+-- @param number
 
 --- The maximum value.
 -- @property max_value
+-- @param number
 
 for _, prop in ipairs {"max_value", "min_value", "border_color", "color",
     "border_width", "paddings"} do
@@ -237,7 +240,7 @@ end
 --- Returns a new radialprogressbar layout. A radialprogressbar layout
 -- radialprogressbars a given widget. Use `.widget` to set the widget.
 -- @param[opt] widget The widget to display.
--- @function wibox.container.radialprogressbar
+-- @constructorfct wibox.container.radialprogressbar
 local function new(widget)
     local ret = base.make_widget(nil, nil, {
         enable_properties = true,

lib/wibox/container/rotate.lua

@@ -4,7 +4,7 @@
 --@DOC_wibox_container_defaults_rotate_EXAMPLE@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @classmod wibox.container.rotate
+-- @containermod wibox.container.rotate
 ---------------------------------------------------------------------------
 
 local error = error
@@ -74,20 +74,16 @@ function rotate:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function rotate:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function rotate:set_children(children)
     self:set_widget(children[1])
 end
 
 --- Reset this layout. The widget will be removed and the rotation reset.
+-- @method reset
 function rotate:reset()
     self._private.direction = nil
     self:set_widget(nil)
@@ -125,7 +121,7 @@ function rotate:set_direction(dir)
     self:emit_signal("widget::layout_changed")
 end
 
---- Get the direction of this rotating layout
+-- Get the direction of this rotating layout
 function rotate:get_direction()
     return self._private.direction or "north"
 end
@@ -137,7 +133,7 @@ end
 -- @param[opt] widget The widget to display.
 -- @param[opt] dir The direction to rotate to.
 -- @treturn table A new rotate container.
--- @function wibox.container.rotate
+-- @constructorfct wibox.container.rotate
 local function new(widget, dir)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 

lib/wibox/container/scroll.lua

@@ -20,7 +20,7 @@
 -- }
 -- @author Uli Schlachter (based on ideas from Saleur Geoffrey)
 -- @copyright 2015 Uli Schlachter
--- @classmod wibox.container.scroll
+-- @containermod wibox.container.scroll
 ---------------------------------------------------------------------------
 
 local cache = require("gears.cache")
@@ -220,6 +220,7 @@ _need_scroll_redraw = function(self)
 end
 
 --- Pause the scrolling animation.
+-- @method pause
 -- @see continue
 function scroll:pause()
     if self._private.paused then
@@ -230,6 +231,7 @@ function scroll:pause()
 end
 
 --- Continue the scrolling animation.
+-- @method continue
 -- @see pause
 function scroll:continue()
     if not self._private.paused then
@@ -244,6 +246,7 @@ end
 -- For must scroll step functions, the effect of this function should be to
 -- display the widget without any scrolling applied.
 -- This function does not undo the effect of @{pause}.
+-- @method reset_scrolling
 function scroll:reset_scrolling()
     self._private.timer:start()
     if self._private.paused then
@@ -252,6 +255,7 @@ function scroll:reset_scrolling()
 end
 
 --- Set the direction in which this widget scroll.
+-- @method set_direction
 -- @param dir Either "h" for horizontal scrolling or "v" for vertical scrolling
 function scroll:set_direction(dir)
     if dir == self._private.dir then
@@ -285,20 +289,16 @@ function scroll:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function scroll:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function scroll:set_children(children)
     self:set_widget(children[1])
 end
 
 --- Specify the expand mode that is used for extra space.
+-- @method set_expand
 -- @tparam boolean expand If true, the widget is expanded to include the extra
 -- space. If false, the extra space is simply left empty.
 -- @see set_extra_space
@@ -311,6 +311,7 @@ function scroll:set_expand(expand)
 end
 
 --- Set the number of frames per second that this widget should draw.
+-- @method set_fps
 -- @tparam number fps The number of frames per second
 function scroll:set_fps(fps)
     if fps == self._private.fps then
@@ -323,6 +324,7 @@ end
 
 --- Set the amount of extra space that should be included in the scrolling. This
 -- extra space will likely be left empty between repetitions of the widgets.
+-- @method set_extra_space
 -- @tparam number extra_space The amount of extra space
 -- @see set_expand
 function scroll:set_extra_space(extra_space)
@@ -336,6 +338,7 @@ end
 --- Set the speed of the scrolling animation. The exact meaning depends on the
 -- step function that is used, but for the simplest step functions, this will be
 -- in pixels per second.
+-- @method set_speed
 -- @tparam number speed The speed for the animation
 function scroll:set_speed(speed)
     if speed == self._private.speed then
@@ -349,6 +352,7 @@ end
 -- @{set_direction}. If the child widget is smaller than this size, no scrolling
 -- is done. If the child widget is larger, then only this size will be visible
 -- and the rest is made visible via scrolling.
+-- @method set_max_size
 -- @tparam number max_size The maximum size of this widget or nil for unlimited.
 function scroll:set_max_size(max_size)
     if max_size == self._private.max_size then
@@ -373,6 +377,7 @@ end
 --
 -- The step function should return a single number. This number is the offset at
 -- which the widget is drawn and should be between 0 and `size+extra_space`.
+-- @method set_step_function
 -- @tparam function step_function A step function.
 -- @see step_functions
 function scroll:set_step_function(step_function)
@@ -387,6 +392,7 @@ end
 
 --- Set an upper limit for the space for scrolling.
 -- This restricts the child widget's maximal size.
+-- @method set_space_for_scrolling
 -- @tparam number space_for_scrolling The space for scrolling
 function scroll:set_space_for_scrolling(space_for_scrolling)
     if space_for_scrolling == self._private.space_for_scrolling then
@@ -419,6 +425,7 @@ local function get_layout(dir, widget, fps, speed, extra_space, expand, max_size
 end
 
 --- Get a new horizontal scrolling container.
+-- @constructorfct wibox.container.scroll.horizontal
 -- @param[opt] widget The widget that should be scrolled
 -- @param[opt=20] fps The number of frames per second
 -- @param[opt=10] speed The speed of the animation
@@ -433,6 +440,7 @@ function scroll.horizontal(widget, fps, speed, extra_space, expand, max_size, st
 end
 
 --- Get a new vertical scrolling container.
+-- @constructorfct wibox.container.scroll.vertical
 -- @param[opt] widget The widget that should be scrolled
 -- @param[opt=20] fps The number of frames per second
 -- @param[opt=10] speed The speed of the animation
@@ -452,18 +460,21 @@ scroll.step_functions = {}
 
 --- A step function that scrolls the widget in an increasing direction with
 -- constant speed.
+-- @callback scroll.step_functions.linear_increase
 function scroll.step_functions.linear_increase(elapsed, size, _, speed, extra_space)
     return (elapsed * speed) % (size + extra_space)
 end
 
 --- A step function that scrolls the widget in an decreasing direction with
 -- constant speed.
+-- @callback scroll.step_functions.linear_decrease
 function scroll.step_functions.linear_decrease(elapsed, size, _, speed, extra_space)
     return (-elapsed * speed) % (size + extra_space)
 end
 
 --- A step function that scrolls the widget to its end and back to its
 -- beginning, then back to its end, etc. The speed is constant.
+-- @callback scroll.step_functions.linear_back_and_forth
 function scroll.step_functions.linear_back_and_forth(elapsed, size, visible_size, speed)
     local state = ((elapsed * speed) % (2 * size)) / size
     state = state <= 1 and state or 2 - state
@@ -473,6 +484,7 @@ end
 --- A step function that scrolls the widget to its end and back to its
 -- beginning, then back to its end, etc. The speed is null at the ends and
 -- maximal in the middle.
+-- @callback scroll.step_functions.nonlinear_back_and_forth
 function scroll.step_functions.nonlinear_back_and_forth(elapsed, size, visible_size, speed)
     local state = ((elapsed * speed) % (2 * size)) / size
     local negate = false
@@ -501,6 +513,7 @@ end
 --- A step function that scrolls the widget to its end and back to its
 -- beginning, then back to its end, etc. The speed is null at the ends and
 -- maximal in the middle. At both ends the widget stands still for a moment.
+-- @callback scroll.step_functions.waiting_nonlinear_back_and_forth
 function scroll.step_functions.waiting_nonlinear_back_and_forth(elapsed, size, visible_size, speed)
     local state = ((elapsed * speed) % (2 * size)) / size
     local negate = false

lib/wibox/hierarchy.lua

@@ -5,7 +5,7 @@
 --
 -- @author Uli Schlachter
 -- @copyright 2015 Uli Schlachter
--- @module wibox.hierarchy
+-- @classmod wibox.hierarchy
 ---------------------------------------------------------------------------
 
 local matrix = require("gears.matrix")
@@ -22,6 +22,7 @@ local widgets_to_count = setmetatable({}, { __mode = "k" })
 -- occurrences. Note that for correct operations, the widget must not yet be
 -- visible in any hierarchy.
 -- @param widget The widget that should be counted.
+-- @staticfct wibox.hierarchy.count_widget
 function hierarchy.count_widget(widget)
     widgets_to_count[widget] = true
 end
@@ -203,6 +204,7 @@ end
 --   hierarchy on widget::layout_changed on some widget.
 -- @param callback_arg A second argument that is given to the above callbacks.
 -- @return A new widget hierarchy
+-- @constructorfct wibox.hierarchy.new
 function hierarchy.new(context, widget, width, height, redraw_callback, layout_callback, callback_arg)
     local result = hierarchy_new(redraw_callback, layout_callback, callback_arg)
     result:update(context, widget, width, height)
@@ -217,6 +219,7 @@ end
 -- @param[opt] region A region to use for accumulating changed parts
 -- @return A cairo region describing the changed parts (either the `region`
 --   argument or a new, internally created region).
+-- @method update
 function hierarchy:update(context, widget, width, height, region)
     region = region or cairo.Region.create()
     hierarchy_update(self, context, widget, width, height, region, self._matrix, self._matrix_to_device)
@@ -224,6 +227,7 @@ function hierarchy:update(context, widget, width, height, region)
 end
 
 --- Get the widget that this hierarchy manages.
+-- @method get_widget
 function hierarchy:get_widget()
     return self._widget
 end
@@ -231,6 +235,7 @@ end
 --- Get a matrix that transforms to the parent's coordinate space from this
 -- hierarchy's coordinate system.
 -- @return A matrix describing the transformation.
+-- @method get_matrix_to_parent
 function hierarchy:get_matrix_to_parent()
     return self._matrix
 end
@@ -239,6 +244,7 @@ end
 -- system (aka the coordinate system of the device that this
 -- hierarchy is applied upon) from this hierarchy's coordinate system.
 -- @return A matrix describing the transformation.
+-- @method get_matrix_to_device
 function hierarchy:get_matrix_to_device()
     return self._matrix_to_device
 end
@@ -246,6 +252,7 @@ end
 --- Get a matrix that transforms from the parent's coordinate space into this
 -- hierarchy's coordinate system.
 -- @return A matrix describing the transformation.
+-- @method get_matrix_from_parent
 function hierarchy:get_matrix_from_parent()
     local m = self:get_matrix_to_parent()
     return m:invert()
@@ -255,6 +262,7 @@ end
 -- system (aka the coordinate system of the device that this
 -- hierarchy is applied upon) into this hierarchy's coordinate system.
 -- @return A matrix describing the transformation.
+-- @method get_matrix_from_device
 function hierarchy:get_matrix_from_device()
     local m = self:get_matrix_to_device()
     return m:invert()
@@ -264,6 +272,7 @@ end
 -- This includes the size of this element plus the size of all children
 -- (after applying the corresponding transformation).
 -- @return x, y, width, height
+-- @method get_draw_extents
 function hierarchy:get_draw_extents()
     local ext = self._draw_extents
     return ext.x, ext.y, ext.width, ext.height
@@ -271,6 +280,7 @@ end
 
 --- Get the size that this hierarchy logically covers (in the current coordinate space).
 -- @return width, height
+-- @method get_size
 function hierarchy:get_size()
     local ext = self._size
     return ext.width, ext.height
@@ -278,6 +288,7 @@ end
 
 --- Get a list of all children.
 -- @return List of all children hierarchies.
+-- @method get_children
 function hierarchy:get_children()
     return self._children
 end
@@ -286,6 +297,7 @@ end
 -- only works with widgets registered via `count_widget`.
 -- @param widget The widget that should be counted
 -- @return The number of times that this widget is contained in this hierarchy.
+-- @method get_count
 function hierarchy:get_count(widget)
     return self._widget_counts[widget] or 0
 end
@@ -301,6 +313,7 @@ end
 -- context. The context's clip is used to skip parts that aren't visible.
 -- @param context The context in which widgets are drawn.
 -- @param cr The cairo context that is used for drawing.
+-- @method draw
 function hierarchy:draw(context, cr)
     local widget = self:get_widget()
     if not widget._private.visible then

lib/wibox/init.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @classmod wibox
+-- @popupmod wibox
 ---------------------------------------------------------------------------
 
 local capi = {
@@ -65,6 +65,7 @@ end
 
 --- Create a widget that reflects the current state of this wibox.
 -- @treturn widget A new widget.
+-- @method to_widget
 function wibox:to_widget()
     local bw = self.border_width or beautiful.border_width or 0
     return wibox.widget {
@@ -88,6 +89,7 @@ end
 --- Save a screenshot of the wibox to `path`.
 -- @tparam string path The path.
 -- @tparam[opt=nil] table context A widget context.
+-- @method save_to_svg
 function wibox:save_to_svg(path, context)
     wibox.widget.draw_to_svg_file(
         self:to_widget(), path, self:geometry().width, self:geometry().height, context
@@ -251,7 +253,7 @@ end
 -- @tparam[opt=nil] table args
 --@DOC_wibox_constructor_COMMON@
 -- @treturn wibox The new wibox
--- @function .wibox
+-- @constructorfct wibox
 
 local function new(args)
     args = args or {}
@@ -350,7 +352,7 @@ end
 --- Redraw a wibox. You should never have to call this explicitely because it is
 -- automatically called when needed.
 -- @param wibox
--- @function draw
+-- @method draw
 
 function wibox.mt:__call(...)
     return new(...)

lib/wibox/layout/align.lua

@@ -3,7 +3,7 @@
 --@DOC_wibox_layout_defaults_align_EXAMPLE@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @classmod wibox.layout.align
+-- @layoutmod wibox.layout.align
 ---------------------------------------------------------------------------
 
 local table = table
@@ -142,6 +142,7 @@ end
 --- Set the layout's first widget.
 -- This is the widget that is at the left/top
 -- @property first
+-- @param widget
 
 function align:set_first(widget)
     if self._private.first == widget then
@@ -153,6 +154,7 @@ end
 
 --- Set the layout's second widget. This is the centered one.
 -- @property second
+-- @param widget
 
 function align:set_second(widget)
     if self._private.second == widget then
@@ -165,6 +167,7 @@ end
 --- Set the layout's third widget.
 -- This is the widget that is at the right/bottom
 -- @property third
+-- @param widget
 
 function align:set_third(widget)
     if self._private.third == widget then
@@ -184,6 +187,7 @@ end
 -- This can be used to replace all 3 widgets at once.
 -- @treturn table a list of all widgets
 -- @property children
+-- @param table
 
 function align:get_children()
     return gtable.from_sparse {self._private.first, self._private.second, self._private.third}
@@ -279,6 +283,7 @@ end
 -- three widgets. The widget set via :set_left() is left-aligned. :set_right()
 -- sets a widget which will be right-aligned. The remaining space between those
 -- two will be given to the widget set via :set_middle().
+-- @constructorfct wibox.layout.align.horizontal
 -- @tparam[opt] widget left Widget to be put to the left.
 -- @tparam[opt] widget middle Widget to be put to the middle.
 -- @tparam[opt] widget right Widget to be put to the right.
@@ -296,6 +301,7 @@ end
 -- three widgets. The widget set via :set_top() is top-aligned. :set_bottom()
 -- sets a widget which will be bottom-aligned. The remaining space between those
 -- two will be given to the widget set via :set_middle().
+-- @constructorfct wibox.layout.align.vertical
 -- @tparam[opt] widget top Widget to be put to the top.
 -- @tparam[opt] widget middle Widget to be put to the middle.
 -- @tparam[opt] widget bottom Widget to be put to the right.

lib/wibox/layout/fixed.lua

@@ -3,7 +3,7 @@
 --@DOC_wibox_layout_defaults_fixed_EXAMPLE@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @classmod wibox.layout.fixed
+-- @layoutmod wibox.layout.fixed
 ---------------------------------------------------------------------------
 
 local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1)
@@ -62,7 +62,8 @@ function fixed:layout(context, width, height)
     return result
 end
 
---- Add some widgets to the given fixed layout
+--- Add some widgets to the given layout
+-- @method add
 -- @param ... Widgets that should be added (must at least be one)
 function fixed:add(...)
     -- No table.pack in Lua 5.1 :-(
@@ -77,6 +78,7 @@ end
 
 
 --- Remove a widget from the layout
+-- @method remove
 -- @tparam number index The widget index to remove
 -- @treturn boolean index If the operation is successful
 function fixed:remove(index)
@@ -92,6 +94,7 @@ end
 --- Remove one or more widgets from the layout
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
+-- @method remove_widgets
 -- @param widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
 function fixed:remove_widgets(...)
@@ -128,6 +131,7 @@ function fixed:set_children(children)
 end
 
 --- Replace the first instance of `widget` in the layout with `widget2`
+-- @method replace_widget
 -- @param widget The widget to replace
 -- @param widget2 The widget to replace `widget` with
 -- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
@@ -219,8 +223,9 @@ function fixed:set_spacing_widget(wdg)
     self:emit_signal("widget::layout_changed")
 end
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
 -- **Signal:** widget::inserted The arguments are the widget and the index
+-- @method insert
 -- @tparam number index The position
 -- @param widget The widget
 -- @treturn boolean If the operation is successful
@@ -235,7 +240,7 @@ function fixed:insert(index, widget)
     return true
 end
 
--- Fit the fixed layout into the given space
+-- Fit the fixed layout into the given space.
 -- @param context The context in which we are fit.
 -- @param orig_width The available width.
 -- @param orig_height The available height.
@@ -286,6 +291,7 @@ end
 -- widget will get all the space that is left. If this is false, the last widget
 -- won't be handled specially and there can be space left unused.
 -- @property fill_space
+-- @param boolean
 
 function fixed:fill_space(val)
     if self._private.fill_space ~= val then
@@ -317,7 +323,7 @@ end
 -- Note that widgets ignore `forced_height`. They will use the preferred/minimum width
 -- on the horizontal axis, and a stretched height on the vertical axis.
 -- @tparam widget ... Widgets that should be added to the layout.
--- @function wibox.layout.fixed.horizontal
+-- @constructorfct wibox.layout.fixed.horizontal
 function fixed.horizontal(...)
     return get_layout("x", ...)
 end
@@ -328,7 +334,7 @@ end
 -- Note that widgets ignore `forced_width`. They will use the preferred/minimum height
 -- on the vertical axis, and a stretched width on the horizontal axis.
 -- @tparam widget ... Widgets that should be added to the layout.
--- @function wibox.layout.fixed.vertical
+-- @constructorfct wibox.layout.fixed.vertical
 function fixed.vertical(...)
     return get_layout("y", ...)
 end

lib/wibox/layout/flex.lua

@@ -3,7 +3,7 @@
 --@DOC_wibox_layout_defaults_flex_EXAMPLE@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
--- @classmod wibox.layout.flex
+-- @layoutmod wibox.layout.flex
 ---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
@@ -17,37 +17,28 @@ local flex = {}
 
 --@DOC_fixed_COMMON@
 
---- Replace the layout children
--- @tparam table children A table composed of valid widgets
--- @name set_children
--- @class function
-
 --- Add some widgets to the given fixed layout
 -- @param layout The layout you are modifying.
 -- @tparam widget ... Widgets that should be added (must at least be one)
--- @name add
+-- @method add
--- @class function
 
 --- Remove a widget from the layout
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
--- @name remove
+-- @method remove
--- @class function
 
 --- Remove one or more widgets from the layout
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
 -- @param widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
--- @name remove_widgets
+-- @method remove_widgets
--- @class function
 
 --- Insert a new widget in the layout at position `index`
 -- @tparam number index The position
 -- @param widget The widget
 -- @treturn boolean If the operation is successful
--- @name insert
+-- @method insert
--- @class function
 
 --- The widget used to fill the spacing between the layout elements.
 --
@@ -179,7 +170,7 @@ end
 --- Returns a new horizontal flex layout. A flex layout shares the available space
 -- equally among all widgets. Widgets can be added via :add(widget).
 -- @tparam widget ... Widgets that should be added to the layout.
--- @function wibox.layout.flex.horizontal
+-- @constructorfct wibox.layout.flex.horizontal
 function flex.horizontal(...)
     return get_layout("horizontal", ...)
 end
@@ -187,7 +178,7 @@ end
 --- Returns a new vertical flex layout. A flex layout shares the available space
 -- equally among all widgets. Widgets can be added via :add(widget).
 -- @tparam widget ... Widgets that should be added to the layout.
--- @function wibox.layout.flex.vertical
+-- @constructorfct wibox.layout.flex.vertical
 function flex.vertical(...)
     return get_layout("vertical", ...)
 end

lib/wibox/layout/grid.lua

@@ -13,7 +13,7 @@
 --@DOC_wibox_layout_defaults_grid_EXAMPLE@
 -- @author getzze
 -- @copyright 2017 getzze
--- @classmod wibox.layout.grid
+-- @layoutmod wibox.layout.grid
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -222,6 +222,7 @@ local function find_widget(widgets_table, widget)
 end
 
 --- Get the number of rows and columns occupied by the widgets in the grid.
+-- @method get_dimension
 -- @treturn number,number The number of rows and columns
 function grid:get_dimension()
     return self._private.num_rows, self._private.num_cols
@@ -248,6 +249,7 @@ end
 
 --- Find the next available cell to insert a widget.
 -- The grid is browsed according to the `orientation`.
+-- @method get_next_empty
 -- @tparam[opt=1] number hint_row The row coordinate of the last occupied cell.
 -- @tparam[opt=1] number hint_column The column coordinate of the last occupied cell.
 -- @return number,number The row,column coordinate of the next empty cell
@@ -281,7 +283,10 @@ end
 
 
 --- Add some widgets to the given grid layout.
--- The widgets are assumed to span one cell
+--
+-- The widgets are assumed to span one cell.
+--
+-- @method add
 -- @param ... Widgets that should be added (must at least be one)
 function grid:add(...)
     local args = { n=select('#', ...), ... }
@@ -298,6 +303,8 @@ end
 --- Add a widget to the grid layout at specific coordinate.
 --
 --@DOC_wibox_layout_grid_add_EXAMPLE@
+--
+-- @method add_widget_at
 -- @param 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
@@ -341,6 +348,7 @@ function grid:add_widget_at(child, row, col, row_span, col_span)
 end
 
 --- Remove one or more widgets from the layout.
+-- @method remove
 -- @param ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
 function grid:remove(...)
@@ -366,6 +374,8 @@ end
 --- Remove widgets at the coordinates.
 --
 --@DOC_wibox_layout_grid_remove_EXAMPLE@
+--
+-- @method remove_widgets_at
 -- @tparam number row The row coordinate of the widget to remove
 -- @tparam number col The column coordinate of the widget to remove
 -- @tparam[opt=1] number row_span The number of rows the area to remove spans.
@@ -388,6 +398,7 @@ function grid:remove_widgets_at(row, col, row_span, col_span)
 end
 
 --- Return the coordinates of the widget.
+-- @method get_widget_position
 -- @param widget The widget
 -- @treturn table The `position` table of the coordinates in the grid, with
 -- fields `row`, `col`, `row_span` and `col_span`.
@@ -405,6 +416,7 @@ end
 
 
 --- Return the widgets at the coordinates.
+-- @method get_widgets_at
 -- @tparam number row The row coordinate of the widget
 -- @tparam number col The column coordinate of the widget
 -- @tparam[opt=1] number row_span The number of rows to span.
@@ -427,6 +439,7 @@ function grid:get_widgets_at(row, col, row_span, col_span)
 end
 
 --- Replace old widget by new widget, spanning the same columns and rows.
+-- @method replace_widget
 -- @param old The widget to remove
 -- @param new The widget to add
 -- @treturn boolean If the operation is successful (widget found)
@@ -494,6 +507,8 @@ end
 --- Insert column at index.
 --
 --@DOC_wibox_layout_grid_insert_column_EXAMPLE@
+--
+-- @method insert_column
 -- @tparam number|nil index Insert the new column at index. If `nil`, the column is added at the end.
 -- @treturn number The index of the inserted column
 function grid:insert_column(index)
@@ -508,8 +523,9 @@ function grid:insert_column(index)
 end
 
 --- Extend column at index.
---
 --@DOC_wibox_layout_grid_extend_column_EXAMPLE@
+--
+-- @method extend_column
 -- @tparam number|nil index Extend the column at index. If `nil`, the last column is extended.
 -- @treturn number The index of the extended column
 function grid:extend_column(index)
@@ -526,6 +542,8 @@ end
 --- Remove column at index.
 --
 --@DOC_wibox_layout_grid_remove_column_EXAMPLE@
+--
+-- @method remove_column
 -- @tparam number|nil index Remove column at index. If `nil`, the last column is removed.
 -- @treturn number The index of the removed column
 function grid:remove_column(index)
@@ -542,6 +560,8 @@ end
 --- Insert row at index.
 --
 -- see `insert_column`
+--
+-- @method insert_row
 -- @tparam number|nil index Insert the new row at index. If `nil`, the row is added at the end.
 -- @treturn number The index of the inserted row
 function grid:insert_row(index)
@@ -558,6 +578,8 @@ end
 --- Extend row at index.
 --
 -- see `extend_column`
+--
+-- @method extend_row
 -- @tparam number|nil index Extend the row at index. If `nil`, the last row is extended.
 -- @treturn number The index of the extended row
 function grid:extend_row(index)
@@ -574,6 +596,8 @@ end
 --- Remove row at index.
 --
 -- see `remove_column`
+--
+-- @method remove_row
 -- @tparam number|nil index Remove row at index. If `nil`, the last row is removed.
 -- @treturn number The index of the removed row
 function grid:remove_row(index)
@@ -597,7 +621,7 @@ function grid:get_children()
     return ret
 end
 
--- Add list of children to the layout
+-- Add list of children to the layout.
 function grid:set_children(children)
     self:reset()
     if #children > 0 then
@@ -837,6 +861,7 @@ end
 -- Remove all widgets and reset row and column counts
 --
 -- **Signal:** widget::reset
+-- @method reset
 function grid:reset()
     self._private.widgets = {}
     -- reset the number of columns and rows to the forced value or to 0
@@ -860,7 +885,7 @@ end
 --
 -- A grid layout sets widgets in a grids of custom number of rows and columns.
 -- @tparam[opt="y"] string orientation The preferred grid extension direction.
--- @function wibox.layout.grid
+-- @constructorfct wibox.layout.grid
 local function new(orientation)
     -- Preference for vertical direction: fill rows first, extend grid with new row
     local dir = (orientation == "horizontal"or orientation == "vertical")
@@ -899,7 +924,7 @@ end
 -- up to `forced_num_rows`. Then the next column is filled, creating it if it doesn't exist.
 -- @tparam number|nil forced_num_rows Forced number of rows (`nil` for automatic).
 -- @tparam widget ... Widgets that should be added to the layout.
--- @function wibox.layout.grid.horizontal
+-- @constructorfct wibox.layout.grid.horizontal
 function grid.horizontal(forced_num_rows, widget, ...)
     local ret = new("horizontal")
     ret:set_forced_num_rows(forced_num_rows)
@@ -917,7 +942,7 @@ end
 -- up to `forced_num_cols`. Then the next row is filled, creating it if it doesn't exist.
 -- @tparam number|nil forced_num_cols Forced number of columns (`nil` for automatic).
 -- @tparam widget ... Widgets that should be added to the layout.
--- @function wibox.layout.grid.vertical
+-- @constructorfct wibox.layout.grid.vertical
 function grid.vertical(forced_num_cols, widget, ...)
     local ret = new("vertical")
     ret:set_forced_num_cols(forced_num_cols)

lib/wibox/layout/manual.lua

@@ -7,7 +7,7 @@
 --@DOC_wibox_layout_defaults_manual_EXAMPLE@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
--- @classmod wibox.layout.manual
+-- @layoutmod wibox.layout.manual
 ---------------------------------------------------------------------------
 local gtable = require("gears.table")
 local base = require("wibox.widget.base")
@@ -15,24 +15,24 @@ local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility
 
 local manual_layout = {}
 
---- Add some widgets to the given stack layout
+--- Add some widgets to the given stack layout.
+--
+-- @method add
 -- @param layout The layout you are modifying.
 -- @tparam widget ... Widgets that should be added
--- @name add
--- @class function
 
---- Remove a widget from the layout
+--- Remove a widget from the layout.
+--
+-- @method remove
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
--- @name remove
--- @class function
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
+--
+-- @method insert
 -- @tparam number index The position
 -- @param widget The widget
 -- @treturn boolean If the operation is successful
--- @name insert
--- @class function
 function manual_layout:insert(index, widget)
     table.insert(self._private.widgets, index, widget)
 
@@ -44,13 +44,14 @@ function manual_layout:insert(index, widget)
     self:emit_signal("widget::layout_changed")
 end
 
---- Remove one or more widgets from the layout
+--- Remove one or more widgets from the layout.
+--
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
+--
+-- @method remove_widgets
 -- @param widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
--- @name remove_widgets
--- @class function
 
 
 function manual_layout:fit(_, width, height)
@@ -145,6 +146,8 @@ end
 --           The function is compatible with the `awful.placement` prototype.
 --
 --@DOC_wibox_layout_manual_add_at_EXAMPLE@
+--
+-- @method add_at
 -- @tparam widget widget The widget.
 -- @tparam table|function point Either an `{x=x,y=y}` table or a function
 --  returning the new geometry.
@@ -167,6 +170,7 @@ function manual_layout:add_at(widget, point)
 end
 
 --- Move a widget (by index).
+-- @method move
 -- @tparam number index The widget index.
 -- @tparam table|function point A new point value.
 -- @see add_at
@@ -179,6 +183,8 @@ end
 --- Move a widget.
 --
 --@DOC_wibox_layout_manual_move_widget_EXAMPLE@
+--
+-- @method move_widget
 -- @tparam widget widget The widget.
 -- @tparam table|function point A new point value.
 -- @see add_at
@@ -206,7 +212,9 @@ function manual_layout:reset()
 end
 
 --- Create a manual layout.
+-- @constructorfct wibox.layout.manual
 -- @tparam table ... Widgets to add to the layout.
+
 local function new_manual(...)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 

lib/wibox/layout/ratio.lua

@@ -6,7 +6,7 @@
 --@DOC_wibox_layout_defaults_ratio_EXAMPLE@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
--- @classmod wibox.layout.ratio
+-- @layoutmod wibox.layout.ratio
 ---------------------------------------------------------------------------
 
 local base  = require("wibox.widget.base" )
@@ -38,7 +38,7 @@ local ratio = {}
 -- @property spacing
 -- @tparam number spacing Spacing between widgets.
 
--- Compute the sum of all ratio (ideally, it should be 1)
+-- Compute the sum of all ratio (ideally, it should be 1).
 local function gen_sum(self, i_s, i_e)
     local sum, new_w = 0,0
 
@@ -201,12 +201,13 @@ function ratio:layout(context, width, height)
     return result
 end
 
---- Increase the ratio of "widget"
+--- Increase the ratio of "widget".
 -- If the increment produce an invalid ratio (not between 0 and 1), the method
 -- do nothing.
 --
 --@DOC_wibox_layout_ratio_inc_ratio_EXAMPLE@
 --
+-- @method inc_ratio
 -- @tparam number index The widget index to change
 -- @tparam number increment An floating point value between -1 and 1 where the
 --   end result is within 0 and 1
@@ -221,9 +222,11 @@ function ratio:inc_ratio(index, increment)
     self:set_ratio(index, self._private.ratios[index] + increment)
 end
 
---- Increment the ratio of the first instance of `widget`
+--- Increment the ratio of the first instance of `widget`.
 -- If the increment produce an invalid ratio (not between 0 and 1), the method
 -- do nothing.
+--
+-- @method inc_widget_ratio
 -- @param widget The widget to ajust
 -- @tparam number increment An floating point value between -1 and 1 where the
 --   end result is within 0 and 1
@@ -235,7 +238,9 @@ function ratio:inc_widget_ratio(widget, increment)
     self:inc_ratio(index, increment)
 end
 
---- Set the ratio of the widget at position `index`
+--- Set the ratio of the widget at position `index`.
+--
+-- @method set_ratio
 -- @tparam number index The index of the widget to change
 -- @tparam number percent An floating point value between 0 and 1
 function ratio:set_ratio(index, percent)
@@ -263,6 +268,8 @@ function ratio:set_ratio(index, percent)
 end
 
 --- Get the ratio at `index`.
+--
+-- @method get_ratio
 -- @tparam number index The widget index to query
 -- @treturn number The index (between 0 and 1)
 function ratio:get_ratio(index)
@@ -271,6 +278,8 @@ function ratio:get_ratio(index)
 end
 
 --- Set the ratio of `widget` to `percent`.
+--
+-- @method set_widget_ratio
 -- @tparam widget widget The widget to ajust.
 -- @tparam number percent A floating point value between 0 and 1.
 function ratio:set_widget_ratio(widget, percent)
@@ -284,6 +293,7 @@ end
 --
 --@DOC_wibox_layout_ratio_ajust_ratio_EXAMPLE@
 --
+-- @method ajust_ratio
 -- @tparam number index The index of the widget to change
 -- @tparam number before The sum of the ratio before the widget
 -- @tparam number itself The ratio for "widget"
@@ -323,7 +333,9 @@ function ratio:ajust_ratio(index, before, itself, after)
     self:emit_signal("widget::layout_changed")
 end
 
---- Update all widgets to match a set of a ratio
+--- Update all widgets to match a set of a ratio.
+--
+-- @method ajust_widget_ratio
 -- @param widget The widget to ajust
 -- @tparam number before The sum of the ratio before the widget
 -- @tparam number itself The ratio for "widget"
@@ -333,8 +345,10 @@ function ratio:ajust_widget_ratio(widget, before, itself, after)
     self:ajust_ratio(index, before, itself, after)
 end
 
---- Add some widgets to the given fixed layout
+--- Add some widgets to the given fixed layout.
+--
 -- **Signal:** widget::added The argument are the widgets
+-- @method add
 -- @tparam widget ... Widgets that should be added (must at least be one)
 function ratio:add(...)
     -- No table.pack in Lua 5.1 :-(
@@ -350,8 +364,10 @@ function ratio:add(...)
     self:emit_signal("widget::added", ...)
 end
 
---- Remove a widget from the layout
+--- Remove a widget from the layout.
+--
 -- **Signal:** widget::removed The arguments are the widget and the index
+-- @method remove
 -- @tparam number index The widget index to remove
 -- @treturn boolean index If the operation is successful
 function ratio:remove(index)
@@ -370,8 +386,10 @@ function ratio:remove(index)
     return true
 end
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
 -- **Signal:** widget::inserted The arguments are the widget and the index
+--
+-- @method insert
 -- @tparam number index The position
 -- @param widget The widget
 function ratio:insert(index, widget)
@@ -437,15 +455,17 @@ local function get_layout(dir, widget1, ...)
     return ret
 end
 
---- Returns a new horizontal ratio layout. A ratio layout shares the available space
+--- Returns a new horizontal ratio layout. A ratio layout shares the available space.
 -- equally among all widgets. Widgets can be added via :add(widget).
+-- @constructorfct wibox.layout.ratio.horizontal
 -- @tparam widget ... Widgets that should be added to the layout.
 function ratio.horizontal(...)
     return get_layout("horizontal", ...)
 end
 
---- Returns a new vertical ratio layout. A ratio layout shares the available space
+--- Returns a new vertical ratio layout. A ratio layout shares the available space.
 -- equally among all widgets. Widgets can be added via :add(widget).
+-- @constructorfct wibox.layout.ratio.vertical
 -- @tparam widget ... Widgets that should be added to the layout.
 function ratio.vertical(...)
     return get_layout("vertical", ...)

lib/wibox/layout/stack.lua

@@ -11,7 +11,7 @@
 --@DOC_wibox_layout_defaults_stack_EXAMPLE@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
--- @classmod wibox.layout.stack
+-- @layoutmod wibox.layout.stack
 ---------------------------------------------------------------------------
 
 local base  = require("wibox.widget.base" )
@@ -24,32 +24,28 @@ local stack = {mt={}}
 
 --@DOC_fixed_COMMON@
 
---- Add some widgets to the given stack layout
+--- Add some widgets to the given stack layout.
 -- @param layout The layout you are modifying.
 -- @tparam widget ... Widgets that should be added (must at least be one)
--- @name add
+-- @method add
--- @class function
 
 --- Remove a widget from the layout
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
--- @name remove
+-- @method remove
--- @class function
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
 -- @tparam number index The position
 -- @param widget The widget
 -- @treturn boolean If the operation is successful
--- @name insert
+-- @method insert
--- @class function
 
---- Remove one or more widgets from the layout
+--- Remove one or more widgets from the layout.
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
 -- @param widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
--- @name remove_widgets
+-- @method remove_widgets
--- @class function
 
 --- Add spacing around the widget, similar to the margin container.
 --@DOC_wibox_layout_stack_spacing_EXAMPLE@
@@ -86,7 +82,7 @@ function stack:fit(context, orig_width, orig_height)
     return math.min(max_w, orig_width), math.min(max_h, orig_height)
 end
 
---- If only the first stack widget is drawn
+--- If only the first stack widget is drawn.
 -- @property top_only
 
 function stack:get_top_only()
@@ -97,7 +93,8 @@ function stack:set_top_only(top_only)
     self._private.top_only = top_only
 end
 
---- Raise a widget at `index` to the top of the stack
+--- Raise a widget at `index` to the top of the stack.
+-- @method raise
 -- @tparam number index the widget index to raise
 function stack:raise(index)
     if (not index) or self._private.widgets[index] then return end
@@ -109,7 +106,8 @@ function stack:raise(index)
     self:emit_signal("widget::layout_changed")
 end
 
---- Raise the first instance of `widget`
+--- Raise the first instance of `widget`.
+-- @method raise_widget
 -- @param widget The widget to raise
 -- @tparam[opt=false] boolean recursive Also look deeper in the hierarchy to
 --   find the widget
@@ -158,7 +156,7 @@ function stack:set_vertical_offset(value)
 end
 
 --- Create a new stack layout.
--- @function wibox.layout.stack
+-- @constructorfct wibox.layout.stack
 -- @treturn widget A new stack layout
 
 local function new(...)

lib/wibox/widget/base.lua

@@ -18,12 +18,12 @@ local base = {}
 
 -- {{{ Functions on widgets
 
---- Functions available on all widgets.
+-- Functions available on all widgets.
 base.widget = {}
 
 --- Set/get a widget's buttons.
 -- @tab _buttons The table of buttons that is bound to the widget.
--- @function buttons
+-- @method buttons
 function base.widget:buttons(_buttons)
     if _buttons then
         self._private.widget_buttons = _buttons
@@ -33,7 +33,7 @@ end
 
 --- Set a widget's visibility.
 -- @tparam boolean b Whether the widget is visible.
--- @function set_visible
+-- @method set_visible
 function base.widget:set_visible(b)
     if b ~= self._private.visible then
         self._private.visible = b
@@ -45,7 +45,7 @@ end
 
 --- Is the widget visible?
 -- @treturn boolean
--- @function get_visible
+-- @method get_visible
 function base.widget:get_visible()
     return self._private.visible or false
 end
@@ -53,7 +53,7 @@ end
 --- Set a widget's opacity.
 -- @tparam number o The opacity to use (a number from 0 (transparent) to 1
 -- (opaque)).
--- @function set_opacity
+-- @method set_opacity
 function base.widget:set_opacity(o)
     if o ~= self._private.opacity then
         self._private.opacity = o
@@ -63,7 +63,7 @@ end
 
 --- Get the widget's opacity.
 -- @treturn number The opacity (between 0 (transparent) and 1 (opaque)).
--- @function get_opacity
+-- @method get_opacity
 function base.widget:get_opacity()
     return self._private.opacity
 end
@@ -72,7 +72,7 @@ end
 -- @tparam[opt] number width With `nil` the default mechanism of calling the
 --   `:fit` method is used.
 -- @see fit_widget
--- @function set_forced_width
+-- @method set_forced_width
 function base.widget:set_forced_width(width)
     if width ~= self._private.forced_width then
         self._private.forced_width = width
@@ -88,7 +88,7 @@ end
 -- actual size is during a `mouse::enter`, `mouse::leave` or button event.
 -- @treturn[opt] number The forced width (nil if automatic).
 -- @see fit_widget
--- @function get_forced_width
+-- @method get_forced_width
 function base.widget:get_forced_width()
     return self._private.forced_width
 end
@@ -97,7 +97,7 @@ end
 -- @tparam[opt] number height With `nil` the default mechanism of calling the
 --   `:fit` method is used.
 -- @see fit_widget
--- @function set_height
+-- @method set_height
 function base.widget:set_forced_height(height)
     if height ~= self._private.forced_height then
         self._private.forced_height = height
@@ -112,7 +112,7 @@ end
 -- If there is no forced width/height, then the only way to get the widget's
 -- actual size is during a `mouse::enter`, `mouse::leave` or button event.
 -- @treturn[opt] number The forced height (nil if automatic).
--- @function get_forced_height
+-- @method get_forced_height
 function base.widget:get_forced_height()
     return self._private.forced_height
 end
@@ -121,7 +121,7 @@ end
 --
 -- This method should be re-implemented by the relevant widgets.
 -- @treturn table The children
--- @function get_children
+-- @method get_children
 function base.widget:get_children()
     return {}
 end
@@ -131,7 +131,7 @@ end
 -- The default implementation does nothing, this must be re-implemented by
 -- all layout and container widgets.
 -- @tab children A table composed of valid widgets.
--- @function set_children
+-- @method set_children
 function base.widget:set_children(children) -- luacheck: no unused
     -- Nothing on purpose
 end
@@ -151,7 +151,7 @@ end
 -- *Warning*: This method it prone to stack overflow if the widget, or any of
 -- its children, contains (directly or indirectly) itself.
 -- @treturn table The children
--- @function get_all_children
+-- @method get_all_children
 function base.widget:get_all_children()
     local ret = {}
     digg_children(ret, self)
@@ -175,7 +175,7 @@ end
 --
 -- @tparam string signal_name
 -- @param ... Other arguments
--- @function emit_signal_recursive
+-- @method emit_signal_recursive
 function base.widget:emit_signal_recursive(signal_name, ...)
     -- This is a convenience wrapper, the real implementation is in the
     -- hierarchy.
@@ -190,7 +190,7 @@ end
 -- @treturn number The index.
 -- @treturn widget The parent widget.
 -- @treturn table The path between "self" and "widget".
--- @function index
+-- @method index
 function base.widget:index(widget, recursive, ...)
     local widgets = self:get_children()
     for idx, w in ipairs(widgets) do
@@ -261,7 +261,7 @@ end
 --
 -- This gives only tight bounds if no rotations by non-multiples of 90° are
 -- used.
--- @function wibox.widget.base.rect_to_device_geometry
+-- @staticfct wibox.widget.base.rect_to_device_geometry
 function base.rect_to_device_geometry(cr, x, y, width, height)
     return matrix.transform_rectangle(cr.matrix, x, y, width, height)
 end
@@ -278,7 +278,7 @@ end
 -- @tparam number height The available height for the widget.
 -- @treturn number The width that the widget wants to use.
 -- @treturn number The height that the widget wants to use.
--- @function wibox.widget.base.fit_widget
+-- @staticfct wibox.widget.base.fit_widget
 function base.fit_widget(parent, context, widget, width, height)
     record_dependency(parent, widget)
 
@@ -326,7 +326,7 @@ end
 -- @tparam number width The available width for the widget.
 -- @tparam number height The available height for the widget.
 -- @treturn[opt] table The result from the widget's `:layout` callback.
--- @function wibox.widget.base.layout_widget
+-- @staticfct wibox.widget.base.layout_widget
 function base.layout_widget(parent, context, widget, width, height)
     record_dependency(parent, widget)
 
@@ -346,7 +346,7 @@ end
 --- Handle a button event on a widget.
 --
 -- This is used internally and should not be called directly.
--- @function wibox.widget.base.handle_button
+-- @staticfct wibox.widget.base.handle_button
 function base.handle_button(event, widget, x, y, button, modifiers, geometry)
     x = x or y -- luacheck: no unused
     local function is_any(mod)
@@ -395,7 +395,7 @@ end
 -- @tparam number height The height of the widget in its own coordinate system.
 --   That is, after applying the transformation matrix.
 -- @treturn table An opaque object that can be returned from `:layout()`.
--- @function wibox.widget.base.place_widget_via_matrix
+-- @staticfct wibox.widget.base.place_widget_via_matrix
 function base.place_widget_via_matrix(widget, mat, width, height)
     return {
         _widget = widget,
@@ -415,7 +415,7 @@ end
 -- @tparam number height The height of the widget in its own coordinate system.
 --   That is, after applying the transformation matrix.
 -- @treturn table An opaque object that can be returned from `:layout()`.
--- @function wibox.widget.base.place_widget_at
+-- @staticfct wibox.widget.base.place_widget_at
 function base.place_widget_at(widget, x, y, width, height)
     return base.place_widget_via_matrix(widget, matrix.create_translate(x, y), width, height)
 end
@@ -535,7 +535,7 @@ end
 --
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html).
 -- @tab args A table containing the widget's disposition.
--- @function setup
+-- @method setup
 function base.widget:setup(args)
     local f,ids = self.set_widget or self.add or self.set_first,{}
     local w, id = drill(ids, args)
@@ -562,7 +562,7 @@ end
 --
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html).
 -- @tab args A table containing the widgets disposition.
--- @function wibox.widget.base.make_widget_declarative
+-- @constructorfct wibox.widget.base.make_widget_declarative
 function base.make_widget_declarative(args)
     local ids = {}
 
@@ -608,6 +608,7 @@ end
 -- @param wdg The value.
 -- @param[opt=nil] ... Arguments passed to the contructor (if any).
 -- @treturn The new widget.
+-- @constructorfct wibox.widget.base.make_widget_from_value
 function base.make_widget_from_value(wdg, ...)
     local is_function, t = is_callable(wdg)
 
@@ -635,7 +636,7 @@ end
 --   and setter methods.
 -- @tparam[opt=nil] table args.class The widget class
 -- @see fit_widget
--- @function wibox.widget.base.make_widget
+-- @constructorfct wibox.widget.base.make_widget
 function base.make_widget(proxy, widget_name, args)
     args = args or {}
     local ret = object {
@@ -714,7 +715,7 @@ function base.make_widget(proxy, widget_name, args)
 end
 
 --- Generate an empty widget which takes no space and displays nothing.
--- @function wibox.widget.base.empty_widget
+-- @constructorfct wibox.widget.base.empty_widget
 function base.empty_widget()
     return base.make_widget()
 end
@@ -722,7 +723,7 @@ end
 --- Do some sanity checking on a widget.
 --
 -- This function raises an error if the widget is not valid.
--- @function wibox.widget.base.check_widget
+-- @staticfct wibox.widget.base.check_widget
 function base.check_widget(widget)
     assert(type(widget) == "table", "Type should be table, but is " .. tostring(type(widget)))
     assert(widget.is_widget, "Argument is not a widget!")

lib/wibox/widget/calendar.lua

@@ -21,7 +21,7 @@
 --
 -- @author getzze
 -- @copyright 2017 getzze
--- @classmod wibox.widget.calendar
+-- @widgetmod wibox.widget.calendar
 ---------------------------------------------------------------------------
 
 
@@ -352,7 +352,7 @@ end
 -- @tparam number|nil date.day Date day
 -- @tparam[opt="Monospace 10"] string font Font of the calendar
 -- @treturn widget The month calendar widget
--- @function wibox.widget.calendar.month
+-- @constructorfct wibox.widget.calendar.month
 function calendar.month(date, font)
     return get_calendar("month", date, font)
 end
@@ -368,7 +368,7 @@ end
 -- @tparam number|nil date.day Date day
 -- @tparam[opt="Monospace 10"] string font Font of the calendar
 -- @treturn widget The year calendar widget
--- @function wibox.widget.calendar.year
+-- @constructorfct wibox.widget.calendar.year
 function calendar.year(date, font)
     return get_calendar("year", date, font)
 end