doc(awful: hotkeys_popup): change variable names to fix ldoc result and add one missing docstring (#1396)

lib/awful/hotkeys_popup/widget.lua

@@ -33,23 +33,25 @@ function markup.bg(color, text)
     return '<span background="' .. tostring(color) .. '">' .. tostring(text) .. '</span>'
 end
 
-local widget_module = {
+local widget = {
     group_rules = {},
 }
 
 --- Don't show hotkeys without descriptions.
-widget_module.hide_without_description = true
+widget.hide_without_description = true
 
 --- Merge hotkey records into one if they have the same modifiers and
 -- description.
-widget_module.merge_duplicates = true
+widget.merge_duplicates = true
 
 
-function widget_module.new()
+--- Create an instance of widget with hotkeys help.
-local widget = {
+-- @return widget instance.
-    hide_without_description = widget_module.hide_without_description,
+function widget.new()
-    merge_duplicates = widget_module.merge_duplicates,
+    local widget_instance = {
-    group_rules = awful.util.table.clone(widget_module.group_rules),
+        hide_without_description = widget.hide_without_description,
+        merge_duplicates = widget.merge_duplicates,
+        group_rules = awful.util.table.clone(widget.group_rules),
         title_font = "Monospace Bold 9",
         description_font = "Monospace 8",
         width = dpi(1200),
@@ -99,16 +101,16 @@ local widget = {
             ['#21']="=",
             Control="Ctrl"
         },
-}
+    }
 
-local cached_wiboxes = {}
+    local cached_wiboxes = {}
-local cached_awful_keys = nil
+    local cached_awful_keys = nil
-local colors_counter = {}
+    local colors_counter = {}
-local colors = beautiful.xresources.get_current_theme()
+    local colors = beautiful.xresources.get_current_theme()
-local group_list = {}
+    local group_list = {}
 
 
-local function get_next_color(id)
+    local function get_next_color(id)
         id = id or "default"
         if colors_counter[id] then
             colors_counter[id] = math.fmod(colors_counter[id] + 1, 15) + 1
@@ -116,22 +118,22 @@ local function get_next_color(id)
             colors_counter[id] = 1
         end
         return colors["color"..tostring(colors_counter[id], 15)]
-end
+    end
 
 
-local function join_plus_sort(modifiers)
+    local function join_plus_sort(modifiers)
         if #modifiers<1 then return "none" end
         table.sort(modifiers)
         return table.concat(modifiers, '+')
-end
+    end
 
 
-local function add_hotkey(key, data, target)
+    local function add_hotkey(key, data, target)
-    if widget.hide_without_description and not data.description then return end
+        if widget_instance.hide_without_description and not data.description then return end
 
         local readable_mods = {}
         for _, mod in ipairs(data.mod) do
-        table.insert(readable_mods, widget.labels[mod] or mod)
+            table.insert(readable_mods, widget_instance.labels[mod] or mod)
         end
         local joined_mods = join_plus_sort(readable_mods)
 
@@ -139,7 +141,7 @@ local function add_hotkey(key, data, target)
         group_list[group] = true
         if not target[group] then target[group] = {} end
         local new_key = {
-        key = (widget.labels[key] or key),
+            key = (widget_instance.labels[key] or key),
             mod = joined_mods,
             description = data.description
         }
@@ -147,7 +149,7 @@ local function add_hotkey(key, data, target)
         if not target[group][index] then
             target[group][index] = new_key
         else
-        if widget.merge_duplicates and joined_mods == target[group][index].mod then
+            if widget_instance.merge_duplicates and joined_mods == target[group][index].mod then
                 target[group][index].key = target[group][index].key .. "/" .. new_key.key
             else
                 while target[group][index] do
@@ -156,10 +158,10 @@ local function add_hotkey(key, data, target)
                 target[group][index] = new_key
             end
         end
-end
+    end
 
 
-local function sort_hotkeys(target)
+    local function sort_hotkeys(target)
         -- @TODO: add sort by 12345qwertyasdf etc
         for group, _ in pairs(group_list) do
             if target[group] then
@@ -174,10 +176,10 @@ local function sort_hotkeys(target)
                 target[group] = sorted_table
             end
         end
-end
+    end
 
 
-local function import_awful_keys()
+    local function import_awful_keys()
         if cached_awful_keys then
             return
         end
@@ -186,15 +188,15 @@ local function import_awful_keys()
             add_hotkey(data.key, data, cached_awful_keys)
         end
         sort_hotkeys(cached_awful_keys)
-end
+    end
 
 
-local function group_label(group, color)
+    local function group_label(group, color)
         local textbox = wibox.widget.textbox(
-        markup.font(widget.title_font,
+            markup.font(widget_instance.title_font,
                 markup.bg(
-                color or (widget.group_rules[group] and
+                    color or (widget_instance.group_rules[group] and
-                    widget.group_rules[group].color or get_next_color("group_title")
+                        widget_instance.group_rules[group].color or get_next_color("group_title")
                     ),
                     markup.fg(beautiful.bg_normal or "#000000", " "..group.." ")
                 )
@@ -202,31 +204,31 @@ local function group_label(group, color)
         )
         local margin = wibox.container.margin()
         margin:set_widget(textbox)
-    margin:set_top(widget.group_margin)
+        margin:set_top(widget_instance.group_margin)
         return margin
-end
+    end
 
-local function get_screen(s)
+    local function get_screen(s)
         return s and capi.screen[s]
-end
+    end
 
-local function create_wibox(s, available_groups)
+    local function create_wibox(s, available_groups)
         s = get_screen(s)
 
         local wa = s.workarea
-    local height = (widget.height < wa.height) and widget.height or
+        local height = (widget_instance.height < wa.height) and widget_instance.height or
-        (wa.height - widget.border_width * 2)
+            (wa.height - widget_instance.border_width * 2)
-    local width = (widget.width < wa.width) and widget.width or
+        local width = (widget_instance.width < wa.width) and widget_instance.width or
-        (wa.width - widget.border_width * 2)
+            (wa.width - widget_instance.border_width * 2)
 
         -- arrange hotkey groups into columns
-    local line_height = beautiful.get_font_height(widget.title_font)
+        local line_height = beautiful.get_font_height(widget_instance.title_font)
-    local group_label_height = line_height + widget.group_margin
+        local group_label_height = line_height + widget_instance.group_margin
         -- -1 for possible pagination:
         local max_height_px = height - group_label_height
         local column_layouts = {}
         for _, group in ipairs(available_groups) do
-        local keys = cached_awful_keys[group] or widget.additional_hotkeys[group]
+            local keys = cached_awful_keys[group] or widget_instance.additional_hotkeys[group]
             local joined_descriptions = ""
             for i, key in ipairs(keys) do
                 joined_descriptions = joined_descriptions .. key.description .. (i~=#keys and "\n" or "")
@@ -256,7 +258,7 @@ local function create_wibox(s, available_groups)
                     table.insert(((i<available_height_items) and new_keys or overlap_leftovers), keys[i])
                 end
                 keys = new_keys
-            table.insert(keys, {key=markup.fg(widget.modifiers_color, "▽"), description=""})
+                table.insert(keys, {key=markup.fg(widget_instance.modifiers_color, "▽"), description=""})
             end
             if not current_column then
                 current_column = {layout=wibox.layout.fixed.vertical()}
@@ -274,11 +276,11 @@ local function create_wibox(s, available_groups)
                         modifiers = ""
                     else
                         length = length + string.len(modifiers) + 1 -- +1 for "+" character
-                    modifiers = markup.fg(widget.modifiers_color, modifiers.."+")
+                        modifiers = markup.fg(widget_instance.modifiers_color, modifiers.."+")
                     end
-                local rendered_hotkey = markup.font(widget.title_font,
+                    local rendered_hotkey = markup.font(widget_instance.title_font,
                         modifiers .. (key.key or "") .. " "
-                ) .. markup.font(widget.description_font,
+                    ) .. markup.font(widget_instance.description_font,
                         key.description or ""
                     )
                     if length > max_label_width then
@@ -289,7 +291,7 @@ local function create_wibox(s, available_groups)
                     end
                 current_column.layout:add(wibox.widget.textbox(joined_labels))
                 local max_width = compute_textbox_width(wibox.widget.textbox(max_label_content), s) +
-                                                widget.group_margin
+                                                    widget_instance.group_margin
                 if not current_column.max_width or max_width > current_column.max_width then
                     current_column.max_width = max_width
                 end
@@ -329,7 +331,7 @@ local function create_wibox(s, available_groups)
             end
             local column_margin = wibox.container.margin()
             column_margin:set_widget(item.layout)
-        column_margin:set_left(widget.group_margin)
+            column_margin:set_left(widget_instance.group_margin)
             columns:add(column_margin)
             previous_page_last_layout = item.layout
         end
@@ -338,12 +340,12 @@ local function create_wibox(s, available_groups)
         local mywibox = wibox({
             ontop = true,
             opacity = beautiful.notification_opacity or 1,
-        border_width = widget.border_width,
+            border_width = widget_instance.border_width,
             border_color = beautiful.fg_normal,
         })
         mywibox:geometry({
-        x = wa.x + math.floor((wa.width - width - widget.border_width*2) / 2),
+            x = wa.x + math.floor((wa.width - width - widget_instance.border_width*2) / 2),
-        y = wa.y + math.floor((wa.height - height - widget.border_width*2) / 2),
+            y = wa.y + math.floor((wa.height - height - widget_instance.border_width*2) / 2),
             width = width,
             height = height,
         })
@@ -374,13 +376,13 @@ local function create_wibox(s, available_groups)
         end
 
         return widget_obj
-end
+    end
 
 
---- Show popup with hotkeys help.
+    --- Show popup with hotkeys help.
--- @tparam[opt] client c Client.
+    -- @tparam[opt] client c Client.
--- @tparam[opt] screen s Screen.
+    -- @tparam[opt] screen s Screen.
-function widget.show_help(c, s)
+    function widget_instance.show_help(c, s)
         import_awful_keys()
         c = c or capi.client.focus
         s = s or (c and c.screen or awful.screen.focused())
@@ -388,7 +390,7 @@ function widget.show_help(c, s)
         local available_groups = {}
         for group, _ in pairs(group_list) do
             local need_match
-        for group_name, data in pairs(widget.group_rules) do
+            for group_name, data in pairs(widget_instance.group_rules) do
                 if group_name==group and (
                     data.rule or data.rule_any or data.except or data.except_any
                 ) then
@@ -429,13 +431,13 @@ function widget.show_help(c, s)
                 end
             end
         end)
-end
+    end
 
 
---- Add hotkey descriptions for third-party applications.
+    --- Add hotkey descriptions for third-party applications.
--- @tparam table hotkeys Table with bindings,
+    -- @tparam table hotkeys Table with bindings,
--- see `awful.hotkeys_popup.key.vim` as an example.
+    -- see `awful.hotkeys_popup.key.vim` as an example.
-function widget.add_hotkeys(hotkeys)
+    function widget_instance.add_hotkeys(hotkeys)
         for group, bindings in pairs(hotkeys) do
             for _, binding in ipairs(bindings) do
                 local modifiers = binding.modifiers
@@ -445,29 +447,29 @@ function widget.add_hotkeys(hotkeys)
                         mod=modifiers,
                         description=description,
                         group=group},
-                widget.additional_hotkeys
+                    widget_instance.additional_hotkeys
                 )
                 end
             end
         end
-    sort_hotkeys(widget.additional_hotkeys)
+        sort_hotkeys(widget_instance.additional_hotkeys)
-end
+    end
 
 
-return widget
+    return widget_instance
 end
 
 local function get_default_widget()
-    if not widget_module.default_widget then
+    if not widget.default_widget then
-        widget_module.default_widget = widget_module.new()
+        widget.default_widget = widget.new()
     end
-    return widget_module.default_widget
+    return widget.default_widget
 end
 
 --- Show popup with hotkeys help (default widget instance will be used).
 -- @tparam[opt] client c Client.
 -- @tparam[opt] screen s Screen.
-function widget_module.show_help(...)
+function widget.show_help(...)
     return get_default_widget().show_help(...)
 end
 
@@ -475,10 +477,10 @@ end
 -- (default widget instance will be used).
 -- @tparam table hotkeys Table with bindings,
 -- see `awful.hotkeys_popup.key.vim` as an example.
-function widget_module.add_hotkeys(...)
+function widget.add_hotkeys(...)
     return get_default_widget().add_hotkeys(...)
 end
 
-return widget_module
+return widget
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80