Lots of random documentation fixes

This is mostly about mis-named parameters, but also other small things.

Signed-off-by: Uli Schlachter <psychon@znc.in>

lib/awful/key.lua.in

@@ -30,7 +30,7 @@ local ignore_modifiers = { "Lock", "Mod2" }
 -- ignored by default by this function), creating key binding with this function
 -- will return 2 key objects: one with CapsLock on, and the other one with
 -- CapsLock off.
--- @see capi.key
+-- @see key
 -- @return A table with one or several key objects.
 function key.new(mod, _key, press, release)
     local ret = {}
@@ -49,7 +49,7 @@ function key.new(mod, _key, press, release)
 end
 
 --- Compare a key object with modifiers and key.
--- @param key The key object.
+-- @param _key The key object.
 -- @param pressed_mod The modifiers to compare with.
 -- @param pressed_key The key to compare with.
 function key.match(_key, pressed_mod, pressed_key)

lib/awful/layout/init.lua.in

@@ -57,7 +57,8 @@ function layout.inc(layouts, i)
 end
 
 --- Set the layout function of the current tag.
--- @param layout Layout name.
+-- @param _layout Layout name.
+-- @param t The tag to modify, if null tag.selected() is used.
 function layout.set(_layout, t)
     t = t or tag.selected()
     tag.setproperty(t, "layout", _layout)

lib/awful/menu.lua.in

@@ -216,9 +216,9 @@ local function grabber(_menu, mod, key, event)
 end
 
 
-function menu.exec(_menu, num, opts)
+function menu:exec(num, opts)
     opts = opts or {}
-    local item = _menu.items[num]
+    local item = self.items[num]
     if not item then return end
     local cmd = item.cmd
     if type(cmd) == "table" then
@@ -229,41 +229,41 @@ function menu.exec(_menu, num, opts)
             end
             return
         end
-        if not _menu.child[num] then
-            _menu.child[num] = menu.new(cmd, _menu)
+        if not self.child[num] then
+            self.child[num] = menu.new(cmd, self)
         end
         local can_invoke_action = opts.exec and
             action and type(action) == "function" and
-            (not opts.mouse or (opts.mouse and (_menu.auto_expand or
-            (_menu.active_child == _menu.child[num] and
-            _menu.active_child.wibox.visible))))
+            (not opts.mouse or (opts.mouse and (self.auto_expand or
+            (self.active_child == self.child[num] and
+            self.active_child.wibox.visible))))
         if can_invoke_action then
-            local visible = action(_menu.child[num], item)
+            local visible = action(self.child[num], item)
             if not visible then
-                menu.get_root(_menu):hide()
+                menu.get_root(self):hide()
                 return
             else
-                _menu.child[num]:update()
+                self.child[num]:update()
             end
         end
-        if _menu.active_child and _menu.active_child ~= _menu.child[num] then
-            _menu.active_child:hide()
+        if self.active_child and self.active_child ~= self.child[num] then
+            self.active_child:hide()
         end
-        _menu.active_child = _menu.child[num]
-        if not _menu.active_child.visible then
-            _menu.active_child:show()
+        self.active_child = self.child[num]
+        if not self.active_child.visible then
+            self.active_child:show()
         end
     elseif type(cmd) == "string" then
-        menu.get_root(_menu):hide()
+        menu.get_root(self):hide()
         util.spawn(cmd)
     elseif type(cmd) == "function" then
-        local visible, action = cmd(item, _menu)
+        local visible, action = cmd(item, self)
         if not visible then
-            menu.get_root(_menu):hide()
+            menu.get_root(self):hide()
         else
-            _menu:update()
-            if _menu.items[num] then
-                _menu:item_enter(num, opts)
+            self:update()
+            if self.items[num] then
+                self:item_enter(num, opts)
             end
         end
         if action and type(action) == "function" then
@@ -272,35 +272,35 @@ function menu.exec(_menu, num, opts)
     end
 end
 
-function menu.item_enter(_menu, num, opts)
+function menu:item_enter(num, opts)
     opts = opts or {}
-    local item = _menu.items[num]
-    if num == nil or _menu.sel == num or not item then
+    local item = self.items[num]
+    if num == nil or self.sel == num or not item then
         return
-    elseif _menu.sel then
-        _menu:item_leave(_menu.sel)
+    elseif self.sel then
+        self:item_leave(self.sel)
     end
     --print("sel", num, menu.sel, item.theme.bg_focus)
     item._background:set_fg(item.theme.fg_focus)
     item._background:set_bg(item.theme.bg_focus)
-    _menu.sel = num
+    self.sel = num
 
-    if _menu.auto_expand and opts.hover then
-        if _menu.active_child then
-            _menu.active_child:hide()
-            _menu.active_child = nil
+    if self.auto_expand and opts.hover then
+        if self.active_child then
+            self.active_child:hide()
+            self.active_child = nil
         end
 
         if type(item.cmd) == "table" then
-            _menu:exec(num, opts)
+            self:exec(num, opts)
         end
     end
 end
 
 
-function menu.item_leave(_menu, num)
+function menu:item_leave(num)
     --print("leave", num)
-    local item = _menu.items[num]
+    local item = self.items[num]
     if item then
         item._background:set_fg(item.theme.fg_normal)
         item._background:set_bg(item.theme.bg_normal)
@@ -309,77 +309,72 @@ end
 
 
 --- Show a menu.
--- @param _menu The menu to show.
 -- @param args.coords Menu position defaulting to mouse.coords()
-function menu.show(_menu, args)
+function menu:show(args)
     args = args or {}
     local coords = args.coords or nil
     local screen_index = capi.mouse.screen
 
-    if not set_size(_menu) then return end
-    set_coords(_menu, screen_index, coords)
+    if not set_size(self) then return end
+    set_coords(self, screen_index, coords)
 
-    keygrabber.run(_menu._keygrabber)
-    _menu.wibox.visible = true
+    keygrabber.run(self._keygrabber)
+    self.wibox.visible = true
 end
 
 --- Hide a menu popup.
--- @param _menu The menu to hide.
-function menu.hide(_menu)
+function menu:hide()
     -- Remove items from screen
-    for i = 1, #_menu.items do
-        _menu:item_leave(i)
+    for i = 1, #self.items do
+        self:item_leave(i)
     end
-    if _menu.active_child then
-        _menu.active_child:hide()
-        _menu.active_child = nil
+    if self.active_child then
+        self.active_child:hide()
+        self.active_child = nil
     end
-    _menu.sel = nil
+    self.sel = nil
 
-    keygrabber.stop(_menu._keygrabber)
-    _menu.wibox.visible = false
+    keygrabber.stop(self._keygrabber)
+    self.wibox.visible = false
 end
 
 --- Toggle menu visibility.
 -- @param _menu The menu to show if it's hidden, or to hide if it's shown.
 -- @param args.coords Menu position {x,y}
-function menu.toggle(_menu, args)
-    if _menu.wibox.visible then
-        _menu:hide()
+function menu:toggle(args)
+    if self.wibox.visible then
+        self:hide()
     else
-        _menu:show(args)
+        self:show(args)
     end
 end
 
 --- Update menu content
--- @param _menu The mnenu to update.
-function menu.update(_menu)
-    if _menu.wibox.visible then
-        _menu:show({ coords = { x = _menu.x, y = _menu.y } })
+function menu:update()
+    if self.wibox.visible then
+        self:show({ coords = { x = self.x, y = self.y } })
     end
 end
 
 
 --- Get the elder parent so for example when you kill
 -- it, it will destroy the whole family.
--- @param _menu The sub menu of the menu family.
-function menu.get_root(_menu)
-    return _menu.parent and menu.get_root(_menu.parent) or _menu
+function menu:get_root()
+    return self.parent and menu.get_root(self.parent) or self
 end
 
---- Add a new menu entry
--- @param _menu The parent menu
+--- Add a new menu entry.
+-- args.new (Default: awful.menu.entry) The menu entry constructor.
+-- args.theme (Optional) The menu entry theme.
+-- args.* params needed for the menu entry constructor.
 -- @param args The item params
--- @param args.new (Default: awful.menu.entry) The menu entry constructor
--- @param args.theme (Optional) The menu entry theme
--- @param args.* params needed for the menu entry constructor
 -- @param index (Optional) the index where the new entry will inserted
-function menu.add(_menu, args, index)
+function menu:add(args, index)
     if not args then return end
-    local theme = load_theme(args.theme or {}, _menu.theme)
+    local theme = load_theme(args.theme or {}, self.theme)
     args.theme = theme
     args.new = args.new or menu.entry
-    local success, item = pcall(args.new, _menu, args)
+    local success, item = pcall(args.new, self, args)
     if not success then
         print("Error while creating menu entry: " .. item)
         return
@@ -388,7 +383,7 @@ function menu.add(_menu, args, index)
         print("Error while checking menu entry: no property widget found.")
         return
     end
-    item.parent = _menu
+    item.parent = self
     item.theme = item.theme or theme
     item.width = item.width or theme.width
     item.height = item.height or theme.height
@@ -401,29 +396,29 @@ function menu.add(_menu, args, index)
 
     -- Create bindings
     item._background:buttons(util.table.join(
-        button({}, 3, function () _menu:hide() end),
+        button({}, 3, function () self:hide() end),
         button({}, 1, function ()
-            local num = util.table.hasitem(_menu.items, item)
-            _menu:item_enter(num, { mouse = true })
-            _menu:exec(num, { exec = true, mouse = true })
+            local num = util.table.hasitem(self.items, item)
+            self:item_enter(num, { mouse = true })
+            self:exec(num, { exec = true, mouse = true })
         end )))
 
 
     item._mouse = function ()
-        local num = util.table.hasitem(_menu.items, item)
-        _menu:item_enter(num, { hover = true, moue = true })
+        local num = util.table.hasitem(self.items, item)
+        self:item_enter(num, { hover = true, moue = true })
     end
     item.widget:connect_signal("mouse::enter", item._mouse)
 
     if index then
-        _menu.layout:reset()
-        table.insert(_menu.items, index, item)
-        for _, i in ipairs(_menu.items) do
-            _menu.layout:add(i._background)
+        self.layout:reset()
+        table.insert(self.items, index, item)
+        for _, i in ipairs(self.items) do
+            self.layout:add(i._background)
         end
     else
-        table.insert(_menu.items, item)
-        _menu.layout:add(item._background)
+        table.insert(self.items, item)
+        self.layout:add(item._background)
     end
     return item
 end
@@ -431,29 +426,29 @@ end
 -- Delete menu entry at given position
 -- @param _menu The menu
 -- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself
-function menu.delete(_menu, num)
+function menu:delete(num)
     if type(num) == "table" then
-        num = util.table.hasitem(_menu.items, num)
+        num = util.table.hasitem(self.items, num)
     end
-    local item = _menu.items[num]
+    local item = self.items[num]
     if not item then return end
     item.widget:disconnect_signal("mouse::enter", item._mouse)
     item.widget.visible = false
-    table.remove(_menu.items, num)
-    if _menu.sel == num then
-        _menu:item_leave(_menu.sel)
-        _menu.sel = nil
+    table.remove(self.items, num)
+    if self.sel == num then
+        self:item_leave(self.sel)
+        self.sel = nil
     end
-    _menu.layout:reset()
-    for _, i in ipairs(_menu.items) do
-        _menu.layout:add(i._background)
+    self.layout:reset()
+    for _, i in ipairs(self.items) do
+        self.layout:add(i._background)
     end
-    if _menu.child[num] then
-         _menu.child[num]:hide()
-        if _menu.active_child == _menu.child[num] then
-            _menu.active_child = nil
+    if self.child[num] then
+         self.child[num]:hide()
+        if self.active_child == self.child[num] then
+            self.active_child = nil
         end
-        table.remove(_menu.child, num)
+        table.remove(self.child, num)
     end
 end
 
@@ -462,8 +457,8 @@ end
 --- Build a popup menu with running clients and shows it.
 -- @param _menu Menu table, see new() function for more informations
 -- @return The menu.
-function menu.clients(_menu, args) -- FIXME crude api
-    _menu = _menu or {}
+function menu:clients(args) -- FIXME crude api
+    _menu = self or {}
     local cls = capi.client.get()
     local cls_t = {}
     for k, c in pairs(cls) do

lib/awful/rules.lua.in

@@ -129,7 +129,7 @@ end
 
 --- Check if a client match a rule. Multiple clients can be matched
 -- @param c The client.
--- @param rules The rule to check.
+-- @param rule The rule to check.
 -- @return True if at least one rule is matched, false otherwise.
 function rules.match_any(c, rule)
     if not rule then return false end

lib/awful/screen.lua.in

@@ -66,7 +66,7 @@ end
 
 --- Give the focus to a screen, and move pointer, by physical position relative to current screen.
 -- @param dir The direction, can be either "up", "down", "left" or "right".
--- @param screen Screen number.
+-- @param _screen Screen number.
 function screen.focus_bydirection(dir, _screen)
     local sel = _screen or capi.mouse.screen
     if sel then
@@ -90,7 +90,7 @@ function screen.focus_relative(i)
 end
 
 --- Get or set the screen padding.
--- @param screen The screen object to change the padding on
+-- @param _screen The screen object to change the padding on
 -- @param padding The padding, an table with 'top', 'left', 'right' and/or
 -- 'bottom'. Can be nil if you only want to retrieve padding
 function screen.padding(_screen, padding)

lib/awful/tag.lua.in

@@ -35,6 +35,8 @@ tag.history.limit = 20
 
 --- Move a tag to an absolute position in the screen[]:tags() table.
 -- @param new_index Integer absolute position in the table to insert.
+-- @param target_tag The tag that should be moved. If null, the currently
+-- selected tag is used.
 function tag.move(new_index, target_tag)
     local target_tag = target_tag or tag.selected()
     local scr = tag.getscreen(target_tag)
@@ -97,7 +99,7 @@ end
 
 --- Find a suitable fallback tag.
 -- @param screen The screen number to look for a tag on. [mouse.screen]
--- @param target A table of tags we consider unacceptable. [selectedlist(scr)]
+-- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)]
 function tag.find_fallback(screen, invalids)
     local scr = screen or capi.mouse.screen
     local t = invalids or tag.selectedlist(scr)
@@ -282,6 +284,7 @@ end
 
 --- Set master width factor.
 -- @param mwfact Master width factor.
+-- @param t The tag to modify, if null tag.selected() is used.
 function tag.setmwfact(mwfact, t)
     local t = t or tag.selected()
     if mwfact >= 0 and mwfact <= 1 then
@@ -291,6 +294,7 @@ end
 
 --- Increase master width factor.
 -- @param add Value to add to master width factor.
+-- @param t The tag to modify, if null tag.selected() is used.
 function tag.incmwfact(add, t)
     tag.setmwfact(tag.getmwfact(t) + add, t)
 end
@@ -321,6 +325,7 @@ end
 
 --- Increase the number of master windows.
 -- @param add Value to add to number of master windows.
+-- @param t The tag to modify, if null tag.selected() is used.
 function tag.incnmaster(add, t)
     tag.setnmaster(tag.getnmaster(t) + add, t)
 end
@@ -328,14 +333,14 @@ end
 
 --- Set the tag icon
 -- @param icon the icon to set, either path or image object
--- @param tag the tag
+-- @param _tag the tag
 function tag.seticon(icon, _tag)
     local _tag = _tag or tag.selected()
     tag.setproperty(_tag, "icon", icon)
 end
 
 --- Get the tag icon
--- @param t the tag
+-- @param _tag the tag
 function tag.geticon(_tag)
     local _tag = _tag or tag.selected()
     return tag.getproperty(_tag, "icon")
@@ -343,6 +348,7 @@ end
 
 --- Set number of column windows.
 -- @param ncol The number of column.
+-- @param t The tag to modify, if null tag.selected() is used.
 function tag.setncol(ncol, t)
     local t = t or tag.selected()
     if ncol >= 1 then
@@ -359,6 +365,7 @@ end
 
 --- Increase number of column windows.
 -- @param add Value to add to number of column windows.
+-- @param t The tag to modify, if null tag.selected() is used.
 function tag.incncol(add, t)
     tag.setncol(tag.getncol(t) + add, t)
 end
@@ -468,7 +475,7 @@ function tag.getdata(_tag)
 end
 
 --- Get a tag property.
--- @param tag The tag.
+-- @param _tag The tag.
 -- @param prop The property name.
 -- @return The property.
 function tag.getproperty(_tag, prop)
@@ -480,7 +487,7 @@ end
 --- Set a tag property.
 -- This properties are internal to awful. Some are used to draw taglist, or to
 -- handle layout, etc.
--- @param tag The tag.
+-- @param _tag The tag.
 -- @param prop The property name.
 -- @param value The value.
 function tag.setproperty(_tag, prop, value)

lib/awful/wibox.lua.in

@@ -105,6 +105,7 @@ end
 -- will be attached.
 -- @param wibox The wibox to attach.
 -- @param position The position of the wibox: top, bottom, left or right.
+-- @param screen TODO, this seems to be unused
 function awfulwibox.attach(wibox, position, screen)
     -- Store wibox as attached in a weak-valued table
     local wibox_prop_table
@@ -202,7 +203,7 @@ function awfulwibox.stretch(wibox, screen)
 end
 
 --- Create a new wibox and attach it to a screen edge.
--- @see capi.wibox
+-- @see wibox
 -- @param args A table with standard arguments to wibox() creator.
 -- You can add also position key with value top, bottom, left or right.
 -- You can also use width or height in % and set align to center, right or left.

lib/awful/widget/graph.lua.in

@@ -161,7 +161,7 @@ function graph.fit(_graph, width, height)
 end
 
 --- Add a value to the graph
--- @param graph The graph.
+-- @param _graph The graph.
 -- @param value The value between 0 and 1.
 -- @param group The stack color group index.
 local function add_value(_graph, value, group)
@@ -199,25 +199,24 @@ end
 
 
 --- Set the graph height.
--- @param graph The graph.
 -- @param height The height to set.
-function graph.set_height(_graph, height)
+function graph:set_height(height)
     if height >= 5 then
-        data[_graph].height = height
-        _graph:emit_signal("widget::updated")
+        data[self].height = height
+        self:emit_signal("widget::updated")
     end
-    return _graph
+    return self
 end
 
 --- Set the graph width.
 -- @param graph The graph.
 -- @param width The width to set.
-function graph.set_width(_graph, width)
+function graph:set_width(width)
     if width >= 5 then
-        data[_graph].width = width
-        _graph:emit_signal("widget::updated")
+        data[self].width = width
+        self:emit_signal("widget::updated")
     end
-    return _graph
+    return self
 end
 
 -- Build properties function

lib/awful/widget/progressbar.lua.in

@@ -158,32 +158,29 @@ function progressbar.fit(pbar, width, height)
 end
 
 --- Set the progressbar value.
--- @param pbar The progress bar.
 -- @param value The progress bar value between 0 and 1.
-function progressbar.set_value(pbar, value)
+function progressbar:set_value(value)
     local value = value or 0
-    local max_value = data[pbar].max_value
-    data[pbar].value = math.min(max_value, math.max(0, value))
-    pbar:emit_signal("widget::updated")
-    return pbar
+    local max_value = data[self].max_value
+    data[self].value = math.min(max_value, math.max(0, value))
+    self:emit_signal("widget::updated")
+    return self
 end
 
 --- Set the progressbar height.
--- @param progressbar The progressbar.
 -- @param height The height to set.
-function progressbar.set_height(_progressbar, height)
-    data[_progressbar].height = height
-    _progressbar:emit_signal("widget::updated")
-    return _progressbar
+function progressbar:set_height(height)
+    data[self].height = height
+    self:emit_signal("widget::updated")
+    return self
 end
 
 --- Set the progressbar width.
--- @param progressbar The progressbar.
 -- @param width The width to set.
-function progressbar.set_width(_progressbar, width)
-    data[_progressbar].width = width
-    _progressbar:emit_signal("widget::updated")
-    return _progressbar
+function progressbar:set_width(width)
+    data[self].width = width
+    self:emit_signal("widget::updated")
+    return self
 end
 
 -- Build properties function

lib/awful/widget/taglist.lua.in

@@ -167,7 +167,7 @@ end
 
 --- Filtering function to include all nonempty tags on the screen.
 -- @param t The tag.
--- @param screen The screen we are drawing on.
+-- @param args unused list of extra arguments.
 -- @return true if t is not empty, else false
 function taglist.filter.noempty(t, args)
     return #t:clients() > 0 or t.selected
@@ -175,7 +175,7 @@ end
 
 --- Filtering function to include all tags on the screen.
 -- @param t The tag.
--- @param screen The screen we are drawing on.
+-- @param args unused list of extra arguments.
 -- @return true
 function taglist.filter.all(t, args)
     return true

lib/gears/object.lua.in

@@ -23,7 +23,7 @@ end
 -- @param obj The object to search in
 -- @param name The signal to find
 -- @param error_msg Error message for if the signal is not found
--- @returns The signal table
+-- @return The signal table
 local function find_signal(obj, name, error_msg)
     check(obj)
     if not obj._signals[name] then

lib/gears/wallpaper.lua.in

@@ -53,7 +53,7 @@ end
 
 --- Get the size of a cairo surface
 -- @param surf The surface you are interested in
--- @returns The surface's width and height
+-- @return The surface's width and height
 local function surface_size(surf)
     local cr = cairo.Context(surf)
     local x, y, w, h = cr:clip_extents()

lib/naughty.lua.in

@@ -26,27 +26,24 @@ local cairo = require("lgi").cairo
 local naughty = {}
 
 --- Naughty configuration - a table containing common popup settings.
--- @name config
--- @field padding Space between popups and edge of the workarea. Default: 4
--- @field spacing Spacing between popups. Default: 1
--- @field icon_dirs List of directories that will be checked by getIcon()
+naughty.config = {}
+--- Space between popups and edge of the workarea. Default: 4
+naughty.config.padding = 4
+--- Spacing between popups. Default: 1
+naughty.config.spacing = 1
+--- List of directories that will be checked by getIcon()
 --   Default: { "/usr/share/pixmaps/", }
--- @field icon_formats List of formats that will be checked by getIcon()
+naughty.config.icon_dirs = { "/usr/share/pixmaps/", }
+--- List of formats that will be checked by getIcon()
 --   Default: { "png", "gif" }
--- @field notify_callback Callback used to modify or reject notifications.
+naughty.config.icon_formats = { "png", "gif" }
+--- Callback used to modify or reject notifications.
 --   Default: nil
 --   Example:
 --      naughty.config.notify_callback = function(args)
 --          args.text = 'prefix: ' .. args.text
 --          return args
 --      end
--- @class table
-
-naughty.config = {}
-naughty.config.padding = 4
-naughty.config.spacing = 1
-naughty.config.icon_dirs = { "/usr/share/pixmaps/", }
-naughty.config.icon_formats = { "png", "gif" }
 naughty.config.notify_callback = nil
 
 
@@ -55,12 +52,10 @@ naughty.config.notify_callback = nil
 -- values (@see defaults)
 -- You have to pass a reference of a preset in your notify() call to use the preset
 -- The presets "low", "normal" and "critical" are used for notifications over DBUS
--- @name config.presets
 -- @field low The preset for notifications with low urgency level
 -- @field normal The default preset for every notification without a preset that will also be used for normal urgency level
 -- @field critical The preset for notifications with a critical urgency level
 -- @class table
-
 naughty.config.presets = {
     normal = {},
     low = {
@@ -75,8 +70,8 @@ naughty.config.presets = {
 
 --- Default values for the params to notify().
 -- These can optionally be overridden by specifying a preset
--- @see config.presets
--- @see notify
+-- @see naughty.config.presets
+-- @see naughty.notify
 naughty.config.defaults = {
     timeout = 5,
     text = "",
@@ -95,7 +90,6 @@ local urgency = {
 }
 
 --- DBUS notification to preset mapping
--- @name config.mapping
 -- The first element is an object containing the filter
 -- If the rules in the filter matches the associated preset will be applied
 -- The rules object can contain: urgency, category, appname

lib/wibox/layout/fixed.lua.in

@@ -17,6 +17,7 @@ local fixed = {}
 -- @param widgets The widgets to draw.
 -- @param fill_space Use all the available space, giving all that is left to the
 --                   last widget
+-- @param wibox The wibox that this widget is drawn to.
 -- @param cr The cairo context to use.
 -- @param width The available width.
 -- @param height The available height.

lib/wibox/layout/flex.lua.in

@@ -21,6 +21,7 @@ end
 --- Draw a flex layout. Each widget gets an equal share of the available space
 -- @param dir "x" for a horizontal layout and "y" for vertical.
 -- @param widgets The widgets to draw.
+-- @param wibox The wibox that this widget is drawn to.
 -- @param cr The cairo context to use.
 -- @param width The available width.
 -- @param height The available height.