From 86d1b1c22ca584640043fc50187ff59a76e488a1 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 5 Jul 2022 01:37:14 -0700 Subject: [PATCH] doc: Add a mandatory `@noreturn` for functions and methods. The goal is to catch cases where the return value exists, but is forgotten. There was a large enough number of them to turn this into a real check. Initially, I just wanted to implement it to fix the problems, then delete the code. But since this is so common, I think it is worth the annoyance. --- docs/common/cobject.ldoc | 4 +++ docs/common/fixed.ldoc | 1 + docs/common/object.ldoc | 5 ++++ docs/common/signals.ldoc | 2 ++ docs/common/wibox.ldoc | 3 ++- docs/common/widget.ldoc | 3 +++ docs/config.ld | 13 +++++++++ lib/awful/button.lua | 3 ++- lib/awful/client.lua | 23 +++++++++++++++- lib/awful/completion.lua | 1 + lib/awful/hotkeys_popup/init.lua | 1 + lib/awful/hotkeys_popup/widget.lua | 18 +++++++++---- lib/awful/key.lua | 11 ++++---- lib/awful/keyboard.lua | 6 +++++ lib/awful/keygrabber.lua | 5 ++++ lib/awful/layout/init.lua | 15 +++++++---- lib/awful/menu.lua | 7 +++++ lib/awful/mouse/client.lua | 4 +-- lib/awful/mouse/init.lua | 6 +++++ lib/awful/permissions/init.lua | 1 + lib/awful/popup.lua | 2 ++ lib/awful/prompt.lua | 1 + lib/awful/screen.lua | 15 +++++++++-- lib/awful/spawn.lua | 11 ++++++-- lib/awful/tag.lua | 27 ++++++++++++++++--- lib/awful/titlebar.lua | 4 +++ lib/awful/tooltip.lua | 2 ++ lib/awful/wallpaper.lua | 10 +++++++ lib/awful/wibar.lua | 1 + lib/awful/widget/calendar_popup.lua | 2 ++ lib/awful/widget/keyboardlayout.lua | 1 + lib/beautiful/init.lua | 1 + lib/beautiful/theme_assets.lua | 2 ++ lib/beautiful/xresources.lua | 1 + lib/gears/color.lua | 1 + lib/gears/debug.lua | 6 ++++- lib/gears/matcher.lua | 6 +++++ lib/gears/object.lua | 4 +++ lib/gears/shape.lua | 27 +++++++++++++++++-- lib/gears/sort/topological.lua | 4 +++ lib/gears/string.lua | 1 + lib/gears/surface.lua | 1 + lib/gears/timer.lua | 7 ++++- lib/menubar/init.lua | 6 +++-- lib/menubar/menu_gen.lua | 4 +-- lib/menubar/utils.lua | 2 ++ lib/naughty/action.lua | 1 + lib/naughty/notification.lua | 4 +++ lib/ruled/client.lua | 6 +++-- lib/ruled/notification.lua | 8 +++++- lib/wibox/container/arcchart.lua | 1 + lib/wibox/container/background.lua | 1 + lib/wibox/container/constraint.lua | 1 + lib/wibox/container/margin.lua | 1 + lib/wibox/container/mirror.lua | 1 + lib/wibox/container/place.lua | 1 + lib/wibox/container/radialprogressbar.lua | 1 + lib/wibox/container/rotate.lua | 1 + lib/wibox/container/scroll.lua | 11 ++++++++ lib/wibox/hierarchy.lua | 3 +++ lib/wibox/init.lua | 4 +++ lib/wibox/layout/fixed.lua | 1 + lib/wibox/layout/flex.lua | 1 + lib/wibox/layout/grid.lua | 5 +++- lib/wibox/layout/manual.lua | 5 ++++ lib/wibox/layout/ratio.lua | 21 +++++++++------ lib/wibox/layout/stack.lua | 3 +++ lib/wibox/widget/base.lua | 13 +++++++++ lib/wibox/widget/graph.lua | 3 +++ lib/wibox/widget/init.lua | 2 ++ lib/wibox/widget/textclock.lua | 1 + luaa.c | 9 +++++++ mousegrabber.c | 6 +++-- objects/client.c | 5 ++++ objects/drawable.c | 9 ++++--- objects/screen.c | 4 +++ root.c | 2 ++ .../awful/placement/center_vertical.lua | 1 + .../awful/placement/maximize_horizontally.lua | 1 + .../awful/placement/maximize_vertically.lua | 1 + xkb.c | 1 + 81 files changed, 367 insertions(+), 53 deletions(-) diff --git a/docs/common/cobject.ldoc b/docs/common/cobject.ldoc index b8bf3d6f2..f449d4752 100644 --- a/docs/common/cobject.ldoc +++ b/docs/common/cobject.ldoc @@ -1,9 +1,11 @@ */ /** Disconnect from a signal. + * * @tparam string name The name of the signal. * @tparam function func The callback that should be disconnected. * @staticfct disconnect_signal + * @noreturn */ /** Emit a signal. @@ -13,12 +15,14 @@ * function receives the object as first argument and then any extra * arguments that are given to emit_signal(). * @staticfct emit_signal + * @noreturn */ /** Connect to a signal. * @tparam string name The name of the signal. * @tparam function func The callback to call when the signal is emitted. * @staticfct connect_signal + * @noreturn */ /* diff --git a/docs/common/fixed.ldoc b/docs/common/fixed.ldoc index 359fd2ad7..365b161f9 100644 --- a/docs/common/fixed.ldoc +++ b/docs/common/fixed.ldoc @@ -68,6 +68,7 @@ --- Reset the layout. This removes all widgets from the layout. -- @method reset +-- @noreturn -- @emits widget::reset -- @emitstparam widget::reset widget self The layout. -- @interface layout diff --git a/docs/common/object.ldoc b/docs/common/object.ldoc index ed21bedac..8eb477e1c 100644 --- a/docs/common/object.ldoc +++ b/docs/common/object.ldoc @@ -3,6 +3,8 @@ -- @tparam string name The name of the signal. -- @tparam function func The callback that should be disconnected. -- @method disconnect_signal +-- @treturn boolean `true` when the function was disconnected or `false` if it +-- wasn't found. -- @baseclass gears.object --- Emit a signal. @@ -12,12 +14,14 @@ -- function receives the object as first argument and then any extra -- arguments that are given to emit_signal(). -- @method emit_signal +-- @noreturn -- @baseclass gears.object --- Connect to a signal. -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method connect_signal +-- @noreturn -- @baseclass gears.object --- Connect to a signal weakly. @@ -31,4 +35,5 @@ -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method weak_connect_signal +-- @noreturn -- @baseclass gears.object diff --git a/docs/common/signals.ldoc b/docs/common/signals.ldoc index 30499a8ef..b8f1a9439 100644 --- a/docs/common/signals.ldoc +++ b/docs/common/signals.ldoc @@ -10,6 +10,7 @@ -- -- @tparam string name The name of the signal -- @tparam function func The function to attach +-- @noreturn -- @staticfct naughty.connect_signal -- @usage naughty.connect_signal("added", function(notif) -- -- do something @@ -18,6 +19,7 @@ --- Emit a module signal. -- @tparam string name The signal name. -- @param ... The signal callback arguments +-- @noreturn -- @staticfct naughty.emit_signal --- Disconnect a signal from a source. diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc index b12440524..7c1415adc 100644 --- a/docs/common/wibox.ldoc +++ b/docs/common/wibox.ldoc @@ -191,7 +191,7 @@ -- @baseclass wibox -- @tparam[opt=nil] table|nil geo A table with coordinates to modify. If -- nothing is specified, it only returns the current geometry. --- @return A table with wibox coordinates and geometry. +-- @treturn table A table with wibox coordinates and geometry. -- @method geometry -- @emits property::geometry When the geometry change. -- @emitstparam property::geometry table geo The geometry table. @@ -217,6 +217,7 @@ -- @param args An array containing the widgets disposition -- @baseclass wibox -- @method setup +-- @noreturn --- The background of the wibox. -- diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index a08fdc75c..1ef1efb57 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -26,6 +26,7 @@ -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @tparam table args An array containing the widgets disposition -- @method setup +-- @noreturn -- @baseclass wibox.widget --- Force a widget height. @@ -60,6 +61,7 @@ --- Add a new `awful.button` to this widget. -- @tparam awful.button button The button to add. -- @method add_button +-- @noreturn -- @baseclass wibox.widget --- Emit a signal and ensure all parent widgets in the hierarchies also @@ -69,6 +71,7 @@ -- @param ... Other arguments -- @baseclass wibox.widget -- @method emit_signal_recursive +-- @noreturn --- When the layout (size) change. -- This signal is emitted when the previous results of `:layout()` and `:fit()` diff --git a/docs/config.ld b/docs/config.ld index a92528d74..56a3efe3e 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -824,6 +824,14 @@ add_custom_tag { auto_subtags = false } +-- Forces every method and function to have either `@treturn` or `@noreturn`. +-- This avoids the many case where the return value was forgotten. +add_custom_tag { + name = "noreturn", + hidden = true, + auto_subtags = false +} + add_custom_tag { name = "signalhandler", hidden = false, @@ -1342,6 +1350,11 @@ local function sanitize_return_type(item) end item.display_type = item.display_type .. "" + elseif not item.tags["noreturn"] then + print( + "WARNING:", item.name, "from", item.module.name, + "doesn't have a return value or @noreturn" + ) end item.compact_signature = true diff --git a/lib/awful/button.lua b/lib/awful/button.lua index 21c46c7f7..db5ecced3 100644 --- a/lib/awful/button.lua +++ b/lib/awful/button.lua @@ -105,7 +105,8 @@ button.names = { -- @tparam function on_release --- Execute this mousebinding. --- @method :trigger +-- @method trigger +-- @noreturn function button:set_button(b) for _, v in ipairs(self) do diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 28df06d51..dbaf3bfcf 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -178,6 +178,7 @@ end -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client and its first -- tag as arguments. +-- @noreturn -- @request client activate client.jumpto granted When a client is activated -- because `c:jump_to()` is called. -- @see activate @@ -298,6 +299,7 @@ end -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @tparam[opt="focused"] client c The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.global_bydirection @@ -329,6 +331,7 @@ end -- @staticfct awful.client.swap.global_bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @tparam[opt=client.focus] client sel The client. +-- @noreturn -- @request client activate client.swap.global_bydirection granted When a client -- could be activated because `awful.client.swap.global_bydirection` was called. -- @see swap @@ -372,6 +375,7 @@ end -- @staticfct awful.client.swap.byidx -- @tparam integer i The index. Use `1` to get the next, `-1` to get the previous. -- @tparam[opt=client.focus] client c The client, otherwise focused one is used. +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.bydirection @@ -397,6 +401,7 @@ end -- @tparam[opt=false] boolean clockwise True to cycle clients clockwise. -- @tparam[opt=awful.screen.focused()] screen s The screen where to cycle clients. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.bydirection @@ -424,6 +429,7 @@ end -- -- @method append_keybinding -- @tparam awful.key key The key. +-- @noreturn -- @see remove_keybinding -- @see append_mousebinding -- @see remove_mousebinding @@ -431,17 +437,20 @@ end --- Remove a keybinding. -- -- @method remove_keybinding +-- @noreturn -- @tparam awful.key key The key. --- Append a mousebinding. -- -- @method append_mousebinding -- @tparam awful.button button The button. +-- @noreturn --- Remove a mousebinding. -- -- @method remove_mousebinding -- @tparam awful.button button The button. +-- @noreturn --- Get the master window. -- @@ -476,6 +485,7 @@ end -- @DOC_sequences_client_to_primary_EXAMPLE@ -- -- @method to_primary_section +-- @noreturn -- @see swap -- @see to_secondary_section function client.object:to_primary_section() @@ -494,6 +504,7 @@ end -- @DOC_sequences_client_to_secondary_EXAMPLE@ -- -- @method to_secondary_section +-- @noreturn -- @see swap -- @see to_primary_section @@ -527,6 +538,7 @@ end -- @tparam[opt=0] integer y The relative y coordinate. -- @tparam[opt=0] integer w The relative width. -- @tparam[opt=0] integer h The relative height. +-- @noreturn -- @see geometry -- @see x -- @see y @@ -558,6 +570,7 @@ end -- -- @method move_to_tag -- @tparam tag target The tag to move the client to. +-- @noreturn -- @request client activate client.movetotag granted When a client could be -- activated because `c:move_to_tag()` was called. -- @see tags @@ -591,6 +604,7 @@ end -- -- @method toggle_tag -- @tparam tag target The tag to move the client to. +-- @noreturn -- @see tags function client.object.toggle_tag(self, target) -- Check that tag and client screen are identical @@ -631,6 +645,7 @@ end -- -- @method move_to_screen -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1. +-- @noreturn -- @see screen -- @see request::activate -- @request client activate client.movetoscreen granted When a client could be @@ -682,6 +697,7 @@ end -- @DOC_sequences_client_to_selected_tags1_EXAMPLE@ -- -- @method to_selected_tags +-- @noreturn -- @see screen.selected_tags function client.object.to_selected_tags(self) local tags = {} @@ -1444,6 +1460,7 @@ end -- @tparam string prop The property name. -- @tparam string kind The type (used for register_xproperty). -- One of "string", "number" or "boolean". +-- @noreturn function client.property.persist(prop, kind) local xprop = "awful.client.property." .. prop capi.awesome.register_xproperty(xprop, kind) @@ -1466,7 +1483,7 @@ end -- @tparam integer start What index to start iterating from. Defaults to using the -- index of the currently focused client. -- @tparam[opt=nil] screen s Which screen to use. nil means all screens. --- +-- @treturn function A Lua iterator (to use in a `for` loop). -- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances -- local urxvt = function (c) @@ -1666,6 +1683,7 @@ end -- @tparam[opt=false] boolean args.switch_to_tag -- @tparam[opt=false] boolean args.action Once activated, perform an action. -- @tparam[opt=false] boolean args.toggle_minimization +-- @noreturn -- @request client activate args.context granted Will use the context defined in -- `args.context`. -- @see awful.permissions.add_activate_filter @@ -1712,6 +1730,7 @@ end -- @method grant -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions --- Deny a permission for a client. @@ -1719,6 +1738,7 @@ end -- @method deny -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions pcommon.setup_grant(client.object, "client") @@ -1849,6 +1869,7 @@ end) -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client as argument. +-- @noreturn -- Add clients during startup to focus history. -- This used to happen through permissions.activate, but that only handles visible diff --git a/lib/awful/completion.lua b/lib/awful/completion.lua index 45ca4598d..a23590cce 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. -- @tparam string src The bash completion source file, `/etc/bash_completion` by default. +-- @noreturn -- @staticfct awful.completion.bashcomp_load function completion.bashcomp_load(src) if src then bashcomp_src = src end diff --git a/lib/awful/hotkeys_popup/init.lua b/lib/awful/hotkeys_popup/init.lua index 4cb6e4772..058bae128 100644 --- a/lib/awful/hotkeys_popup/init.lua +++ b/lib/awful/hotkeys_popup/init.lua @@ -25,6 +25,7 @@ local hotkeys_popup = { -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. -- @staticfct awful.hotkeys_popup.show_help +-- @noreturn -- @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 e0d5a5613..b6e4ec54b 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -685,11 +685,13 @@ function widget.new(args) --- Show popup with hotkeys help. - -- @tparam[opt] client c Client. - -- @tparam[opt] screen s Screen. - -- @tparam[opt] table show_args Additional arguments. + -- @tparam[opt=client.focus] client c Client. + -- @tparam[opt=c.screen] screen s Screen. + -- @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. + -- @treturn awful.keygrabber The keybrabber used to detect when the key is + -- released. -- @method show_help function widget_instance:show_help(c, s, show_args) show_args = show_args or {} @@ -750,6 +752,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. + -- @noreturn -- @method add_hotkeys function widget_instance:add_hotkeys(hotkeys) for group, bindings in pairs(hotkeys) do @@ -773,6 +776,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. + -- @noreturn -- @method add_group_rules function widget_instance:add_group_rules(group, data) self.group_rules[group] = data @@ -794,6 +798,8 @@ 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. +-- @treturn awful.keygrabber The keybrabber used to detect when the key is +-- released. -- @staticfct awful.hotkeys_popup.widget.show_help function widget.show_help(...) return get_default_widget():show_help(...) @@ -803,9 +809,10 @@ end -- (default widget instance will be used). -- @tparam table hotkeys Table with bindings, -- see `awful.hotkeys_popup.key.vim` as an example. +-- @noreturn -- @staticfct awful.hotkeys_popup.widget.add_hotkeys function widget.add_hotkeys(...) - return get_default_widget():add_hotkeys(...) + get_default_widget():add_hotkeys(...) end --- Add hotkey group rules for third-party applications @@ -813,9 +820,10 @@ end -- @tparam string group Rule group name, -- @tparam table data Rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. +-- @noreturn -- @staticfct awful.hotkeys_popup.widget.add_group_rules function widget.add_group_rules(group, data) - return get_default_widget():add_group_rules(group, data) + get_default_widget():add_group_rules(group, data) end return widget diff --git a/lib/awful/key.lua b/lib/awful/key.lua index efb07a52e..35fff8f61 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -159,7 +159,8 @@ end --- Execute this keybinding. -- --- @method :trigger +-- @method trigger +-- @noreturn function key:trigger() local data = reverse_map[self] @@ -432,10 +433,10 @@ function key.new(args, keycode, press, release, data) end --- Compare a key object with modifiers and key. --- @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 +-- @tparam table pressed_mod The modifiers to compare with. +-- @tparam string pressed_key The key to compare with. +-- @treturn boolean If the key and modifier match. +-- @method match function key.match(self, pressed_mod, pressed_key) -- First, compare key. if pressed_key ~= self.key then return false end diff --git a/lib/awful/keyboard.lua b/lib/awful/keyboard.lua index ea49ba6bb..3ca61dc1f 100644 --- a/lib/awful/keyboard.lua +++ b/lib/awful/keyboard.lua @@ -46,6 +46,7 @@ capi.awesome.connect_signal("xkb::map_changed", function() conversion = nil end) -- @tparam table modifiers A modified table. Valid modifiers are: `Any`, `Mod1`, -- `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. -- @tparam string key The key. +-- @noreturn -- @staticfct awful.keyboard.emulate_key_combination function module.emulate_key_combination(modifiers, key) local modmap = generate_conversion_map() @@ -90,6 +91,7 @@ end -- -- @staticfct awful.keyboard.append_global_keybinding -- @tparam awful.key key The key object. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybindings -- @see awful.keyboard.remove_global_keybinding @@ -107,6 +109,7 @@ end -- @tparam table keys A table of `awful.key` objects. Optionally, it can have -- a `group` entry. If set, the `group` property will be set on all `awful.keys` -- objects. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybinding -- @see awful.keyboard.remove_global_keybinding @@ -131,6 +134,7 @@ end -- -- @staticfct awful.keyboard.remove_global_keybinding -- @tparam awful.key key The key object. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybinding @@ -145,6 +149,7 @@ local default_keys = {} -- -- @staticfct awful.keyboard.append_client_keybinding -- @tparam awful.key key The key. +-- @noreturn -- @emits client_keybinding::added -- @emitstparam client_keybinding::added awful.key key The key. -- @see awful.key @@ -164,6 +169,7 @@ end -- -- @staticfct awful.keyboard.append_client_keybindings -- @tparam table keys A table containing `awful.key` objects. +-- @noreturn -- @emits client_keybinding::added -- @emitstparam client_keybinding::added awful.key key The key. -- @see awful.key diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index f28cce404..ca5211060 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -500,6 +500,7 @@ end -- @method stop -- @tparam string|nil stop_key Override the key passed to `stop_callback` **DEPRECATED** -- @tparam tale|nil Override the modifiers passed to `stop_callback` **DEPRECATED** +-- @noreturn -- @emits stopped -- @emits property::current_instance function keygrabber:stop(stop_key, stop_mods) @@ -535,6 +536,7 @@ end -- @method add_keybinding -- @tparam awful.key key The key. -- @tparam string description.group The keybinding group +-- @noreturn function keygrabber:add_keybinding(key, keycode, callback, description) local mods = not key._is_awful_key and key or nil @@ -852,6 +854,7 @@ local signals = {} -- @staticfct awful.keygrabber.connect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. +-- @noreturn function keygrab.connect_signal(name, callback) signals[name] = signals[name] or {} @@ -865,6 +868,7 @@ end -- @staticfct awful.keygrabber.disconnect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. +-- @noreturn function keygrab.disconnect_signal(name, callback) signals[name] = signals[name] or {} @@ -885,6 +889,7 @@ end -- @staticfct awful.keygrabber.emit_signal -- @tparam string name The signal name. -- @param ... Other arguments for the callbacks. +-- @noreturn function keygrab.emit_signal(name, ...) signals[name] = signals[name] or {} diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua index ba7106234..d66be87bd 100644 --- a/lib/awful/layout/init.lua +++ b/lib/awful/layout/init.lua @@ -109,7 +109,7 @@ local arrange_lock = false local delayed_arrange = {} --- Get the current layout. --- @param screen The screen. +-- @tparam screen screen The screen. -- @return The layout function. -- @staticfct awful.layout.get function layout.get(screen) @@ -122,9 +122,10 @@ function layout.get(screen) end --- Change the layout of the current tag. --- @param i Relative index. --- @param s The screen. --- @param[opt] layouts A table of layouts. +-- @tparam integer i Relative index. +-- @tparam screen s The screen. +-- @tparam[opt=s.selected_tag.layouts] table layouts A table of layouts. +-- @noreturn -- @staticfct awful.layout.inc function layout.inc(i, s, layouts) if type(i) == "table" then @@ -171,6 +172,7 @@ end --- Set the layout function of the current tag. -- @tparam layout|function l Layout object or function. -- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify. +-- @noreturn -- @staticfct awful.layout.set function layout.set(l, t) t = t or capi.mouse.screen.selected_tag @@ -232,7 +234,8 @@ function layout.parameters(t, screen) end --- Arrange a screen using its current layout. --- @param screen The screen to arrange. +-- @tparam screen screen The screen to arrange. +-- @noreturn -- @staticfct awful.layout.arrange function layout.arrange(screen) screen = get_screen(screen) @@ -275,6 +278,7 @@ end -- -- @staticfct awful.layout.append_default_layout -- @tparam layout to_add A valid tag layout. +-- @noreturn -- @see awful.layout.layouts function layout.append_default_layout(to_add) rawset(default_layouts, #default_layouts+1, to_add) @@ -311,6 +315,7 @@ end -- -- @staticfct awful.layout.append_default_layouts -- @tparam table layouts A table of valid tag layout. +-- @noreturn -- @see awful.layout.layouts function layout.append_default_layouts(layouts) for _, l in ipairs(layouts) do diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index 33caa8ceb..474b74320 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -360,6 +360,7 @@ end -- @tparam[opt={}] table args The arguments -- @tparam[opt=mouse.coords] table args.coords The menu position. A table with -- `x` and `y` as keys and position (in pixels) as values. +-- @noreturn -- @method show function menu:show(args) args = args or {} @@ -375,6 +376,7 @@ end --- Hide a menu popup. -- @method hide +-- @noreturn function menu:hide() -- Remove items from screen for i = 1, #self.items do @@ -394,6 +396,7 @@ end -- @tparam table args The arguments. -- @tparam[opt=mouse.coords] table args.coords The menu position. A table with -- `x` and `y` as keys and position (in pixels) as values. +-- @noreturn -- @method toggle function menu:toggle(args) if self.wibox.visible then @@ -405,6 +408,7 @@ end --- Update menu content. -- @method update +-- @noreturn function menu:update() if self.wibox.visible then self:show({ coords = { x = self.x, y = self.y } }) @@ -415,6 +419,7 @@ end --- Get the elder parent so for example when you kill -- it, it will destroy the whole family. -- @method get_root +-- @treturn awful.menu The root menu. function menu:get_root() return self.parent and menu.get_root(self.parent) or self end @@ -425,6 +430,7 @@ end -- @tparam[opt=awful.menu.entry] function args.new The menu entry constructor. -- @tparam[opt] table args.theme The menu entry theme. -- @tparam[opt] number index The index where the new entry will inserted. +-- @treturn table|nil The new item. -- @method add function menu:add(args, index) if not args then return end @@ -482,6 +488,7 @@ end --- Delete menu entry at given position. -- @tparam table|number num The index in the table of the menu entry to be deleted; can be also the menu entry itself. +-- @noreturn -- @method delete function menu:delete(num) if type(num) == "table" then diff --git a/lib/awful/mouse/client.lua b/lib/awful/mouse/client.lua index 5170eb3a1..3a495b86b 100644 --- a/lib/awful/mouse/client.lua +++ b/lib/awful/mouse/client.lua @@ -13,9 +13,9 @@ local module = {} --- Move a client. -- @staticfct awful.mouse.client.move --- @param c The client to move, or the focused one if nil. +-- @tparam client 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. +-- @noreturn -- @request client geometry mouse.move granted When `awful.mouse.client.move` is -- called. function module.move(c, snap, finished_cb) --luacheck: no unused args diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index b4d620360..9648f7ab4 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -201,6 +201,7 @@ end --- Move the wibox under the cursor. -- @staticfct awful.mouse.wibox.move -- @tparam wibox w The wibox to move, or none to use that under the pointer +-- @noreturn -- @request wibox geometry mouse.move granted Requests to move the wibox. function mouse.wibox.move(w) w = w or mouse.current_wibox @@ -248,6 +249,7 @@ end -- -- @staticfct awful.mouse.append_global_mousebinding -- @tparam awful.button button The button object. +-- @noreturn -- @see awful.button function mouse.append_global_mousebinding(button) @@ -264,6 +266,7 @@ end -- @tparam table buttons A table of `awful.button` objects. Optionally, it can have -- a `group` entry. If set, the `group` property will be set on all `awful.buttons` -- objects. +-- @noreturn -- @see awful.button function mouse.append_global_mousebindings(buttons) @@ -286,6 +289,7 @@ end -- -- @staticfct awful.mouse.remove_global_mousebinding -- @tparam awful.button button The button object. +-- @noreturn -- @see awful.button function mouse.remove_global_mousebinding(button) @@ -298,6 +302,7 @@ local default_buttons = {} -- -- @staticfct awful.mouse.append_client_mousebinding -- @tparam awful.button button The button. +-- @noreturn -- @emits client_mousebinding::added -- @emitstparam client_mousebinding::added awful.button button The button. -- @see awful.button @@ -317,6 +322,7 @@ end -- -- @staticfct awful.mouse.append_client_mousebindings -- @tparam table buttons A table containing `awful.button` objects. +-- @noreturn -- @see awful.button -- @see awful.keyboard.append_client_keybinding -- @see awful.mouse.append_client_mousebinding diff --git a/lib/awful/permissions/init.lua b/lib/awful/permissions/init.lua index 5b59b8e1a..9c5be3a79 100644 --- a/lib/awful/permissions/init.lua +++ b/lib/awful/permissions/init.lua @@ -241,6 +241,7 @@ end -- -- @tparam function f The callback -- @tparam[opt] string context The `request::activate` context +-- @noreturn -- @see generic_activate_filters -- @see contextual_activate_filters -- @see remove_activate_filter diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index cde263434..9c5845891 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -264,6 +264,7 @@ end -- @tparam widget widget The widget -- @tparam[opt=1] number button The button index -- @method bind_to_widget +-- @noreturn function popup:bind_to_widget(widget, button) if not self._private.button_for_widget then self._private.button_for_widget = {} @@ -276,6 +277,7 @@ end --- Unbind the popup from a widget button. -- @tparam widget widget The widget -- @method unbind_to_widget +-- @noreturn 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 caf3c57b0..52b4f34e8 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -461,6 +461,7 @@ end -- @tparam[opt] function keypressed_callback The callback function to call -- with mod table, key and command as arguments when a key was pressed. -- [**DEPRECATED**] +-- @noreturn -- @see gears.color -- @staticfct awful.prompt.run function prompt.run(args, textbox, exe_callback, completion_callback, diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index 6d931bda3..e73128624 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -91,6 +91,7 @@ end -- or keeps its position relative to the current focused screen. -- @staticfct awful.screen.focus -- @tparam screen screen Screen number (defaults / falls back to mouse.screen). +-- @treturn screen The newly focused screen. -- @request client activate screen.focus granted The most recent focused client -- for this screen should be re-activated. function screen.focus(_screen) @@ -126,6 +127,8 @@ function screen.focus(_screen) if c then c:emit_signal("request::activate", "screen.focus", {raise=false}) end + + return _screen end --- Get the next screen in a specific direction. @@ -175,6 +178,7 @@ end -- @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. +-- @treturn screen The newly focusd screen. function screen.focus_relative(offset) return screen.focus(gmath.cycle(capi.screen.count(), screen.focused().index + offset)) @@ -542,6 +546,7 @@ end -- @staticfct awful.screen.connect_for_each_screen -- @tparam function func The function to call. -- @tparam screen func.screen The screen. +-- @noreturn function screen.connect_for_each_screen(func) for s in capi.screen do func(s) @@ -552,6 +557,7 @@ end --- Undo the effect of `awful.screen.connect_for_each_screen`. -- @staticfct awful.screen.disconnect_for_each_screen -- @tparam function func The function that should no longer be called. +-- @noreturn function screen.disconnect_for_each_screen(func) capi.screen.disconnect_signal("added", func) end @@ -652,10 +658,14 @@ end -- -- @DOC_awful_screen_split2_EXAMPLE@ -- --- @tparam[opt] table ratios The different ratios to split into. If none is --- provided, it is split in half. +-- @tparam[opt={50﹐50}] table ratios The different ratios to split into. If none +-- is provided, it is split in half. -- @tparam[opt] string mode Either "vertical" or "horizontal". If none is -- specified, it will split along the longest axis. +-- @treturn table A table with the screen objects. The first value is the +-- original screen object (`s`) and the following one(s) are the new screen +-- objects. The values are ordered from left to right or top to bottom depending +-- on the value of `mode`. -- @method split function screen.object.split(s, ratios, mode, _geo) s = get_screen(s) @@ -737,6 +747,7 @@ end -- defaulting to 96. -- -- @tparam boolean enabled Enable or disable automatic DPI support. +-- @noreturn -- @staticfct awful.screen.set_auto_dpi_enabled function screen.set_auto_dpi_enabled(enabled) for s in capi.screen do diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua index beae02d0a..7d3e94508 100644 --- a/lib/awful/spawn.lua +++ b/lib/awful/spawn.lua @@ -364,6 +364,10 @@ end --- Spawn a program using the shell. -- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`). -- @tparam string cmd The command. +-- @treturn[1] integer The forked PID. +-- @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.with_shell function spawn.with_shell(cmd) if cmd and cmd ~= "" then @@ -500,6 +504,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? +-- @noreturn -- @staticfct awful.spawn.read_lines function spawn.read_lines(input_stream, line_callback, done_callback, close) local stream = Gio.DataInputStream.new(input_stream) @@ -649,8 +654,9 @@ end -- @tparam[opt] string unique_id A string to identify the client so it isn't executed -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. --- @see ruled.client +-- @noreturn -- @staticfct awful.spawn.once +-- @see ruled.client 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) @@ -682,8 +688,9 @@ end -- @tparam[opt] string unique_id A string to identify the client so it isn't executed -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. --- @see ruled.client +-- @noreturn -- @staticfct awful.spawn.single_instance +-- @see ruled.client 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) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 958da3937..2ceadb4d4 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -221,6 +221,7 @@ end -- -- @method swap -- @tparam tag tag2 The second tag +-- @noreturn -- @see client.swap function tag.object.swap(self, tag2) local idx1, idx2 = tag.object.get_index(self), tag.object.get_index(tag2) @@ -335,6 +336,7 @@ end -- @staticfct awful.tag.find_fallback -- @tparam[opt=awful.screen.focused()] screen screen The screen to look for a tag on. -- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. +-- @treturn tag|nil Returns a fallback tag if one was found, otherwise `nil`. function tag.find_fallback(screen, invalids) local scr = screen or ascreen.focused() local t = invalids or scr.selected_tags @@ -356,6 +358,7 @@ end -- @tparam table args The arguments. -- @tparam tag args.fallback_tag A fallback tag. -- @tparam[opt=false] boolean args.allow_untagged Allow the untagged clients to remain untagged. +-- @noreturn -- @emits cleared After all clients have been untagged. -- @emits untagged For each currently tagged clients. -- @emitstparam untagged client c The untagged client. @@ -480,6 +483,7 @@ end --- Update the tag history. -- @staticfct awful.tag.history.update -- @tparam screen obj Screen object. +-- @noreturn function tag.history.update(obj) local s = get_screen(obj) local curtags = s.selected_tags @@ -520,6 +524,7 @@ end --- Revert tag history. -- @staticfct awful.tag.history.restore +-- @noreturn -- @tparam screen screen The screen. -- @tparam number 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 @@ -752,6 +757,7 @@ end -- @see master_width_factor -- @tparam number add Value to add to master width factor. -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. +-- @noreturn function tag.incmwfact(add, t) t = t or t or ascreen.focused().selected_tag tag.object.set_master_width_factor(t, tag.object.get_master_width_factor(t) + add) @@ -1128,6 +1134,7 @@ end -- @staticfct awful.tag.incgap -- @tparam number add Value to add to the spacing between clients -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. +-- @noreturn -- @see gap -- @see beautiful.useless_gap function tag.incgap(add, t) @@ -1247,6 +1254,7 @@ end -- "expand" (fill all the available workarea) or -- `master_width_factor` (fill only an area inside the master width factor) -- @tparam[opt=tag.selected()] tag t The tag to modify +-- @noreturn function tag.setmfpol(policy, t) gdebug.deprecate("Use t.master_fill_policy = policy instead of awful.tag.setmfpol", {deprecated_in=4}) @@ -1257,6 +1265,7 @@ end --- Toggle size fill policy for the master client(s) -- between "expand" and `master_width_factor`. -- @staticfct awful.tag.togglemfpol +-- @noreturn -- @see master_fill_policy -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.togglemfpol(t) @@ -1343,6 +1352,7 @@ end -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @tparam[opt=false] boolean sensible Limit nmaster based on the number of -- visible tiled windows? +-- @noreturn function tag.incnmaster(add, t, sensible) t = t or ascreen.focused().selected_tag @@ -1461,6 +1471,7 @@ end -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @tparam[opt=false] boolean sensible Limit column_count based on the number -- of visible tiled windows? +-- @noreturn function tag.incncol(add, t, sensible) t = t or ascreen.focused().selected_tag @@ -1492,6 +1503,7 @@ end -- -- @staticfct awful.tag.viewnone -- @tparam[opt] int|screen screen The screen. +-- @noreturn function tag.viewnone(screen) screen = screen or ascreen.focused() local tags = screen.tags @@ -1511,6 +1523,7 @@ end -- @see screen.tags -- @tparam number i The **relative** index to see. -- @tparam[opt] screen screen The screen. +-- @noreturn -- @see awful.tag.viewnext -- @see awful.tag.viewprev function tag.viewidx(i, screen) @@ -1552,10 +1565,11 @@ end -- -- @staticfct awful.tag.viewnext -- @tparam screen screen The screen. +-- @noreturn -- @see awful.tag.viewidx -- @see awful.tag.viewprev function tag.viewnext(screen) - return tag.viewidx(1, screen) + tag.viewidx(1, screen) end --- View previous tag. This is the same a `tag.viewidx(-1)`. @@ -1566,10 +1580,11 @@ end -- -- @staticfct awful.tag.viewprev -- @tparam screen screen The screen. +-- @noreturn -- @see awful.tag.viewidx -- @see awful.tag.viewnext function tag.viewprev(screen) - return tag.viewidx(-1, screen) + tag.viewidx(-1, screen) end --- View only a tag. @@ -1577,6 +1592,7 @@ end -- @DOC_sequences_tag_view_only_EXAMPLE@ -- -- @method view_only +-- @noreturn -- @see selected function tag.object.view_only(self) local tags = self.screen.tags @@ -1595,6 +1611,7 @@ end --- View only a tag. -- @deprecated awful.tag.viewonly +-- @noreturn -- @see tag.view_only -- @tparam tag t The tag object. function tag.viewonly(t) @@ -1613,6 +1630,7 @@ end -- @tparam table tags A table with tags to view only. -- @tparam[opt] screen screen The screen of the tags. -- @tparam[opt=#tags] number maximum The maximum number of tags to select. +-- @noreturn function tag.viewmore(tags, screen, maximum) maximum = maximum or #tags local selected = 0 @@ -1643,8 +1661,9 @@ end --- Toggle selection of a tag -- @staticfct awful.tag.viewtoggle --- @see selected -- @tparam tag t Tag to be toggled +-- @noreturn +-- @see selected function tag.viewtoggle(t) t.selected = not t.selected capi.screen[tag.getproperty(t, "screen")]:emit_signal("tag::history::update") @@ -1701,6 +1720,7 @@ end --- Tag a client with the set of current tags. -- @deprecated awful.tag.withcurrent -- @tparam client c The client to tag. +-- @noreturn function tag.withcurrent(c) gdebug.deprecate("Use c:to_selected_tags() instead of awful.tag.selectedlist", {deprecated_in=4}) @@ -1740,6 +1760,7 @@ end -- @tparam screen|nil screen The screen concerned, or all if `nil`. -- @tparam string signal The signal name. -- @tparam function callback +-- @noreturn function tag.attached_connect_signal(screen, ...) if screen then attached_connect_signal_screen(screen, ...) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index db59510c0..99873b216 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -535,6 +535,7 @@ local titlebar = { -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @tparam table args An array containing the widgets disposition -- @method setup +-- @noreturn local all_titlebars = setmetatable({}, { __mode = 'k' }) @@ -713,6 +714,7 @@ end -- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.show -- @request client titlebars show granted Called when `awful.titlebar.show` is -- called. @@ -729,6 +731,7 @@ end -- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.hide function titlebar.hide(c, position) position = position or "top" @@ -739,6 +742,7 @@ end -- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.toggle -- @request client titlebars toggle granted Called when `awful.titlebar.toggle` is -- called. diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index e06ecbeaf..3c6a8a14c 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -575,6 +575,7 @@ end -- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. +-- @noreturn -- @method add_to_object function tooltip:add_to_object(obj) if not obj then return end @@ -588,6 +589,7 @@ end -- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. +-- @noreturn -- @method remove_from_object function tooltip:remove_from_object(obj) obj:disconnect_signal("mouse::enter", self.show) diff --git a/lib/awful/wallpaper.lua b/lib/awful/wallpaper.lua index 19dd08c9f..0a8340558 100644 --- a/lib/awful/wallpaper.lua +++ b/lib/awful/wallpaper.lua @@ -713,6 +713,7 @@ end -- -- @method add_screen -- @tparam screen screen The screen object. +-- @noreturn -- @see remove_screen function module:add_screen(s) s = get_screen(s) @@ -741,6 +742,7 @@ end -- wallpaper will have an overlap. -- -- @method detach +-- @noreturn -- @see remove_screen -- @see add_screen function module:detach() @@ -764,6 +766,7 @@ end -- really need to repaint the wallpaper, call this method. -- -- @method repaint +-- @noreturn function module:repaint() for _, s in ipairs(self._private.screens) do pending_repaint[s] = true @@ -791,21 +794,28 @@ end -- -- @method remove_screen -- @tparam screen screen The screen to remove. +-- @treturn boolean `true` if the screen was removed and `false` if the screen +-- wasn't found. -- @see detach -- @see add_screen -- @see screens function module:remove_screen(s) + local ret = false + s = get_screen(s) for k, s2 in ipairs(self._private.screens) do if s == s2 then table.remove(self._private.screens, k) + ret = true end end backgrounds[s] = nil self:repaint() + + return ret end --- Create a wallpaper. diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index 02377e292..2a35b03a2 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -442,6 +442,7 @@ end --- Remove a wibar. -- @method remove +-- @noreturn function awfulwibar.remove(self) self.visible = false diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 5ec6effa9..ff7dc3c03 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -240,10 +240,12 @@ function calendar_popup:call_calendar(offset, position, screen) end --- Toggle calendar visibility. +-- @treturn boolean The new value of `visible`. -- @method toggle function calendar_popup:toggle() self:call_calendar(0) self.visible = not self.visible + return self.visible end --- Attach the calendar to a widget to display at a specific position. diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index a512d9fdc..781646dfb 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -256,6 +256,7 @@ local function update_layout(self) end --- Select the next layout. +-- @noreturn -- @method next_layout --- Create a keyboard layout widget. diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index 44601324c..d0d0a3d99 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -225,6 +225,7 @@ end --- Get the height of a font. -- -- @tparam string name Name of the font. +-- @treturn number The font height. -- @staticfct beautiful.get_font_height function beautiful.get_font_height(name) return load_font(name).height diff --git a/lib/beautiful/theme_assets.lua b/lib/beautiful/theme_assets.lua index 555a963f8..d4f61de03 100644 --- a/lib/beautiful/theme_assets.lua +++ b/lib/beautiful/theme_assets.lua @@ -86,6 +86,7 @@ end -- @tparam color bg Background color. -- @tparam color fg Main foreground color. -- @tparam color alt_fg Accent foreground color. +-- @noreturn -- @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 @@ -155,6 +156,7 @@ end -- @tparam number height Height. -- @tparam color bg Background color. -- @tparam color fg Foreground color. +-- @noreturn -- @staticfct beautiful.theme_assets.gen_logo function theme_assets.gen_logo(cr, width, height, bg, fg) local ls = math.min(width, height) diff --git a/lib/beautiful/xresources.lua b/lib/beautiful/xresources.lua index 71299cb44..97f51697f 100644 --- a/lib/beautiful/xresources.lua +++ b/lib/beautiful/xresources.lua @@ -119,6 +119,7 @@ end --- Set DPI for a given screen (defaults to global). -- @tparam number dpi DPI value. -- @tparam[opt] integer s Screen. +-- @noreturn -- @staticfct beautiful.xresources.set_dpi function xresources.set_dpi(dpi, s) s = get_screen(s) diff --git a/lib/gears/color.lua b/lib/gears/color.lua index f872221a3..5035da5a5 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -282,6 +282,7 @@ end --- Create a pattern from a given string, same as @{gears.color}. -- @see gears.color +-- @treturn gears.color A cairo pattern object. -- @staticfct gears.color.create_pattern function color.create_pattern(col) if cairo.Pattern:is_type_of(col) then diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua index 835e099fd..4718966a7 100644 --- a/lib/gears/debug.lua +++ b/lib/gears/debug.lua @@ -50,7 +50,7 @@ end -- @param data Value to inspect. -- @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. +-- @treturn 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) @@ -61,6 +61,7 @@ end -- @param tag The name of the table. -- @tparam[opt] int depth Depth of recursion. -- @staticfct gears.debug.dump +-- @noreturn function debug.dump(data, tag, depth) print(debug.dump_return(data, tag, depth)) end @@ -68,6 +69,7 @@ end --- Print an warning message -- @tparam string message The warning message to print. -- @staticfct gears.debug.print_warning +-- @noreturn function debug.print_warning(message) io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n") end @@ -75,6 +77,7 @@ end --- Print an error message -- @tparam string message The error message to print. -- @staticfct gears.debug.print_error +-- @noreturn function debug.print_error(message) io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n") end @@ -93,6 +96,7 @@ local displayed_deprecations = {} -- @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 +-- @noreturn -- @emits debug::deprecation This is usually routed to stdout when the API is -- newly deprecated. -- @emitstparam debug::deprecation string msg The full formatted message. diff --git a/lib/gears/matcher.lua b/lib/gears/matcher.lua index 869147c9d..5b4e3e1b0 100644 --- a/lib/gears/matcher.lua +++ b/lib/gears/matcher.lua @@ -225,6 +225,7 @@ end -- "except" and "except_any" keys. If no rules are provided, all rules -- registered with a source will be matched. -- @method matching_rules +-- @treturn table The matching rules. function matcher:matching_rules(o, rules) -- Match all sources. @@ -290,6 +291,7 @@ end -- @tparam string name The property name. -- @tparam function f The matching function. -- @method add_property_matcher +-- @noreturn -- @usage -- Manually match the screen in various ways. -- matcher:add_property_matcher("screen", function(c, value) -- return c.screen == value @@ -313,6 +315,7 @@ end -- the context of a rule. -- -- @method add_property_setter +-- @noreturn -- @tparam string name The property name. -- @tparam function f The setter function. function matcher:add_property_setter(name, f) @@ -472,6 +475,7 @@ end -- -- @param o The object. -- @method apply +-- @noreturn function matcher:apply(o) local callbacks, props = {}, {} for _, v in ipairs(self._matching_source) do @@ -514,6 +518,7 @@ end -- @tparam string source The source name. -- @tparam table rule A valid rule. -- @method append_rule +-- @noreturn function matcher:append_rule(source, rule) if not self._matching_rules[source] then self:add_matching_rules(source, {}, {}, {}) @@ -526,6 +531,7 @@ end -- @tparam string source The source name. -- @tparam table rules A table with rules. -- @method append_rules +-- @noreturn function matcher:append_rules(source, rules) for _, rule in ipairs(rules) do self:append_rule(source, rule) diff --git a/lib/gears/object.lua b/lib/gears/object.lua index b9b381c5c..35beeb223 100644 --- a/lib/gears/object.lua +++ b/lib/gears/object.lua @@ -52,6 +52,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method connect_signal +-- @noreturn function object:connect_signal(name, func) assert(type(func) == "function", "callback must be a function, got: " .. type(func)) local sig = find_signal(self, name) @@ -105,6 +106,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method weak_connect_signal +-- @noreturn 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) @@ -116,6 +118,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback that should be disconnected. -- @method disconnect_signal +-- @noreturn function object:disconnect_signal(name, func) local sig = find_signal(self, name) sig.weak[func] = nil @@ -129,6 +132,7 @@ end -- function receives the object as first argument and then any extra -- arguments that are given to emit_signal() -- @method emit_signal +-- @noreturn function object:emit_signal(name, ...) local sig = find_signal(self, name) for func in pairs(sig.strong) do diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index b78c733c1..8b7fbea8a 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -74,7 +74,9 @@ local module = {} -- @tparam boolean br If the bottom right corner is rounded -- @tparam boolean bl If the bottom left corner is rounded -- @tparam number rate The "squareness" of the squircle, should be greater than 1 --- @tparam number delta The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not +-- @tparam number delta The "smoothness" of the shape, delta must be greate +-- than 0.01 and will be reset to 0.01 if not +-- @noreturn -- @staticfct gears.shape.partial_squircle function module.partial_squircle(cr, width, height, tl, tr, br, bl, rate, delta) -- rate ~ 2 can be used by icon @@ -167,7 +169,9 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam number rate The "squareness" of the squircle, should be greater than 1 --- @tparam number delta The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not +-- @tparam number delta The "smoothness" of the shape, delta must be greater +-- than 0.01 and will be reset to 0.01 if not +-- @noreturn -- @staticfct gears.shape.squircle function module.squircle(cr, width, height, rate, delta) module.partial_squircle(cr, width, height, true, true, true, true, rate, delta) @@ -182,6 +186,7 @@ end -- @tparam number width The width constraint -- @tparam number height The height constraint -- @tparam number n Number of grams (default n = 5 -> pentagram) +-- @noreturn -- @staticfct gears.shape.star function module.star(cr, width, height, n) -- use the minimum as size @@ -216,6 +221,7 @@ end -- @tparam number width The rectangle width -- @tparam number height The rectangle height -- @tparam number radius The corner radius +-- @noreturn -- @staticfct gears.shape.rounded_rect function module.rounded_rect(cr, width, height, radius) @@ -246,6 +252,7 @@ end -- @param cr A cairo content -- @param width The rectangle width -- @param height The rectangle height. +-- @noreturn -- @staticfct gears.shape.rounded_bar function module.rounded_bar(cr, width, height) module.rounded_rect(cr, width, height, height / 2) @@ -263,6 +270,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 +-- @noreturn -- @staticfct gears.shape.partially_rounded_rect function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad) rad = rad or 10 @@ -319,6 +327,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 +-- @noreturn -- @staticfct gears.shape.infobubble function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position) arrow_size = arrow_size or 10 @@ -353,6 +362,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 +-- @noreturn -- @staticfct gears.shape.rectangular_tag function module.rectangular_tag(cr, width, height, arrow_length) arrow_length = arrow_length or height/2 @@ -383,6 +393,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) +-- @noreturn -- @staticfct gears.shape.arrow function module.arrow(cr, width, height, head_width, shaft_width, shaft_length) shaft_length = shaft_length or height / 2 @@ -408,6 +419,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.hexagon function module.hexagon(cr, width, height) cr:move_to(height/2,0) @@ -428,6 +440,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 +-- @noreturn -- @staticfct gears.shape.powerline function module.powerline(cr, width, height, arrow_depth) arrow_depth = arrow_depth or height/2 @@ -456,6 +469,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.isosceles_triangle function module.isosceles_triangle(cr, width, height) cr:move_to( width/2, 0 ) @@ -472,6 +486,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=width/3] number thickness The cross section thickness +-- @noreturn -- @staticfct gears.shape.cross function module.cross(cr, width, height, thickness) thickness = thickness or width/3 @@ -500,6 +515,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam number corner_radius +-- @noreturn -- @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) @@ -524,6 +540,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 +-- @noreturn -- @staticfct gears.shape.circle function module.circle(cr, width, height, radius) radius = radius or math.min(width, height) / 2 @@ -539,6 +556,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.rectangle function module.rectangle(cr, width, height) cr:rectangle(0, 0, width, height) @@ -553,6 +571,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 +-- @noreturn -- @staticfct gears.shape.parallelogram function module.parallelogram(cr, width, height, base_width) base_width = base_width or width/3 @@ -570,6 +589,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.losange function module.losange(cr, width, height) cr:move_to(width/2 , 0 ) @@ -591,6 +611,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 +-- @noreturn -- @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) @@ -629,6 +650,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 +-- @noreturn -- @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 @@ -752,6 +774,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 +-- @noreturn -- @staticfct gears.shape.radial_progress function module.radial_progress(cr, w, h, percent, hide_left) percent = percent or 1 diff --git a/lib/gears/sort/topological.lua b/lib/gears/sort/topological.lua index 8064e40cb..e11e89e2a 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`. +-- @noreturn -- @method append function tsort:append(node, dependencies) add_node(self, node) @@ -30,6 +31,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`. +-- @noreturn -- @method prepend function tsort:prepend(node, subordinates) for _, dep in ipairs(subordinates) do @@ -65,6 +67,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. +-- @treturn gears.sort.topological The cloned sorter object. -- @method clone function tsort:clone() local new = tsort.topological() @@ -78,6 +81,7 @@ end --- Remove a node from the topological map. -- -- @param node The node +-- @noreturn -- @method remove function tsort:remove(node) self._edges[node] = nil diff --git a/lib/gears/string.lua b/lib/gears/string.lua index 229ed810b..722c66ad5 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -74,6 +74,7 @@ end --- Generate a pattern matching expression that ignores case. -- @tparam string q Original pattern matching expression. +-- @treturn string The pattern. -- @staticfct gears.string.query_to_pattern function gstring.query_to_pattern(q) local s = gstring.quote_pattern(q) diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index 3bf983571..21b4e1531 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -201,6 +201,7 @@ end -- @tparam gears.shape|function shape The shape. -- @param[opt] ... Any additional parameters will be passed to the shape function. -- @staticfct apply_shape_bounding +-- @noreturn function surface.apply_shape_bounding(draw, shape, ...) local geo = draw:geometry() diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index c27ef6480..0c50c954b 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -91,6 +91,7 @@ local timer = { mt = {} } --- Start the timer. -- @method start +-- @noreturn -- @emits start function timer:start() if self.data.source_id ~= nil then @@ -110,6 +111,7 @@ end -- Does nothing if the timer isn't running. -- -- @method stop +-- @noreturn -- @emits stop function timer:stop() if self.data.source_id == nil then @@ -124,6 +126,7 @@ end -- This is equivalent to stopping the timer if it is running and then starting -- it. -- @method again +-- @noreturn -- @emits start -- @emits stop function timer:again() @@ -269,6 +272,7 @@ local delayed_calls = {} -- all, because it means that less batching happens and the delayed calls run -- prematurely. -- @staticfct gears.timer.run_delayed_calls_now +-- @noreturn function timer.run_delayed_calls_now() for _, callback in ipairs(delayed_calls) do protected_call(unpack(callback)) @@ -278,7 +282,8 @@ end --- Call the given function at the end of the current GLib event loop iteration. -- @tparam function callback The function that should be called ---@param ... Arguments to the callback function +-- @param ... Arguments to the callback function +-- @noreturn -- @staticfct gears.timer.delayed_call function timer.delayed_call(callback, ...) assert(type(callback) == "function", "callback must be a function, got: " .. type(callback)) diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index e594fafd1..337483892 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -395,7 +395,8 @@ local function menulist_update(scr) end --- Refresh menubar's cache by reloading .desktop files. --- @tparam[opt] screen scr Screen. +-- @tparam[opt=awful.screen.focused()] screen scr Screen. +-- @noreturn -- @staticfct menubar.refresh function menubar.refresh(scr) scr = get_screen(scr or awful.screen.focused() or 1) @@ -452,7 +453,8 @@ local function prompt_keypressed_callback(mod, key, comm) end --- Show the menubar on the given screen. --- @param[opt] scr Screen. +-- @tparam[opt=awful.screen.focused()] screen scr Screen. +-- @noreturn -- @staticfct menubar.show -- @usebeautiful beautiful.menubar_fg_normal -- @usebeautiful beautiful.menubar_bg_normal diff --git a/lib/menubar/menu_gen.lua b/lib/menubar/menu_gen.lua index 19fb6e735..193eef1c5 100644 --- a/lib/menubar/menu_gen.lua +++ b/lib/menubar/menu_gen.lua @@ -57,8 +57,7 @@ menu_gen.all_categories = { icon_name = "applications-accessories", use = true } } ---- Find icons for category entries. --- @staticfct menubar.menu_gen.lookup_category_icons +-- Find icons for category entries. function menu_gen.lookup_category_icons() for _, v in pairs(menu_gen.all_categories) do v.icon = utils.lookup_icon(v.icon_name) @@ -81,6 +80,7 @@ end -- with the resulting list of menu entries as argument. -- @tparam table callback.entries All menu entries. -- @staticfct menubar.menu_gen.generate +-- @noreturn 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 a3f1e1945..77945a398 100644 --- a/lib/menubar/utils.lua +++ b/lib/menubar/utils.lua @@ -201,6 +201,7 @@ end --- Remove CR newline from the end of the string. -- @tparam string s The string to trim -- @staticfct menubar.utils.rtrim +-- @treturn string The trimmed string. function utils.rtrim(s) if not s then return end if string.byte(s, #s) == 13 then @@ -357,6 +358,7 @@ end -- with the resulting list of menu entries as argument. -- @tparam table callback.programs Paths of found .desktop files. -- @staticfct menubar.utils.parse_dir +-- @noreturn function utils.parse_dir(dir_path, callback) local function get_readable_path(file) diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index a9576c8b3..f88c84869 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -120,6 +120,7 @@ end -- the action was invoked. If a notification is shared by many object (like -- a "mute" or "snooze" action added to all notification), calling `:invoke()` -- without adding the `notif` context will cause unexpected results. +-- @noreturn function action:invoke(notif) self:emit_signal("invoked", notif) end diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index a2e9e02d1..a3da5e5c3 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -498,6 +498,7 @@ end --- Set new notification timeout. -- @method reset_timeout -- @tparam number new_timeout Time in seconds after which notification disappears. +-- @noreturn function notification:reset_timeout(new_timeout) if self.timer then self.timer:stop() end @@ -793,6 +794,7 @@ end --- Add more actions to the notification. -- @method append_actions -- @tparam table new_actions +-- @noreturn function notification:append_actions(new_actions) self._private.actions = self._private.actions or {} @@ -1062,6 +1064,7 @@ end -- @method grant -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions --- Deny a permission for a notification @@ -1069,6 +1072,7 @@ end -- @method deny -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions pcommon.setup_grant(notification, "notification") diff --git a/lib/ruled/client.lua b/lib/ruled/client.lua index 98e0fe0cb..0ac6f049d 100644 --- a/lib/ruled/client.lua +++ b/lib/ruled/client.lua @@ -180,9 +180,10 @@ end --- Apply ruled.client.rules to a client. -- @tparam client c The client. +-- @noreturn -- @staticfct ruled.client.apply function module.apply(c) - return crules:apply(c) + crules:apply(c) end --- Add a new rule to the default set. @@ -527,7 +528,8 @@ end --- Apply properties and callbacks to a client. -- @tparam client c The client. -- @tparam table props Properties to apply. --- @tparam[opt] table callbacks Callbacks to apply. +-- @tparam[opt={}] table callbacks Callbacks to apply. +-- @noreturn -- @staticfct ruled.client.execute -- @request client titlebars rules granted The `titlebars_enabled` is set in the -- rules. diff --git a/lib/ruled/notification.lua b/lib/ruled/notification.lua index 55e8905ea..6203cb3b6 100644 --- a/lib/ruled/notification.lua +++ b/lib/ruled/notification.lua @@ -158,6 +158,7 @@ end -- -- @tparam naughty.notification n The notification. -- @staticfct ruled.notification.apply +-- @noreturn function module.apply(n) local callbacks, props = {}, {} @@ -179,6 +180,7 @@ end --- Add a new rule to the default set. -- @tparam table rule A valid rule. -- @staticfct ruled.notification.append_rule +-- @noreturn function module.append_rule(rule) nrules:append_rule("ruled.notifications", rule) end @@ -186,16 +188,20 @@ end --- Add a new rules to the default set. -- @tparam table rule A table with rules. -- @staticfct ruled.notification.append_rules +-- @noreturn function module.append_rules(rules) nrules:append_rules("ruled.notifications", rules) end --- Remove a new rule to the default set. -- @tparam table rule A valid rule. +-- @treturn boolean `true` if the rule was removed. -- @staticfct ruled.notification.remove_rule function module.remove_rule(rule) - nrules:remove_rule("ruled.notifications", rule) + local ret = nrules:remove_rule("ruled.notifications", rule) module.emit_signal("rule::removed", rule) + + return ret end --- Add a new rule source. diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index 95b07df86..261539237 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -217,6 +217,7 @@ end --- Reset this layout. The widget will be removed and the rotation reset. -- @method reset +-- @noreturn -- @interface container function arcchart:reset() self:set_widget(nil) diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index 384ae7efd..cada81e29 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -316,6 +316,7 @@ end -- -- @method set_shape -- @tparam gears.shape|function shape A function taking a context, width and height as arguments +-- @noreturn -- @propemits true false -- @see gears.shape -- @see shape diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index 62c051f01..7f4661e83 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -135,6 +135,7 @@ end -- and the constraints set to nil. -- -- @method reset +-- @noreturn -- @interface container function constraint:reset() self._private.width = nil diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index 1c8bd90a0..eb8ff267a 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -159,6 +159,7 @@ end --- Reset this layout. The widget will be unreferenced, the margins set to 0 -- and the color erased -- @method reset +-- @noreturn -- @interface container function margin:reset() self:set_widget(nil) diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua index 288308823..d21724f30 100644 --- a/lib/wibox/container/mirror.lua +++ b/lib/wibox/container/mirror.lua @@ -70,6 +70,7 @@ end --- Reset this layout. The widget will be removed and the axes reset. -- -- @method reset +-- @noreturn -- @interface container function mirror:reset() self._private.horizontal = false diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua index 7fd6a8091..352f2c18f 100644 --- a/lib/wibox/container/place.lua +++ b/lib/wibox/container/place.lua @@ -94,6 +94,7 @@ end --- Reset this layout. The widget will be removed and the rotation reset. -- @method reset +-- @noreturn -- @interface container function place:reset() self:set_widget(nil) diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index ac458e9c0..a9effcd78 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -148,6 +148,7 @@ end --- Reset this container. -- -- @method reset +-- @noreturn -- @interface container function radialprogressbar:reset() self:set_widget(nil) diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index fedc8e4f9..c4da7cd0a 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -84,6 +84,7 @@ end -- The widget will be removed and the rotation reset. -- -- @method reset +-- @noreturn -- @interface container function rotate:reset() self._private.direction = nil diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua index 46f928229..c520b443c 100644 --- a/lib/wibox/container/scroll.lua +++ b/lib/wibox/container/scroll.lua @@ -222,6 +222,7 @@ end --- Pause the scrolling animation. -- @method pause +-- @noreturn -- @see continue function scroll:pause() if self._private.paused then @@ -233,6 +234,7 @@ end --- Continue the scrolling animation. -- @method continue +-- @noreturn -- @see pause function scroll:continue() if not self._private.paused then @@ -248,6 +250,7 @@ end -- display the widget without any scrolling applied. -- This function does not undo the effect of @{pause}. -- @method reset_scrolling +-- @noreturn function scroll:reset_scrolling() self._private.timer:start() if self._private.paused then @@ -258,6 +261,7 @@ end --- Set the direction in which this widget scroll. -- @method set_direction -- @param dir Either "h" for horizontal scrolling or "v" for vertical scrolling +-- @noreturn function scroll:set_direction(dir) if dir == self._private.dir then return @@ -306,6 +310,7 @@ end -- @method set_expand -- @tparam boolean expand If true, the widget is expanded to include the extra -- space. If false, the extra space is simply left empty. +-- @noreturn -- @see set_extra_space function scroll:set_expand(expand) if expand == self._private.expand then @@ -318,6 +323,7 @@ end --- Set the number of frames per second that this widget should draw. -- @method set_fps -- @tparam number fps The number of frames per second +-- @noreturn function scroll:set_fps(fps) if fps == self._private.fps then return @@ -331,6 +337,7 @@ end -- extra space will likely be left empty between repetitions of the widgets. -- @method set_extra_space -- @tparam number extra_space The amount of extra space +-- @noreturn -- @see set_expand function scroll:set_extra_space(extra_space) if extra_space == self._private.extra_space then @@ -345,6 +352,7 @@ end -- in pixels per second. -- @method set_speed -- @tparam number speed The speed for the animation +-- @noreturn function scroll:set_speed(speed) if speed == self._private.speed then return @@ -359,6 +367,7 @@ end -- and the rest is made visible via scrolling. -- @method set_max_size -- @tparam number max_size The maximum size of this widget or nil for unlimited. +-- @noreturn function scroll:set_max_size(max_size) if max_size == self._private.max_size then return @@ -384,6 +393,7 @@ end -- which the widget is drawn and should be between 0 and `size+extra_space`. -- @method set_step_function -- @tparam function step_function A step function. +-- @noreturn -- @see step_functions function scroll:set_step_function(step_function) -- Call the step functions once to see if it works @@ -399,6 +409,7 @@ end -- This restricts the child widget's maximal size. -- @method set_space_for_scrolling -- @tparam number space_for_scrolling The space for scrolling +-- @noreturn function scroll:set_space_for_scrolling(space_for_scrolling) if space_for_scrolling == self._private.space_for_scrolling then return diff --git a/lib/wibox/hierarchy.lua b/lib/wibox/hierarchy.lua index 3472716d1..13ec3e4e3 100644 --- a/lib/wibox/hierarchy.lua +++ b/lib/wibox/hierarchy.lua @@ -23,6 +23,7 @@ local widgets_to_count = setmetatable({}, { __mode = "k" }) -- visible in any hierarchy. -- @param widget The widget that should be counted. -- @staticfct wibox.hierarchy.count_widget +-- @noreturn function hierarchy.count_widget(widget) widgets_to_count[widget] = true end @@ -232,6 +233,7 @@ end --- Get the widget that this hierarchy manages. -- @method get_widget +-- @treturn wibox.widget The widget held by this node. function hierarchy:get_widget() return self._widget end @@ -318,6 +320,7 @@ end -- @param context The context in which widgets are drawn. -- @param cr The cairo context that is used for drawing. -- @method draw +-- @noreturn function hierarchy:draw(context, cr) local widget = self:get_widget() if not widget._private.visible then diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index ff458fe78..9715a93ee 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -103,6 +103,7 @@ end -- @tparam string path The path. -- @tparam[opt=nil] table context A widget context. -- @method save_to_svg +-- @noreturn function wibox:save_to_svg(path, context) wibox.widget.draw_to_svg_file( self:to_widget(), path, self:geometry().width, self:geometry().height, context @@ -404,6 +405,7 @@ end -- automatically called when needed. -- @param wibox -- @method draw +-- @noreturn --- Connect a global signal on the wibox class. -- @@ -416,6 +418,7 @@ end -- @tparam string name The name of the signal -- @tparam function func The function to attach -- @staticfct wibox.connect_signal +-- @noreturn -- @usage wibox.connect_signal("added", function(notif) -- -- do something -- end) @@ -424,6 +427,7 @@ end -- @tparam string name The signal name. -- @param ... The signal callback arguments -- @staticfct wibox.emit_signal +-- @noreturn --- Disconnect a signal from a source. -- @tparam string name The name of the signal diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index 5d4affcbf..e8e94743f 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -136,6 +136,7 @@ end -- -- @method add -- @tparam widget ... Widgets that should be added (must at least be one). +-- @noreturn -- @interface layout function fixed:add(...) -- No table.pack in Lua 5.1 :-( diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index 153629bae..a0c403e6c 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -48,6 +48,7 @@ local flex = {} -- -- @tparam widget ... Widgets that should be added (must at least be one). -- @method add +-- @noreturn -- @interface layout --- Remove a widget from the layout. diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index dc292ac22..e822ec81a 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -288,7 +288,9 @@ end -- The widgets are assumed to span one cell. -- -- @method add --- @param ... Widgets that should be added (must at least be one) +-- @tparam wibox.widget ... Widgets that should be added (must at least be one) +-- @interface layout +-- @noreturn function grid:add(...) local args = { n=select('#', ...), ... } assert(args.n > 0, "need at least one widget to add") @@ -863,6 +865,7 @@ end -- -- **Signal:** widget::reset -- @method reset +-- @noreturn function grid:reset() self._private.widgets = {} -- reset the number of columns and rows to the forced value or to 0 diff --git a/lib/wibox/layout/manual.lua b/lib/wibox/layout/manual.lua index eb2bdbdeb..e98458cd1 100644 --- a/lib/wibox/layout/manual.lua +++ b/lib/wibox/layout/manual.lua @@ -20,6 +20,8 @@ local manual_layout = {} -- -- @method add -- @tparam widget ... Widgets that should be added +-- @interface layout +-- @noreturn --- Remove a widget from the layout. -- @@ -166,6 +168,7 @@ end -- @tparam widget widget The widget. -- @tparam table|function point Either an `{x=x,y=y}` table or a function -- returning the new geometry. +-- @noreturn function manual_layout:add_at(widget, point) assert(not widget.point, "2 points are specified, only one is supported") @@ -189,6 +192,7 @@ end -- @method move -- @tparam number index The widget index. -- @tparam table|function point A new point value. +-- @noreturn -- @see add_at function manual_layout:move(index, point) assert(self._private.pos[index]) @@ -203,6 +207,7 @@ end -- @method move_widget -- @tparam widget widget The widget. -- @tparam table|function point A new point value. +-- @noreturn -- @see add_at function manual_layout:move_widget(widget, point) local idx, l = self:index(widget, false) diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua index ba73b4b22..bfc30d523 100644 --- a/lib/wibox/layout/ratio.lua +++ b/lib/wibox/layout/ratio.lua @@ -215,6 +215,7 @@ end -- @tparam number index The widget index to change -- @tparam number increment An floating point value between -1 and 1 where the -- end result is within 0 and 1 +-- @noreturn function ratio:inc_ratio(index, increment) if #self._private.widgets == 1 or (not index) or (not self._private.ratios[index]) or increment < -1 or increment > 1 then @@ -234,6 +235,7 @@ end -- @tparam widget widget The widget to adjust -- @tparam number increment An floating point value between -1 and 1 where the -- end result is within 0 and 1 +-- @noreturn function ratio:inc_widget_ratio(widget, increment) if not widget or not increment then return end @@ -247,6 +249,7 @@ end -- @method set_ratio -- @tparam number index The index of the widget to change -- @tparam number percent An floating point value between 0 and 1 +-- @noreturn function ratio:set_ratio(index, percent) if not percent or #self._private.widgets == 1 or not index or not self._private.widgets[index] or percent < 0 or percent > 1 then @@ -286,6 +289,7 @@ end -- @method set_widget_ratio -- @tparam widget widget The widget to adjust. -- @tparam number percent A floating point value between 0 and 1. +-- @noreturn function ratio:set_widget_ratio(widget, percent) local index = self:index(widget) @@ -302,6 +306,7 @@ end -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:adjust_ratio(index, before, itself, after) if not self._private.widgets[index] or not before or not itself or not after then return @@ -342,19 +347,15 @@ end -- @see wibox.layout.ratio.adjust_ratio -- @deprecated wibox.layout.ratio.ajust_ratio -- @tparam number index The index of the widget to change --- @tparam number index The index of the widget to change --- @tparam number before The sum of the ratio before the widget -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" --- @tparam number itself The ratio for "widget" --- @tparam number after The sum of the ratio after the widget -- @tparam number after The sum of the ratio after the widget function ratio:ajust_ratio(...) require('gears.debug').deprecate( "Use `:adjust_ratio` rather than `:ajust_ratio`", { deprecated_in = 5 } ) - return self:adjust_ratio(...) + self:adjust_ratio(...) end --- Update all widgets to match a set of a ratio. @@ -364,6 +365,7 @@ end -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:adjust_widget_ratio(widget, before, itself, after) local index = self:index(widget) self:adjust_ratio(index, before, itself, after) @@ -375,11 +377,9 @@ end -- @deprecated wibox.layout.ratio.ajust_widget_ratio -- @tparam widget widget The widget to adjust -- @tparam number before The sum of the ratio before the widget --- @tparam number before The sum of the ratio before the widget --- @tparam number itself The ratio for "widget" -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget --- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:ajust_widget_ratio(...) require('gears.debug').deprecate( "Use `:adjust_widget_ratio` rather than `:ajust_widget_ratio`", @@ -392,6 +392,7 @@ end -- -- @method add -- @tparam widget ... Widgets that should be added (must at least be one) +-- @noreturn -- @emits widget::added All new widgets are passed in the parameters. -- @emitstparam widget::added widget self The layout. function ratio:add(...) @@ -439,6 +440,8 @@ end -- @method insert -- @tparam number index The position. -- @tparam widget widget The widget. +-- @treturn boolean `true` if the widget was inserted and `false` if the index +-- is invalid. -- @emits widget::inserted -- @emitstparam widget::inserted widget self The ratio layout. -- @emitstparam widget::inserted widget widget index The inserted widget. @@ -454,6 +457,8 @@ function ratio:insert(index, widget) self:emit_signal("widget::layout_changed") self:emit_signal("widget::inserted", widget, #self._private.widgets) + + return true end --- Set how the space of invisible or `0x0` sized widget is redistributed. diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index f89b2c515..962127f67 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -26,6 +26,7 @@ local stack = {mt={}} --- Add some widgets to the given stack layout. -- -- @tparam widget ... Widgets that should be added (must at least be one) +-- @noreturn -- @method add -- @interface layout @@ -116,6 +117,7 @@ end -- -- @method raise -- @tparam number index The widget index to raise +-- @noreturn function stack:raise(index) if (not index) or (not self._private.widgets[index]) then return end @@ -132,6 +134,7 @@ end -- @tparam widget widget The widget to raise -- @tparam[opt=false] boolean recursive Also look deeper in the hierarchy to -- find the widget +-- @noreturn function stack:raise_widget(widget, recursive) local idx, layout = self:index(widget, recursive) diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index 1cae73bc0..82759442f 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -225,6 +225,7 @@ end --- Add a new `awful.button` to this widget. -- @tparam awful.button button The button to add. -- @method wibox.widget.base:add_button +-- @noreturn function base.widget:add_button(button) if not button then return end @@ -412,6 +413,7 @@ end -- @tparam string signal_name -- @param ... Other arguments -- @method wibox.widget.base:emit_signal_recursive +-- @noreturn function base.widget:emit_signal_recursive(signal_name, ...) -- This is a convenience wrapper, the real implementation is in the -- hierarchy. @@ -500,6 +502,15 @@ end -- This gives only tight bounds if no rotations by non-multiples of 90° are -- used. -- @staticfct wibox.widget.base.rect_to_device_geometry +-- @param cr The cairo context. +-- @tparam number x The `x` value. +-- @tparam number y The `y` value. +-- @tparam number width The `width` value. +-- @tparam number height The `height` value. +-- @treturn number The new `x` value. +-- @treturn number The new `y` value. +-- @treturn number The new `width` value. +-- @treturn number The new `height` value. function base.rect_to_device_geometry(cr, x, y, width, height) return matrix.transform_rectangle(cr.matrix, x, y, width, height) end @@ -585,6 +596,7 @@ end -- -- This is used internally and should not be called directly. -- @staticfct wibox.widget.base.handle_button +-- @noreturn function base.handle_button(event, widget, x, y, button, modifiers, geometry) x = x or y -- luacheck: no unused local function is_any(mod) @@ -997,6 +1009,7 @@ end -- -- This function raises an error if the widget is not valid. -- @staticfct wibox.widget.base.check_widget +-- @noreturn 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/graph.lua b/lib/wibox/widget/graph.lua index 9d8e1cb7f..76795ce3e 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -672,6 +672,7 @@ end -- -- @method compute_drawn_values_num -- @tparam number usable_width +-- @treturn number The number of values. function graph:compute_drawn_values_num(usable_width) if usable_width <= 0 then return 0 @@ -718,6 +719,7 @@ end -- @method add_value -- @tparam[opt=NaN] number value The value to be added to a graph's data group. -- @tparam[opt=1] integer group The index of the data group. +-- @noreturn Note that it actually returns something, but that's better undocumented. function graph:add_value(value, group) value = value or 0/0 -- default to NaN group = group or 1 @@ -762,6 +764,7 @@ end -- Removes all values from all data groups. -- -- @method clear +-- @noreturn Note that it actually returns something, but that's better undocumented. function graph:clear() self._private.values = {} self:emit_signal("widget::redraw_needed") diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index 26afbda31..b96caac7f 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -41,6 +41,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. +-- @noreturn -- @staticfct wibox.widget.draw_to_cairo_context function widget.draw_to_cairo_context(wdg, cr, width, height, context) local function no_op() end @@ -55,6 +56,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. +-- @noreturn -- @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) diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 61a04295d..6d3776831 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -114,6 +114,7 @@ end --- Force a textclock to update now. -- +-- @noreturn -- @method force_update function textclock:force_update() self._timer:emit_signal("timeout") diff --git a/luaa.c b/luaa.c index 2dbd3ac5f..bf1800ce9 100644 --- a/luaa.c +++ b/luaa.c @@ -36,6 +36,7 @@ * * @tparam string name The name of the X11 property. * @tparam string type One of "string", "number" or "boolean". + * @noreturn * @staticfct register_xproperty */ @@ -229,6 +230,7 @@ composite_manager_running(void) /** Quit awesome. * @tparam[opt=0] integer code The exit code to use when exiting. * @staticfct quit + * @noreturn */ static int luaA_quit(lua_State *L) @@ -246,6 +248,7 @@ luaA_quit(lua_State *L) * * @tparam string cmd The command line to execute. * @staticfct exec + * @noreturn */ static int luaA_exec(lua_State *L) @@ -260,6 +263,7 @@ luaA_exec(lua_State *L) /** Restart awesome. * @staticfct restart + * @noreturn */ static int luaA_restart(lua_State *L) @@ -290,6 +294,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. * @staticfct sync + * @noreturn */ static int luaA_sync(lua_State *L) @@ -352,6 +357,7 @@ luaA_load_image(lua_State *L) * * @tparam integer size The size of the icons in pixels. * @staticfct set_preferred_icon_size + * @noreturn */ static int luaA_set_preferred_icon_size(lua_State *L) @@ -808,6 +814,7 @@ luaA_awesome_index(lua_State *L) * @tparam string name A string with the event name. * @tparam function func The function to call. * @staticfct connect_signal + * @noreturn */ static int luaA_awesome_connect_signal(lua_State *L) @@ -823,6 +830,7 @@ luaA_awesome_connect_signal(lua_State *L) * @tparam string name A string with the event name. * @tparam function func The function to call. * @staticfct disconnect_signal + * @noreturn */ static int luaA_awesome_disconnect_signal(lua_State *L) @@ -840,6 +848,7 @@ luaA_awesome_disconnect_signal(lua_State *L) * @tparam function name A string with the event name. * @param ... The signal arguments. * @staticfct emit_signal + * @noreturn */ static int luaA_awesome_emit_signal(lua_State *L) diff --git a/mousegrabber.c b/mousegrabber.c index f048d5d22..35bbeb520 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -87,8 +87,9 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask) *@DOC_cursor_c_COMMON@ * * - * @param func A callback function as described above. - * @param cursor The name of a X cursor to use while grabbing. + * @tparam function func A callback function as described above. + * @tparam string cursor The name of a X cursor to use while grabbing. + * @noreturn * @staticfct run */ static int @@ -120,6 +121,7 @@ luaA_mousegrabber_run(lua_State *L) /** Stop grabbing the mouse pointer. * * @staticfct stop + * @noreturn */ int luaA_mousegrabber_stop(lua_State *L) diff --git a/objects/client.c b/objects/client.c index 74bb0d6fc..8b35b7d97 100644 --- a/objects/client.c +++ b/objects/client.c @@ -3191,6 +3191,7 @@ out: * @DOC_sequences_client_kill1_EXAMPLE@ * * @method kill + * @noreturn * @see awesome.kill */ static int @@ -3206,6 +3207,7 @@ luaA_client_kill(lua_State *L) * @DOC_sequences_client_swap1_EXAMPLE@ * * @tparam client c A client to swap with. + * @noreturn * @method swap * @emits swapped * @emitstparam swapped client other The other client. @@ -3338,6 +3340,7 @@ luaA_client_get_first_tag(lua_State *L, client_t *c) /** Raise a client on top of others which are on the same layer. * * @method raise + * @noreturn * @emits raised * @see above * @see below @@ -3364,6 +3367,7 @@ luaA_client_raise(lua_State *L) /** Lower a client on bottom of others which are on the same layer. * * @method lower + * @noreturn * @emits lowered * @see above * @see below @@ -3396,6 +3400,7 @@ luaA_client_lower(lua_State *L) /** Stop managing a client. * * @method unmanage + * @noreturn */ static int luaA_client_unmanage(lua_State *L) diff --git a/objects/drawable.c b/objects/drawable.c index d404b7a46..a26abedd5 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -35,8 +35,8 @@ /** Drawable object. * - * @field surface The drawable's cairo surface. - * @staticfct drawable + * @property surface The drawable's cairo surface. + * @tparam gears.surface surface */ /** @@ -89,12 +89,12 @@ * @staticfct instances */ -/** Set a __index metamethod for all drawable instances. +/* Set a __index metamethod for all drawable instances. * @tparam function cb The meta-method * @staticfct set_index_miss_handler */ -/** Set a __newindex metamethod for all drawable instances. +/* Set a __newindex metamethod for all drawable instances. * @tparam function cb The meta-method * @staticfct set_newindex_miss_handler */ @@ -186,6 +186,7 @@ luaA_drawable_get_surface(lua_State *L, drawable_t *drawable) * the drawable's surface has been done and should become visible. * * @method refresh + * @noreturn */ static int luaA_drawable_refresh(lua_State *L) diff --git a/objects/screen.c b/objects/screen.c index 9582671e1..b72aab97e 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -1564,6 +1564,7 @@ luaA_screen_module_newindex(lua_State *L) * for s in screen do * print("Oh, wow, we have screen " .. tostring(s)) * end + * @treturn function A lua iterator function. * @staticfct screen */ static int @@ -1725,6 +1726,7 @@ luaA_screen_fake_add(lua_State *L) * @DOC_sequences_screen_fake_remove_EXAMPLE@ * * @method fake_remove + * @noreturn */ static int luaA_screen_fake_remove(lua_State *L) @@ -1763,6 +1765,7 @@ luaA_screen_fake_remove(lua_State *L) * @tparam integer width The new width for screen. * @tparam integer height The new height for screen. * @method fake_resize + * @noreturn * @see split * @see geometry */ @@ -1800,6 +1803,7 @@ luaA_screen_fake_resize(lua_State *L) * * @tparam client s A screen to swap with. * @method swap + * @noreturn */ static int luaA_screen_swap(lua_State *L) diff --git a/root.c b/root.c index a159cc15c..94f04977b 100644 --- a/root.c +++ b/root.c @@ -280,6 +280,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. + * @noreturn * @staticfct fake_input */ static int @@ -437,6 +438,7 @@ luaA_root_buttons(lua_State *L) *@DOC_cursor_c_COMMON@ * * @tparam string cursor_name A X cursor name. + * @noreturn * @staticfct cursor */ static int diff --git a/tests/examples/awful/placement/center_vertical.lua b/tests/examples/awful/placement/center_vertical.lua index 0817921df..23658e9f7 100644 --- a/tests/examples/awful/placement/center_vertical.lua +++ b/tests/examples/awful/placement/center_vertical.lua @@ -2,6 +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 +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.center_vertical --DOC_HEADER require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_horizontally.lua b/tests/examples/awful/placement/maximize_horizontally.lua index 7fad3db57..4b7698c8d 100644 --- a/tests/examples/awful/placement/maximize_horizontally.lua +++ b/tests/examples/awful/placement/maximize_horizontally.lua @@ -2,6 +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 +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.maximize_horizontally --DOC_HEADER require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_vertically.lua b/tests/examples/awful/placement/maximize_vertically.lua index e5011b56a..9bdef475f 100644 --- a/tests/examples/awful/placement/maximize_vertically.lua +++ b/tests/examples/awful/placement/maximize_vertically.lua @@ -2,6 +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 +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.maximize_vertically --DOC_HEADER require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE diff --git a/xkb.c b/xkb.c index 44d1bb8b7..0ab49a541 100644 --- a/xkb.c +++ b/xkb.c @@ -38,6 +38,7 @@ * * @staticfct xkb_set_layout_group * @tparam integer num Keyboard layout number, integer from 0 to 3 + * @noreturn */ int luaA_xkb_set_layout_group(lua_State *L)