diff --git a/docs/common/cobject.ldoc b/docs/common/cobject.ldoc index dcacb3a8c..b8bf3d6f2 100644 --- a/docs/common/cobject.ldoc +++ b/docs/common/cobject.ldoc @@ -3,7 +3,7 @@ /** Disconnect from a signal. * @tparam string name The name of the signal. * @tparam function func The callback that should be disconnected. - * @function disconnect_signal + * @staticfct disconnect_signal */ /** Emit a signal. @@ -12,13 +12,13 @@ * @param ... Extra arguments for the callback functions. Each connected * function receives the object as first argument and then any extra * arguments that are given to emit_signal(). - * @function emit_signal + * @staticfct emit_signal */ /** Connect to a signal. * @tparam string name The name of the signal. * @tparam function func The callback to call when the signal is emitted. - * @function connect_signal + * @staticfct connect_signal */ /* diff --git a/docs/config.ld b/docs/config.ld index 8a0494569..764989faa 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -56,6 +56,9 @@ tparam_alias('screen_or_idx', 'screen|int') new_type("constructorfct", "Constructors", false, "Parameters") -- Hack to get the functions on top of the signals and properties new_type("function", "Functions", false, "Parameters") +-- For "classes", use an explicit type for static functions. This allows +-- @function and its implicit cousin to be banned in the CI. +new_type("staticfct", "Static module functions", false, "Parameters") -- Documentation for objects properties new_type("property", "Object properties", false, "Type") -- Documentation for objects deprecated properties @@ -141,6 +144,7 @@ file = { '../lib/wibox/container/init.lua', '../lib/naughty/constants.lua', '../lib/naughty/dbus.lua', + '../lib/beautiful/gtk.lua', -- Ignore some parts of the widget library '../lib/awful/widget/init.lua', @@ -189,7 +193,23 @@ local coreclassmap = { mouse = "mouse and awful.mouse", } +-- Add the full module name in front. +local add_mod = { + ["function"] = true, + constructorfct = true, + staticfct = true, + deprecated = true, +} + +-- Add the arguments. +local add_args = { + constructorfct = true, + staticfct = true, +} + custom_display_name_handler = function(item, default_handler) + local ret = default_handler(item) + -- Remove the "namespace" from the signals and properties if no_prefix[item.type] then local name = item.name:match("%.([^.]+)$") @@ -201,15 +221,22 @@ custom_display_name_handler = function(item, default_handler) return coreclassmap[item.name] end + -- Undocumented API to make the libraries and classmod "function" section + -- more consistent. Right now some have their full awful.foo.bar while other + -- have "just" `bar`. Given we use constructors from metatables, we have no + -- choice but to use the full function name. It also makes copy/paste easier. + if add_mod[item.type] and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then + ret = item.module.name .. "." .. ret + end + if item.type == "deprecated" or item.type == "deprecatedproperty" then - return default_handler(item) .. " [deprecated]" + return ret .. " [deprecated]" end if item.type == "method" then return render_methods(item) end - local ret = default_handler(item) -- Get rid of the "module:" in front of method names. It is either wrong or -- just redundant. @@ -221,17 +248,8 @@ custom_display_name_handler = function(item, default_handler) return ret:gsub("^module", item.module.name) end - -- Undocumented API to make the libraries and classmod "function" section - -- more consistent. Right now some have their full awful.foo.bar while other - -- have "just" `bar`. Given we use constructors from metatables, we have no - -- choice but to use the full function name. It also makes copy/paste easier. - if (item.type == "function" or item.type == "constructorfct") - and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then - ret = item.module.name .. "." .. ret - end - -- It isn't there by default. - if item.type == "constructorfct" then + if add_args[item.type] then ret = ret .. " " .. item.args end diff --git a/lib/awful/client.lua b/lib/awful/client.lua index e45381dee..c4ff1f005 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -239,7 +239,7 @@ end --- Get a client by its relative index to another client. -- If no client is passed, the focused client will be used. -- --- @function awful.client.next +-- @staticfct awful.client.next -- @tparam int i The index. Use 1 to get the next, -1 to get the previous. -- @client[opt] sel The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) @@ -274,7 +274,7 @@ function client.next(i, sel, stacked) end --- Swap a client with another client in the given direction. --- @function awful.client.swap.bydirection +-- @staticfct awful.client.swap.bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @client[opt=focused] c The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) @@ -295,8 +295,9 @@ function client.swap.bydirection(dir, c, stacked) end end ---- Swap a client with another client in the given direction. Swaps across screens. --- @function awful.client.swap.global_bydirection +--- Swap a client with another client in the given direction. +-- Swaps across screens. +-- @staticfct awful.client.swap.global_bydirection -- @param dir The direction, can be either "up", "down", "left" or "right". -- @client[opt] sel The client. function client.swap.global_bydirection(dir, sel) @@ -329,7 +330,7 @@ function client.swap.global_bydirection(dir, sel) end --- Swap a client by its relative index. --- @function awful.client.swap.byidx +-- @staticfct awful.client.swap.byidx -- @param i The index. -- @client[opt] c The client, otherwise focused one is used. function client.swap.byidx(i, c) @@ -342,7 +343,7 @@ end --- Cycle clients. -- --- @function awful.client.cycle +-- @staticfct awful.client.cycle -- @param clockwise True to cycle clients clockwise. -- @param[opt] s The screen where to cycle clients. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) @@ -886,7 +887,7 @@ end --- Restore (=unminimize) a random client. --- @function awful.client.restore +-- @staticfct awful.client.restore -- @param s The screen to use. -- @return The restored client if some client was restored, otherwise nil. function client.restore(s) @@ -907,7 +908,7 @@ function client.restore(s) return nil end ---- Normalize a set of numbers to 1 +--- Normalize a set of numbers to 1. -- @param set the set of numbers to normalize -- @param num the number of numbers to normalize local function normalize(set, num) @@ -1204,7 +1205,7 @@ end --- Set a client property to be persistent across restarts (via X properties). -- --- @function awful.client.property.persist +-- @staticfct awful.client.property.persist -- @param prop The property name. -- @param kind The type (used for register_xproperty). -- One of "string", "number" or "boolean". @@ -1221,16 +1222,17 @@ function client.property.persist(prop, kind) end end ---- --- Returns an iterator to cycle through, starting from the client in focus or --- the given index, all clients that match a given criteria. +--- Returns an iterator to cycle through clients. +-- +-- Starting from the client in focus or the given index, all clients that match +-- a given criteria. -- -- @param filter a function that returns true to indicate a positive match -- @param start what index to start iterating from. Defaults to using the -- index of the currently focused client. -- @param s which screen to use. nil means all screens. -- --- @function awful.client.iterate +-- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances -- local urxvt = function (c) -- return awful.rules.match(c, {class = "URxvt"}) @@ -1387,7 +1389,7 @@ do -- See `awful.client.focus.history.enable_tracking` to enable it again. -- @treturn int The internal value of `disabled_count` (calls to this -- function without calling `awful.client.focus.history.enable_tracking`). - -- @function awful.client.focus.history.disable_tracking + -- @staticfct awful.client.focus.history.disable_tracking function client.focus.history.disable_tracking() disabled_count = disabled_count + 1 if disabled_count == 1 then @@ -1401,7 +1403,7 @@ do -- This is the default, but can be disabled -- through `awful.client.focus.history.disable_tracking`. -- @treturn boolean True if history tracking has been enabled. - -- @function awful.client.focus.history.enable_tracking + -- @staticfct awful.client.focus.history.enable_tracking function client.focus.history.enable_tracking() assert(disabled_count > 0) disabled_count = disabled_count - 1 @@ -1414,7 +1416,7 @@ do --- Is history tracking enabled? -- @treturn bool True if history tracking is enabled. -- @treturn int The number of times that tracking has been disabled. - -- @function awful.client.focus.history.is_enabled + -- @staticfct awful.client.focus.history.is_enabled function client.focus.history.is_enabled() return disabled_count == 0, disabled_count end diff --git a/lib/awful/completion.lua b/lib/awful/completion.lua index 4fd14840b..f374c9094 100644 --- a/lib/awful/completion.lua +++ b/lib/awful/completion.lua @@ -32,6 +32,7 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion" --- Enable programmable bash completion in awful.completion.bash at the price of -- a slight overhead. -- @param src The bash completion source file, /etc/bash_completion by default. +-- @staticfct awful.completion.bashcomp_load function completion.bashcomp_load(src) if src then bashcomp_src = src end local c, err = io.popen("/usr/bin/env bash -c 'source " .. bashcomp_src .. "; complete -p'") @@ -70,6 +71,7 @@ completion.default_shell = nil -- @treturn string The new command. -- @treturn number The new cursor position. -- @treturn table The table with all matches. +-- @staticfct awful.completion.shell function completion.shell(command, cur_pos, ncomp, shell) local wstart = 1 local wend = 1 @@ -192,6 +194,7 @@ end -- @param ncomp The number of yet requested completion using current text. -- @param keywords The keywords table uised for completion. -- @return The new match, the new cursor position, the table of all matches. +-- @staticfct awful.completion.generic function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args -- The keywords table may be empty if #keywords == 0 then diff --git a/lib/awful/ewmh.lua b/lib/awful/ewmh.lua index 139e8e1a5..d98f62ac8 100644 --- a/lib/awful/ewmh.lua +++ b/lib/awful/ewmh.lua @@ -54,6 +54,7 @@ local ewmh = { --- Update a client's settings when its geometry changes, skipping signals -- resulting from calls within. local repair_geometry_lock = false + local function repair_geometry(window) if repair_geometry_lock then return end repair_geometry_lock = true @@ -166,6 +167,7 @@ end -- @see generic_activate_filters -- @see contextual_activate_filters -- @see remove_activate_filter +-- @staticfct awful.ewmh.add_activate_filter function ewmh.add_activate_filter(f, context) if not context then table.insert(ewmh.generic_activate_filters, f) @@ -185,6 +187,7 @@ end -- @see generic_activate_filters -- @see contextual_activate_filters -- @see add_activate_filter +-- @staticfct awful.ewmh.remove_activate_filter function ewmh.remove_activate_filter(f, context) local tab = context and (ewmh.contextual_activate_filters[context] or {}) or ewmh.generic_activate_filters diff --git a/lib/awful/hotkeys_popup/init.lua b/lib/awful/hotkeys_popup/init.lua index 182fe5abc..8aaa75445 100644 --- a/lib/awful/hotkeys_popup/init.lua +++ b/lib/awful/hotkeys_popup/init.lua @@ -24,7 +24,7 @@ local hotkeys_popup = { -- @tparam[opt] screen s The screen. -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. --- @function awful.hotkeys_popup.show_help +-- @staticfct awful.hotkeys_popup.show_help -- @see awful.hotkeys_popup.widget.show_help hotkeys_popup.show_help = hotkeys_popup.widget.show_help diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index a92787451..1068c16ed 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -490,6 +490,7 @@ function widget.new(args) -- @tparam[opt] table show_args Additional arguments. -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. + -- @method show_help function widget_instance:show_help(c, s, show_args) show_args = show_args or {} local show_awesome_keys = show_args.show_awesome_keys ~= false @@ -549,6 +550,7 @@ function widget.new(args) --- Add hotkey descriptions for third-party applications. -- @tparam table hotkeys Table with bindings, -- see `awful.hotkeys_popup.key.vim` as an example. + -- @method add_hotkeys function widget_instance:add_hotkeys(hotkeys) for group, bindings in pairs(hotkeys) do for _, binding in ipairs(bindings) do @@ -571,6 +573,7 @@ function widget.new(args) -- @tparam string group hotkeys group name, -- @tparam table data rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. + -- @method add_group_rules function widget_instance:add_group_rules(group, data) self.group_rules[group] = data end @@ -591,6 +594,7 @@ end -- @tparam[opt] table args Additional arguments. -- @tparam[opt=true] boolean args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. +-- @staticfct awful.hotkeys_popup.widget.show_help function widget.show_help(...) return get_default_widget():show_help(...) end @@ -599,6 +603,7 @@ end -- (default widget instance will be used). -- @tparam table hotkeys Table with bindings, -- see `awful.hotkeys_popup.key.vim` as an example. +-- @staticfct awful.hotkeys_popup.widget.add_hotkeys function widget.add_hotkeys(...) return get_default_widget():add_hotkeys(...) end @@ -608,6 +613,7 @@ end -- @tparam string group rule group name, -- @tparam table data rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. +-- @staticfct awful.hotkeys_popup.widget.add_group_rules function widget.add_group_rules(group, data) return get_default_widget():add_group_rules(group, data) end diff --git a/lib/awful/key.lua b/lib/awful/key.lua index ee4b5148a..6e0a56919 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -3,7 +3,7 @@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou --- @module awful.key +-- @classmod awful.key --------------------------------------------------------------------------- -- Grab environment we need @@ -59,6 +59,7 @@ capi.awesome.connect_signal("xkb::map_changed" , function() conversion = nil en -- @tparam table mod A modified table. Valid modifiers are: Any, Mod1, -- Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control. -- @tparam string k The key +-- @staticfct awful.key.execute function key.execute(mod, k) local modmap = generate_conversion_map() local active = capi.awesome._active_modifiers @@ -111,6 +112,7 @@ end -- @tparam table data User data for key, -- for example {description="select next tag", group="tag"}. -- @treturn table A table with one or several key objects. +-- @constructorfct awful.key function key.new(mod, _key, press, release, data) if type(release)=='table' then data=release @@ -145,6 +147,7 @@ end -- @param _key The key object. -- @param pressed_mod The modifiers to compare with. -- @param pressed_key The key to compare with. +-- @staticfct awful.key.match function key.match(_key, pressed_mod, pressed_key) -- First, compare key. if pressed_key ~= _key.key then return false end diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index 65b7629cb..4c94e66d6 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -724,16 +724,6 @@ function keygrab.run_with_keybindings(args) return ret end ---- Run a grabbing function. --- --- Calling this is equivalent to `keygrabber.run`. --- --- @param g The key grabber callback that will get the key events until it --- will be deleted or a new grabber is added. --- @return the given callback `g`. --- --- @deprecated awful.keygrabber.run - --- A lower level API to interact with the keygrabber directly. -- -- Grab keyboard input and read pressed keys, calling the least callback @@ -750,7 +740,7 @@ end -- -- Here is the content of the modifier table: -- --- +--
-- -- -- @@ -785,7 +775,7 @@ end -- end -- end) -- end --- @function awful.keygrabber.run +-- @deprecated awful.keygrabber.run function keygrab.run(g) -- Remove the grabber if it is in the stack. keygrab.stop(g) @@ -807,7 +797,7 @@ end local signals = {} --- Connect to a signal for all keygrabbers at once. --- @function awful.keygrabber.connect_signal +-- @staticfct awful.keygrabber.connect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. function keygrab.connect_signal(name, callback) @@ -820,7 +810,7 @@ function keygrab.connect_signal(name, callback) end --- Disconnect to a signal for all keygrabbers at once. --- @function awful.keygrabber.disconnect_signal +-- @staticfct awful.keygrabber.disconnect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. function keygrab.disconnect_signal(name, callback) @@ -840,7 +830,7 @@ end -- `my_keygrabber:emit_signal(name, ...)`. This function works on the whole -- keygrabber module, not one of its instance. -- --- @function awful.keygrabber.emit_signal +-- @staticfct awful.keygrabber.emit_signal -- @tparam string name The signal name. -- @param ... Other arguments for the callbacks. function keygrab.emit_signal(name, ...) diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua index 6dcfaa412..29c6b8856 100644 --- a/lib/awful/layout/init.lua +++ b/lib/awful/layout/init.lua @@ -73,7 +73,7 @@ layout.layouts = { -- awful.layout.suit.corner.sw, -- awful.layout.suit.corner.se, -- --- @field layout.layouts +-- @field awful.layout.layouts --- Return the tag layout index (from `awful.layout.layouts`). -- @@ -82,6 +82,7 @@ layout.layouts = { -- -- @tparam tag t The tag. -- @treturn nil|number The layout index. +-- @staticfct awful.layout.get_tag_layout_index function layout.get_tag_layout_index(t) return gtable.hasitem(layout.layouts, t.layout) end @@ -95,6 +96,7 @@ local delayed_arrange = {} --- Get the current layout. -- @param screen The screen. -- @return The layout function. +-- @staticfct awful.layout.get function layout.get(screen) screen = screen or capi.mouse.screen local t = get_screen(screen).selected_tag @@ -105,6 +107,7 @@ end -- @param i Relative index. -- @param s The screen. -- @param[opt] layouts A table of layouts. +-- @staticfct awful.layout.inc function layout.inc(i, s, layouts) if type(i) == "table" then -- Older versions of this function had arguments (layouts, i, s), but @@ -150,6 +153,7 @@ end --- Set the layout function of the current tag. -- @param _layout Layout name. -- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify. +-- @staticfct awful.layout.set function layout.set(_layout, t) t = t or capi.mouse.screen.selected_tag t.layout = _layout @@ -168,6 +172,7 @@ end -- @treturn table A table with the workarea (x, y, width, height), the screen -- geometry (x, y, width, height), the clients, the screen and sometime, a -- "geometries" table with client as keys and geometry as value +-- @staticfct awful.layout.parameters function layout.parameters(t, screen) screen = get_screen(screen) t = t or screen.selected_tag @@ -210,6 +215,7 @@ end --- Arrange a screen using its current layout. -- @param screen The screen to arrange. +-- @staticfct awful.layout.arrange function layout.arrange(screen) screen = get_screen(screen) if not screen or delayed_arrange[screen] then return end @@ -250,6 +256,7 @@ end --- Get the current layout name. -- @param _layout The layout. -- @return The layout name. +-- @staticfct awful.layout.getname function layout.getname(_layout) _layout = _layout or layout.get() return _layout.name @@ -318,6 +325,7 @@ capi.client.connect_signal("list", function() -- @tparam client c The client -- @tparam string context The context -- @tparam table hints Additional hints +-- @signalhandler awful.layout.move_handler function layout.move_handler(c, context, hints) --luacheck: no unused args -- Quit if it isn't a mouse.move on a tiled layout, that's handled elsewhere if c.floating then return end diff --git a/lib/awful/layout/suit/fair.lua b/lib/awful/layout/suit/fair.lua index 161b6edf2..6930a09e7 100644 --- a/lib/awful/layout/suit/fair.lua +++ b/lib/awful/layout/suit/fair.lua @@ -88,21 +88,30 @@ local function do_fair(p, orientation) end end ---- Horizontal fair layout. +-- Horizontal fair layout. -- @param screen The screen to arrange. fair.horizontal = {} fair.horizontal.name = "fairh" + function fair.horizontal.arrange(p) return do_fair(p, "east") end ---- Vertical fair layout. +-- Vertical fair layout. -- @param screen The screen to arrange. fair.name = "fairv" function fair.arrange(p) return do_fair(p, "south") end +--- The fair layout. +-- Try to give all clients the same size. +-- @clientlayout awful.layout.suit.fair + +--- The horizontal fair layout. +-- Try to give all clients the same size. +-- @clientlayout awful.layout.suit.fair.horizontal + return fair -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/awful/layout/suit/floating.lua b/lib/awful/layout/suit/floating.lua index b76943574..9c2e6ea42 100644 --- a/lib/awful/layout/suit/floating.lua +++ b/lib/awful/layout/suit/floating.lua @@ -22,6 +22,7 @@ local capi = local floating = {} --- Jump mouse cursor to the client's corner when resizing it. +-- @field awful.layout.suit.floating.resize_jump_to_corner floating.resize_jump_to_corner = true function floating.mouse_resize_handler(c, corner, x, y) @@ -103,7 +104,7 @@ function floating.arrange() end --- The floating layout. --- @clientlayout awful.layout.suit. +-- @clientlayout awful.layout.suit.floating floating.name = "floating" diff --git a/lib/awful/layout/suit/tile.lua b/lib/awful/layout/suit/tile.lua index 09e95d1cd..335398fb7 100644 --- a/lib/awful/layout/suit/tile.lua +++ b/lib/awful/layout/suit/tile.lua @@ -43,6 +43,7 @@ local tile = {} -- @see gears.surface --- Jump mouse cursor to the client's corner when resizing it. +-- @field awful.layout.suit.tile.resize_jump_to_corner tile.resize_jump_to_corner = true local function mouse_resize_handler(c, _, _, _, orientation) diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index 78d1e55b8..cc1d29ac5 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -5,7 +5,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @author dodo -- @copyright 2008, 2011 Damien Leone, Julien Danjou, dodo --- @module awful.menu +-- @popupmod awful.menu -------------------------------------------------------------------------------- local wibox = require("wibox") @@ -358,6 +358,7 @@ end --- Show a menu. -- @param args The arguments -- @param args.coords Menu position defaulting to mouse.coords() +-- @method show function menu:show(args) args = args or {} local coords = args.coords or nil @@ -371,6 +372,7 @@ function menu:show(args) end --- Hide a menu popup. +-- @method hide function menu:hide() -- Remove items from screen for i = 1, #self.items do @@ -389,6 +391,7 @@ end --- Toggle menu visibility. -- @param args The arguments -- @param args.coords Menu position {x,y} +-- @method toggle function menu:toggle(args) if self.wibox.visible then self:hide() @@ -397,7 +400,8 @@ function menu:toggle(args) end end ---- Update menu content +--- Update menu content. +-- @method update function menu:update() if self.wibox.visible then self:show({ coords = { x = self.x, y = self.y } }) @@ -407,6 +411,7 @@ end --- Get the elder parent so for example when you kill -- it, it will destroy the whole family. +-- @method get_root function menu:get_root() return self.parent and menu.get_root(self.parent) or self end @@ -417,6 +422,7 @@ end -- @param args.new (Default: awful.menu.entry) The menu entry constructor. -- @param[opt] args.theme The menu entry theme. -- @param[opt] index The index where the new entry will inserted. +-- @method add function menu:add(args, index) if not args then return end local theme = load_theme(args.theme or {}, self.theme) @@ -470,8 +476,9 @@ function menu:add(args, index) return item end ---- Delete menu entry at given position --- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself +--- Delete menu entry at given position. +-- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself. +-- @method delete function menu:delete(num) if type(num) == "table" then num = gtable.hasitem(self.items, num) @@ -511,6 +518,7 @@ end -- returning `true` or `false` to indicate whether the client should be -- included in the menu. -- @return The menu. +-- @constructorfct awful.menu.clients function menu.clients(args, item_args, filter) local cls_t = {} for c in client_iterate(filter or function() return true end) do @@ -553,6 +561,7 @@ local clients_menu = nil -- returning `true` or `false` to indicate whether the client should be -- included in the menu. -- @return The menu. +-- @constructorfct awful.menu.client_list function menu.client_list(args, item_args, filter) if clients_menu and clients_menu.wibox.visible then clients_menu:hide() @@ -565,10 +574,11 @@ end -------------------------------------------------------------------------------- ---- Default awful.menu.entry constructor +--- Default awful.menu.entry constructor. -- @param parent The parent menu (TODO: This is apparently unused) -- @param args the item params -- @return table with 'widget', 'cmd', 'akey' and all the properties the user wants to change +-- @constructorfct awful.menu.entry function menu.entry(parent, args) -- luacheck: no unused args args = args or {} args.text = args[1] or args.text or "" @@ -668,6 +678,7 @@ end -- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false. -- -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user. +-- @constructorfct awful.menu -- @usage -- The following function builds and shows a menu of clients that match -- -- a particular rule. -- -- Bound to a key, it can be used to select from dozens of terminals open on diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index 662daa068..b94d63eb3 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -72,7 +72,7 @@ function mouse.client_under_pointer() end --- Move a client. --- @function awful.mouse.client.move +-- @staticfct awful.mouse.client.move -- @param c The client to move, or the focused one if nil. -- @param snap The pixel to snap clients. -- @param finished_cb Deprecated, do not use @@ -125,7 +125,7 @@ function mouse.client.dragtotag.border(c) end --- Move the wibox under the cursor. --- @function awful.mouse.wibox.move +-- @staticfct awful.mouse.wibox.move --@tparam wibox w The wibox to move, or none to use that under the pointer function mouse.wibox.move(w) w = w or mouse.current_wibox @@ -183,7 +183,7 @@ function mouse.client.corner(c, corner) end --- Resize a client. --- @function awful.mouse.client.resize +-- @staticfct awful.mouse.client.resize -- @param c The client to resize, or the focused one by default. -- @tparam string corner The corner to grab on resize. Auto detected by default. -- @tparam[opt={}] table args A set of `awful.placement` arguments @@ -417,7 +417,7 @@ end) -- @treturn integer table.y The vertical position -- @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true -- when button 1 is pressed. --- @function mouse.coords +-- @staticfct mouse.coords return mouse diff --git a/lib/awful/placement.lua b/lib/awful/placement.lua index 73f49360b..e79c9ed22 100644 --- a/lib/awful/placement.lua +++ b/lib/awful/placement.lua @@ -811,7 +811,8 @@ end -- or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn table The new geometry --- @treturn string The corner name +-- @treturn string The corner name. +-- @staticfct awful.placement.closest_corner function placement.closest_corner(d, args) args = add_context(args, "closest_corner") d = d or capi.client.focus @@ -855,6 +856,7 @@ end -- @tparam[opt={}] table args The arguments -- @tparam[opt=client's screen] integer args.screen The screen. -- @treturn table The new client geometry. +-- @staticfct awful.placement.no_offscreen function placement.no_offscreen(c, args) --compatibility with the old API @@ -897,6 +899,7 @@ end -- @param c The client. -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.no_overlap function placement.no_overlap(c, args) c = c or capi.client.focus args = add_context(args, "no_overlap") @@ -969,6 +972,7 @@ end -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.under_mouse function placement.under_mouse(d, args) args = add_context(args, "under_mouse") d = d or capi.client.focus @@ -993,6 +997,7 @@ end -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.next_to_mouse function placement.next_to_mouse(d, args) if type(args) == "number" then gdebug.deprecate( @@ -1042,6 +1047,7 @@ end -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.resize_to_mouse function placement.resize_to_mouse(d, args) d = d or capi.client.focus args = add_context(args, "resize_to_mouse") @@ -1119,6 +1125,7 @@ end -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.align function placement.align(d, args) args = add_context(args, "align") d = d or capi.client.focus @@ -1193,6 +1200,7 @@ end -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn table The new geometry +-- @staticfct awful.placement.stretch function placement.stretch(d, args) args = add_context(args, "stretch") @@ -1265,6 +1273,7 @@ end -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn table The new geometry +-- @staticfct awful.placement.maximize function placement.maximize(d, args) args = add_context(args, "maximize") d = d or capi.client.focus @@ -1318,6 +1327,7 @@ end -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn table The new geometry +-- @staticfct awful.placement.scale function placement.scale(d, args) args = add_context(args, "scale_to_percent") d = d or capi.client.focus @@ -1400,6 +1410,7 @@ end -- @treturn table The new geometry -- @treturn string The choosen position ("left", "right", "top" or "bottom") -- @treturn string The choosen anchor ("front", "middle" or "back") +-- @staticfct awful.placement.next_to function placement.next_to(d, args) args = add_context(args, "next_to") d = d or capi.client.focus @@ -1527,6 +1538,7 @@ end -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn boolean If the geometry was restored +-- @staticfct awful.placement.restore function placement.restore(d, args) if not args or not args.context then return false end d = d or capi.client.focus diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index c9e97e8f8..fd87a3043 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -234,6 +234,7 @@ end -- @see awful.popup.preferred_positions -- @see awful.popup.preferred_anchors -- @treturn table The new geometry +-- @method move_next_to function popup:move_next_to(obj) if self._private.is_relative == false then return end @@ -256,6 +257,7 @@ end -- -- @tparam widget widget The widget -- @tparam[opt=1] number button The button index +-- @method bind_to_widget function popup:bind_to_widget(widget, button) if not self._private.button_for_widget then self._private.button_for_widget = {} @@ -267,6 +269,7 @@ end --- Unbind the popup from a widget button. -- @tparam widget widget The widget +-- @method unbind_to_widget function popup:unbind_to_widget(widget) widget:disconnect_signal("button::press", self._private.show_fct) end diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index fb49d69ab..de25e8e2b 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -454,6 +454,7 @@ end -- with mod table, key and command as arguments when a key was pressed. -- [**DEPRECATED**] -- @see gears.color +-- @staticfct awful.prompt.run function prompt.run(args, textbox, exe_callback, completion_callback, history_path, history_max, done_callback, changed_callback, keypressed_callback) diff --git a/lib/awful/rules.lua b/lib/awful/rules.lua index 9aa9db7d0..4b1e86bbd 100644 --- a/lib/awful/rules.lua +++ b/lib/awful/rules.lua @@ -134,6 +134,7 @@ local crules = gmatcher() -- @client c The client. -- @tab rule The rule to check. -- @treturn bool True if it matches, false otherwise. +-- @staticfct awful.rules.match function rules.match(c, rule) return crules:_match(c, rule) end @@ -142,6 +143,7 @@ end -- @client c The client. -- @tab rule The rule to check. -- @treturn bool True if at least one rule is matched, false otherwise. +-- @staticfct awful.rules.match_any function rules.match_any(c, rule) return crules:_match_any(c, rule) end @@ -151,6 +153,7 @@ end -- @tab entry Rule entry (with keys `rule`, `rule_any`, `except` and/or -- `except_any`). -- @treturn bool +-- @staticfct awful.rules.matches function rules.matches(c, entry) return crules:matches_rule(c, entry) end @@ -160,6 +163,7 @@ end -- @tab _rules The rules to check. List with "rule", "rule_any", "except" and -- "except_any" keys. -- @treturn table The list of matched rules. +-- @staticfct awful.rules.matching_rules function rules.matching_rules(c, _rules) return crules:matching_rules(c, _rules) end @@ -169,13 +173,15 @@ end -- @tab _rules The rules to check. List of tables with `rule`, `rule_any`, -- `except` and `except_any` keys. -- @treturn bool True if at least one rule is matched, false otherwise. +-- @staticfct awful.rules.matches_list function rules.matches_list(c, _rules) return crules:matches_rules(c, _rules) end --- Remove a source. -- @tparam string name The source name. --- @treturn boolean If the source was removed, +-- @treturn boolean If the source was removed. +-- @staticfct awful.rules.remove_rule_source function rules.remove_rule_source(name) return crules:remove_matching_source(name) end @@ -183,6 +189,7 @@ end --- Apply awful.rules.rules to a client. -- @client c The client. +-- @staticfct awful.rules.apply function rules.apply(c) return crules:apply(c) end @@ -226,7 +233,7 @@ end -- @tparam[opt={}] table precede A list of names of sources this source have a -- priority over. -- @treturn boolean Returns false if a dependency conflict was found. --- @function awful.rules.add_rule_source +-- @staticfct awful.rules.add_rule_source function rules.add_rule_source(name, cb, ...) local function callback(_, ...) @@ -519,7 +526,7 @@ end -- @client c The client. -- @tab props Properties to apply. -- @tab[opt] callbacks Callbacks to apply. --- @function awful.rules.execute +-- @staticfct awful.rules.execute crules._execute = function(_, c, props, callbacks) -- This has to be done first, as it will impact geometry related props. diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index ae0a5f84c..b9043f974 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -69,7 +69,7 @@ end -- -- The number returned can be used as an index into the global -- `screen` table/object. --- @function awful.screen.getbycoord +-- @staticfct awful.screen.getbycoord -- @tparam number x The x coordinate -- @tparam number y The y coordinate -- @treturn ?number The screen index @@ -86,7 +86,7 @@ end -- -- This moves the mouse pointer to the last known position on the new screen, -- or keeps its position relative to the current focused screen. --- @function awful.screen.focus +-- @staticfct awful.screen.focus -- @screen _screen Screen number (defaults / falls back to mouse.screen). function screen.focus(_screen) client = client or require("awful.client") @@ -149,7 +149,7 @@ end -- -- This moves the mouse pointer to the last known position on the new screen, -- or keeps its position relative to the current focused screen. --- @function awful.screen.focus_bydirection +-- @staticfct awful.screen.focus_bydirection -- @param dir The direction, can be either "up", "down", "left" or "right". -- @param _screen Screen. function screen.focus_bydirection(dir, _screen) @@ -166,7 +166,7 @@ end -- This moves the mouse pointer to the last known position on the new screen, -- or keeps its position relative to the current focused screen. -- --- @function awful.screen.focus_relative +-- @staticfct awful.screen.focus_relative -- @tparam int offset Value to add to the current focused screen index. 1 to -- focus the next one, -1 to focus the previous one. function screen.focus_relative(offset) @@ -242,6 +242,7 @@ end -- focused screen by default. -- @tparam client c A client. -- @treturn screen The preferred screen. +-- @staticfct awful.screen.preferred function screen.preferred(c) return capi.awesome.startup and c.screen or screen.focused() end @@ -254,7 +255,7 @@ end -- It is possible to set `awful.screen.default_focused_args` to override the -- default settings. -- --- @function awful.screen.focused +-- @staticfct awful.screen.focused -- @tparam[opt] table args -- @tparam[opt=false] boolean args.client Use the client screen instead of the -- mouse screen. @@ -272,7 +273,7 @@ end -- -- This method computes the different variants of the "usable" screen geometry. -- --- @function screen.get_bounding_geometry +-- @staticfct screen.get_bounding_geometry -- @tparam[opt={}] table args The arguments -- @tparam[opt=false] boolean args.honor_padding Whether to honor the screen's padding. -- @tparam[opt=false] boolean args.honor_workarea Whether to honor the screen's workarea. @@ -341,7 +342,7 @@ end -- -- This is used by `screen.clients` internally (with `stacked=true`). -- --- @function screen:get_clients +-- @method get_clients -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom) -- @treturn table The clients list. function screen.object.get_clients(s, stacked) @@ -430,7 +431,7 @@ end --- Call a function for each existing and created-in-the-future screen. -- --- @function awful.screen.connect_for_each_screen +-- @staticfct awful.screen.connect_for_each_screen -- @tparam function func The function to call. -- @screen func.screen The screen. function screen.connect_for_each_screen(func) @@ -441,7 +442,7 @@ function screen.connect_for_each_screen(func) end --- Undo the effect of connect_for_each_screen. --- @function awful.screen.disconnect_for_each_screen +-- @staticfct awful.screen.disconnect_for_each_screen -- @tparam function func The function that should no longer be called. function screen.disconnect_for_each_screen(func) capi.screen.disconnect_signal("added", func) @@ -525,6 +526,7 @@ end -- defaulting to 96. -- -- @tparam boolean enabled Enable or disable automatic DPI support. +-- @staticfct awful.screen.set_auto_dpi_enabled function screen.set_auto_dpi_enabled(enabled) for s in capi.screen do s.data.dpi_cache = nil diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua index 3ff8449bd..8b54b4d89 100644 --- a/lib/awful/spawn.lua +++ b/lib/awful/spawn.lua @@ -344,6 +344,7 @@ end -- @treturn[1] ?string The startup notification ID, if `sn` is not false, or -- a `callback` is provided. -- @treturn[2] string Error message. +-- @staticfct awful.spawn function spawn.spawn(cmd, sn_rules, callback) if cmd and cmd ~= "" then local enable_sn = (sn_rules ~= false or callback) @@ -363,6 +364,7 @@ end --- Spawn a program using the shell. -- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`). -- @tparam string cmd The command. +-- @staticfct awful.spawn.with_shell function spawn.with_shell(cmd) if cmd and cmd ~= "" then cmd = { util.shell, "-c", cmd } @@ -389,6 +391,7 @@ end -- termination. -- @treturn[1] Integer the PID of the forked process. -- @treturn[2] string Error message. +-- @staticfct awful.spawn.with_line_callback function spawn.with_line_callback(cmd, callbacks) local stdout_callback, stderr_callback, done_callback, exit_callback = callbacks.stdout, callbacks.stderr, callbacks.output_done, callbacks.exit @@ -434,6 +437,7 @@ end -- @treturn[1] Integer the PID of the forked process. -- @treturn[2] string Error message. -- @see spawn.with_line_callback +-- @staticfct awful.spawn.easy_async function spawn.easy_async(cmd, callback) local stdout = '' local stderr = '' @@ -484,6 +488,7 @@ end -- @treturn[1] Integer the PID of the forked process. -- @treturn[2] string Error message. -- @see spawn.with_line_callback +-- @staticfct awful.spawn.easy_async_with_shell function spawn.easy_async_with_shell(cmd, callback) return spawn.easy_async({ util.shell, "-c", cmd or "" }, callback) end @@ -495,6 +500,7 @@ end -- @tparam[opt] function done_callback Function that is called when the -- operation finishes (e.g. due to end of file). -- @tparam[opt=false] boolean close Should the stream be closed after end-of-file? +-- @staticfct awful.spawn.read_lines function spawn.read_lines(input_stream, line_callback, done_callback, close) local stream = Gio.DataInputStream.new(input_stream) local function done() @@ -644,6 +650,7 @@ end -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. -- @see awful.rules +-- @staticfct awful.spawn.once function spawn.once(cmd, rules, matcher, unique_id, callback) local hash = unique_id or hash_command(cmd, rules) local status = register_common(hash, rules, matcher, callback) @@ -676,6 +683,7 @@ end -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. -- @see awful.rules +-- @staticfct awful.spawn.single_instance function spawn.single_instance(cmd, rules, matcher, unique_id, callback) local hash = unique_id or hash_command(cmd, rules) register_common(hash, rules, matcher, callback) @@ -703,6 +711,7 @@ local raise_rules = {focus = true, switch_to_tags = true, raise = true} -- @tparam[opt] function callback A callback function when the client is created. -- @see awful.rules -- @treturn client The client if it already exists. +-- @staticfct awful.spawn.raise_or_spawn function spawn.raise_or_spawn(cmd, rules, matcher, unique_id, callback) local hash = unique_id or hash_command(cmd, rules) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 9066f5d3f..de66251bc 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -296,7 +296,7 @@ function tag.add(name, props) end --- Create a set of tags and attach it to a screen. --- @function awful.tag.new +-- @staticfct awful.tag.new -- @param names The tag name, in a table -- @param screen The tag screen, or 1 if not set. -- @param layout The layout or layout table to set for this tags by default. @@ -322,7 +322,7 @@ function tag.new(names, screen, layout) end --- Find a suitable fallback tag. --- @function awful.tag.find_fallback +-- @staticfct awful.tag.find_fallback -- @param screen The screen to look for a tag on. [awful.screen.focused()] -- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)] function tag.find_fallback(screen, invalids) @@ -340,7 +340,7 @@ end -- -- mouse.screen.selected_tag:delete() -- --- @function tag.delete +-- @method delete -- @see awful.tag.add -- @see awful.tag.find_fallback -- @tparam[opt=awful.tag.find_fallback()] tag fallback_tag Tag to assign @@ -429,7 +429,7 @@ function tag.delete(target_tag, fallback_tag) end --- Update the tag history. --- @function awful.tag.history.update +-- @staticfct awful.tag.history.update -- @param obj Screen object. function tag.history.update(obj) local s = get_screen(obj) @@ -470,7 +470,7 @@ function tag.history.update(obj) end --- Revert tag history. --- @function awful.tag.history.restore +-- @staticfct awful.tag.history.restore -- @param screen The screen. -- @param idx Index in history. Defaults to "previous" which is a special index -- toggling between last two selected sets of tags. Number (eg 1) will go back @@ -522,6 +522,7 @@ end -- @tparam screen s The screen of the tag -- @tparam string name The name of the tag -- @return The tag found, or `nil` +-- @staticfct awful.tag.find_by_name -- @usage -- For the current screen -- local t = awful.tag.find_by_name(awful.screen.focused(), "name") -- @@ -696,7 +697,7 @@ function tag.setmwfact(mwfact, t) end --- Increase master width factor. --- @function awful.tag.incmwfact +-- @staticfct awful.tag.incmwfact -- @see master_width_factor -- @param add Value to add to master width factor. -- @param t The tag to modify, if null tag.selected() is used. @@ -972,7 +973,7 @@ function tag.setgap(useless_gap, t) end --- Increase the spacing between clients --- @function awful.tag.incgap +-- @staticfct awful.tag.incgap -- @see gap -- @param add Value to add to the spacing between clients -- @param t The tag to modify, if null tag.selected() is used. @@ -1079,7 +1080,7 @@ end --- Toggle size fill policy for the master client(s) -- between "expand" and "master_width_factor". --- @function awful.tag.togglemfpol +-- @staticfct awful.tag.togglemfpol -- @see master_fill_policy -- @tparam tag t The tag to modify, if null tag.selected() is used. function tag.togglemfpol(t) @@ -1160,7 +1161,7 @@ function tag.getnmaster(t) end --- Increase the number of master windows. --- @function awful.tag.incnmaster +-- @staticfct awful.tag.incnmaster -- @see master_count -- @param add Value to add to number of master windows. -- @param[opt] t The tag to modify, if null tag.selected() is used. @@ -1278,7 +1279,7 @@ function tag.getncol(t) end --- Increase number of column windows. --- @function awful.tag.incncol +-- @staticfct awful.tag.incncol -- @param add Value to add to number of column windows. -- @param[opt] t The tag to modify, if null tag.selected() is used. -- @tparam[opt=false] boolean sensible Limit column_count based on the number @@ -1309,7 +1310,7 @@ function tag.incncol(add, t, sensible) end --- View no tag. --- @function awful.tag.viewnone +-- @staticfct awful.tag.viewnone -- @tparam[opt] int|screen screen The screen. function tag.viewnone(screen) screen = screen or ascreen.focused() @@ -1322,7 +1323,7 @@ end --- View a tag by its taglist index. -- -- This is equivalent to `screen.tags[i]:view_only()` --- @function awful.tag.viewidx +-- @staticfct awful.tag.viewidx -- @see screen.tags -- @param i The **relative** index to see. -- @param[opt] screen The screen. @@ -1357,14 +1358,14 @@ function tag.getidx(query_tag) end --- View next tag. This is the same as tag.viewidx(1). --- @function awful.tag.viewnext +-- @staticfct awful.tag.viewnext -- @param screen The screen. function tag.viewnext(screen) return tag.viewidx(1, screen) end --- View previous tag. This is the same a tag.viewidx(-1). --- @function awful.tag.viewprev +-- @staticfct awful.tag.viewprev -- @param screen The screen. function tag.viewprev(screen) return tag.viewidx(-1, screen) @@ -1404,7 +1405,7 @@ end -- selected. The tags already selected do not count. To do nothing if one or -- more of the tags are already selected, set `maximum` to zero. -- --- @function awful.tag.viewmore +-- @staticfct awful.tag.viewmore -- @param tags A table with tags to view only. -- @param[opt] screen The screen of the tags. -- @tparam[opt=#tags] number maximum The maximum number of tags to select. @@ -1437,7 +1438,7 @@ function tag.viewmore(tags, screen, maximum) end --- Toggle selection of a tag --- @function awful.tag.viewtoggle +-- @staticfct awful.tag.viewtoggle -- @see selected -- @tparam tag t Tag to be toggled function tag.viewtoggle(t) @@ -1530,7 +1531,7 @@ end --- Add a signal to all attached tags and all tags that will be attached in the -- future. When a tag is detached from the screen, its signal is removed. -- --- @function awful.tag.attached_connect_signal +-- @staticfct awful.tag.attached_connect_signal -- @screen screen The screen concerned, or all if nil. -- @tparam[opt] string signal The signal name. -- @tparam[opt] function Callback diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 85d318144..60e602c04 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -431,8 +431,7 @@ local titlebar = { --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @param args An array containing the widgets disposition --- @name setup --- @class function +-- @method setup local all_titlebars = setmetatable({}, { __mode = 'k' }) @@ -564,6 +563,7 @@ end -- @param c The client whose titlebar is modified -- @param[opt] position The position of the titlebar. Must be one of "left", -- "right", "top", "bottom". Default is "top". +-- @staticfct awful.titlebar.show function titlebar.show(c, position) position = position or "top" if load_titlebars(c, true, position) then return end @@ -577,6 +577,7 @@ end -- @param c The client whose titlebar is modified -- @param[opt] position The position of the titlebar. Must be one of "left", -- "right", "top", "bottom". Default is "top". +-- @staticfct awful.titlebar.hide function titlebar.hide(c, position) position = position or "top" get_titlebar_function(c, position)(c, 0) @@ -586,6 +587,7 @@ end -- @param c The client whose titlebar is modified -- @param[opt] position The position of the titlebar. Must be one of "left", -- "right", "top", "bottom". Default is "top". +-- @staticfct awful.titlebar.toggle function titlebar.toggle(c, position) position = position or "top" if load_titlebars(c, true, position) then return end @@ -602,6 +604,7 @@ end -- This way, you can e.g. modify the font that is used. -- @param c The client for which a titlewidget should be created. -- @return The title widget. +-- @staticfct awful.titlebar.widget.titlewidget function titlebar.widget.titlewidget(c) local ret = textbox() local function update() @@ -618,6 +621,7 @@ end -- available. This way, you can e.g. disallow resizes. -- @param c The client for which an icon widget should be created. -- @return The icon widget. +-- @staticfct awful.titlebar.widget.iconwidget function titlebar.widget.iconwidget(c) return clienticon(c) end @@ -635,6 +639,7 @@ end -- @param selector A function that selects the image that should be displayed. -- @param action Function that is called when the button is clicked. -- @return The widget +-- @staticfct awful.titlebar.widget.button function titlebar.widget.button(c, name, selector, action) local ret = imagebox() @@ -718,6 +723,7 @@ end --- Create a new float button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.floatingbutton function titlebar.widget.floatingbutton(c) local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle) c:connect_signal("property::floating", widget.update) @@ -726,6 +732,7 @@ end --- Create a new maximize button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.maximizedbutton function titlebar.widget.maximizedbutton(c) local widget = titlebar.widget.button(c, "maximized", function(cl) return cl.maximized @@ -738,6 +745,7 @@ end --- Create a new minimize button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.minimizebutton function titlebar.widget.minimizebutton(c) local widget = titlebar.widget.button(c, "minimize", function() return "" end, @@ -748,12 +756,14 @@ end --- Create a new closing button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.closebutton function titlebar.widget.closebutton(c) return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end) end --- Create a new ontop button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.ontopbutton function titlebar.widget.ontopbutton(c) local widget = titlebar.widget.button(c, "ontop", function(cl) return cl.ontop end, @@ -764,6 +774,7 @@ end --- Create a new sticky button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.stickybutton function titlebar.widget.stickybutton(c) local widget = titlebar.widget.button(c, "sticky", function(cl) return cl.sticky end, diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index 0420eb72c..930010adf 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -276,20 +276,13 @@ function tooltip:set_align(value) end --- The shape of the tooltip window. --- If the shape require some parameters, use `set_shape`. -- -- @DOC_awful_tooltip_shape_EXAMPLE@ -- -- @property shape -- @see gears.shape --- @see set_shape -- @see beautiful.tooltip_shape ---- Set the tooltip shape. --- All other arguments will be passed to the shape function. --- @tparam gears.shape s The shape --- @see shape --- @see gears.shape function tooltip:set_shape(s) self.backgroundbox:set_shape(s) end @@ -520,7 +513,7 @@ end -- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. --- @function add_to_object +-- @method add_to_object function tooltip:add_to_object(obj) if not obj then return end @@ -533,7 +526,7 @@ end -- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. --- @function remove_from_object +-- @method remove_from_object function tooltip:remove_from_object(obj) obj:disconnect_signal("mouse::enter", self.show) obj:disconnect_signal("mouse::leave", self.hide) diff --git a/lib/awful/util.lua b/lib/awful/util.lua index 66be0871a..d0a14d1fc 100644 --- a/lib/awful/util.lua +++ b/lib/awful/util.lua @@ -99,6 +99,7 @@ end --- Eval Lua code. -- @return The return value of Lua code. +-- @staticfct awful.util.eval function util.eval(s) return assert(load(s))() end @@ -129,6 +130,7 @@ end -- @param path The file path. -- @return A function if everything is alright, a string with the error -- otherwise. +-- @staticfct awful.util.checkfile function util.checkfile(path) local f, e = loadfile(path) -- Return function if function, otherwise return error. @@ -140,6 +142,7 @@ end -- It checks if the configuration file is valid, and then restart if it's ok. -- If it's not ok, the error will be returned. -- @return Never return if awesome restart, or return a string error. +-- @staticfct awful.util.restart function util.restart() local c = util.checkfile(capi.awesome.conffile) @@ -225,6 +228,7 @@ end -- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' } -- @tparam[opt] string size The size. If this is specified, subdirectories `x` -- of the dirs are searched first. +-- @staticfct awful.util.geticonpath function util.geticonpath(iconname, exts, dirs, size) exts = exts or { 'png', 'gif' } dirs = dirs or { '/usr/share/pixmaps/', '/usr/share/icons/hicolor/' } diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index 84846be72..b29d6d846 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -217,11 +217,6 @@ local function set_position(wb, position, skip_reattach) end end ---- Stretch the wibar. --- --- @property stretch --- @param[opt=true] boolean - local function get_stretch(w) return w._stretch end @@ -233,7 +228,8 @@ local function set_stretch(w, value) end --- Remove a wibar. --- @function remove +-- @method remove + local function remove(self) self.visible = false diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 566218768..f7e480f03 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -203,6 +203,7 @@ end -- @tparam string position Two-character position of the calendar in the screen -- @tparam screen screen Screen where to display the calendar -- @treturn wibox The wibox calendar +-- @method call_calendar function calendar_popup:call_calendar(offset, position, screen) local inc_offset = offset or 0 local pos = position or self.position @@ -230,7 +231,8 @@ function calendar_popup:call_calendar(offset, position, screen) return self end ---- Toggle calendar visibility +--- Toggle calendar visibility. +-- @method toggle function calendar_popup:toggle() self:call_calendar(0) self.visible = not self.visible @@ -247,6 +249,7 @@ end -- @tparam[opt={}] table args Additional options -- @tparam[opt=true] bool args.on_hover Show popup during mouse hover -- @treturn wibox The wibox calendar +-- @method attach function calendar_popup:attach(widget, position, args) position = position or "tr" args = args or {} diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index 3c15799c6..a87b556a1 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -135,6 +135,7 @@ end -- xkb_symbols pattern "vendor/file(section):group_idx". -- @tparam string group_names The string awesome.xkb_get_group_names() returns. -- @treturn table An array of tables whose keys are vendor, file, section, and group_idx. +-- @staticfct awful.keyboardlayout.get_groups_from_group_names function keyboardlayout.get_groups_from_group_names(group_names) if group_names == nil then return nil diff --git a/lib/beautiful/gtk.lua b/lib/beautiful/gtk.lua index 13a8023b8..1ff793838 100644 --- a/lib/beautiful/gtk.lua +++ b/lib/beautiful/gtk.lua @@ -63,54 +63,6 @@ local function read_gtk_color_properties_from_widget(gtk_widget, properties) return result end - --- luacheck: max comment line length 300 - ---- Get GTK+3 theme variables from GtkStyleContext --- @treturn table Key-value table with the following structure: ---
Modifier name Key name
--- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
Result key StyleContext key StyleContext fallback #1 StyleContext fallback #2 GTK Widget fallback
`font_size` Label font-size
`font_family` Label font-family
`bg_color` `theme_bg_color` Window bg
`fg_color` `theme_fg_color` Window fg
`base_color` `theme_base_color` Entry bg
`text_color` `theme_text_color` Entry fg
`button_bg_color` `theme_button_bg_color` `theme_bg_color` Button bg
`button_fg_color` `theme_button_fg_color` `theme_fg_color` Button fg
`button_border_color` Button border-color
`button_border_radius` Button border-radius
`button_border_width` Button border-top-width
`selected_bg_color` `theme_selected_bg_color` ToggleButton bg
`selected_fg_color` `theme_selected_fg_color` ToggleButton fg
`menubar_bg_color` `menubar_bg_color` `theme_bg_color` HeaderBar bg
`menubar_fg_color` `menubar_fg_color` `theme_fg_color` HeaderBar fg
`header_button_bg_color` `header_button_bg_color` `menubar_bg_color` `theme_bg_color` HeaderBar > Button bg
`header_button_fg_color` `header_button_fg_color` `menubar_fg_color` `theme_fg_color` HeaderBar > Button fg
`header_button_border_color` HeaderBar > Button border-color
`error_color` `error_color` `error_bg_color` destructive Button bg
`error_bg_color` `error_bg_color` `error_color` destructive Button bg
`error_fg_color` `error_fg_color` `theme_selected_fg_color` destructive Button fg
`warning_color` `warning_color` `warning_bg_color`
`warning_bg_color` `warning_bg_color` `warning_color`
`warning_fg_color` `warning_fg_color` `theme_selected_fg_color`
`success_color` `success_color` `success_bg_color`
`success_bg_color` `success_bg_color` `success_color`
`success_fg_color` `success_fg_color` `theme_selected_fg_color`
`tooltip_bg_color` `theme_tooltip_bg_color` `theme_bg_color`
`tooltip_fg_color` `theme_tooltip_fg_color` `theme_fg_color`
`osd_bg_color` `osd_bg` `theme_tooltip_bg_color` `theme_bg_color`
`osd_fg_color` `osd_fg` `theme_tooltip_fg_color` `theme_fg_color`
`osd_border_color` `osd_borders_color` `osd_fg_color`
`wm_bg_color` `wm_bg` `menubar_bg_color` `theme_bg_color` HeaderBar bg
`wm_border_focused_color` `wm_border_focused` `theme_selected_bg_color` ToggleButton bg
`wm_border_unfocused_color` `wm_border_unfocused` `wm_border` `menubar_bg_color` HeaderBar bg
`wm_title_focused_color` `wm_title_focused` `wm_title` `theme_selected_fg_color` ToggleButton fg
`wm_title_unfocused_color` `wm_title_unfocused` `wm_unfocused_title` `menubar_fg_color` HeaderBar fg
`wm_icons_focused_color` `wm_icons_focused` `wm_title_focused` `theme_selected_fg_color` ToggleButton fg
`wm_icons_unfocused_color` `wm_icons_unfocused` `wm_title_unfocused` `menubar_fg_color` HeaderBar fg
--- function gtk.get_theme_variables() if gtk.cached_theme_variables then return gtk.cached_theme_variables diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index f87aafd9e..5ab2d5821 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -37,6 +37,56 @@ local descs = setmetatable({}, { __mode = 'k' }) local fonts = setmetatable({}, { __mode = 'v' }) local active_font + +-- luacheck: max comment line length 300 + +--- Get GTK+3 theme variables from GtkStyleContext +-- @treturn table Key-value table with the following structure: +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +--
Result key StyleContext key StyleContext fallback #1 StyleContext fallback #2 GTK Widget fallback
`font_size` Label font-size
`font_family` Label font-family
`bg_color` `theme_bg_color` Window bg
`fg_color` `theme_fg_color` Window fg
`base_color` `theme_base_color` Entry bg
`text_color` `theme_text_color` Entry fg
`button_bg_color` `theme_button_bg_color` `theme_bg_color` Button bg
`button_fg_color` `theme_button_fg_color` `theme_fg_color` Button fg
`button_border_color` Button border-color
`button_border_radius` Button border-radius
`button_border_width` Button border-top-width
`selected_bg_color` `theme_selected_bg_color` ToggleButton bg
`selected_fg_color` `theme_selected_fg_color` ToggleButton fg
`menubar_bg_color` `menubar_bg_color` `theme_bg_color` HeaderBar bg
`menubar_fg_color` `menubar_fg_color` `theme_fg_color` HeaderBar fg
`header_button_bg_color` `header_button_bg_color` `menubar_bg_color` `theme_bg_color` HeaderBar > Button bg
`header_button_fg_color` `header_button_fg_color` `menubar_fg_color` `theme_fg_color` HeaderBar > Button fg
`header_button_border_color` HeaderBar > Button border-color
`error_color` `error_color` `error_bg_color` destructive Button bg
`error_bg_color` `error_bg_color` `error_color` destructive Button bg
`error_fg_color` `error_fg_color` `theme_selected_fg_color` destructive Button fg
`warning_color` `warning_color` `warning_bg_color`
`warning_bg_color` `warning_bg_color` `warning_color`
`warning_fg_color` `warning_fg_color` `theme_selected_fg_color`
`success_color` `success_color` `success_bg_color`
`success_bg_color` `success_bg_color` `success_color`
`success_fg_color` `success_fg_color` `theme_selected_fg_color`
`tooltip_bg_color` `theme_tooltip_bg_color` `theme_bg_color`
`tooltip_fg_color` `theme_tooltip_fg_color` `theme_fg_color`
`osd_bg_color` `osd_bg` `theme_tooltip_bg_color` `theme_bg_color`
`osd_fg_color` `osd_fg` `theme_tooltip_fg_color` `theme_fg_color`
`osd_border_color` `osd_borders_color` `osd_fg_color`
`wm_bg_color` `wm_bg` `menubar_bg_color` `theme_bg_color` HeaderBar bg
`wm_border_focused_color` `wm_border_focused` `theme_selected_bg_color` ToggleButton bg
`wm_border_unfocused_color` `wm_border_unfocused` `wm_border` `menubar_bg_color` HeaderBar bg
`wm_title_focused_color` `wm_title_focused` `wm_title` `theme_selected_fg_color` ToggleButton fg
`wm_title_unfocused_color` `wm_title_unfocused` `wm_unfocused_title` `menubar_fg_color` HeaderBar fg
`wm_icons_focused_color` `wm_icons_focused` `wm_title_focused` `theme_selected_fg_color` ToggleButton fg
`wm_icons_unfocused_color` `wm_icons_unfocused` `wm_title_unfocused` `menubar_fg_color` HeaderBar fg
+-- +-- @staticfct beautiful.gtk.get_theme_variables + --- The default font. -- @beautiful beautiful.font @@ -155,6 +205,7 @@ end -- See https://developer.gnome.org/pango/stable/pango-Fonts.html#PangoFontDescription. -- @tparam string|lgi.Pango.FontDescription name The name of the font. -- @treturn lgi.Pango.FontDescription +-- @staticfct beautiful.get_font function beautiful.get_font(name) return load_font(name).description end @@ -165,6 +216,7 @@ end -- @tparam string|Pango.FontDescription name The base font. -- @tparam string merge Attributes that should be merged, e.g. "bold". -- @treturn lgi.Pango.FontDescription +-- @staticfct beautiful.get_merged_font function beautiful.get_merged_font(name, merge) local font = beautiful.get_font(name) merge = Pango.FontDescription.from_string(merge) @@ -175,7 +227,8 @@ end --- Get the height of a font. -- --- @param name Name of the font +-- @param name Name of the font. +-- @staticfct beautiful.get_font_height function beautiful.get_font_height(name) return load_font(name).height end @@ -208,6 +261,7 @@ end -- the theme file (which should return a table) or directly a table -- containing all the theme values. -- @treturn true|nil True if successful, nil in case of error. +-- @staticfct beautiful.init function beautiful.init(config) if config then local state, t_theme = nil, nil @@ -258,6 +312,7 @@ end --- Get the current theme. -- -- @treturn table The current theme table. +-- @staticfct beautiful.get function beautiful.get() return theme end diff --git a/lib/beautiful/theme_assets.lua b/lib/beautiful/theme_assets.lua index b7f6e7806..555a963f8 100644 --- a/lib/beautiful/theme_assets.lua +++ b/lib/beautiful/theme_assets.lua @@ -3,7 +3,7 @@ -- -- @author Yauhen Kirylau <yawghen@gmail.com> -- @copyright 2015 Yauhen Kirylau --- @submodule beautiful +-- @module beautiful ---------------------------------------------------------------------------- local cairo = require("lgi").cairo @@ -19,6 +19,7 @@ local theme_assets = {} -- @tparam number size Size. -- @tparam color fg Background color. -- @return Image with the square. +-- @staticfct beautiful.theme_assets.taglist_squares_sel function theme_assets.taglist_squares_sel(size, fg) local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size) local cr = cairo.Context(img) @@ -31,6 +32,7 @@ end -- @tparam number size Size. -- @tparam color fg Background color. -- @return Image with the square. +-- @staticfct beautiful.theme_assets.taglist_squares_unsel function theme_assets.taglist_squares_unsel(size, fg) local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size) local cr = cairo.Context(img) @@ -84,6 +86,7 @@ end -- @tparam color bg Background color. -- @tparam color fg Main foreground color. -- @tparam color alt_fg Accent foreground color. +-- @staticfct beautiful.theme_assets.gen_awesome_name function theme_assets.gen_awesome_name(cr, height, bg, fg, alt_fg) local ls = height/10 -- letter_size local letter_line = ls/18 @@ -152,6 +155,7 @@ end -- @tparam number height Height. -- @tparam color bg Background color. -- @tparam color fg Foreground color. +-- @staticfct beautiful.theme_assets.gen_logo function theme_assets.gen_logo(cr, width, height, bg, fg) local ls = math.min(width, height) @@ -174,6 +178,7 @@ end -- @tparam color bg Background color. -- @tparam color fg Background color. -- @return Image with the logo. +-- @staticfct beautiful.theme_assets.awesome_icon function theme_assets.awesome_icon(size, bg, fg) local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size) local cr = cairo.Context(img) @@ -187,6 +192,7 @@ end -- @tparam color alt_fg Accent foreground color. -- @tparam screen s Screen (to get wallpaper size). -- @return Wallpaper image. +-- @staticfct beautiful.theme_assets.wallpaper function theme_assets.wallpaper(bg, fg, alt_fg, s) s = s or screen.primary local height = s.geometry.height @@ -215,6 +221,7 @@ end -- @tparam string postfix `nil`, `"hover"` or `"press"`. -- @tparam string toggle_state `nil`, `"active"` or `"inactive"`. -- @treturn table Beautiful theme table with the images recolored. +-- @staticfct beautiful.theme_assets.recolor_titlebar function theme_assets.recolor_titlebar(theme, color, state, postfix, toggle_state) if postfix then postfix='_'..postfix end if toggle_state then toggle_state='_'..toggle_state end @@ -266,6 +273,7 @@ end -- @tparam table theme Beautiful theme table -- @tparam color color Icons' color. -- @treturn table Beautiful theme table with the images recolored. +-- @staticfct beautiful.theme_assets.recolor_layout function theme_assets.recolor_layout(theme, color) for _, layout_name in ipairs({ 'layout_fairh', diff --git a/lib/beautiful/xresources.lua b/lib/beautiful/xresources.lua index 5e45b4fc3..71299cb44 100644 --- a/lib/beautiful/xresources.lua +++ b/lib/beautiful/xresources.lua @@ -3,7 +3,7 @@ -- -- @author Yauhen Kirylau <yawghen@gmail.com> -- @copyright 2015 Yauhen Kirylau --- @submodule beautiful +-- @module beautiful ---------------------------------------------------------------------------- -- Grab environment @@ -45,7 +45,8 @@ local fallback = { } --- Get current base colorscheme from xrdb. --- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15' +-- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15'. +-- @staticfct beautiful.xresources.get_current_theme function xresources.get_current_theme() local keys = { 'background', 'foreground' } for i=0,15 do table.insert(keys, "color"..i) end @@ -77,7 +78,7 @@ end -- This function is deprecated. Use `s.dpi` and avoid getting the DPI without -- a screen. -- --- @deprecated xresources.get_dpi +-- @deprecated beautiful.xresources.get_dpi -- @tparam[opt] integer|screen s The screen. -- @treturn number DPI value. @@ -118,6 +119,7 @@ end --- Set DPI for a given screen (defaults to global). -- @tparam number dpi DPI value. -- @tparam[opt] integer s Screen. +-- @staticfct beautiful.xresources.set_dpi function xresources.set_dpi(dpi, s) s = get_screen(s) if not s then @@ -132,6 +134,7 @@ end -- @tparam number size Size -- @tparam[opt] integer|screen s The screen. -- @treturn integer Resulting size (rounded to integer). +-- @staticfct beautiful.xresources.apply_dpi function xresources.apply_dpi(size, s) return round(size / 96 * xresources.get_dpi(s)) end diff --git a/lib/gears/color.lua b/lib/gears/color.lua index 10f6a2bc4..0e1d9be48 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -32,10 +32,6 @@ -- calling :set_matrix() on it, because this function uses a cache and your -- changes could thus have unintended side effects. Use @{create_pattern_uncached} -- if you need to modify the returned pattern. --- @see create_pattern_uncached, create_solid_pattern, create_png_pattern, --- create_linear_pattern, create_radial_pattern --- @tparam string col The string describing the pattern. --- @return a cairo pattern object -- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter @@ -65,6 +61,7 @@ local pattern_cache -- @param col The color to parse -- @treturn table 4 values representing color in RGBA format (each of them in -- [0, 1] range) or nil if input is incorrect. +-- @staticfct gears.color.parse_color -- @usage -- This will return 0, 1, 0, 1 -- gears.color.parse_color("#00ff00ff") function color.parse_color(col) @@ -123,6 +120,7 @@ end -- -- @param col The color for the pattern -- @return A cairo pattern object +-- @staticfct gears.color.create_solid_pattern function color.create_solid_pattern(col) if col == nil then col = "#000000" @@ -136,6 +134,7 @@ end -- -- @param file The filename of the file -- @return a cairo pattern object +-- @staticfct gears.color.create_png_pattern function color.create_png_pattern(file) if type(file) == "table" then file = file.file @@ -192,6 +191,7 @@ end -- For the explanation of ``, see `color.create_pattern`. -- @tparam string|table arg The argument describing the pattern. -- @return a cairo pattern object +-- @staticfct gears.color.create_linear_pattern function color.create_linear_pattern(arg) local pat @@ -217,6 +217,7 @@ end -- For the explanation of ``, see `color.create_pattern`. -- @tparam string|table arg The argument describing the pattern -- @return a cairo pattern object +-- @staticfct gears.color.create_radial_pattern function color.create_radial_pattern(arg) local pat @@ -249,6 +250,7 @@ color.types = { -- @see create_pattern -- @param col The string describing the pattern. -- @return a cairo pattern object +-- @staticfct gears.color.create_pattern_uncached function color.create_pattern_uncached(col) -- If it already is a cairo pattern, just leave it as that if cairo.Pattern:is_type_of(col) then @@ -273,6 +275,7 @@ end --- Create a pattern from a given string, same as @{gears.color}. -- @see gears.color +-- @staticfct gears.color.create_pattern function color.create_pattern(col) if cairo.Pattern:is_type_of(col) then return col @@ -285,6 +288,7 @@ end -- operator OVER) doesn't influence the visual result. -- @param col An argument that `create_pattern` accepts. -- @return The pattern if it is surely opaque, else nil +-- @staticfct gears.color.create_opaque_pattern function color.create_opaque_pattern(col) local pattern = color.create_pattern(col) local kind = pattern:get_type() @@ -335,6 +339,7 @@ end -- @param image Image or path to it. -- @param new_color New color. -- @return Recolored image. +-- @staticfct gears.color.recolor_image function color.recolor_image(image, new_color) if type(image) == 'string' then image = surface.duplicate_surface(image) @@ -349,6 +354,7 @@ end -- @param check_color The color to check. -- @tparam string fallback The color to return if the first is invalid. (default: black) -- @treturn string color if it is valid, else fallback. +-- @staticfct gears.color.ensure_pango_color function color.ensure_pango_color(check_color, fallback) check_color = tostring(check_color) -- Pango markup supports alpha, PangoColor does not. Thus, check for this. diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua index f8aeccff0..98271f180 100644 --- a/lib/gears/debug.lua +++ b/lib/gears/debug.lua @@ -49,6 +49,7 @@ end -- @param tag The name of the value. -- @tparam[opt] int depth Depth of recursion. -- @return string A string that contains the expanded value of data. +-- @staticfct gears.debug.dump_return function debug.dump_return(data, tag, depth) return dump_raw(data, nil, tag, depth) end @@ -57,23 +58,27 @@ end -- @param data Table to print. -- @param tag The name of the table. -- @tparam[opt] int depth Depth of recursion. +-- @staticfct gears.debug.dump function debug.dump(data, tag, depth) print(debug.dump_return(data, tag, depth)) end --- Print an warning message --- @tparam string message The warning message to print +-- @tparam string message The warning message to print. +-- @staticfct gears.debug.print_warning function debug.print_warning(message) io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n") end --- Print an error message --- @tparam string message The error message to print +-- @tparam string message The error message to print. +-- @staticfct gears.debug.print_error function debug.print_error(message) io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n") end local displayed_deprecations = {} + --- Display a deprecation notice, but only once per traceback. -- -- This function also emits the `debug::deprecate` signal on the `awesome` @@ -84,6 +89,7 @@ local displayed_deprecations = {} -- @tparam boolean args.raw Print the message as-is without the automatic context -- @tparam integer args.deprecated_in Print the message only when Awesome's -- version is equal to or greater than deprecated_in. +-- @staticfct gears.debug.deprecate function debug.deprecate(see, args) args = args or {} if args.deprecated_in then @@ -124,6 +130,7 @@ end -- @tparam string old_name The old class name -- @tparam string new_name The new class name -- @treturn table A proxy class. +-- @staticfct gears.debug.deprecate_class function debug.deprecate_class(fallback, old_name, new_name) local message = old_name.." has been renamed to "..new_name diff --git a/lib/gears/filesystem.lua b/lib/gears/filesystem.lua index 3179292ac..a555130d2 100644 --- a/lib/gears/filesystem.lua +++ b/lib/gears/filesystem.lua @@ -26,6 +26,7 @@ end --- Create a directory, including all missing parent directories. -- @tparam string dir The directory. -- @return (true, nil) on success, (false, err) on failure +-- @staticfct gears.filesystem.make_directories function filesystem.make_directories(dir) return make_directory(Gio.File.new_for_path(dir)) end @@ -37,7 +38,8 @@ end --- Create all parent directories for a given path. -- @tparam string path The path whose parents should be created. --- @return (true, nil) on success, (false, err) on failure +-- @return (true, nil) on success, (false, err) on failure. +-- @staticfct gears.filesystem.make_parent_directories function filesystem.make_parent_directories(path) return make_directory(Gio.File.new_for_path(path):get_parent()) end @@ -45,6 +47,7 @@ end --- Check if a file exists, is readable and not a directory. -- @tparam string filename The file path. -- @treturn boolean True if file exists and is readable. +-- @staticfct gears.filesystem.file_readable function filesystem.file_readable(filename) local gfile = Gio.File.new_for_path(filename) local gfileinfo = gfile:query_info("standard::type,access::can-read", @@ -56,6 +59,7 @@ end --- Check if a file exists, is executable and not a directory. -- @tparam string filename The file path. -- @treturn boolean True if file exists and is executable. +-- @staticfct gears.filesystem.file_executable function filesystem.file_executable(filename) local gfile = Gio.File.new_for_path(filename) local gfileinfo = gfile:query_info("standard::type,access::can-execute", @@ -67,6 +71,7 @@ end --- Check if a path exists, is readable and a directory. -- @tparam string path The directory path. -- @treturn boolean True if path exists and is readable. +-- @staticfct gears.filesystem.dir_readable function filesystem.dir_readable(path) local gfile = Gio.File.new_for_path(path) local gfileinfo = gfile:query_info("standard::type,access::can-read", @@ -78,30 +83,35 @@ end --- Check if a path is a directory. -- @tparam string path The directory path -- @treturn boolean True if path exists and is a directory. +-- @staticfct gears.filesystem.is_dir function filesystem.is_dir(path) return Gio.File.new_for_path(path):query_file_type({}) == "DIRECTORY" end --- Get the config home according to the XDG basedir specification. -- @return the config home (XDG_CONFIG_HOME) with a slash at the end. +-- @staticfct gears.filesystem.get_xdg_config_home function filesystem.get_xdg_config_home() return (os.getenv("XDG_CONFIG_HOME") or os.getenv("HOME") .. "/.config") .. "/" end --- Get the cache home according to the XDG basedir specification. -- @return the cache home (XDG_CACHE_HOME) with a slash at the end. +-- @staticfct gears.filesystem.get_xdg_cache_home function filesystem.get_xdg_cache_home() return (os.getenv("XDG_CACHE_HOME") or os.getenv("HOME") .. "/.cache") .. "/" end --- Get the data home according to the XDG basedir specification. -- @treturn string the data home (XDG_DATA_HOME) with a slash at the end. +-- @staticfct gears.filesystem.get_xdg_data_home function filesystem.get_xdg_data_home() return (os.getenv("XDG_DATA_HOME") or os.getenv("HOME") .. "/.local/share") .. "/" end --- Get the data dirs according to the XDG basedir specification. -- @treturn table the data dirs (XDG_DATA_DIRS) with a slash at the end of each entry. +-- @staticfct gears.filesystem.get_xdg_data_dirs function filesystem.get_xdg_data_dirs() local xdg_data_dirs = os.getenv("XDG_DATA_DIRS") or "/usr/share:/usr/local/share" return gtable.map( @@ -112,12 +122,14 @@ end --- Get the path to the user's config dir. -- This is the directory containing the configuration file ("rc.lua"). -- @return A string with the requested path with a slash at the end. +-- @staticfct gears.filesystem.get_configuration_dir function filesystem.get_configuration_dir() return awesome.conffile:match(".*/") or "./" end --- Get the path to a directory that should be used for caching data. -- @return A string with the requested path with a slash at the end. +-- @staticfct gears.filesystem.get_cache_dir function filesystem.get_cache_dir() local result = filesystem.get_xdg_cache_home() .. "awesome/" filesystem.make_directories(result) @@ -126,12 +138,14 @@ end --- Get the path to the directory where themes are installed. -- @return A string with the requested path with a slash at the end. +-- @staticfct gears.filesystem.get_themes_dir function filesystem.get_themes_dir() return (os.getenv('AWESOME_THEMES_PATH') or awesome.themes_path) .. "/" end --- Get the path to the directory where our icons are installed. -- @return A string with the requested path with a slash at the end. +-- @staticfct gears.filesystem.get_awesome_icon_dir function filesystem.get_awesome_icon_dir() return (os.getenv('AWESOME_ICON_PATH') or awesome.icon_path) .. "/" end @@ -141,6 +155,7 @@ end -- default paths. -- @param d The directory to get (either "config" or "cache"). -- @return A string containing the requested path. +-- @staticfct gears.filesystem.get_dir function filesystem.get_dir(d) if d == "config" then -- No idea why this is what is returned, I recommend everyone to use @@ -159,6 +174,7 @@ end -- If ommited, all files are considered. -- @treturn string|nil A randomly selected filename from the specified path (with -- a specified extension if required) or nil if no suitable file is found. +-- @staticfct gears.filesystem.get_random_file_from_dir function filesystem.get_random_file_from_dir(path, exts) local files, valid_exts = {}, {} diff --git a/lib/gears/geometry.lua b/lib/gears/geometry.lua index 98c5c2ab3..364aedf96 100644 --- a/lib/gears/geometry.lua +++ b/lib/gears/geometry.lua @@ -21,7 +21,8 @@ local gears = {geometry = {rectangle = {} } } -- @tparam number geom.height The rectangle height -- @tparam number x X coordinate of point -- @tparam number y Y coordinate of point --- @treturn number The squared distance of the rectangle to the provided point +-- @treturn number The squared distance of the rectangle to the provided point. +-- @staticfct gears.geometry.rectangle.get_square_distance function gears.geometry.rectangle.get_square_distance(geom, x, y) local dist_x, dist_y = 0, 0 if x < geom.x then @@ -42,6 +43,7 @@ end -- @tparam number x The x coordinate -- @tparam number y The y coordinate -- @return The key from the closest geometry. +-- @staticfct gears.geometry.rectangle.get_closest_by_coord function gears.geometry.rectangle.get_closest_by_coord(list, x, y) local dist = math.huge local ret = nil @@ -66,6 +68,7 @@ end -- @tparam number y The y coordinate -- @return The key from the closest geometry. In case no result is found, *nil* -- is returned. +-- @staticfct gears.geometry.rectangle.get_by_coord function gears.geometry.rectangle.get_by_coord(list, x, y) for k, geometry in pairs(list) do if x >= geometry.x and x < geometry.x + geometry.width @@ -126,6 +129,7 @@ end -- @tparam table recttbl A table of rectangle specifications. -- @tparam table cur The current rectangle. -- @return The index for the rectangle in recttbl closer to cur in the given direction. nil if none found. +-- @staticfct gears.geometry.rectangle.get_in_direction function gears.geometry.rectangle.get_in_direction(dir, recttbl, cur) local dist, dist_min local target = nil @@ -151,6 +155,7 @@ end -- @param a The area. -- @param b The other area. -- @return True if they intersect, false otherwise. +-- @staticfct gears.geometry.rectangle.area_intersect_area function gears.geometry.rectangle.area_intersect_area(a, b) return (b.x < a.x + a.width and b.x + b.width > a.x @@ -170,6 +175,7 @@ end -- @tparam number b.width The rectangle width -- @tparam number b.height The rectangle height -- @treturn table The intersect area. +-- @staticfct gears.geometry.rectangle.get_intersection function gears.geometry.rectangle.get_intersection(a, b) local g = {} g.x = math.max(a.x, b.x) @@ -191,6 +197,7 @@ end -- @tparam number elem.width The rectangle width -- @tparam number elem.height The rectangle height -- @return The new area list. +-- @staticfct gears.geometry.rectangle.area_remove function gears.geometry.rectangle.area_remove(areas, elem) for i = #areas, 1, -1 do -- Check if the 'elem' intersect diff --git a/lib/gears/math.lua b/lib/gears/math.lua index 58c69ad8f..2bacf6bbf 100644 --- a/lib/gears/math.lua +++ b/lib/gears/math.lua @@ -37,10 +37,9 @@ end -- For example, if we consider a set with value { 10, 15, 34 }, -- it will return a table containing 2^n set: -- { }, { 10 }, { 15 }, { 34 }, { 10, 15 }, { 10, 34 }, etc. --- @class function --- @name subsets -- @param set A set. -- @return A table with all subset. +-- @staticfct gears.math.subsets function gmath.subsets(set) local mask = {} local ret = {} @@ -56,11 +55,10 @@ function gmath.subsets(set) end --- Make i cycle. --- @class function --- @name cycle -- @param t A length. Must be greater than zero. -- @param i An absolute index to fit into #t. -- @return An integer in (1, t) or nil if t is less than or equal to zero. +-- @staticfct gears.math.cycle function gmath.cycle(t, i) if t < 1 then return end i = i % t @@ -71,10 +69,9 @@ function gmath.cycle(t, i) end --- Round a number to an integer. --- @class function --- @name round -- @tparam number x -- @treturn integer +-- @staticfct gears.math.round function gmath.round(x) return math.floor(x + 0.5) end diff --git a/lib/gears/object.lua b/lib/gears/object.lua index d6f539fdc..a7be7f35c 100644 --- a/lib/gears/object.lua +++ b/lib/gears/object.lua @@ -49,6 +49,7 @@ end --@DOC_text_gears_object_signal_EXAMPLE@ -- @tparam string name The name of the signal -- @tparam function func The callback to call when the signal is emitted +-- @method connect_signal function object:connect_signal(name, func) assert(type(func) == "function", "callback must be a function, got: " .. type(func)) local sig = find_signal(self, name) @@ -95,6 +96,7 @@ end -- collected and automatically disconnects the signal when that happens. -- @tparam string name The name of the signal -- @tparam function func The callback to call when the signal is emitted +-- @method weak_connect_signal function object:weak_connect_signal(name, func) assert(type(func) == "function", "callback must be a function, got: " .. type(func)) local sig = find_signal(self, name) @@ -105,6 +107,7 @@ end --- Disonnect to a signal. -- @tparam string name The name of the signal -- @tparam function func The callback that should be disconnected +-- @method disconnect_signal function object:disconnect_signal(name, func) local sig = find_signal(self, name) sig.weak[func] = nil @@ -117,6 +120,7 @@ end -- @param ... Extra arguments for the callback functions. Each connected -- function receives the object as first argument and then any extra arguments -- that are given to emit_signal() +-- @method emit_signal function object:emit_signal(name, ...) local sig = find_signal(self, name) for func in pairs(sig.strong) do @@ -179,7 +183,8 @@ end -- when an unknown property is set. -- @tparam[opt=nil] table args.class -- @treturn table A new object --- @function gears.object +-- @constructorfct gears.object + local function new(args) args = args or {} local ret = {} @@ -236,6 +241,7 @@ end -- @tparam[opt=2] integer level Level for `debug.getinfo(level, "S")`. -- Typically 2 or 3. -- @treturn string The module name, e.g. "wibox.container.background". +-- @staticfct gears.object.modulename function object.modulename(level) return debug.getinfo(level, "S").source:gsub(".*/lib/", ""):gsub("/", "."):gsub("%.lua", "") end diff --git a/lib/gears/protected_call.lua b/lib/gears/protected_call.lua index d8f626421..e42bc7079 100644 --- a/lib/gears/protected_call.lua +++ b/lib/gears/protected_call.lua @@ -43,6 +43,7 @@ end -- @tparam function func The function to call -- @param ... Arguments to the function -- @return The result of the given function, or nothing if an error occurred. +-- @staticfct gears.protected_call function protected_call.call(func, ...) return do_pcall(func, ...) end diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index 707e06cc5..c051a0110 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -55,6 +55,7 @@ local module = {} -- @tparam number width The rectangle width -- @tparam number height The rectangle height -- @tparam number radius the corner radius +-- @staticfct gears.shape.rounded_rect function module.rounded_rect(cr, width, height, radius) radius = radius or 10 @@ -83,7 +84,8 @@ end -- -- @param cr A cairo content -- @param width The rectangle width --- @param height The rectangle height +-- @param height The rectangle height. +-- @staticfct gears.shape.rounded_bar function module.rounded_bar(cr, width, height) module.rounded_rect(cr, width, height, height / 2) end @@ -100,6 +102,7 @@ end -- @tparam boolean br If the bottom right corner is rounded -- @tparam boolean bl If the bottom left corner is rounded -- @tparam number rad The corner radius +-- @staticfct gears.shape.partially_rounded_rect function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad) rad = rad or 10 if width / 2 < rad then @@ -151,6 +154,7 @@ end -- @tparam[opt=5] number corner_radius The corner radius -- @tparam[opt=10] number arrow_size The width and height of the arrow -- @tparam[opt=width/2 - arrow_size/2] number arrow_position The position of the arrow +-- @staticfct gears.shape.infobubble function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position) arrow_size = arrow_size or 10 corner_radius = math.min((height-arrow_size)/2, corner_radius or 5) @@ -184,6 +188,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=height/2] number arrow_length The length of the arrow part +-- @staticfct gears.shape.rectangular_tag function module.rectangular_tag(cr, width, height, arrow_length) arrow_length = arrow_length or height/2 if arrow_length > 0 then @@ -213,6 +218,7 @@ end -- @tparam[opt=head_width] number head_width The width of the head (/\) of the arrow -- @tparam[opt=width /2] number shaft_width The width of the shaft of the arrow -- @tparam[opt=height/2] number shaft_length The head_length of the shaft (the rest is the head) +-- @staticfct gears.shape.arrow function module.arrow(cr, width, height, head_width, shaft_width, shaft_length) shaft_length = shaft_length or height / 2 shaft_width = shaft_width or width / 2 @@ -237,6 +243,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @staticfct gears.shape.hexagon function module.hexagon(cr, width, height) cr:move_to(height/2,0) cr:line_to(width-height/2,0) @@ -256,6 +263,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=height/2] number arrow_depth The width of the arrow part of the shape +-- @staticfct gears.shape.powerline function module.powerline(cr, width, height, arrow_depth) arrow_depth = arrow_depth or height/2 local offset = 0 @@ -283,6 +291,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @staticfct gears.shape.isosceles_triangle function module.isosceles_triangle(cr, width, height) cr:move_to( width/2, 0 ) cr:line_to( width , height ) @@ -298,6 +307,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=width/3] number thickness The cross section thickness +-- @staticfct gears.shape.cross function module.cross(cr, width, height, thickness) thickness = thickness or width/3 local xpadding = (width - thickness) / 2 @@ -325,6 +335,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam number corner_radius +-- @staticfct gears.shape.octogon function module.octogon(cr, width, height, corner_radius) corner_radius = corner_radius or math.min(10, math.min(width, height)/4) local offset = math.sqrt( (corner_radius*corner_radius) / 2 ) @@ -348,6 +359,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=math.min(width height) / 2)] number radius The radius +-- @staticfct gears.shape.circle function module.circle(cr, width, height, radius) radius = radius or math.min(width, height) / 2 cr:move_to(width/2+radius, height/2) @@ -362,6 +374,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @staticfct gears.shape.rectangle function module.rectangle(cr, width, height) cr:rectangle(0, 0, width, height) end @@ -375,6 +388,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=width/3] number base_width The parallelogram base width +-- @staticfct gears.shape.parallelogram function module.parallelogram(cr, width, height, base_width) base_width = base_width or width/3 cr:move_to(width-base_width, 0 ) @@ -391,6 +405,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @staticfct gears.shape.losange function module.losange(cr, width, height) cr:move_to(width/2 , 0 ) cr:line_to(width , height/2 ) @@ -411,6 +426,7 @@ end -- @tparam[opt=0] number start_angle The start angle (in radian) -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian) -- @tparam[opt=math.min(width height)/2] number radius The shape height +-- @staticfct gears.shape.pie function module.pie(cr, width, height, start_angle, end_angle, radius) radius = radius or math.floor(math.min(width, height)/2) start_angle, end_angle = start_angle or 0, end_angle or math.pi/2 @@ -444,6 +460,7 @@ end -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian) -- @tparam[opt=false] boolean start_rounded if the arc start rounded -- @tparam[opt=false] boolean end_rounded if the arc end rounded +-- @staticfct gears.shape.arc function module.arc(cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded) start_angle = start_angle or 0 end_angle = end_angle or math.pi/2 @@ -562,6 +579,7 @@ end -- @tparam number h The shape height -- @tparam number percent The progressbar percent -- @tparam boolean hide_left Do not draw the left side of the shape +-- @staticfct gears.shape.radial_progress function module.radial_progress(cr, w, h, percent, hide_left) percent = percent or 1 local total_length = (2*(w-h))+2*((h/2)*math.pi) @@ -628,6 +646,7 @@ end -- -- @param shape A shape function -- @return A transformation handle, also act as a shape function +-- @staticfct gears.shape.transform function module.transform(shape) -- Apply the transformation matrix and apply the shape, then restore diff --git a/lib/gears/sort/topological.lua b/lib/gears/sort/topological.lua index 58ff32c7f..8064e40cb 100644 --- a/lib/gears/sort/topological.lua +++ b/lib/gears/sort/topological.lua @@ -18,6 +18,7 @@ end --- Ensure that `node` appears after all `dependencies`. -- @param node The node that edges are added to. -- @tparam table dependencies List of nodes that have to appear before `node`. +-- @method append function tsort:append(node, dependencies) add_node(self, node) for _, dep in ipairs(dependencies) do @@ -29,6 +30,7 @@ end --- Ensure that `node` appears before all `subordinates`. -- @param node The node that edges are added to. -- @tparam table subordinates List of nodes that have to appear after `node`. +-- @method prepend function tsort:prepend(node, subordinates) for _, dep in ipairs(subordinates) do self:append(dep, { node }) @@ -63,6 +65,7 @@ end --- Create a copy of this topological sort. -- This is useful to backup it before adding elements that can potentially -- have circular dependencies and thus render the original useless. +-- @method clone function tsort:clone() local new = tsort.topological() @@ -75,6 +78,7 @@ end --- Remove a node from the topological map. -- -- @param node The node +-- @method remove function tsort:remove(node) self._edges[node] = nil for _, deps in pairs(self._edges) do @@ -86,6 +90,7 @@ end -- @treturn[1] table A sorted list of nodes -- @treturn[2] nil -- @return[2] A node around which a loop exists +-- @method sort function tsort:sort() local result, state = {}, {} for node in pairs(self._edges) do @@ -104,7 +109,7 @@ end -- --@DOC_text_gears_sort_topological_EXAMPLE@ -- --- @function gears.sort.topological +-- @constructorfct gears.sort.topological function tsort.topological() return setmetatable({ diff --git a/lib/gears/string.lua b/lib/gears/string.lua index 84c577881..ff551883a 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -7,43 +7,41 @@ local gstring = {} local xml_entity_names = { ["'"] = "'", ["\""] = """, ["<"] = "<", [">"] = ">", ["&"] = "&" }; + --- Escape a string from XML char. -- Useful to set raw text in textbox. --- @class function --- @name xml_escape -- @param text Text to escape. -- @return Escape text. +-- @staticfct gears.string.xml_escape function gstring.xml_escape(text) return text and text:gsub("['&<>\"]", xml_entity_names) or nil end local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "'", ndash = "-", mdash = "-", - amp = "&" }; + amp = "&" }; + --- Unescape a string from entities. --- @class function --- @name xml_unescape -- @param text Text to unescape. -- @return Unescaped text. +-- @staticfct gears.string.xml_unescape function gstring.xml_unescape(text) return text and text:gsub("&(%a+);", xml_entity_chars) or nil end --- Count number of lines in a string --- @class function --- @name linecount -- @tparam string text Input string. -- @treturn int Number of lines. +-- @staticfct gears.string.linecount function gstring.linecount(text) return select(2, text:gsub('\n', '\n')) + 1 end ---- Split a string into multiple lines --- @class function --- @name linewrap +--- Split a string into multiple lines. -- @param text String to wrap. -- @param width Maximum length of each line. Default: 72. -- @param indent Number of spaces added before each wrapped line. Default: 0. -- @return The string with lines wrapped to width. +-- @staticfct gears.string.linewrap function gstring.linewrap(text, width, indent) text = text or "" width = width or 72 @@ -62,8 +60,7 @@ end --- Escape all special pattern-matching characters so that lua interprets them -- literally instead of as a character class. -- Source: http://stackoverflow.com/a/20778724/15690 --- @class function --- @name quote_pattern +-- @staticfct gears.string.quote_pattern function gstring.quote_pattern(s) -- All special characters escaped in a string: %%, %^, %$, ... local patternchars = '['..("%^$().[]*+-?"):gsub("(.)", "%%%1")..']' @@ -72,8 +69,7 @@ end --- Generate a pattern matching expression that ignores case. -- @param s Original pattern matching expression. --- @class function --- @name query_to_pattern +-- @staticfct gears.string.query_to_pattern function gstring.query_to_pattern(q) local s = gstring.quote_pattern(q) -- Poor man's case-insensitive character matching. @@ -87,11 +83,10 @@ end --- Split separates a string containing a delimiter into the list of -- substrings between that delimiter. --- @class function --- @name split -- @tparam string str String to be splitted -- @tparam string delimiter Character where the string will be splitted -- @treturn table list of the substrings +-- @staticfct gears.string.split function gstring.split(str, delimiter) local pattern = "(.-)" .. delimiter .. "()" local result = {} @@ -106,22 +101,20 @@ function gstring.split(str, delimiter) return result end ---- Check if a string starts with another string --- @class function --- @name startswith +--- Check if a string starts with another string. -- @tparam string str String to search --- @tparam string sub String to check for +-- @tparam string sub String to check for. +-- @staticfct gears.string.startswith function gstring.startswith(str, sub) - return string.sub(str, 1, string.len(sub)) == sub + return string.sub(str, 1, string.len(sub)) == sub end ---- Check if a string ends with another string --- @class function --- @name endswith +--- Check if a string ends with another string. -- @tparam string str String to search --- @tparam string sub String to check for +-- @tparam string sub String to check for. +-- @staticfct gears.string.endswith function gstring.endswith(str, sub) - return sub == "" or string.sub(str,-string.len(sub)) == sub + return sub == "" or string.sub(str,-string.len(sub)) == sub end return gstring diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index dc61efd82..b85c7de19 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -35,7 +35,8 @@ end -- @param default The default value to return on error; when nil, then a surface -- in an error state is returned. -- @return The loaded surface, or the replacement default --- @return An error message, or nil on success +-- @return An error message, or nil on success. +-- @staticfct load_uncached_silently function surface.load_uncached_silently(_surface, default) -- On nil, return some sane default if not _surface then @@ -71,7 +72,8 @@ end -- in an error state is returned. -- @return The loaded surface, or the replacement default, or nil if called with -- nil. --- @return An error message, or nil on success +-- @return An error message, or nil on success. +-- @staticfct load_silently function surface.load_silently(_surface, default) if type(_surface) == "string" then local cache = surface_cache[_surface] @@ -106,6 +108,7 @@ end -- via `gears.debug.print_error`. -- @param _surface The surface to load or nil -- @return The loaded surface, or nil +-- @staticfct load_uncached function surface.load_uncached(_surface) return do_load_and_handle_errors(_surface, surface.load_uncached_silently) end @@ -114,7 +117,8 @@ end -- This is usually needed for loading images by file name. Errors are handled -- via `gears.debug.print_error`. -- @param _surface The surface to load or nil --- @return The loaded surface, or nil +-- @return The loaded surface, or nil. +-- @staticfct gears.surface function surface.load(_surface) return do_load_and_handle_errors(_surface, surface.load_silently) end @@ -125,7 +129,8 @@ end --- Get the size of a cairo surface -- @param surf The surface you are interested in --- @return The surface's width and height +-- @return The surface's width and height. +-- @staticfct get_size function surface.get_size(surf) local cr = cairo.Context(surf) local x, y, w, h = cr:clip_extents() @@ -142,6 +147,7 @@ end -- surface. -- @param s Source surface. -- @return The surface's duplicate. +-- @staticfct duplicate_surface function surface.duplicate_surface(s) s = surface.load(s) @@ -166,6 +172,7 @@ end -- @param[opt=white] shape_color The shape color or pattern -- @param[opt=transparent] bg_color The surface background color -- @treturn cairo.surface the new surface +-- @staticfct load_from_shape function surface.load_from_shape(width, height, shape, shape_color, bg_color, ...) color = color or require("gears.color") @@ -191,7 +198,8 @@ end -- @param draw A wibox or a client -- @param shape or gears.shape function or a custom function with a context, -- width and height as parameter. --- @param[opt] Any additional parameters will be passed to the shape function +-- @param[opt] Any additional parameters will be passed to the shape function. +-- @staticfct apply_shape_bounding function surface.apply_shape_bounding(draw, shape, ...) local geo = draw:geometry() @@ -224,13 +232,15 @@ end --- Create an SVG file with this widget content. -- This is dynamic, so the SVG will be updated along with the widget content. -- because of this, the painting may happen hover multiple event loop cycles. --- @deprecated wibox.widget.draw_to_svg_file +-- @deprecated draw_to_svg_file -- @tparam widget widget A widget -- @tparam string path The output file path -- @tparam number width The surface width -- @tparam number height The surface height -- @return The cairo surface --- @return The hierarchy +-- @return The hierarchy. +-- @see wibox.widget.draw_to_svg_file +-- @see wibox.widget.draw_to_image_surface function surface.widget_to_svg(widget, path, width, height) gdebug.deprecate("Use wibox.widget.draw_to_svg_file instead of ".. "gears.surface.render_to_svg", {deprecated_in=5}) @@ -243,13 +253,15 @@ end --- Create a cairo surface with this widget content. -- This is dynamic, so the SVG will be updated along with the widget content. -- because of this, the painting may happen hover multiple event loop cycles. --- @deprecated wibox.widget.draw_to_image_surface +-- @deprecated draw_to_image_surface -- @tparam widget widget A widget -- @tparam number width The surface width -- @tparam number height The surface height -- @param[opt=cairo.Format.ARGB32] format The surface format -- @return The cairo surface --- @return The hierarchy +-- @return The hierarchy. +-- @see wibox.widget.draw_to_svg_file +-- @see wibox.widget.draw_to_image_surface function surface.widget_to_surface(widget, width, height, format) gdebug.deprecate("Use wibox.widget.draw_to_image_surface instead of ".. "gears.surface.render_to_surface", {deprecated_in=5}) diff --git a/lib/gears/table.lua b/lib/gears/table.lua index 70f990031..dd848a73e 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -12,10 +12,9 @@ local gtable = {} --- Join all tables given as arguments. -- This will iterate over all tables and insert their entries into a new table. --- @class function --- @name join -- @tparam table ... Tables to join. -- @treturn table A new table containing all entries from the arguments. +-- @staticfct gears.table.join function gtable.join(...) local ret = {} for i = 1, select("#", ...) do @@ -36,12 +35,12 @@ end --- Override elements in the first table by the one in the second. -- -- Note that this method doesn't copy entries found in `__index`. --- @class function --- @name crush +-- -- @tparam table t the table to be overriden -- @tparam table set the table used to override members of `t` -- @tparam[opt=false] bool raw Use rawset (avoid the metatable) -- @treturn table t (for convenience) +-- @staticfct gears.table.crush function gtable.crush(t, set, raw) if raw then for k, v in pairs(set) do @@ -63,10 +62,9 @@ end -- -- This function removes any entries with non-numeric keys. -- --- @class function --- @name from_sparse -- @tparam table t A potentially sparse table. -- @treturn table A packed table with only numeric keys. +-- @staticfct gears.table.from_sparse function gtable.from_sparse(t) local keys= {} for k in pairs(t) do @@ -86,12 +84,12 @@ function gtable.from_sparse(t) end --- Check if a table has an item and return its key. --- @class function --- @name hasitem +-- -- @tparam table t The table. -- @param item The item to look for in values of the table. -- @treturn[1] string|number The key of the item. -- @treturn[2] nil +-- @staticfct gears.table.hasitem function gtable.hasitem(t, item) for k, v in pairs(t) do if v == item then @@ -110,6 +108,7 @@ end -- @tparam[opt=nil] number max The maximum number of entries to find. -- @treturn table|nil An ordered table with all the keys or `nil` if none were -- found. +-- @staticfct gears.table.find_keys function gtable.find_keys(t, matcher, ordered, max) if max == 0 then return nil end @@ -134,7 +133,8 @@ end -- returning a boolean. -- @tparam[opt=false] boolean ordered If true, only look for continuous -- numeric keys. --- @return The table key or nil +-- @return The table key or nil. +-- @staticfct gears.table.find_first_key function gtable.find_first_key(t, matcher, ordered) local ret = gtable.find_keys(t, matcher, ordered, 1) @@ -143,10 +143,10 @@ end --- Get a sorted table with all integer keys from a table. --- @class function --- @name keys +-- -- @tparam table t The table for which the keys to get. --- @treturn table A table with keys +-- @treturn table A table with keys. +-- @staticfct gears.table.keys function gtable.keys(t) local keys = { } for k, _ in pairs(t) do @@ -159,11 +159,11 @@ function gtable.keys(t) end --- Filter a table's keys for certain content type. --- @class function --- @name keys_filter +-- -- @tparam table t The table to retrieve the keys for. -- @tparam string ... The types to look for. -- @treturn table A filtered table. +-- @staticfct gears.table.keys_filter function gtable.keys_filter(t, ...) local keys = gtable.keys(t) local keys_filtered = { } @@ -179,10 +179,10 @@ function gtable.keys_filter(t, ...) end --- Reverse a table. --- @class function --- @name reverse +-- -- @tparam table t The table to reverse. -- @treturn table A reversed table. +-- @staticfct gears.table.reverse function gtable.reverse(t) local tr = { } -- Reverse all elements with integer keys. @@ -199,11 +199,11 @@ function gtable.reverse(t) end --- Clone a table. --- @class function --- @name clone +-- -- @tparam table t The table to clone. -- @tparam[opt=true] bool deep Create a deep clone? -- @treturn table A clone of `t`. +-- @staticfct gears.table.clone function gtable.clone(t, deep) deep = deep == nil and true or deep local c = { } @@ -218,11 +218,10 @@ function gtable.clone(t, deep) end --- Iterate over a table. +-- -- Returns an iterator to cycle through all elements of a table that match a -- given criteria, starting from the first element or the given index. -- --- @class function --- @name iterate -- @tparam table t The table to iterate. -- @tparam func filter A function that returns true to indicate a positive -- match. @@ -230,6 +229,7 @@ end -- @tparam[opt=1] int start Index to start iterating from. -- Default is 1 (=> start of the table). -- @treturn func +-- @staticfct gears.table.iterate function gtable.iterate(t, filter, start) local count = 0 local index = start or 1 @@ -246,11 +246,11 @@ function gtable.iterate(t, filter, start) end --- Merge items from one table to another one. --- @class function --- @name merge +-- -- @tparam table t The container table -- @tparam table set The mixin table. --- @treturn table (for convenience) +-- @treturn table (for convenience). +-- @staticfct gears.table.merge function gtable.merge(t, set) for _, v in ipairs(set) do table.insert(t, v) @@ -259,13 +259,14 @@ function gtable.merge(t, set) end --- Map a function to a table. +-- -- The function is applied to each value on the table, returning a modified -- table. --- @class function --- @name map +-- -- @tparam function f The function to be applied to each value in the table. -- @tparam table tbl The container table whose values will be operated on. -- @treturn table +-- @staticfct gears.table.map function gtable.map(f, tbl) local t = {} for k,v in pairs(tbl) do diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index ab51e006f..5eb5ec4ab 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -194,7 +194,7 @@ end -- @tparam number timeout Timeout in seconds (e.g. 1.5). -- @tparam function callback Function to run. -- @treturn timer The timer object that was set up. --- @function gears.timer.start_new +-- @staticfct gears.timer.start_new -- @see gears.timer.weak_start_new function timer.start_new(timeout, callback) local t = timer.new({ timeout = timeout }) @@ -216,7 +216,7 @@ end -- @tparam number timeout Timeout in seconds (e.g. 1.5). -- @tparam function callback Function to start. -- @treturn timer The timer object that was set up. --- @function gears.timer.weak_start_new +-- @staticfct gears.timer.weak_start_new -- @see gears.timer.start_new function timer.weak_start_new(timeout, callback) local indirection = setmetatable({}, { __mode = "v" }) @@ -234,7 +234,7 @@ local delayed_calls = {} --- Run all pending delayed calls now. This function should best not be used at -- all, because it means that less batching happens and the delayed calls run -- prematurely. --- @function gears.timer.run_delayed_calls_now +-- @staticfct gears.timer.run_delayed_calls_now function timer.run_delayed_calls_now() for _, callback in ipairs(delayed_calls) do protected_call(unpack(callback)) @@ -245,7 +245,7 @@ end --- Call the given function at the end of the current main loop iteration -- @tparam function callback The function that should be called -- @param ... Arguments to the callback function --- @function gears.timer.delayed_call +-- @staticfct gears.timer.delayed_call function timer.delayed_call(callback, ...) assert(type(callback) == "function", "callback must be a function, got: " .. type(callback)) table.insert(delayed_calls, { callback, ... }) diff --git a/lib/gears/wallpaper.lua b/lib/gears/wallpaper.lua index 13da9b7b4..8b3f796a9 100644 --- a/lib/gears/wallpaper.lua +++ b/lib/gears/wallpaper.lua @@ -50,7 +50,8 @@ end -- global variable. -- @param s The screen to set the wallpaper on or nil for all screens -- @return[1] The available geometry (table with entries width and height) --- @return[1] A cairo context that the wallpaper should be drawn to +-- @return[1] A cairo context that the wallpaper should be drawn to. +-- @staticfct gears.wallpaper.prepare_context function wallpaper.prepare_context(s) s = get_screen(s) @@ -109,6 +110,7 @@ end -- @param pattern The wallpaper that should be set. This can be a cairo surface, -- a description for gears.color or a cairo pattern. -- @see gears.color +-- @staticfct gears.wallpaper.set function wallpaper.set(pattern) if cairo.Surface:is_type_of(pattern) then pattern = cairo.Pattern.create_for_surface(pattern) @@ -130,6 +132,7 @@ end -- gears.color. The default is black. -- @param scale The scale factor for the wallpaper. Default is 1 (original size). -- @see gears.color +-- @staticfct gears.wallpaper.centered function wallpaper.centered(surf, s, background, scale) local geom, cr = wallpaper.prepare_context(s) local original_surf = surf @@ -169,6 +172,7 @@ end -- @param s The screen whose wallpaper should be set. Can be nil, in which case -- all screens are set. -- @param offset This can be set to a table with entries x and y. +-- @staticfct gears.wallpaper.tiled function wallpaper.tiled(surf, s, offset) local _, cr = wallpaper.prepare_context(s) @@ -198,6 +202,7 @@ end -- @param ignore_aspect If this is true, the image's aspect ratio is ignored. -- The default is to honor the aspect ratio. -- @param offset This can be set to a table with entries x and y. +-- @staticfct gears.wallpaper.maximized function wallpaper.maximized(surf, s, ignore_aspect, offset) local geom, cr = wallpaper.prepare_context(s) local original_surf = surf @@ -238,6 +243,7 @@ end -- @param background The background color that should be used. Gets handled via -- gears.color. The default is black. -- @see gears.color +-- @staticfct gears.wallpaper.fit function wallpaper.fit(surf, s, background) local geom, cr = wallpaper.prepare_context(s) local original_surf = surf diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index 55ad383e2..16cf5d5be 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -4,19 +4,25 @@ -- List of menubar keybindings: -- --- -- --- * "Left" | "C-j" select an item on the left --- * "Right" | "C-k" select an item on the right --- * "Backspace" exit the current category if we are in any --- * "Escape" exit the current directory or exit menubar --- * "Home" select the first item --- * "End" select the last --- * "Return" execute the entry --- * "C-Return" execute the command with awful.spawn --- * "C-M-Return" execute the command in a terminal +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +--
KeybindingDescription
LeftC-j select an item on the left
RightC-k select an item on the right
Backspace exit the current category if we are in any
Escape exit the current directory or exit menubar
Home select the first item
End select the last
Return execute the entry
C-Return execute the command with awful.spawn
C-M-Return execute the command in a terminal
-- -- @author Alexander Yakushev <yakushev.alex@gmail.com> -- @copyright 2011-2012 Alexander Yakushev --- @module menubar +-- @popupmod menubar --------------------------------------------------------------------------- -- Grab environment we need @@ -362,6 +368,7 @@ end --- Refresh menubar's cache by reloading .desktop files. -- @tparam[opt] screen scr Screen. +-- @staticfct menubar.refresh function menubar.refresh(scr) scr = get_screen(scr or awful.screen.focused() or 1) menubar.menu_gen.generate(function(entries) @@ -418,6 +425,7 @@ end --- Show the menubar on the given screen. -- @param[opt] scr Screen. +-- @staticfct menubar.show function menubar.show(scr) scr = get_screen(scr or awful.screen.focused() or 1) local fg_color = theme.menubar_fg_normal or theme.menu_fg_normal or theme.fg_normal @@ -492,6 +500,7 @@ function menubar.show(scr) end --- Hide the menubar. +-- @staticfct menubar.hide function menubar.hide() if instance then instance.wibox.visible = false diff --git a/lib/menubar/menu_gen.lua b/lib/menubar/menu_gen.lua index a2434aa27..19fb6e735 100644 --- a/lib/menubar/menu_gen.lua +++ b/lib/menubar/menu_gen.lua @@ -58,6 +58,7 @@ menu_gen.all_categories = { } --- Find icons for category entries. +-- @staticfct menubar.menu_gen.lookup_category_icons function menu_gen.lookup_category_icons() for _, v in pairs(menu_gen.all_categories) do v.icon = utils.lookup_icon(v.icon_name) @@ -79,6 +80,7 @@ end -- @tparam function callback Will be fired when all menu entries were parsed -- with the resulting list of menu entries as argument. -- @tparam table callback.entries All menu entries. +-- @staticfct menubar.menu_gen.generate function menu_gen.generate(callback) -- Update icons for category entries menu_gen.lookup_category_icons() diff --git a/lib/menubar/utils.lua b/lib/menubar/utils.lua index 9b20c96b9..ae0817473 100644 --- a/lib/menubar/utils.lua +++ b/lib/menubar/utils.lua @@ -131,6 +131,7 @@ local all_icon_sizes = { local supported_icon_file_exts = { png = 1, xpm = 2, svg = 3 } local icon_lookup_path = nil + --- Get a list of icon lookup paths. -- @treturn table A list of directories, without trailing slash. local function get_icon_lookup_path() @@ -198,6 +199,7 @@ end --- Remove CR newline from the end of the string. -- @param s string to trim +-- @staticfct menubar.utils.rtrim function utils.rtrim(s) if not s then return end if string.byte(s, #s) == 13 then @@ -209,6 +211,7 @@ end --- Lookup an icon in different folders of the filesystem. -- @tparam string icon_file Short or full name of the icon. -- @treturn string|boolean Full name of the icon, or false on failure. +-- @staticfct menubar.utils.lookup_icon_uncached function utils.lookup_icon_uncached(icon_file) if not icon_file or icon_file == "" then return false @@ -244,6 +247,7 @@ local lookup_icon_cache = {} --- Lookup an icon in different folders of the filesystem (cached). -- @param icon Short or full name of the icon. -- @return full name of the icon. +-- @staticfct menubar.utils.lookup_icon function utils.lookup_icon(icon) if not lookup_icon_cache[icon] and lookup_icon_cache[icon] ~= false then lookup_icon_cache[icon] = utils.lookup_icon_uncached(icon) @@ -254,6 +258,7 @@ end --- Parse a .desktop file. -- @param file The .desktop file. -- @return A table with file entries. +-- @staticfct menubar.utils.parse_desktop_file function utils.parse_desktop_file(file) local program = { show = true, file = file } @@ -350,6 +355,7 @@ end -- @tparam function callback Will be fired when all the files were parsed -- with the resulting list of menu entries as argument. -- @tparam table callback.programs Paths of found .desktop files. +-- @staticfct menubar.utils.parse_dir function utils.parse_dir(dir_path, callback) local function get_readable_path(file) @@ -413,6 +419,7 @@ end -- @tparam str text Text. -- @tparam number|screen s Screen -- @treturn int Text width. +-- @staticfct menubar.utils.compute_text_width function utils.compute_text_width(text, s) local w, _ = w_textbox(gstring.xml_escape(text)):get_preferred_size(s) return w diff --git a/lib/naughty/core.lua b/lib/naughty/core.lua index f21a20a5c..3b93f7745 100644 --- a/lib/naughty/core.lua +++ b/lib/naughty/core.lua @@ -196,6 +196,7 @@ local conns = {} -- @usage naughty.connect_signal("added", function(notif) -- -- do something -- end) +-- @staticfct naughty.connect_signal function naughty.connect_signal(name, func) assert(name) conns[name] = conns[name] or {} @@ -205,6 +206,7 @@ end --- Emit a notification signal. -- @tparam string name The signal name. -- @param ... The signal callback arguments +-- @staticfct naughty.emit_signal function naughty.emit_signal(name, ...) assert(name) for _, func in pairs(conns[name] or {}) do @@ -216,6 +218,7 @@ end -- @tparam string name The name of the signal -- @tparam function func The attached function -- @treturn boolean If the disconnection was successful +-- @staticfct naughty.disconnect_signal function naughty.disconnect_signal(name, func) for k, v in ipairs(conns[name] or {}) do if v == func then @@ -291,6 +294,7 @@ end -- @treturn true|nil True if all notifications were successfully destroyed, nil -- otherwise. -- @see notification_closed_reason +-- @staticfct naughty.destroy_all_notifications function naughty.destroy_all_notifications(screens, reason) if not screens then screens = {} @@ -323,6 +327,7 @@ end -- -- @param id ID of the notification -- @return notification object if it was found, nil otherwise +-- @staticfct naughty.get_by_id function naughty.get_by_id(id) -- iterate the notifications to get the notfications with the correct ID for s in pairs(naughty.notifications) do diff --git a/lib/wibox/hierarchy.lua b/lib/wibox/hierarchy.lua index e0da295ce..a5edddfad 100644 --- a/lib/wibox/hierarchy.lua +++ b/lib/wibox/hierarchy.lua @@ -5,7 +5,7 @@ -- -- @author Uli Schlachter -- @copyright 2015 Uli Schlachter --- @module wibox.hierarchy +-- @classmod wibox.hierarchy --------------------------------------------------------------------------- local matrix = require("gears.matrix") @@ -22,6 +22,7 @@ local widgets_to_count = setmetatable({}, { __mode = "k" }) -- occurrences. Note that for correct operations, the widget must not yet be -- visible in any hierarchy. -- @param widget The widget that should be counted. +-- @staticfct wibox.hierarchy.count_widget function hierarchy.count_widget(widget) widgets_to_count[widget] = true end @@ -203,6 +204,7 @@ end -- hierarchy on widget::layout_changed on some widget. -- @param callback_arg A second argument that is given to the above callbacks. -- @return A new widget hierarchy +-- @constructorfct wibox.hierarchy.new function hierarchy.new(context, widget, width, height, redraw_callback, layout_callback, callback_arg) local result = hierarchy_new(redraw_callback, layout_callback, callback_arg) result:update(context, widget, width, height) @@ -217,6 +219,7 @@ end -- @param[opt] region A region to use for accumulating changed parts -- @return A cairo region describing the changed parts (either the `region` -- argument or a new, internally created region). +-- @method update function hierarchy:update(context, widget, width, height, region) region = region or cairo.Region.create() hierarchy_update(self, context, widget, width, height, region, self._matrix, self._matrix_to_device) @@ -224,6 +227,7 @@ function hierarchy:update(context, widget, width, height, region) end --- Get the widget that this hierarchy manages. +-- @method get_widget function hierarchy:get_widget() return self._widget end @@ -231,6 +235,7 @@ end --- Get a matrix that transforms to the parent's coordinate space from this -- hierarchy's coordinate system. -- @return A matrix describing the transformation. +-- @method get_matrix_to_parent function hierarchy:get_matrix_to_parent() return self._matrix end @@ -239,6 +244,7 @@ end -- system (aka the coordinate system of the device that this -- hierarchy is applied upon) from this hierarchy's coordinate system. -- @return A matrix describing the transformation. +-- @method get_matrix_to_device function hierarchy:get_matrix_to_device() return self._matrix_to_device end @@ -246,6 +252,7 @@ end --- Get a matrix that transforms from the parent's coordinate space into this -- hierarchy's coordinate system. -- @return A matrix describing the transformation. +-- @method get_matrix_from_parent function hierarchy:get_matrix_from_parent() local m = self:get_matrix_to_parent() return m:invert() @@ -255,6 +262,7 @@ end -- system (aka the coordinate system of the device that this -- hierarchy is applied upon) into this hierarchy's coordinate system. -- @return A matrix describing the transformation. +-- @method get_matrix_from_device function hierarchy:get_matrix_from_device() local m = self:get_matrix_to_device() return m:invert() @@ -264,6 +272,7 @@ end -- This includes the size of this element plus the size of all children -- (after applying the corresponding transformation). -- @return x, y, width, height +-- @method get_draw_extents function hierarchy:get_draw_extents() local ext = self._draw_extents return ext.x, ext.y, ext.width, ext.height @@ -271,6 +280,7 @@ end --- Get the size that this hierarchy logically covers (in the current coordinate space). -- @return width, height +-- @method get_size function hierarchy:get_size() local ext = self._size return ext.width, ext.height @@ -278,6 +288,7 @@ end --- Get a list of all children. -- @return List of all children hierarchies. +-- @method get_children function hierarchy:get_children() return self._children end @@ -286,6 +297,7 @@ end -- only works with widgets registered via `count_widget`. -- @param widget The widget that should be counted -- @return The number of times that this widget is contained in this hierarchy. +-- @method get_count function hierarchy:get_count(widget) return self._widget_counts[widget] or 0 end @@ -301,6 +313,7 @@ end -- context. The context's clip is used to skip parts that aren't visible. -- @param context The context in which widgets are drawn. -- @param cr The cairo context that is used for drawing. +-- @method draw function hierarchy:draw(context, cr) local widget = self:get_widget() if not widget._private.visible then diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index a0ddf5510..dc8bf5ff0 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -18,12 +18,12 @@ local base = {} -- {{{ Functions on widgets ---- Functions available on all widgets. +-- Functions available on all widgets. base.widget = {} --- Set/get a widget's buttons. -- @tab _buttons The table of buttons that is bound to the widget. --- @function buttons +-- @method buttons function base.widget:buttons(_buttons) if _buttons then self._private.widget_buttons = _buttons @@ -33,7 +33,7 @@ end --- Set a widget's visibility. -- @tparam boolean b Whether the widget is visible. --- @function set_visible +-- @method set_visible function base.widget:set_visible(b) if b ~= self._private.visible then self._private.visible = b @@ -45,7 +45,7 @@ end --- Is the widget visible? -- @treturn boolean --- @function get_visible +-- @method get_visible function base.widget:get_visible() return self._private.visible or false end @@ -53,7 +53,7 @@ end --- Set a widget's opacity. -- @tparam number o The opacity to use (a number from 0 (transparent) to 1 -- (opaque)). --- @function set_opacity +-- @method set_opacity function base.widget:set_opacity(o) if o ~= self._private.opacity then self._private.opacity = o @@ -63,7 +63,7 @@ end --- Get the widget's opacity. -- @treturn number The opacity (between 0 (transparent) and 1 (opaque)). --- @function get_opacity +-- @method get_opacity function base.widget:get_opacity() return self._private.opacity end @@ -72,7 +72,7 @@ end -- @tparam[opt] number width With `nil` the default mechanism of calling the -- `:fit` method is used. -- @see fit_widget --- @function set_forced_width +-- @method set_forced_width function base.widget:set_forced_width(width) if width ~= self._private.forced_width then self._private.forced_width = width @@ -88,7 +88,7 @@ end -- actual size is during a `mouse::enter`, `mouse::leave` or button event. -- @treturn[opt] number The forced width (nil if automatic). -- @see fit_widget --- @function get_forced_width +-- @method get_forced_width function base.widget:get_forced_width() return self._private.forced_width end @@ -97,7 +97,7 @@ end -- @tparam[opt] number height With `nil` the default mechanism of calling the -- `:fit` method is used. -- @see fit_widget --- @function set_height +-- @method set_height function base.widget:set_forced_height(height) if height ~= self._private.forced_height then self._private.forced_height = height @@ -112,7 +112,7 @@ end -- If there is no forced width/height, then the only way to get the widget's -- actual size is during a `mouse::enter`, `mouse::leave` or button event. -- @treturn[opt] number The forced height (nil if automatic). --- @function get_forced_height +-- @method get_forced_height function base.widget:get_forced_height() return self._private.forced_height end @@ -121,7 +121,7 @@ end -- -- This method should be re-implemented by the relevant widgets. -- @treturn table The children --- @function get_children +-- @method get_children function base.widget:get_children() return {} end @@ -131,7 +131,7 @@ end -- The default implementation does nothing, this must be re-implemented by -- all layout and container widgets. -- @tab children A table composed of valid widgets. --- @function set_children +-- @method set_children function base.widget:set_children(children) -- luacheck: no unused -- Nothing on purpose end @@ -151,7 +151,7 @@ end -- *Warning*: This method it prone to stack overflow if the widget, or any of -- its children, contains (directly or indirectly) itself. -- @treturn table The children --- @function get_all_children +-- @method get_all_children function base.widget:get_all_children() local ret = {} digg_children(ret, self) @@ -175,7 +175,7 @@ end -- -- @tparam string signal_name -- @param ... Other arguments --- @function emit_signal_recursive +-- @method emit_signal_recursive function base.widget:emit_signal_recursive(signal_name, ...) -- This is a convenience wrapper, the real implementation is in the -- hierarchy. @@ -190,7 +190,7 @@ end -- @treturn number The index. -- @treturn widget The parent widget. -- @treturn table The path between "self" and "widget". --- @function index +-- @method index function base.widget:index(widget, recursive, ...) local widgets = self:get_children() for idx, w in ipairs(widgets) do @@ -261,7 +261,7 @@ end -- -- This gives only tight bounds if no rotations by non-multiples of 90° are -- used. --- @function wibox.widget.base.rect_to_device_geometry +-- @staticfct wibox.widget.base.rect_to_device_geometry function base.rect_to_device_geometry(cr, x, y, width, height) return matrix.transform_rectangle(cr.matrix, x, y, width, height) end @@ -278,7 +278,7 @@ end -- @tparam number height The available height for the widget. -- @treturn number The width that the widget wants to use. -- @treturn number The height that the widget wants to use. --- @function wibox.widget.base.fit_widget +-- @staticfct wibox.widget.base.fit_widget function base.fit_widget(parent, context, widget, width, height) record_dependency(parent, widget) @@ -326,7 +326,7 @@ end -- @tparam number width The available width for the widget. -- @tparam number height The available height for the widget. -- @treturn[opt] table The result from the widget's `:layout` callback. --- @function wibox.widget.base.layout_widget +-- @staticfct wibox.widget.base.layout_widget function base.layout_widget(parent, context, widget, width, height) record_dependency(parent, widget) @@ -346,7 +346,7 @@ end --- Handle a button event on a widget. -- -- This is used internally and should not be called directly. --- @function wibox.widget.base.handle_button +-- @staticfct wibox.widget.base.handle_button function base.handle_button(event, widget, x, y, button, modifiers, geometry) x = x or y -- luacheck: no unused local function is_any(mod) @@ -395,7 +395,7 @@ end -- @tparam number height The height of the widget in its own coordinate system. -- That is, after applying the transformation matrix. -- @treturn table An opaque object that can be returned from `:layout()`. --- @function wibox.widget.base.place_widget_via_matrix +-- @staticfct wibox.widget.base.place_widget_via_matrix function base.place_widget_via_matrix(widget, mat, width, height) return { _widget = widget, @@ -415,7 +415,7 @@ end -- @tparam number height The height of the widget in its own coordinate system. -- That is, after applying the transformation matrix. -- @treturn table An opaque object that can be returned from `:layout()`. --- @function wibox.widget.base.place_widget_at +-- @staticfct wibox.widget.base.place_widget_at function base.place_widget_at(widget, x, y, width, height) return base.place_widget_via_matrix(widget, matrix.create_translate(x, y), width, height) end @@ -535,7 +535,7 @@ end -- -- See [The declarative layout system](../documentation/03-declarative-layout.md.html). -- @tab args A table containing the widget's disposition. --- @function setup +-- @method setup function base.widget:setup(args) local f,ids = self.set_widget or self.add or self.set_first,{} local w, id = drill(ids, args) @@ -562,7 +562,7 @@ end -- -- See [The declarative layout system](../documentation/03-declarative-layout.md.html). -- @tab args A table containing the widgets disposition. --- @function wibox.widget.base.make_widget_declarative +-- @constructorfct wibox.widget.base.make_widget_declarative function base.make_widget_declarative(args) local ids = {} @@ -608,6 +608,7 @@ end -- @param wdg The value. -- @param[opt=nil] ... Arguments passed to the contructor (if any). -- @treturn The new widget. +-- @constructorfct wibox.widget.base.make_widget_from_value function base.make_widget_from_value(wdg, ...) local is_function, t = is_callable(wdg) @@ -635,7 +636,7 @@ end -- and setter methods. -- @tparam[opt=nil] table args.class The widget class -- @see fit_widget --- @function wibox.widget.base.make_widget +-- @constructorfct wibox.widget.base.make_widget function base.make_widget(proxy, widget_name, args) args = args or {} local ret = object { @@ -714,7 +715,7 @@ function base.make_widget(proxy, widget_name, args) end --- Generate an empty widget which takes no space and displays nothing. --- @function wibox.widget.base.empty_widget +-- @constructorfct wibox.widget.base.empty_widget function base.empty_widget() return base.make_widget() end @@ -722,7 +723,7 @@ end --- Do some sanity checking on a widget. -- -- This function raises an error if the widget is not valid. --- @function wibox.widget.base.check_widget +-- @staticfct wibox.widget.base.check_widget function base.check_widget(widget) assert(type(widget) == "table", "Type should be table, but is " .. tostring(type(widget))) assert(widget.is_widget, "Argument is not a widget!") diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index d151e8de3..683e8bc7b 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -37,6 +37,7 @@ setmetatable(widget, { -- @tparam number width The width of the widget -- @tparam number height The height of the widget -- @tparam[opt={dpi=96}] table context The context information to give to the widget. +-- @staticfct wibox.widget.draw_to_cairo_context function widget.draw_to_cairo_context(wdg, cr, width, height, context) local function no_op() end context = context or {dpi=96} @@ -50,6 +51,7 @@ end -- @tparam number width The surface width -- @tparam number height The surface height -- @tparam[opt={dpi=96}] table context The context information to give to the widget. +-- @staticfct wibox.widget.draw_to_svg_file function widget.draw_to_svg_file(wdg, path, width, height, context) local img = cairo.SvgSurface.create(path, width, height) local cr = cairo.Context(img) @@ -64,6 +66,7 @@ end -- @param[opt=cairo.Format.ARGB32] format The surface format -- @tparam[opt={dpi=96}] table context The context information to give to the widget. -- @return The cairo surface +-- @staticfct wibox.widget.draw_to_image_surface function widget.draw_to_image_surface(wdg, width, height, format, context) local img = cairo.ImageSurface(format or cairo.Format.ARGB32, width, height) local cr = cairo.Context(img) diff --git a/luaa.c b/luaa.c index 803d44d01..e6b073866 100644 --- a/luaa.c +++ b/luaa.c @@ -33,7 +33,7 @@ * * @tparam string name The name of the X11 property. * @tparam string type One of "string", "number" or "boolean". - * @function register_xproperty + * @staticfct register_xproperty */ #define _GNU_SOURCE @@ -216,7 +216,7 @@ composite_manager_running(void) /** Quit awesome. * @tparam[opt=0] integer code The exit code to use when exiting. - * @function quit + * @staticfct quit */ static int luaA_quit(lua_State *L) @@ -233,7 +233,7 @@ luaA_quit(lua_State *L) * awesome. * * @param cmd The command line to execute. - * @function exec + * @staticfct exec */ static int luaA_exec(lua_State *L) @@ -247,7 +247,7 @@ luaA_exec(lua_State *L) } /** Restart awesome. - * @function restart + * @staticfct restart */ static int luaA_restart(lua_State *L) @@ -262,7 +262,7 @@ luaA_restart(lua_State *L) * @tparam integer sig Signal number. * See `awesome.unix_signal` for a list of signals. * @treturn boolean true if the signal was successfully sent, else false - * @function kill + * @staticfct kill */ static int luaA_kill(lua_State *L) @@ -277,7 +277,7 @@ luaA_kill(lua_State *L) /** Synchronize with the X11 server. This is needed in the test suite to avoid * some race conditions. You should never need to use this function. - * @function sync + * @staticfct sync */ static int luaA_sync(lua_State *L) @@ -291,7 +291,7 @@ luaA_sync(lua_State *L) * @param pixbuf The pixbuf as a light user datum. * @param path The pixbuf origin path * @return A cairo surface as light user datum. - * @function pixbuf_to_surface + * @staticfct pixbuf_to_surface */ static int luaA_pixbuf_to_surface(lua_State *L) @@ -310,7 +310,7 @@ luaA_pixbuf_to_surface(lua_State *L) * @return[1] A cairo surface as light user datum. * @return[2] nil * @treturn[2] string Error message - * @function load_image + * @staticfct load_image */ static int luaA_load_image(lua_State *L) @@ -340,7 +340,7 @@ luaA_load_image(lua_State *L) * smaller size is picked. The default is 0 pixels, ie. the smallest icon. * * @param size The size of the icons in pixels. - * @function set_preferred_icon_size + * @staticfct set_preferred_icon_size */ static int luaA_set_preferred_icon_size(lua_State *L) @@ -674,7 +674,7 @@ luaA_awesome_index(lua_State *L) * * @param name A string with the event name. * @param func The function to call. - * @function connect_signal + * @staticfct connect_signal */ static int luaA_awesome_connect_signal(lua_State *L) @@ -689,7 +689,7 @@ luaA_awesome_connect_signal(lua_State *L) * * @param name A string with the event name. * @param func The function to call. - * @function disconnect_signal + * @staticfct disconnect_signal */ static int luaA_awesome_disconnect_signal(lua_State *L) @@ -706,7 +706,7 @@ luaA_awesome_disconnect_signal(lua_State *L) * * @param name A string with the event name. * @param ... The signal arguments. - * @function emit_signal + * @staticfct emit_signal */ static int luaA_awesome_emit_signal(lua_State *L) diff --git a/mouse.c b/mouse.c index 3f2ccf897..c446243a9 100644 --- a/mouse.c +++ b/mouse.c @@ -274,7 +274,7 @@ luaA_mouse_coords(lua_State *L) /** Get the client or any object which is under the pointer. * * @treturn client.object|nil A client or nil. - * @function object_under_pointer + * @staticfct object_under_pointer */ static int luaA_mouse_object_under_pointer(lua_State *L) diff --git a/mousegrabber.c b/mousegrabber.c index 5efe72052..abb6b6c81 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -89,7 +89,7 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask) * * @param func A callback function as described above. * @param cursor The name of a X cursor to use while grabbing. - * @function run + * @staticfct run */ static int luaA_mousegrabber_run(lua_State *L) @@ -119,7 +119,7 @@ luaA_mousegrabber_run(lua_State *L) /** Stop grabbing the mouse pointer. * - * @function stop + * @staticfct stop */ int luaA_mousegrabber_stop(lua_State *L) @@ -132,7 +132,7 @@ luaA_mousegrabber_stop(lua_State *L) /** Check if mousegrabber is running. * * @treturn boolean True if running, false otherwise. - * @function isrunning + * @staticfct isrunning */ static int luaA_mousegrabber_isrunning(lua_State *L) diff --git a/objects/button.c b/objects/button.c index 9670b4709..892347a92 100644 --- a/objects/button.c +++ b/objects/button.c @@ -45,17 +45,17 @@ /** Get the number of instances. * @treturn int The number of button objects alive. - * @function instances + * @staticfct instances */ /** Set a __index metamethod for all button instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /** Set a __newindex metamethod for all button instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ /** When bound mouse button + modifiers are pressed. diff --git a/objects/client.c b/objects/client.c index 65d9061df..38a45cd6c 100644 --- a/objects/client.c +++ b/objects/client.c @@ -932,17 +932,17 @@ /** Get the number of instances. * * @return The number of client objects alive. - * @function instances + * @staticfct instances */ /* Set a __index metamethod for all client instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /* Set a __newindex metamethod for all client instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ typedef enum { @@ -2426,7 +2426,7 @@ client_kill(client_t *c) * @tparam[opt] boolean stacked Return clients in stacking order? (ordered from * top to bottom). * @treturn table A table with clients. - * @function get + * @staticfct get */ static int luaA_client_get(lua_State *L) diff --git a/objects/drawable.c b/objects/drawable.c index 07d15aead..bd6c78926 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -39,7 +39,7 @@ /** Drawable object. * * @field surface The drawable's cairo surface. - * @function drawable + * @staticfct drawable */ /** @@ -89,17 +89,17 @@ /** Get the number of instances. * * @return The number of drawable objects alive. - * @function instances + * @staticfct instances */ /** Set a __index metamethod for all drawable instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /** Set a __newindex metamethod for all drawable instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ static lua_class_t drawable_class; diff --git a/objects/key.c b/objects/key.c index eca16c7f7..c42f7446d 100644 --- a/objects/key.c +++ b/objects/key.c @@ -74,17 +74,17 @@ /** Get the number of instances. * * @return The number of key objects alive. - * @function instances + * @staticfct instances */ /** Set a __index metamethod for all key instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /** Set a __newindex metamethod for all key instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ static void diff --git a/objects/screen.c b/objects/screen.c index b3e4f81fd..05e82375e 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -191,17 +191,17 @@ /** Get the number of instances. * * @return The number of screen objects alive. - * @function instances + * @staticfct instances */ /* Set a __index metamethod for all screen instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /* Set a __newindex metamethod for all screen instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ DO_ARRAY(xcb_randr_output_t, randr_output, DO_NOTHING); @@ -1090,7 +1090,7 @@ luaA_screen_module_index(lua_State *L) * for s in screen do * print("Oh, wow, we have screen " .. tostring(s)) * end - * @function screen + * @staticfct screen */ static int luaA_screen_module_call(lua_State *L) @@ -1147,7 +1147,7 @@ luaA_screen_get_workarea(lua_State *L, screen_t *s) /** Get the number of screens. * * @return The screen count, at least 1. - * @function count + * @staticfct count */ static int luaA_screen_count(lua_State *L) diff --git a/objects/tag.c b/objects/tag.c index 7c95aecc5..401a66a57 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -240,17 +240,17 @@ /** Get the number of instances. * * @return The number of tag objects alive. - * @function instances + * @staticfct instances */ /* Set a __index metamethod for all tag instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /* Set a __newindex metamethod for all tag instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ @@ -408,10 +408,10 @@ luaA_tag_new(lua_State *L) /** Get or set the clients attached to this tag. * - * @param clients_table None or a table of clients to set as being tagged with + * @tparam[opt=nil] table clients_table None or a table of clients to set as being tagged with * this tag. * @return A table with the clients attached to this tags. - * @function clients + * @method clients */ static int luaA_tag_clients(lua_State *L) diff --git a/root.c b/root.c index 9edef1d58..4da0f6605 100644 --- a/root.c +++ b/root.c @@ -223,7 +223,7 @@ _string_to_key_code(const char *s) * "Shift". Here is a list of the "real" key names matching the modifiers in * `fake_input`: * - * + *
* * * @@ -266,7 +266,7 @@ _string_to_key_code(const char *s) * coordinates relatives. * @param x In case of a motion event, this is the X coordinate. * @param y In case of a motion event, this is the Y coordinate. - * @function fake_input + * @staticfct fake_input */ static int luaA_root_fake_input(lua_State *L) @@ -334,7 +334,7 @@ luaA_root_fake_input(lua_State *L) * * @tparam table|nil keys_array An array of key binding objects, or nothing. * @return The array of key bindings objects of this client. - * @function keys + * @staticfct keys */ static int luaA_root_keys(lua_State *L) @@ -374,7 +374,7 @@ luaA_root_keys(lua_State *L) * * @param button_table An array of mouse button bindings objects, or nothing. * @return The array of mouse button bindings objects. - * @function buttons + * @staticfct buttons */ static int luaA_root_buttons(lua_State *L) @@ -413,7 +413,7 @@ luaA_root_buttons(lua_State *L) *@DOC_cursor_c_COMMON@ * * @param cursor_name A X cursor name. - * @function cursor + * @staticfct cursor */ static int luaA_root_cursor(lua_State *L) @@ -439,7 +439,7 @@ luaA_root_cursor(lua_State *L) /** Get the drawins attached to a screen. * * @return A table with all drawins. - * @function drawins + * @staticfct drawins */ static int luaA_root_drawins(lua_State *L) @@ -459,7 +459,7 @@ luaA_root_drawins(lua_State *L) * * @param pattern A cairo pattern as light userdata * @return A cairo surface or nothing. - * @function wallpaper + * @staticfct wallpaper */ static int luaA_root_wallpaper(lua_State *L) @@ -484,7 +484,7 @@ luaA_root_wallpaper(lua_State *L) * * @return Width of the root window. * @return height of the root window. - * @function size + * @staticfct size */ static int luaA_root_size(lua_State *L) @@ -498,7 +498,7 @@ luaA_root_size(lua_State *L) * * @return Width of the root window, in millimeters. * @return height of the root window, in millimeters. - * @function size_mm + * @staticfct size_mm */ static int luaA_root_size_mm(lua_State *L) @@ -510,7 +510,7 @@ luaA_root_size_mm(lua_State *L) /** Get the attached tags. * @return A table with all tags. - * @function tags + * @staticfct tags */ static int luaA_root_tags(lua_State *L) diff --git a/selection.c b/selection.c index ba164c13f..ea9582cd1 100644 --- a/selection.c +++ b/selection.c @@ -38,7 +38,7 @@ /** Get the selection (clipboard) content. * * @return A string with the selection (clipboard) content. - * @function selection + * @staticfct selection */ static xcb_window_t selection_window = XCB_NONE; diff --git a/spawn.c b/spawn.c index 29eede74a..d736d5834 100644 --- a/spawn.c +++ b/spawn.c @@ -426,7 +426,7 @@ spawn_child_exited(pid_t pid, int status) * @treturn[1] integer stdout, if `stdout` is true. * @treturn[1] integer stderr, if `stderr` is true. * @treturn[2] string An error string if an error occurred. - * @function spawn + * @staticfct spawn */ int luaA_spawn(lua_State *L) diff --git a/tests/examples/awful/placement/bottom.lua b/tests/examples/awful/placement/bottom.lua index 75ae8ff90..c70ee710e 100644 --- a/tests/examples/awful/placement/bottom.lua +++ b/tests/examples/awful/placement/bottom.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name bottom --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.bottom --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/bottom_left.lua b/tests/examples/awful/placement/bottom_left.lua index f4704947d..125a0e648 100644 --- a/tests/examples/awful/placement/bottom_left.lua +++ b/tests/examples/awful/placement/bottom_left.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name bottom_left --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.bottom_left --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/bottom_right.lua b/tests/examples/awful/placement/bottom_right.lua index 2c00137e8..b0d450821 100644 --- a/tests/examples/awful/placement/bottom_right.lua +++ b/tests/examples/awful/placement/bottom_right.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name bottom_right --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.bottom_right --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/center_horizontal.lua b/tests/examples/awful/placement/center_horizontal.lua index 44f81b7a2..1ab1eee22 100644 --- a/tests/examples/awful/placement/center_horizontal.lua +++ b/tests/examples/awful/placement/center_horizontal.lua @@ -3,8 +3,8 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name center_horizontal --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.center_horizontal --DOC_HEADER + screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/center_vertical.lua b/tests/examples/awful/placement/center_vertical.lua index 8e71e7701..a867eab20 100644 --- a/tests/examples/awful/placement/center_vertical.lua +++ b/tests/examples/awful/placement/center_vertical.lua @@ -2,8 +2,7 @@ -- Align a client to the vertical center of the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER --- @name center_vertical --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.center_vertical --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/centered.lua b/tests/examples/awful/placement/centered.lua index be9fa5be4..c7af1052d 100644 --- a/tests/examples/awful/placement/centered.lua +++ b/tests/examples/awful/placement/centered.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name centered --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.centered --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/left.lua b/tests/examples/awful/placement/left.lua index a916b63bb..3621383d7 100644 --- a/tests/examples/awful/placement/left.lua +++ b/tests/examples/awful/placement/left.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name left --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.left --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_horizontally.lua b/tests/examples/awful/placement/maximize_horizontally.lua index b862e816d..7fdf965ff 100644 --- a/tests/examples/awful/placement/maximize_horizontally.lua +++ b/tests/examples/awful/placement/maximize_horizontally.lua @@ -2,8 +2,7 @@ -- Horizontally maximize the drawable in the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER --- @name maximize_horizontally --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.maximize_horizontally --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_vertically.lua b/tests/examples/awful/placement/maximize_vertically.lua index a8b177bcd..b37581157 100644 --- a/tests/examples/awful/placement/maximize_vertically.lua +++ b/tests/examples/awful/placement/maximize_vertically.lua @@ -2,8 +2,7 @@ -- Vetically maximize the drawable in the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER --- @name maximize_vertically --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.maximize_vertically --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/right.lua b/tests/examples/awful/placement/right.lua index 40c334843..b1f63b66a 100644 --- a/tests/examples/awful/placement/right.lua +++ b/tests/examples/awful/placement/right.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name right --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.right --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_down.lua b/tests/examples/awful/placement/stretch_down.lua index 76101bae8..e22caf5d8 100644 --- a/tests/examples/awful/placement/stretch_down.lua +++ b/tests/examples/awful/placement/stretch_down.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name stretch_down --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.stretch_down --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_left.lua b/tests/examples/awful/placement/stretch_left.lua index d00d511e9..db81f765d 100644 --- a/tests/examples/awful/placement/stretch_left.lua +++ b/tests/examples/awful/placement/stretch_left.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name stretch_left --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.stretch_left --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_right.lua b/tests/examples/awful/placement/stretch_right.lua index 963f67f0b..d217a781d 100644 --- a/tests/examples/awful/placement/stretch_right.lua +++ b/tests/examples/awful/placement/stretch_right.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name stretch_right --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.stretch_right --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_up.lua b/tests/examples/awful/placement/stretch_up.lua index 6cf4f1cbf..67a2bea75 100644 --- a/tests/examples/awful/placement/stretch_up.lua +++ b/tests/examples/awful/placement/stretch_up.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name stretch_up --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.stretch_up --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/top.lua b/tests/examples/awful/placement/top.lua index 4d8f9d38c..60fc17006 100644 --- a/tests/examples/awful/placement/top.lua +++ b/tests/examples/awful/placement/top.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name top --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.top --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/top_left.lua b/tests/examples/awful/placement/top_left.lua index 87ae8472d..339bd9e10 100644 --- a/tests/examples/awful/placement/top_left.lua +++ b/tests/examples/awful/placement/top_left.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name top_left --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.top_left --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/top_right.lua b/tests/examples/awful/placement/top_right.lua index 952bdfd20..2df7c70a2 100644 --- a/tests/examples/awful/placement/top_right.lua +++ b/tests/examples/awful/placement/top_right.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name top_right --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.top_right --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/xkb.c b/xkb.c index 04dd3b597..40b98f8e2 100644 --- a/xkb.c +++ b/xkb.c @@ -36,7 +36,7 @@ /** * Switch keyboard layout. * - * @function xkb_set_layout_group + * @staticfct xkb_set_layout_group * @tparam integer num keyboard layout number, integer from 0 to 3 */ int @@ -56,7 +56,7 @@ luaA_xkb_set_layout_group(lua_State *L) /** * Get current layout number. * - * @function xkb_get_layout_group + * @staticfct xkb_get_layout_group * @treturn integer num Current layout number, integer from 0 to 3. */ int @@ -87,7 +87,7 @@ luaA_xkb_get_layout_group(lua_State *L) /** * Get layout short names. * - * @function xkb_get_group_names + * @staticfct xkb_get_group_names * @treturn string A string describing the current layout settings, * e.g.: 'pc+us+de:2+inet(evdev)+group(alt_shift_toggle)+ctrl(nocaps)' */
Modifier name Key name