Merge pull request #1113 from Elv13/upstream_shape_api_p4.02

Upstream shape API p4.02

CMakeLists.txt

@@ -276,7 +276,10 @@ if(GENERATE_DOC)
     add_custom_target(ldoc ALL
         COMMAND ${LDOC_EXECUTABLE} . 3>&1 1>&2 2>&3 | awk "{ fail=1 \; print } END { exit fail }"
         WORKING_DIRECTORY ${AWE_DOC_DIR}
-        DEPENDS ${AWE_LUA_FILES} ${AWE_MD_FILES})
+        DEPENDS ${AWE_LUA_FILES} ${AWE_MD_FILES} ${BUILD_DIR}/docs/06-appearance.md
+        ${BUILD_DIR}/docs/05-awesomerc.md
+    )
+
 endif()
 # }}}
 

awesomeConfig.cmake

@@ -329,7 +329,6 @@ set(AWESOME_CONFIGURE_FILES
     ${awesome_lua_configure_files}
     config.h
     docs/config.ld
-    awesomerc.lua
     awesome-version-internal.h)
 
 foreach(file ${AWESOME_CONFIGURE_FILES})
@@ -340,6 +339,22 @@ foreach(file ${AWESOME_CONFIGURE_FILES})
 endforeach()
 #}}}
 
+# {{{ Generate some aggregated documentation from lua script
+add_custom_command(
+        OUTPUT ${BUILD_DIR}/docs/06-appearance.md
+        COMMAND lua ${SOURCE_DIR}/docs/06-appearance.md.lua
+        ${BUILD_DIR}/docs/06-appearance.md
+)
+
+add_custom_command(
+        OUTPUT ${BUILD_DIR}/awesomerc.lua ${BUILD_DIR}/docs/05-awesomerc.md
+        COMMAND lua ${SOURCE_DIR}/docs/05-awesomerc.md.lua
+        ${BUILD_DIR}/docs/05-awesomerc.md ${SOURCE_DIR}/awesomerc.lua
+        ${BUILD_DIR}/awesomerc.lua
+)
+
+#}}}
+
 # {{{ Copy additional files
 file(GLOB awesome_md_docs RELATIVE ${SOURCE_DIR}
     ${SOURCE_DIR}/docs/*.md)

awesomerc.lua

@@ -1,3 +1,4 @@
+-- @DOC_REQUIRE_SECTION@
 -- Standard awesome library
 local gears = require("gears")
 local awful = require("awful")
@@ -12,6 +13,7 @@ local menubar = require("menubar")
 local hotkeys_popup = require("awful.hotkeys_popup").widget
 
 -- {{{ Error handling
+-- @DOC_ERROR_HANDLING@
 -- Check if awesome encountered an error during startup and fell back to
 -- another config (This code will only ever execute for the fallback config)
 if awesome.startup_errors then
@@ -37,9 +39,11 @@ end
 -- }}}
 
 -- {{{ Variable definitions
+-- @DOC_LOAD_THEME@
 -- Themes define colours, icons, font and wallpapers.
 beautiful.init(awful.util.get_themes_dir() .. "default/theme.lua")
 
+-- @DOC_DEFAULT_APPLICATIONS@
 -- This is used later as the default terminal and editor to run.
 terminal = "xterm"
 editor = os.getenv("EDITOR") or "nano"
@@ -52,6 +56,7 @@ editor_cmd = terminal .. " -e " .. editor
 -- However, you can use another modifier like Mod1, but it may interact with others.
 modkey = "Mod4"
 
+-- @DOC_LAYOUT@
 -- Table of layouts to cover with awful.layout.inc, order matters.
 awful.layout.layouts = {
     awful.layout.suit.floating,
@@ -89,6 +94,7 @@ end
 -- }}}
 
 -- {{{ Menu
+-- @DOC_MENU@
 -- Create a launcher widget and a main menu
 myawesomemenu = {
    { "hotkeys", function() return false, hotkeys_popup.show_help end},
@@ -113,7 +119,7 @@ menubar.utils.terminal = terminal -- Set the terminal for applications that requ
 -- Keyboard map indicator and switcher
 mykeyboardlayout = awful.widget.keyboardlayout()
 
--- {{{ Wibox
+-- {{{ Wibar
 -- Create a textclock widget
 mytextclock = wibox.widget.textclock()
 
@@ -122,6 +128,7 @@ mywibox = {}
 mypromptbox = {}
 mylayoutbox = {}
 mytaglist = {}
+-- @TAGLIST_BUTTON@
 mytaglist.buttons = awful.util.table.join(
                     awful.button({ }, 1, function(t) t:view_only() end),
                     awful.button({ modkey }, 1, function(t)
@@ -140,6 +147,7 @@ mytaglist.buttons = awful.util.table.join(
                 )
 
 mytasklist = {}
+-- @TASKLIST_BUTTON@
 mytasklist.buttons = awful.util.table.join(
                      awful.button({ }, 1, function (c)
                                               if c == client.focus then
@@ -165,7 +173,9 @@ mytasklist.buttons = awful.util.table.join(
                                               awful.client.focus.byidx(-1)
                                           end))
 
+-- @DOC_WALLPAPER@
 local function set_wallpaper(s)
+    -- Wallpaper
     if beautiful.wallpaper then
         local wallpaper = beautiful.wallpaper
         -- If wallpaper is a function, call it with the screen
@@ -179,6 +189,7 @@ end
 -- Re-set wallpaper when a screen's geometry changes (e.g. different resolution)
 screen.connect_signal("property::geometry", set_wallpaper)
 
+-- @DOC_FOR_EACH_SCREEN@
 awful.screen.connect_for_each_screen(function(s)
     -- Wallpaper
     set_wallpaper(s)
@@ -202,9 +213,11 @@ awful.screen.connect_for_each_screen(function(s)
     -- Create a tasklist widget
     mytasklist[s] = awful.widget.tasklist(s, awful.widget.tasklist.filter.currenttags, mytasklist.buttons)
 
+    -- @DOC_WIBAR@
     -- Create the wibox
     mywibox[s] = awful.wibar({ position = "top", screen = s })
 
+    -- @DOC_SETUP_WIDGETS@
     -- Add widgets to the wibox
     mywibox[s]:setup {
         layout = wibox.layout.align.horizontal,
@@ -227,6 +240,7 @@ end)
 -- }}}
 
 -- {{{ Mouse bindings
+-- @DOC_ROOT_BUTTONS@
 root.buttons(awful.util.table.join(
     awful.button({ }, 3, function () mymainmenu:toggle() end),
     awful.button({ }, 4, awful.tag.viewnext),
@@ -235,6 +249,7 @@ root.buttons(awful.util.table.join(
 -- }}}
 
 -- {{{ Key bindings
+-- @DOC_GLOBAL_KEYBINDINGS@
 globalkeys = awful.util.table.join(
     awful.key({ modkey,           }, "s",      hotkeys_popup.show_help,
               {description="show help", group="awesome"}),
@@ -333,6 +348,7 @@ globalkeys = awful.util.table.join(
               {description = "show the menubar", group = "launcher"})
 )
 
+-- @DOC_CLIENT_KEYBINDINGS@
 clientkeys = awful.util.table.join(
     awful.key({ modkey,           }, "f",
         function (c)
@@ -365,6 +381,7 @@ clientkeys = awful.util.table.join(
         {description = "maximize", group = "client"})
 )
 
+-- @DOC_NUMBER_KEYBINDINGS@
 -- Bind all key numbers to tags.
 -- Be careful: we use keycodes to make it works on any keyboard layout.
 -- This should map on the top row of your keyboard, usually 1 to 9.
@@ -415,6 +432,7 @@ for i = 1, 9 do
     )
 end
 
+-- @DOC_CLIENT_BUTTONS@
 clientbuttons = awful.util.table.join(
     awful.button({ }, 1, function (c) client.focus = c; c:raise() end),
     awful.button({ modkey }, 1, awful.mouse.client.move),
@@ -426,7 +444,9 @@ root.keys(globalkeys)
 
 -- {{{ Rules
 -- Rules to apply to new clients (through the "manage" signal).
+-- @DOC_RULES@
 awful.rules.rules = {
+    -- @DOC_GLOBAL_RULE@
     -- All clients will match this rule.
     { rule = { },
       properties = { border_width = beautiful.border_width,
@@ -440,6 +460,7 @@ awful.rules.rules = {
      }
     },
 
+    -- @DOC_FLOATING_RULE@
     -- Floating clients.
     { rule_any = {
         instance = {
@@ -466,6 +487,7 @@ awful.rules.rules = {
         }
       }, properties = { floating = true }},
 
+    -- @DOC_DIALOG_RULE@
     -- Add titlebars to normal clients and dialogs
     { rule_any = {type = { "normal", "dialog" }
       }, properties = { titlebars_enabled = true }
@@ -479,6 +501,7 @@ awful.rules.rules = {
 
 -- {{{ Signals
 -- Signal function to execute when a new client appears.
+-- @DOC_MANAGE_HOOK@
 client.connect_signal("manage", function (c)
     -- Set the windows at the slave,
     -- i.e. put it at the end of others instead of setting it master.
@@ -492,6 +515,7 @@ client.connect_signal("manage", function (c)
     end
 end)
 
+-- @DOC_TITLEBARS@
 -- Add a titlebar if titlebars_enabled is set to true in the rules.
 client.connect_signal("request::titlebars", function(c)
     -- buttons for the titlebar
@@ -542,6 +566,7 @@ client.connect_signal("mouse::enter", function(c)
     end
 end)
 
+-- @DOC_BORDER@
 client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus end)
 client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal end)
 -- }}}

docs/05-awesomerc.md.lua

@@ -0,0 +1,241 @@
+local filename, rcfile, new_rcfile = ...
+
+local f = io.open(filename, "w")
+
+f:write[[# Default configuration file documentation
+
+This document explain the default `rc.lua` file provided by Awesome.
+
+]]
+
+-- Document sections of the file to guide new users to the right doc pages
+
+local sections = {}
+
+sections.DOC_REQUIRE_SECTION = [[
+Awesome API is distributed across many libraries (also called modules).
+
+Here is the modules being imported:
+
+<table class='widget_list' border=1>
+  <tr><td>`gears`</td><td>Utilities such as color parsing and objects</td></tr>
+  <tr><td>`wibox`</td><td>Awesome own generic widget framework</td></tr>
+  <tr><td>`awful`</td><td>Everything related to window managment</td></tr>
+  <tr><td>`naughty`</td><td>Notifications</td></tr>
+  <tr><td>`menubar`</td><td>XDG (application) menu implementation</td></tr>
+  <tr><td>`beautiful`</td><td>Awesome theme module</td></tr>
+</table>
+
+]]
+
+sections.DOC_ERROR_HANDLING = [[
+Awesome is a window managing framework. It allows its users great (ultimate?)
+flexibility. However, it also allows the user to write invalid code. There is
+multiple "levels" of problems:
+
+ * Syntax: There is an `awesome -k` option available in the command line to
+   check this. Awesome cannot start with an invalid `rc.lua`
+ * Invalid APIs and type errors: Lua is a dynamic language. It doesn't have much
+   support for static/compile time checks. There is the `luacheck` utility to
+   help find some categories of errors. Those errors will cause Awesome to
+   "drop" the current call stack and start over. Note that if the config cannot
+   reach the end of the `rc.lua` without errors, it will fallback to the
+   original file.
+ * Invalid logic: It is possible to write fully valid code that will leave
+   Awesome unusable (like an infinite loop or blocking commands). In that case,
+   the best way to debug this is either using `print()` or using `gdb`. For
+   this, see the [Debugging tips Readme section](../documentation/01-readme.md.html)
+ * Deprecated APIs: Awesome API is not frozen for eternity. While after a
+   decade and recent changes to enforce consistency, it doesn't change as much,
+   it will likely be changed in the future. When possible, changes wont cause
+   errors but will instead print a deprecation message in Awesome logs. Those
+   logs are placed in various places depending on the distribution. By default,
+   Awesome will print this on stderr and stdout.
+
+
+]]
+
+
+sections.DOC_LOAD_THEME = [[
+To create custom themes, the easiest way is to copy the `default` theme folder
+from `/usr/share/awesome/themes/` into `~/.config/awesome` and modify it.
+
+Awesome currently doesn't behave well without a theme containing all the "basic"
+variables such as `bg_normal`. To get a list of all official variables, see
+the [appearance guide](../documentation/06-appearance.md.html).
+]]
+
+
+sections.DOC_DEFAULT_APPLICATIONS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_LAYOUT = [[
+ &nbsp;
+]]
+
+
+sections.DOC_MENU = [[
+ &nbsp;
+]]
+
+
+sections.TAGLIST_BUTTON = [[
+ &nbsp;
+]]
+
+
+sections.TASKLIST_BUTTON = [[
+ &nbsp;
+]]
+
+
+sections.DOC_FOR_EACH_SCREEN = [[
+ &nbsp;
+]]
+
+
+sections.DOC_WIBAR = [[
+ &nbsp;
+]]
+
+
+sections.DOC_SETUP_WIDGETS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_ROOT_BUTTONS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_GLOBAL_KEYBINDINGS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_CLIENT_KEYBINDINGS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_NUMBER_KEYBINDINGS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_CLIENT_BUTTONS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_RULES = [[
+ &nbsp;
+]]
+
+
+sections.DOC_GLOBAL_RULE = [[
+ &nbsp;
+]]
+
+
+sections.DOC_FLOATING_RULE = [[
+ &nbsp;
+]]
+
+
+sections.DOC_DIALOG_RULE = [[
+ &nbsp;
+]]
+
+
+sections.DOC_MANAGE_HOOK = [[
+ &nbsp;
+]]
+
+
+sections.DOC_TITLEBARS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_BORDER = [[
+ &nbsp;
+]]
+
+-- Ask ldoc to generate links
+
+local function add_links(line)
+    for _, module in ipairs {
+        "awful", "wibox", "gears", "naughty", "menubar", "beautiful"
+    } do
+        if line:match(module.."%.") then
+            line = line:gsub("("..module.."[.a-zA-Z]+)", "`%1`")
+        end
+    end
+
+    return "    "..line.."\n"
+end
+
+-- Parse the default awesomerc.lua
+
+local rc = io.open(rcfile)
+
+local doc_block = false
+
+local output = {}
+
+for line in rc:lines() do
+    local tag = line:match("@([^@]+)@")
+
+    if not tag then
+        local section = line:match("--[ ]*{{{[ ]*(.*)")
+        if line == "-- }}}" or line == "-- {{{" then
+            -- Hide some noise
+        elseif section then
+            -- Turn Vim sections into markdown sections
+            if doc_block then
+                f:write("\n")
+                doc_block = false
+            end
+            f:write("## "..section.."\n")
+        elseif line:sub(1,2) == "--" then
+            -- Display "top level" comments are normal text.
+            if doc_block then
+                f:write("\n")
+                doc_block = false
+            end
+            f:write(line:sub(3).."\n")
+        else
+            -- Write the code in <code> sections
+            if not doc_block then
+                f:write("\n")
+                doc_block = true
+            end
+            f:write(add_links(line))
+        end
+        table.insert(output, line)
+    else
+        -- Take the documentation found in this file and append it
+        if doc_block then
+            f:write("\n")
+            doc_block = false
+        end
+
+        if sections[tag] then
+            f:write(sections[tag])
+        else
+            f:write(" \n\n")
+        end
+    end
+end
+
+f:write("\n")
+
+f:close()
+
+local rc_lua = io.open(new_rcfile, "w")
+rc_lua:write(table.concat(output, "\n"))
+rc_lua:close()

docs/06-appearance.md.lua

@@ -0,0 +1,224 @@
+#! /usr/bin/lua
+local args = {...}
+
+local gio = require("lgi").Gio
+local gobject = require("lgi").GObject
+local glib = require("lgi").GLib
+
+local name_attr = gio.FILE_ATTRIBUTE_STANDARD_NAME
+local type_attr = gio.FILE_ATTRIBUTE_STANDARD_TYPE
+
+-- Recursive file scanner
+local function get_all_files(path, ext, ret)
+    ret = ret or {}
+    local enumerator = gio.File.new_for_path(path):enumerate_children(
+        table.concat({name_attr, type_attr}, ",") , 0, nil, nil
+    )
+
+    for file in function() return enumerator:next_file() end do
+        local file_name = file:get_attribute_as_string(name_attr)
+        local file_type = file:get_file_type()
+        if file_type == "REGULAR" and file_name:match(ext or "") then
+            table.insert(ret, enumerator:get_child(file):get_path())
+        elseif file_type == "DIRECTORY" then
+            get_all_files(enumerator:get_child(file):get_path(), ext, ret)
+        end
+    end
+
+    return ret
+end
+
+local function path_to_module(path)
+    for _, module in ipairs {
+        "awful", "wibox", "gears", "naughty", "menubar", "beautiful"
+    } do
+        local match = path:match("/"..module.."/([^.]+).lua")
+        if match then
+            return module.."."..match:gsub("/",".")
+        end
+    end
+
+    error("Cannot figure out module for " .. tostring(path))
+end
+
+local function module_to_html(mod)
+    mod = mod:gsub(".init", "")
+
+    local f = io.open("doc/classes/".. mod ..".html","r")
+
+    if f~=nil then
+        f:close()
+        return "../classes/".. mod ..".html"
+    end
+
+    f = io.open("doc/libraries/".. mod ..".html","r")
+
+    if f~=nil then
+        f:close()
+        return "../libraries/".. mod ..".html"
+    end
+
+    -- This can happen
+    return ""
+end
+
+local function get_link(file, element)
+    return table.concat {
+        "<a href='",
+        module_to_html(path_to_module(file)),
+        "#",
+        element,
+        "'>",
+        element:match("[. ](.+)"),
+        "</a>"
+    }
+end
+
+local all_files = get_all_files("./lib/", "lua")
+
+local beautiful_vars = {}
+
+-- Find all @beautiful doc entries
+for _,file in ipairs(all_files) do
+    local f = io.open(file)
+
+    local buffer = ""
+
+    for line in f:lines() do
+
+        local var = line:gmatch("--[ ]*@beautiful ([^ \n]*)")()
+
+        -- There is no backward/forward pattern in lua
+        if #line <= 1 then
+            buffer = ""
+        elseif #buffer and not var then
+            buffer = buffer.."\n"..line
+        elseif line:sub(1,3) == "---" then
+            buffer = line
+        end
+
+
+        if var then
+            -- Get the @param, @see and @usage
+            local params = ""
+            for line in f:lines() do
+                if line:sub(1,2) ~= "--" then
+                    break
+                else
+                    params = params.."\n"..line
+                end
+            end
+
+            local name = var:gmatch("[ ]*beautiful.(.+)")()
+            if not name then
+                print("WARNING:", var,
+                    "seems to be misformatted. Use `beautiful.namespace_name`"
+                )
+            else
+                table.insert(beautiful_vars, {
+                    file = file,
+                    name = name,
+                    link = get_link(file, var),
+                    desc = buffer:gmatch("[- ]+([^\n.]*)")() or "",
+                    mod  = path_to_module(file),
+                })
+            end
+
+            buffer = ""
+        end
+    end
+end
+
+local function create_table(entries, columns)
+    local lines = {}
+
+    for _, entry in ipairs(entries) do
+        local line = "  <tr>"
+
+        for _, column in ipairs(columns) do
+            line = line.."<td>"..entry[column].."</td>"
+        end
+
+        table.insert(lines, line.."</tr>\n")
+    end
+
+    return [[<br \><br \><table class='widget_list' border=1>
+ <tr style='font-weight: bold;'>
+  <th align='center'>Name</th>
+  <th align='center'>Description</th>
+ </tr>]] .. table.concat(lines) .. "</table>\n"
+end
+
+local override_cats = {
+    ["border"  ] = true,
+    ["bg"      ] = true,
+    ["fg"      ] = true,
+    ["useless" ] = true,
+    [""        ] = true,
+}
+
+local function categorize(entries)
+    local ret = {}
+
+    local cats = {
+        ["Default variables"] = {}
+    }
+
+    for _, v in ipairs(entries) do
+        local ns = v.name:match("([^_]+)_") or ""
+        ns = override_cats[ns] and "Default variables" or ns
+        cats[ns] = cats[ns] or {}
+        table.insert(cats[ns], v)
+    end
+
+    return cats
+end
+
+local function create_sample(entries)
+    local ret = {
+        "    local theme = {}"
+    }
+
+    for name, cat in pairs(categorize(entries)) do
+        table.insert(ret, "\n    -- "..name)
+        for _, v in ipairs(cat) do
+            table.insert(ret, "    -- theme."..v.name.." = nil")
+        end
+    end
+
+    table.insert(ret, [[
+
+    return theme
+
+    -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80]]
+    )
+
+    return table.concat(ret, '\n')
+end
+
+-- Create the file
+local filename = args[1]
+
+local f = io.open(filename, "w")
+
+f:write[[
+# Change Awesome appearance
+
+## The beautiful themes
+
+Beautiful is where Awesome theme variables are stored.
+
+]]
+f:write(create_table(beautiful_vars, {"link", "desc"}))
+
+f:write("\n\n## Sample theme file\n\n")
+
+f:write(create_sample(beautiful_vars, {"link", "desc"}))
+
+f:close()
+
+--TODO add some linting to direct undeclared beautiful variables
+--TODO re-generate all official themes
+--TODO generate a complete sample theme
+--TODO also parse C files.
+

docs/common/cursor_c.ldoc

@@ -0,0 +1,80 @@
+ * <table class='widget_list' border=1>
+ * <tr><td>num_glyphs          </td></tr>
+ * <tr><td>cursor              </td></tr>
+ * <tr><td>arrow               </td></tr>
+ * <tr><td>based_arrow_down    </td></tr>
+ * <tr><td>based_arrow_up      </td></tr>
+ * <tr><td>boat                </td></tr>
+ * <tr><td>bogosity            </td></tr>
+ * <tr><td>bottom_left_corner  </td></tr>
+ * <tr><td>bottom_right_corner </td></tr>
+ * <tr><td>bottom_side         </td></tr>
+ * <tr><td>bottom_tee          </td></tr>
+ * <tr><td>box_spiral          </td></tr>
+ * <tr><td>center_ptr          </td></tr>
+ * <tr><td>circle              </td></tr>
+ * <tr><td>clock               </td></tr>
+ * <tr><td>coffee_mug          </td></tr>
+ * <tr><td>cross               </td></tr>
+ * <tr><td>cross_reverse       </td></tr>
+ * <tr><td>crosshair           </td></tr>
+ * <tr><td>diamond_cross       </td></tr>
+ * <tr><td>dot                 </td></tr>
+ * <tr><td>dotbox              </td></tr>
+ * <tr><td>double_arrow        </td></tr>
+ * <tr><td>draft_large         </td></tr>
+ * <tr><td>draft_small         </td></tr>
+ * <tr><td>draped_box          </td></tr>
+ * <tr><td>exchange            </td></tr>
+ * <tr><td>fleur               </td></tr>
+ * <tr><td>gobbler             </td></tr>
+ * <tr><td>gumby               </td></tr>
+ * <tr><td>hand                </td></tr>
+ * <tr><td>hand                </td></tr>
+ * <tr><td>heart               </td></tr>
+ * <tr><td>icon                </td></tr>
+ * <tr><td>iron_cross          </td></tr>
+ * <tr><td>left_ptr            </td></tr>
+ * <tr><td>left_side           </td></tr>
+ * <tr><td>left_tee            </td></tr>
+ * <tr><td>leftbutton          </td></tr>
+ * <tr><td>ll_angle            </td></tr>
+ * <tr><td>lr_angle            </td></tr>
+ * <tr><td>man                 </td></tr>
+ * <tr><td>middlebutton        </td></tr>
+ * <tr><td>mouse               </td></tr>
+ * <tr><td>pencil              </td></tr>
+ * <tr><td>pirate              </td></tr>
+ * <tr><td>plus                </td></tr>
+ * <tr><td>question_arrow      </td></tr>
+ * <tr><td>right_ptr           </td></tr>
+ * <tr><td>right_side          </td></tr>
+ * <tr><td>right_tee           </td></tr>
+ * <tr><td>rightbutton         </td></tr>
+ * <tr><td>rtl_logo            </td></tr>
+ * <tr><td>sailboat            </td></tr>
+ * <tr><td>sb_down_arrow       </td></tr>
+ * <tr><td>sb_h_double_arrow   </td></tr>
+ * <tr><td>sb_left_arrow       </td></tr>
+ * <tr><td>sb_right_arrow      </td></tr>
+ * <tr><td>sb_up_arrow         </td></tr>
+ * <tr><td>sb_v_double_arrow   </td></tr>
+ * <tr><td>shuttle             </td></tr>
+ * <tr><td>sizing              </td></tr>
+ * <tr><td>spider              </td></tr>
+ * <tr><td>spraycan            </td></tr>
+ * <tr><td>star                </td></tr>
+ * <tr><td>target              </td></tr>
+ * <tr><td>tcross              </td></tr>
+ * <tr><td>top_left_arrow      </td></tr>
+ * <tr><td>top_left_corner     </td></tr>
+ * <tr><td>top_right_corner    </td></tr>
+ * <tr><td>top_side            </td></tr>
+ * <tr><td>top_tee             </td></tr>
+ * <tr><td>trek                </td></tr>
+ * <tr><td>ul_angle            </td></tr>
+ * <tr><td>umbrella            </td></tr>
+ * <tr><td>ur_angle            </td></tr>
+ * <tr><td>watch               </td></tr>
+ * <tr><td>xterm               </td></tr>
+ * </table>

docs/config.ld

@@ -21,6 +21,8 @@ topics={
     '02-contributing.md',
     '03-declarative-layout.md',
     '04-new-widgets.md',
+    '05-awesomerc.md',
+    '06-appearance.md',
     '16-using-cairo.md',
     '90-FAQ.md',
 }

lib/awful/layout/suit/corner.lua

@@ -14,6 +14,26 @@ local math = math
 local capi = {screen = screen}
 local tag = require("awful.tag")
 
+--- The cornernw layout layoutbox icon.
+-- @beautiful beautiful.layout_cornernw
+-- @param surface
+-- @see gears.surface
+
+--- The cornerne layout layoutbox icon.
+-- @beautiful beautiful.layout_cornerne
+-- @param surface
+-- @see gears.surface
+
+--- The cornersw layout layoutbox icon.
+-- @beautiful beautiful.layout_cornersw
+-- @param surface
+-- @see gears.surface
+
+--- The cornerse layout layoutbox icon.
+-- @beautiful beautiful.layout_cornerse
+-- @param surface
+-- @see gears.surface
+
 --- Actually arrange clients of p.clients for corner layout
 -- @param p Mandatory table containing required informations for layouts
 -- (clients to arrange, workarea geometry, etc.)

lib/awful/layout/suit/fair.lua

@@ -11,6 +11,16 @@
 local ipairs = ipairs
 local math = math
 
+--- The fairh layout layoutbox icon.
+-- @beautiful beautiful.layout_fairh
+-- @param surface
+-- @see gears.surface
+
+--- The fairv layout layoutbox icon.
+-- @beautiful beautiful.layout_fairv
+-- @param surface
+-- @see gears.surface
+
 local fair = {}
 
 local function do_fair(p, orientation)

lib/awful/layout/suit/floating.lua

@@ -15,6 +15,11 @@ local capi =
     mousegrabber = mousegrabber
 }
 
+--- The floating layout layoutbox icon.
+-- @beautiful beautiful.layout_floating
+-- @param surface
+-- @see gears.surface
+
 local floating = {}
 
 --- Jump mouse cursor to the client's corner when resizing it.

lib/awful/layout/suit/magnifier.lua

@@ -18,6 +18,11 @@ local capi =
     mousegrabber = mousegrabber
 }
 
+--- The magnifier layout layoutbox icon.
+-- @beautiful beautiful.layout_magnifier
+-- @param surface
+-- @see gears.surface
+
 local magnifier = {}
 
 function magnifier.mouse_resize_handler(c, corner, x, y)

lib/awful/layout/suit/max.lua

@@ -12,6 +12,16 @@ local pairs = pairs
 
 local max = {}
 
+--- The max layout layoutbox icon.
+-- @beautiful beautiful.layout_max
+-- @param surface
+-- @see gears.surface
+
+--- The fullscreen layout layoutbox icon.
+-- @beautiful beautiful.layout_fullscreen
+-- @param surface
+-- @see gears.surface
+
 local function fmax(p, fs)
     -- Fullscreen?
     local area

lib/awful/layout/suit/spiral.lua

@@ -13,6 +13,16 @@
 local ipairs = ipairs
 local math = math
 
+--- The spiral layout layoutbox icon.
+-- @beautiful beautiful.layout_spiral
+-- @param surface
+-- @see gears.surface
+
+--- The dwindle layout layoutbox icon.
+-- @beautiful beautiful.layout_dwindle
+-- @param surface
+-- @see gears.surface
+
 local spiral = {}
 
 local function do_spiral(p, _spiral)

lib/awful/layout/suit/tile.lua

@@ -23,6 +23,26 @@ local capi =
 
 local tile = {}
 
+--- The tile layout layoutbox icon.
+-- @beautiful beautiful.layout_tile
+-- @param surface
+-- @see gears.surface
+
+--- The tile top layout layoutbox icon.
+-- @beautiful beautiful.layout_tiletop
+-- @param surface
+-- @see gears.surface
+
+--- The tile bottom layout layoutbox icon.
+-- @beautiful beautiful.layout_tilebottom
+-- @param surface
+-- @see gears.surface
+
+--- The tile left layout layoutbox icon.
+-- @beautiful beautiful.layout_tileleft
+-- @param surface
+-- @see gears.surface
+
 --- Jump mouse cursor to the client's corner when resizing it.
 tile.resize_jump_to_corner = true
 

lib/awful/menu.lua

@@ -48,6 +48,49 @@ local table_update = function (t, set)
     return t
 end
 
+--- The icon used for sub-menus.
+-- @beautiful beautiful.menu_submenu_icon
+
+--- The item height.
+-- @beautiful beautiful.menu_height
+-- @tparam[opt=16] number menu_height
+
+--- The default menu width.
+-- @beautiful beautiful.menu_width
+-- @tparam[opt=100] number menu_width
+
+--- The menu item border color.
+-- @beautiful beautiful.menu_border_color
+-- @tparam[opt=0] number menu_border_color
+
+--- The menu item border width.
+-- @beautiful beautiful.menu_border_width
+-- @tparam[opt=0] number menu_border_width
+
+--- The default focused item foreground (text) color.
+-- @beautiful beautiful.menu_fg_focus
+-- @param color
+-- @see gears.color
+
+--- The default focused item background color.
+-- @beautiful beautiful.menu_bg_focus
+-- @param color
+-- @see gears.color
+
+--- The default foreground (text) color.
+-- @beautiful beautiful.menu_fg_normal
+-- @param color
+-- @see gears.color
+
+--- The default background color.
+-- @beautiful beautiful.menu_bg_normal
+-- @param color
+-- @see gears.color
+
+--- The default sub-menu indicator if no menu_submenu_icon is provided.
+-- @beautiful beautiful.menu_submenu
+-- @tparam[opt="▶"] string menu_submenu The sub-menu text.
+-- @see beautiful.menu_submenu_icon
 
 --- Key bindings for menu navigation.
 -- Keys are: up, down, exec, enter, back, close. Value are table with a list of valid

lib/awful/titlebar.lua

@@ -25,6 +25,191 @@ local titlebar = {
     widget = {}
 }
 
+--- The titlebar foreground (text) color.
+-- @beautiful beautiful.titlebar_fg_normal
+-- @param color
+-- @see gears.color
+
+--- The titlebar background color.
+-- @beautiful beautiful.titlebar_bg_normal
+-- @param color
+-- @see gears.color
+
+--- The titlebar background image image.
+-- @beautiful beautiful.titlebar_bgimage_normal
+-- @param surface
+-- @see gears.surface
+
+--- The titlebar foreground (text) color.
+-- @beautiful beautiful.titlebar_fg
+-- @param color
+-- @see gears.color
+
+--- The titlebar background color.
+-- @beautiful beautiful.titlebar_bg
+-- @param color
+-- @see gears.color
+
+--- The titlebar background image image.
+-- @beautiful beautiful.titlebar_bgimage
+-- @param surface
+-- @see gears.surface
+
+--- The focused titlebar foreground (text) color.
+-- @beautiful beautiful.titlebar_fg_focus
+-- @param color
+-- @see gears.color
+
+--- The focused titlebar background color.
+-- @beautiful beautiful.titlebar_bg_focus
+-- @param color
+-- @see gears.color
+
+--- The focused titlebar background image image.
+-- @beautiful beautiful.titlebar_bgimage_focus
+-- @param surface
+-- @see gears.surface
+
+--- floating_button_normal.
+-- @beautiful beautiful.titlebar_floating_button_normal
+-- @param surface
+-- @see gears.surface
+
+--- maximized_button_normal.
+-- @beautiful beautiful.titlebar_maximized_button_normal
+-- @param surface
+-- @see gears.surface
+
+--- minimize_button_normal
+-- @beautiful beautiful.titlebar_minimize_button_normal
+-- @param surface
+-- @see gears.surface
+
+--- close_button_normal.
+-- @beautiful beautiful.titlebar_close_button_normal
+-- @param surface
+-- @see gears.surface
+
+--- ontop_button_normal.
+-- @beautiful beautiful.titlebar_ontop_button_normal
+-- @param surface
+-- @see gears.surface
+
+--- sticky_button_normal.
+-- @beautiful beautiful.titlebar_sticky_button_normal
+-- @param surface
+-- @see gears.surface
+
+--- floating_button_focus.
+-- @beautiful beautiful.titlebar_floating_button_focus
+-- @param surface
+-- @see gears.surface
+
+--- maximized_button_focus.
+-- @beautiful beautiful.titlebar_maximized_button_focus
+-- @param surface
+-- @see gears.surface
+
+--- minimize_button_focus.
+-- @beautiful beautiful.titlebar_minimize_button_focus
+-- @param surface
+-- @see gears.surface
+
+--- close_button_focus.
+-- @beautiful beautiful.titlebar_close_button_focus
+-- @param surface
+-- @see gears.surface
+
+--- ontop_button_focus.
+-- @beautiful beautiful.titlebar_ontop_button_focus
+-- @param surface
+-- @see gears.surface
+
+--- sticky_button_focus.
+-- @beautiful beautiful.titlebar_sticky_button_focus
+-- @param surface
+-- @see gears.surface
+
+--- floating_button_normal_active.
+-- @beautiful beautiful.titlebar_floating_button_normal_active
+-- @param surface
+-- @see gears.surface
+
+--- maximized_button_normal_active.
+-- @beautiful beautiful.titlebar_maximized_button_normal_active
+-- @param surface
+-- @see gears.surface
+
+--- ontop_button_normal_active.
+-- @beautiful beautiful.titlebar_ontop_button_normal_active
+-- @param surface
+-- @see gears.surface
+
+--- sticky_button_normal_active.
+-- @beautiful beautiful.titlebar_sticky_button_normal_active
+-- @param surface
+-- @see gears.surface
+
+--- floating_button_focus_active.
+-- @beautiful beautiful.titlebar_floating_button_focus_active
+-- @param surface
+-- @see gears.surface
+
+--- maximized_button_focus_active.
+-- @beautiful beautiful.titlebar_maximized_button_focus_active
+-- @param surface
+-- @see gears.surface
+
+--- ontop_button_focus_active.
+-- @beautiful beautiful.titlebar_ontop_button_focus_active
+-- @param surface
+-- @see gears.surface
+
+--- sticky_button_focus_active.
+-- @beautiful beautiful.titlebar_sticky_button_focus_active
+-- @param surface
+-- @see gears.surface
+
+--- floating_button_normal_inactive.
+-- @beautiful beautiful.titlebar_floating_button_normal_inactive
+-- @param surface
+-- @see gears.surface
+
+--- maximized_button_normal_inactive.
+-- @beautiful beautiful.titlebar_maximized_button_normal_inactive
+-- @param surface
+-- @see gears.surface
+
+--- ontop_button_normal_inactive.
+-- @beautiful beautiful.titlebar_ontop_button_normal_inactive
+-- @param surface
+-- @see gears.surface
+
+--- sticky_button_normal_inactive.
+-- @beautiful beautiful.titlebar_sticky_button_normal_inactive
+-- @param surface
+-- @see gears.surface
+
+--- floating_button_focus_inactive.
+-- @beautiful beautiful.titlebar_floating_button_focus_inactive
+-- @param surface
+-- @see gears.surface
+
+--- maximized_button_focus_inactive.
+-- @beautiful beautiful.titlebar_maximized_button_focus_inactive
+-- @param surface
+-- @see gears.surface
+
+--- ontop_button_focus_inactive.
+-- @beautiful beautiful.titlebar_ontop_button_focus_inactive
+-- @param surface
+-- @see gears.surface
+
+--- sticky_button_focus_inactive.
+-- @beautiful beautiful.titlebar_sticky_button_focus_inactive
+-- @param surface
+-- @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

lib/awful/widget/taglist.lua

@@ -141,9 +141,25 @@ end
 -- @param screen The screen to draw taglist for.
 -- @param filter Filter function to define what clients will be listed.
 -- @param buttons A table with buttons binding to set.
--- @param style The style overrides default theme.
+-- @tparam[opt={}] table style The style overrides default theme.
+-- @tparam[opt=nil] string|pattern style.fg_focus
+-- @tparam[opt=nil] string|pattern style.bg_focus
+-- @tparam[opt=nil] string|pattern style.fg_urgent
+-- @tparam[opt=nil] string|pattern style.bg_urgent
+-- @tparam[opt=nil] string|pattern style.bg_occupied
+-- @tparam[opt=nil] string|pattern style.fg_occupied
+-- @tparam[opt=nil] string|pattern style.bg_empty
+-- @tparam[opt=nil] string|pattern style.fg_empty
+-- @tparam[opt=nil] string style.taglist_squares_sel
+-- @tparam[opt=nil] string style.taglist_squares_unsel
+-- @tparam[opt=nil] string style.taglist_squares_sel_empty
+-- @tparam[opt=nil] string style.taglist_squares_unsel_empty
+-- @tparam[opt=nil] string style.taglist_squares_resize
+-- @tparam[opt=nil] string style.taglist_disable_icon
+-- @tparam[opt=nil] string style.font
+-- @tparam[opt=nil] number style.spacing The spacing between tags.
 -- @param[opt] update_function Function to create a tag widget on each
---   update. @see awful.widget.common.
+--   update. See `awful.widget.common`.
 -- @param[opt] base_widget Optional container widget for tag widgets. Default
 --   is wibox.layout.fixed.horizontal().
 -- @param base_widget.bg_focus The background color for focused client.

lib/awful/widget/tasklist.lua

@@ -149,29 +149,29 @@ end
 -- @param screen The screen to draw tasklist for.
 -- @param filter Filter function to define what clients will be listed.
 -- @param buttons A table with buttons binding to set.
--- @param style The style overrides default theme.
+-- @tparam[opt={}] table style The style overrides default theme.
+-- @tparam[opt=nil] string|pattern style.fg_normal
+-- @tparam[opt=nil] string|pattern style.bg_normal
+-- @tparam[opt=nil] string|pattern style.fg_focus
+-- @tparam[opt=nil] string|pattern style.bg_focus
+-- @tparam[opt=nil] string|pattern style.fg_urgent
+-- @tparam[opt=nil] string|pattern style.bg_urgent
+-- @tparam[opt=nil] string|pattern style.fg_minimize
+-- @tparam[opt=nil] string|pattern style.bg_minimize
+-- @tparam[opt=nil] string style.bg_image_normal
+-- @tparam[opt=nil] string style.bg_image_focus
+-- @tparam[opt=nil] string style.bg_image_urgent
+-- @tparam[opt=nil] string style.bg_image_minimize
+-- @tparam[opt=nil] boolean style.tasklist_disable_icon
+-- @tparam[opt=nil] string style.font
+-- @tparam[opt=nil] string style.font_focus
+-- @tparam[opt=nil] string style.font_minimized
+-- @tparam[opt=nil] string style.font_urgent
 -- @param[opt] update_function Function to create a tag widget on each
 --   update. See `awful.widget.common.list_update`.
 -- @tparam[opt] table base_widget Container widget for tag widgets. Default
 --   is `wibox.layout.flex.horizontal`.
--- @param base_widget.align The alignment ("left", "center" or "right").
+-- @function awful.tasklist
--- @param base_widget.bg_normal The background color for unfocused client.
--- @param base_widget.bg_normal The background color for unfocused client.
--- @param base_widget.fg_normal The foreground color for unfocused client.
--- @param base_widget.bg_focus The background color for focused client.
--- @param base_widget.fg_focus The foreground color for focused client.
--- @param base_widget.bg_urgent The background color for urgent clients.
--- @param base_widget.fg_urgent The foreground color for urgent clients.
--- @param base_widget.bg_minimize The background color for minimized clients.
--- @param base_widget.fg_minimize The foreground color for minimized clients.
--- @param base_widget.floating Symbol to use for floating clients.
--- @param base_widget.ontop Symbol to use for ontop clients.
--- @param base_widget.above Symbol to use for clients kept above others.
--- @param base_widget.below Symbol to use for clients kept below others.
--- @param base_widget.maximized Symbol to use for clients that have been maximized (vertically and horizontally).
--- @param base_widget.maximized_horizontal Symbol to use for clients that have been horizontally maximized.
--- @param base_widget.maximized_vertical Symbol to use for clients that have been vertically maximized.
--- @param base_widget.font The font.
 function tasklist.new(screen, filter, buttons, style, update_function, base_widget)
     screen = get_screen(screen)
     local uf = update_function or common.list_update

lib/beautiful/init.lua

@@ -30,6 +30,66 @@ local descs = setmetatable({}, { __mode = 'k' })
 local fonts = setmetatable({}, { __mode = 'v' })
 local active_font
 
+--- The default font.
+-- @beautiful beautiful.font
+
+-- The default background color.
+-- @beautiful beautiful.bg_normal
+
+-- The default focused element background color.
+-- @beautiful beautiful.bg_focus
+
+-- The default urgent element background color.
+-- @beautiful beautiful.bg_urgent
+
+-- The default minimized element background color.
+-- @beautiful beautiful.bg_minimize
+
+-- The system tray background color.
+-- Please note that only solid colors are currently supported.
+-- @beautiful beautiful.bg_systray
+
+-- The default focused element foreground (text) color.
+-- @beautiful beautiful.fg_normal
+
+-- The default focused element foreground (text) color.
+-- @beautiful beautiful.fg_focus
+
+-- The default urgent element foreground (text) color.
+-- @beautiful beautiful.fg_urgent
+
+-- The default minimized element foreground (text) color.
+-- @beautiful beautiful.fg_minimize
+
+--- The gap between clients.
+-- @beautiful beautiful.useless_gap
+-- @param[opt=0] number
+
+--- The client border width.
+-- @beautiful beautiful.border_width
+
+--- The default clients border width.
+-- Note that only solid colors are supported.
+-- @beautiful beautiful.border_normal
+
+--- The focused client border width.
+-- Note that only solid colors are supported.
+-- @beautiful beautiful.border_focus
+
+--- The marked clients border width.
+-- Note that only solid colors are supported.
+-- @beautiful beautiful.border_marked
+
+--- The wallpaper path.
+-- @beautiful beautiful.wallpaper
+
+-- The icon theme name.
+-- It has to be a directory in `/usr/share/icons` or an XDG icon folder.
+-- @beautiful beautiful.icon_theme
+
+--- The Awesome icon path.
+-- @beautiful beautiful.awesome_icon
+
 --- Load a font from a string or a font description.
 --
 -- @see https://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string

lib/gears/object/properties.lua

@@ -27,7 +27,7 @@ local function cobj_register(cobj)
     return fallback
 end
 
---- Add the missing properties handler to a CAPI object such as client/tag/screen
+--- Add the missing properties handler to a CAPI object such as client/tag/screen.
 -- Valid args:
 --
 -- * **getter**: A smart getter (handle property getter itself)

lib/gears/timer.lua

@@ -4,7 +4,7 @@
 -- @author Uli Schlachter
 -- @copyright 2014 Uli Schlachter
 -- @release @AWESOME_VERSION@
--- @module gears.timer
+-- @classmod gears.timer
 ---------------------------------------------------------------------------
 
 local capi = { awesome = awesome }
@@ -30,10 +30,13 @@ local protected_call = require("gears.protected_call")
 -- @table timer
 
 --- When the timer is started.
--- @signal start
+-- @signal .start
 
 --- When the timer is stopped.
--- @signal stop
+-- @signal .stop
+
+--- When the timer had a timeout event.
+-- @signal .timeout
 
 local timer = { mt = {} }
 
@@ -71,6 +74,15 @@ function timer:again()
     self:start()
 end
 
+--- The timer is started.
+-- @property started
+-- @param boolean
+
+--- The timer timeout value.
+-- **Signal:** property::timeout
+-- @property timeout
+-- @param number
+
 local timer_instance_mt = {
     __index = function(self, property)
         if property == "timeout" then
@@ -94,6 +106,7 @@ local timer_instance_mt = {
 -- @tparam table args Arguments.
 -- @tparam number args.timeout Timeout in seconds (e.g. 1.5).
 -- @treturn timer
+-- @function gears.timer
 timer.new = function(args)
     local ret = object()
 
@@ -115,6 +128,7 @@ end
 -- @tparam function callback Function to run.
 -- @treturn timer The timer object that was set up.
 -- @see timer.weak_start_new
+-- @function gears.timer.start_new
 function timer.start_new(timeout, callback)
     local t = timer.new({ timeout = timeout })
     t:connect_signal("timeout", function()
@@ -136,6 +150,7 @@ end
 -- @tparam function callback Function to start.
 -- @treturn timer The timer object that was set up.
 -- @see timer.start_new
+-- @function gears.timer.weak_start_new
 function timer.weak_start_new(timeout, callback)
     local indirection = setmetatable({}, { __mode = "v" })
     indirection.callback = callback
@@ -158,6 +173,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
 function timer.delayed_call(callback, ...)
     assert(type(callback) == "function", "callback must be a function, got: " .. type(callback))
     table.insert(delayed_calls, { callback, ... })

lib/menubar/init.lua

@@ -46,34 +46,47 @@ local compute_text_width = menubar.utils.compute_text_width
 --- When true the .desktop files will be reparsed only when the
 -- extension is initialized. Use this if menubar takes much time to
 -- open.
+-- @tfield[opt=true] boolean cache_entries
 menubar.cache_entries = true
 
 --- When true the categories will be shown alongside application
 -- entries.
+-- @tfield[opt=true] boolean show_categories
 menubar.show_categories = true
 
 --- Specifies the geometry of the menubar. This is a table with the keys
 -- x, y, width and height. Missing values are replaced via the screen's
 -- geometry. However, missing height is replaced by the font size.
+-- @table geometry
+-- @tfield number geometry.x A forced horizontal position
+-- @tfield number geometry.y A forced vertical position
+-- @tfield number geometry.width A forced width
+-- @tfield number geometry.height A forced height
 menubar.geometry = { width = nil,
                      height = nil,
                      x = nil,
                      y = nil }
+
 --- Width of blank space left in the right side.
+-- @tfield number right_margin
 menubar.right_margin = theme.xresources.apply_dpi(8)
 
 --- Label used for "Next page", default "▶▶".
+-- @tfield[opt="▶▶"] string right_label
 menubar.right_label = "▶▶"
 
 --- Label used for "Previous page", default "◀◀".
+-- @tfield[opt="◀◀"] string left_label
 menubar.left_label = "◀◀"
 
 -- awful.widget.common.list_update adds three times a margin of dpi(4)
 -- for each item:
+-- @tfield number list_interspace
 local list_interspace = theme.xresources.apply_dpi(4) * 3
 
 --- Allows user to specify custom parameters for prompt.run function
 -- (like colors).
+-- @see awful.prompt
 menubar.prompt_args = {}
 
 -- Private section

lib/wibox/widget/progressbar.lua

@@ -69,13 +69,13 @@ local data = setmetatable({}, { __mode = "k" })
 -- @param value The value.
 
 --- The progressbar background color.
--- @beautiful beautiful.graph_bg
+-- @beautiful beautiful.progressbar_bg
 
 --- The progressbar foreground color.
--- @beautiful beautiful.graph_fg
+-- @beautiful beautiful.progressbar_fg
 
 --- The progressbar border color.
--- @beautiful beautiful.graph_border_color
+-- @beautiful beautiful.progressbar_border_color
 
 local properties = { "width", "height", "border_color",
                      "color", "background_color",

luaa.c

@@ -296,18 +296,48 @@ luaA_fixups(lua_State *L)
     lua_setglobal(L, "selection");
 }
 
-/** awesome global table.
+
- * @field version The version of awesome.
+/**
- * @field release The release name of awesome.
+ * The version of awesome.
- * @field conffile The configuration file which has been loaded.
+ * @tfield string version
- * @field startup True if we are still in startup, false otherwise.
- * @field startup_errors Error message for errors that occured during
- *  startup.
- * @field composite_manager_running True if a composite manager is running.
- * @field unix_signal Table mapping between signal numbers and signal identifiers.
- * @field hostname The hostname of the computer on which we are running.
- * @table awesome
  */
+
+/**
+ * The release name of awesome.
+ * @tfield string release
+ */
+
+/**
+ * The configuration file which has been loaded.
+ * @tfield string conffile
+ */
+
+/**
+ * True if we are still in startup, false otherwise.
+ * @tfield boolean startup
+ */
+
+/**
+ * Error message for errors that occured during
+ *  startup.
+ * @tfield string startup_errors
+ */
+
+/**
+ * True if a composite manager is running.
+ * @tfield boolean composite_manager_running
+ */
+
+/**
+ * Table mapping between signal numbers and signal identifiers.
+ * @tfield table unix_signal
+ */
+
+/**
+ * The hostname of the computer on which we are running.
+ * @tfield string hostname
+ */
+
 static int
 luaA_awesome_index(lua_State *L)
 {

mousegrabber.c

@@ -83,6 +83,11 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask)
  * The function is called with one argument:
  * a table containing modifiers pointer coordinates.
  *
+ * The list of valid cusrors are:
+ *
+ *@DOC_cursor_c_COMMON@
+ *
+ *
  * @param func A callback function as described above.
  * @param cursor The name of a X cursor to use while grabbing.
  * @function run

root.c

@@ -361,7 +361,11 @@ luaA_root_buttons(lua_State *L)
     return 1;
 }
 
-/** Set the root cursor.
+/** Set the root cursor
+ *
+ * The possible values are:
+ *
+ *@DOC_cursor_c_COMMON@
  *
  * @param cursor_name A X cursor name.
  * @function cursor

tests/examples/shims/_common_template.lua

@@ -1,7 +1,7 @@
 return function(_, _, luacovpath)
 
     -- Set the global shims
-    -- luacheck: globals awesome root tag screen client mouse drawin
+    -- luacheck: globals awesome root tag screen client mouse drawin button
     awesome = require( "awesome" )
     root    = require( "root"    )
     tag     = require( "tag"     )
@@ -9,6 +9,7 @@ return function(_, _, luacovpath)
     client  = require( "client"  )
     mouse   = require( "mouse"   )
     drawin  = require( "drawin"  )
+    button  = require( "button"  )
 
     -- Force luacheck to be silent about setting those as unused globals
     assert(awesome and root and tag and screen and client and mouse)

tests/examples/shims/button.lua

@@ -0,0 +1,3 @@
+return function() return {
+    connect_signal = function() end
+} end

tests/examples/wibox/layout/template.lua

@@ -5,14 +5,15 @@ local wibox     = require( "wibox"         )
 local surface   = require( "gears.surface" )
 local color     = require( "gears.color"   )
 local beautiful = require( "beautiful"     )
+local unpack    = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1)
 
 -- Create a generic rectangle widget to show layout disposition
-local function generic_widget(text)
+local function generic_widget(text, col)
     return {
         {
             {
                 draw = function(_, _, cr, width, height)
-                    cr:set_source(color(beautiful.bg_normal))
+                    cr:set_source(color(col or beautiful.bg_normal))
                     cr:set_line_width(3)
                     cr:rectangle(0, 0, width, height)
                     cr:fill_preserve()
@@ -34,8 +35,63 @@ local function generic_widget(text)
     }
 end
 
+local names = {
+    "first"  ,
+    "second" ,
+    "third"  ,
+    "fourth" ,
+    "fifth"  ,
+    "sixth"  ,
+    "seventh",
+    "eighth" ,
+    "ninth"  ,
+}
+
+-- Generic template to create "before and after" for layout mutators
+local function generic_before_after(layout, layout_args, count, method, method_args)
+    local ls = {}
+
+    -- Create the layouts
+    for i=1, 2 do
+        local args = {layout = layout}
+
+        -- In case the layout change the array (it is technically not forbidden)
+        for k,v in pairs(layout_args) do
+            args[k] = v
+        end
+
+        local l = wibox.layout(args)
+        for j=1, count or 3 do
+            l:add(wibox.widget(generic_widget(names[j] or "N/A")))
+        end
+
+        ls[i] = l
+    end
+
+    -- Mutate
+    if type(method) == "function" then
+        method(ls[2], unpack(method_args or {}))
+    else
+        ls[2][method](ls[2], unpack(method_args or {}))
+    end
+
+    return wibox.layout {
+        {
+            markup = "<b>Before:</b>",
+            widget = wibox.widget.textbox,
+        },
+        ls[1],
+        {
+            markup = "<b>After:</b>",
+            widget = wibox.widget.textbox,
+        },
+        ls[2],
+        layout = wibox.layout.fixed.vertical
+    }
+end
+
 -- Let the test request a size and file format
-local widget, w, h = loadfile(file_path)(generic_widget)
+local widget, w, h = loadfile(file_path)(generic_widget, generic_before_after)
 
 -- Emulate the event loop for 10 iterations
 for _ = 1, 10 do