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.
2022-07-05 01:37:14 -07:00 · 2022-07-05 01:37:14 -07:00 · 86d1b1c22c
parent 3510d96d6c
commit 86d1b1c22c
81 changed files with 367 additions and 53 deletions
--- 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
 */

 /*
--- 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
--- 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
--- 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.
--- 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.
 --
--- 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()`
--- 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 .. "</span>"
+    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
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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 {}

--- 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
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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,
--- 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
--- 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)
--- 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, ...)
--- 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.
--- 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)
--- 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.
--- 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
--- 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.
--- 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.
--- 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
--- 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)
--- 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)
--- 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
--- 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.
--- 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)
--- 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
--- 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
--- 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
--- 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)
--- 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()

--- 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))
--- 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
--- 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()
--- 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)
--- 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
--- 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")
--- 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.
--- 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.
--- 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)
--- 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
--- 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
--- 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)
--- 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
--- 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)
--- 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)
--- 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
--- 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
--- 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
--- 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
--- 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 :-(
--- 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.
--- 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
--- 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)
--- 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.
--- 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)

--- 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!")
--- 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")
--- 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)
--- 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")
--- 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)
--- 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)
--- 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)
--- 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)
--- 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)
--- 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
--- 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
--- 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
--- 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
--- 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)