diff --git a/lib/awful/key.lua.in b/lib/awful/key.lua.in index 8f082ce0..5e211fde 100644 --- a/lib/awful/key.lua.in +++ b/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) diff --git a/lib/awful/layout/init.lua.in b/lib/awful/layout/init.lua.in index 44a9c699..387fb860 100644 --- a/lib/awful/layout/init.lua.in +++ b/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) diff --git a/lib/awful/menu.lua.in b/lib/awful/menu.lua.in index fe1aefb0..c273d6fc 100644 --- a/lib/awful/menu.lua.in +++ b/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 diff --git a/lib/awful/rules.lua.in b/lib/awful/rules.lua.in index 20983cc9..8891d440 100644 --- a/lib/awful/rules.lua.in +++ b/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 diff --git a/lib/awful/screen.lua.in b/lib/awful/screen.lua.in index e6bc1e27..d174c2c1 100644 --- a/lib/awful/screen.lua.in +++ b/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) diff --git a/lib/awful/tag.lua.in b/lib/awful/tag.lua.in index cad27d88..0a5899b5 100644 --- a/lib/awful/tag.lua.in +++ b/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) diff --git a/lib/awful/wibox.lua.in b/lib/awful/wibox.lua.in index 1251564e..1e359442 100644 --- a/lib/awful/wibox.lua.in +++ b/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. diff --git a/lib/awful/widget/graph.lua.in b/lib/awful/widget/graph.lua.in index d082c499..4c14e1ed 100644 --- a/lib/awful/widget/graph.lua.in +++ b/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 diff --git a/lib/awful/widget/progressbar.lua.in b/lib/awful/widget/progressbar.lua.in index 75a17949..b8c906d5 100644 --- a/lib/awful/widget/progressbar.lua.in +++ b/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 diff --git a/lib/awful/widget/taglist.lua.in b/lib/awful/widget/taglist.lua.in index 03e1d58f..11bccc6e 100644 --- a/lib/awful/widget/taglist.lua.in +++ b/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 diff --git a/lib/gears/object.lua.in b/lib/gears/object.lua.in index f26046ee..7b1c5171 100644 --- a/lib/gears/object.lua.in +++ b/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 diff --git a/lib/gears/wallpaper.lua.in b/lib/gears/wallpaper.lua.in index a2841d96..5cfad093 100644 --- a/lib/gears/wallpaper.lua.in +++ b/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() diff --git a/lib/naughty.lua.in b/lib/naughty.lua.in index f79172b1..27b424ab 100644 --- a/lib/naughty.lua.in +++ b/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 diff --git a/lib/wibox/layout/fixed.lua.in b/lib/wibox/layout/fixed.lua.in index 0be1191d..a42627ca 100644 --- a/lib/wibox/layout/fixed.lua.in +++ b/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. diff --git a/lib/wibox/layout/flex.lua.in b/lib/wibox/layout/flex.lua.in index 92ee41d3..e1dc9509 100644 --- a/lib/wibox/layout/flex.lua.in +++ b/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.