doc: Use an explicit @method stereotype for all methods.

ldoc has a magical `@classmod` module type which tries to detect
what is a method and what is a static function. It fails about as
often as it works. This commit makes everything explicit to remove
such issues.

Fixes #2640
Ref #1373

docs/common/fixed.ldoc

@@ -4,8 +4,7 @@
 -- @tparam number index A widget or a widget index
 -- @param widget2 The widget to take the place of the first one
 -- @treturn boolean If the operation is successful
--- @name set
+-- @method set
--- @class function
 
 --- Replace the first instance of `widget` in the layout with `widget2`.
 -- **Signal:** widget::replaced The argument is the new widget and the old one
@@ -14,16 +13,14 @@
 -- @param widget2 The widget to replace `widget` with
 -- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
 -- @treturn boolean If the operation is successful
--- @name replace_widget
+-- @method replace_widget
--- @class function
 
 --- Swap 2 widgets in a layout.
 -- **Signal:** widget::swapped The arguments are both widgets and both (new) indexes.
 -- @tparam number index1 The first widget index
 -- @tparam number index2 The second widget index
 -- @treturn boolean If the operation is successful
--- @name swap
+-- @method swap
--- @class function
 
 --- Swap 2 widgets in a layout.
 -- If widget1 is present multiple time, only the first instance is swapped
@@ -33,8 +30,7 @@
 -- @param widget2 The second widget
 -- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
 -- @treturn boolean If the operation is successful
--- @name swap_widgets
+-- @method swap_widgets
--- @class function
 
 --- Get all direct children of this layout.
 -- @param layout The layout you are modifying.
@@ -43,5 +39,4 @@
 --- Reset a ratio layout. This removes all widgets from the layout.
 -- **Signal:** widget::reset
 -- @param layout The layout you are modifying.
--- @name reset
+-- @method reset
--- @class function

docs/common/object.ldoc

@@ -2,7 +2,7 @@
 --- Disconnect from a signal.
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback that should be disconnected.
--- @function disconnect_signal
+-- @method disconnect_signal
 
 --- Emit a signal.
 --
@@ -10,12 +10,12 @@
 -- @param ... Extra arguments for the callback functions. Each connected
 --   function receives the object as first argument and then any extra
 --   arguments that are given to emit_signal().
--- @function emit_signal
+-- @method emit_signal
 
 --- Connect to a signal.
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback to call when the signal is emitted.
--- @function connect_signal
+-- @method connect_signal
 
 --- Connect to a signal weakly.
 --
@@ -27,4 +27,4 @@
 -- are doing.
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback to call when the signal is emitted.
--- @function weak_connect_signal
+-- @method weak_connect_signal

docs/common/wibox.ldoc

@@ -199,20 +199,20 @@
 --- Get or set mouse buttons bindings to a wibox.
 --
 -- @param buttons_table A table of buttons objects, or nothing.
--- @function buttons
+-- @method buttons
 
 --- Get or set wibox geometry. That's the same as accessing or setting the x,
 -- y, width or height properties of a wibox.
 --
 -- @param A table with coordinates to modify.
 -- @return A table with wibox coordinates and geometry.
--- @function geometry
+-- @method geometry
 
 --- Get or set wibox struts.
 --
 -- @param strut A table with new strut, or nothing
 -- @return The wibox strut in a table.
--- @function struts
+-- @method struts
 -- @see client.struts
 
 --- The default background color.
@@ -226,8 +226,7 @@
 --- Set a declarative widget hierarchy description.
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
 -- @param args An array containing the widgets disposition
--- @name setup
+-- @method setup
--- @class function
 
 --- The background of the wibox.
 -- @param c The background to use. This must either be a cairo pattern object,
@@ -255,5 +254,4 @@
 -- @treturn table A sorted table of widgets positions. The first element is the biggest
 -- container while the last is the topmost widget. The table contains *x*, *y*,
 -- *width*, *height* and *widget*.
--- @name find_widgets
+-- @method find_widgets
--- @class function

docs/common/widget.ldoc

@@ -6,19 +6,23 @@
 -- @return The index
 -- @return The parent layout
 -- @return The path between self and widget
--- @function index
+-- @method index
+
+--- Get or set the children elements.
+-- @property children
+-- @tparam table The children
 
 --- Get all direct and indirect children widgets.
 -- This will scan all containers recursively to find widgets
 -- Warning: This method it prone to stack overflow id the widget, or any of its
 -- children, contain (directly or indirectly) itself.
--- @treturn table The children
+-- @property all_children
--- @function get_all_children
+-- @tparam table The children
 
 --- Set a declarative widget hierarchy description.
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
 -- @param args An array containing the widgets disposition
--- @function setup
+-- @method setup
 
 --- Force a widget height.
 -- @property forced_height
@@ -38,14 +42,14 @@
 
 --- Set/get a widget's buttons.
 -- @param _buttons The table of buttons that should bind to the widget.
--- @function buttons
+-- @method buttons
 
 --- Emit a signal and ensure all parent widgets in the hierarchies also
 -- forward the signal. This is useful to track signals when there is a dynamic
 -- set of containers and layouts wrapping the widget.
 -- @tparam string signal_name
 -- @param ... Other arguments
--- @function emit_signal_recursive
+-- @method emit_signal_recursive
 
 --- When the layout (size) change.
 -- This signal is emitted when the previous results of `:layout()` and `:fit()`

docs/config.ld

@@ -52,12 +52,16 @@ tparam_alias('tab', 'table')
 tparam_alias('screen', 'screen')
 tparam_alias('screen_or_idx', 'screen|int')
 
--- Hack to get the functions and method on top of the signals and properties
+-- Hack to get the functions on top of the signals and properties
 new_type("function", "Functions", false, "Parameters")
 -- Documentation for objects properties
 new_type("property", "Object properties", false, "Type")
 -- Documentation for objects deprecated properties
 new_type("deprecatedproperty", "Deprecated object properties", false, "Type")
+-- Use a custom type for the methods to bypass the faulty ldoc built-in detection.
+-- (yes, the space after Methods *is* on purpose to avoid clashing with ldoc
+--  internal "methods" concept)
+new_type("method", "Object methods ", false, "Parameters")
 -- New type for signals
 new_type("signal", "Signals", false, "Arguments")
 -- New type for signals connections
@@ -155,6 +159,21 @@ file = {
     }
 }
 
+-- Mimics the ldoc built-in method style, but better.
+--
+-- This custom renderer exists because using ldoc built-in method detection
+-- turned out to be too unreliable and upstream is dead.
+local function render_methods(item)
+    local ret = item.name
+
+    -- Some methods will have it depending on the weather. Most wont.
+    if not ret:find(":") then
+        ret = ":"..ret
+    end
+
+    return ret .. (item.args and " "..item.args or "")
+end
+
 local no_prefix = {
     property = true, signal = true, clientruleproperty = true,
     deprecatedproperty = true,
@@ -184,6 +203,10 @@ custom_display_name_handler = function(item, default_handler)
         return default_handler(item) .. "<i class=\"deprecated_label\"> [deprecated]</i>"
     end
 
+    if item.type == "method" then
+        return render_methods(item)
+    end
+
     local ret = default_handler(item)
 
     -- Get rid of the "module:" in front of method names. It is either wrong or

lib/awful/client.lua

@@ -164,7 +164,7 @@ end
 --- Jump to the given client.
 -- Takes care of focussing the screen, the right tag, etc.
 --
--- @function client.jump_to
+-- @method jump_to
 -- @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 and its first
@@ -409,7 +409,7 @@ function client.moveresize(x, y, w, h, c)
 end
 
 --- Move/resize a client relative to current coordinates.
--- @function client.relative_move
+-- @method relative_move
 -- @see geometry
 -- @tparam[opt=c.x] number x The relative x coordinate.
 -- @tparam[opt=c.y] number y The relative y coordinate.
@@ -435,7 +435,7 @@ function client.movetotag(target, c)
 end
 
 --- Move a client to a tag.
--- @function client.move_to_tag
+-- @method move_to_tag
 -- @tparam tag target The tag to move the client to.
 function client.object.move_to_tag(self, target)
     local s = target.screen
@@ -460,7 +460,7 @@ function client.toggletag(target, c)
 end
 
 --- Toggle a tag on a client.
--- @function client.toggle_tag
+-- @method toggle_tag
 -- @tparam tag target The tag to move the client to.
 function client.object.toggle_tag(self, target)
     -- Check that tag and client screen are identical
@@ -496,7 +496,7 @@ function client.movetoscreen(c, s)
 end
 
 --- Move a client to a screen. Default is next screen, cycling.
--- @function client.move_to_screen
+-- @method move_to_screen
 -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1.
 -- @see screen
 -- @see request::activate
@@ -524,7 +524,7 @@ function client.object.move_to_screen(self, s)
 end
 
 --- Tag a client with the set of current tags.
--- @function client.to_selected_tags
+-- @method to_selected_tags
 -- @see screen.selected_tags
 function client.object.to_selected_tags(self)
     local tags = {}
@@ -625,7 +625,7 @@ function client.togglemarked(c)
 end
 
 --- Return the marked clients and empty the marked table.
--- @function awful.client.getmarked
+-- @deprecated awful.client.getmarked
 -- @return A table with all marked clients.
 function client.getmarked()
     local copy = gtable.clone(client.data.marked, false)
@@ -1300,7 +1300,7 @@ function client.get_transient_for_matching(c, matcher)
 end
 
 --- Get a matching transient_for client (if any).
--- @function client.get_transient_for_matching
+-- @method get_transient_for_matching
 -- @tparam function matcher A function that should return true, if
 --   a matching parent client is found.
 -- @treturn client.client|nil The matching parent client or nil.
@@ -1328,7 +1328,7 @@ function client.is_transient_for(c, c2)
 end
 
 --- Is a client transient for another one?
--- @function client.is_transient_for
+-- @method is_transient_for
 -- @client c2 The parent client to check.
 -- @treturn client.client|nil The parent client or nil.
 function client.object.is_transient_for(self, c2)
@@ -1432,6 +1432,8 @@ object.properties(capi.client, {
     setter_fallback = client.property.set,
 })
 
+--@DOC_object_COMMON@
+
 return client
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/keygrabber.lua

@@ -463,6 +463,7 @@ end
 -- Note that only a single keygrabber can be started at any one time. If another
 -- keygrabber (or this one) is currently running. This method returns false.
 --
+-- @method start
 -- @treturn boolean If the keygrabber was successfully started.
 function keygrabber:start()
     if self.grabber or keygrab.current_instance then
@@ -514,7 +515,7 @@ function keygrabber:start()
 end
 
 --- Stop the keygrabber.
--- @function keygrabber:stop
+-- @method stop
 function keygrabber:stop(_stop_key, _stop_mods) -- (at)function disables ldoc params
     keygrab.stop(self.grabber)
 
@@ -534,6 +535,7 @@ end
 --
 -- Those keybindings will automatically start the keygrabbing when hit.
 --
+-- @method add_keybinding
 -- @tparam table mods A table with modifier keys, such as `shift`, `mod4`, `mod1` (alt) or
 --  `control`.
 -- @tparam string key The key name, such as `left` or `f`

lib/awful/screen.lua

@@ -57,7 +57,7 @@ function screen.getdistance_sq(s, x, y)
 end
 
 --- Get the square distance between a `screen` and a point.
--- @function screen.get_square_distance
+-- @method get_square_distance
 -- @tparam number x X coordinate of point
 -- @tparam number y Y coordinate of point
 -- @treturn number The squared distance of the screen to the provided point.
@@ -128,7 +128,7 @@ end
 -- This gets the next screen relative to this one in
 -- the specified direction.
 --
--- @function screen:get_next_in_direction
+-- @method get_next_in_direction
 -- @param self Screen.
 -- @param dir The direction, can be either "up", "down", "left" or "right".
 function screen.object.get_next_in_direction(self, dir)
@@ -388,7 +388,7 @@ end
 --
 -- This is used by `all_clients` internally (with `stacked=true`).
 --
--- @function screen:get_all_clients
+-- @method get_all_clients
 -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table The clients list.
 function screen.object.get_all_clients(s, stacked)
@@ -410,7 +410,7 @@ end
 --
 -- This is used by `tiles_clients` internally (with `stacked=true`).
 --
--- @function screen:get_tiled_clients
+-- @method get_tiled_clients
 -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table The clients list.
 function screen.object.get_tiled_clients(s, stacked)
@@ -661,6 +661,8 @@ object.properties(capi.screen, {
     auto_emit    = true,
 })
 
+--@DOC_object_COMMON@
+
 return screen
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/tag.lua

@@ -218,8 +218,8 @@ function tag.move(new_index, target_tag)
     tag.object.set_index(target_tag, new_index)
 end
 
---- Swap 2 tags
+--- Swap 2 tags.
--- @function tag.swap
+-- @method swap
 -- @param tag2 The second tag
 -- @see client.swap
 function tag.object.swap(self, tag2)
@@ -1371,7 +1371,7 @@ function tag.viewprev(screen)
 end
 
 --- View only a tag.
--- @function tag.view_only
+-- @method view_only
 -- @see selected
 function tag.object.view_only(self)
     local tags = self.screen.tags
@@ -1685,6 +1685,8 @@ object.properties(capi.tag, {
     setter_fallback = tag.setproperty,
 })
 
+--@DOC_object_COMMON@
+
 return setmetatable(tag, tag.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/only_on_screen.lua

@@ -63,15 +63,10 @@ function only_on_screen:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function only_on_screen:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function only_on_screen:set_children(children)
     self:set_widget(children[1])
 end

lib/gears/timer.lua

@@ -84,6 +84,7 @@ local gdebug = require("gears.debug")
 local timer = { mt = {} }
 
 --- Start the timer.
+-- @method start
 function timer:start()
     if self.data.source_id ~= nil then
         gdebug.print_error(traceback("timer already started"))
@@ -97,6 +98,7 @@ function timer:start()
 end
 
 --- Stop the timer.
+-- @method stop
 function timer:stop()
     if self.data.source_id == nil then
         gdebug.print_error(traceback("timer not started"))
@@ -110,6 +112,7 @@ end
 --- Restart the timer.
 -- This is equivalent to stopping the timer if it is running and then starting
 -- it.
+-- @method again
 function timer:again()
     if self.data.source_id ~= nil then
         self:stop()

lib/naughty/notification.lua

@@ -240,6 +240,7 @@ local notification = {}
 
 --- Destroy notification by notification object.
 --
+-- @method destroy
 -- @tparam string reason One of the reasons from `notification_closed_reason`
 -- @tparam[opt=false] boolean keep_visible If true, keep the notification visible
 -- @return True if the popup was successfully destroyed, false otherwise
@@ -261,6 +262,7 @@ function notification:destroy(reason, keep_visible)
 end
 
 --- Set new notification timeout.
+-- @method reset_timeout
 -- @tparam number new_timeout Time in seconds after which notification disappears.
 function notification:reset_timeout(new_timeout)
     if self.timer then self.timer:stop() end
@@ -543,4 +545,6 @@ function notification._gen_next_id()
     return counter
 end
 
+--@DOC_object_COMMON@
+
 return setmetatable(notification, {__call = function(_, ...) return create(...) end})

lib/wibox/container/arcchart.lua

@@ -197,21 +197,17 @@ function arcchart:set_widget(widget)
     self:emit_signal("widget::layout_changed")
 end
 
---- Get the children elements.
--- @treturn table The children
 function arcchart:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function arcchart:set_children(children)
     self._private.widget = children and children[1]
     self:emit_signal("widget::layout_changed")
 end
 
 --- Reset this layout. The widget will be removed and the rotation reset.
+-- @method reset
 function arcchart:reset()
     self:set_widget(nil)
 end

lib/wibox/container/background.lua

@@ -175,15 +175,10 @@ function background:get_widget()
     return self._private.widget
 end
 
--- Get children element
--- @treturn table The children
 function background:get_children()
     return {self._private.widget}
 end
 
--- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function background:set_children(children)
     self:set_widget(children[1])
 end
@@ -239,6 +234,7 @@ end
 --- Set the background shape.
 --
 -- Any other arguments will be passed to the shape function
+-- @method set_shape
 -- @param shape A function taking a context, width and height as arguments
 -- @see gears.shape
 -- @see shape

lib/wibox/container/constraint.lua

@@ -51,15 +51,10 @@ function constraint:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function constraint:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function constraint:set_children(children)
     self:set_widget(children[1])
 end
@@ -121,6 +116,7 @@ end
 
 --- Reset this layout. The widget will be unreferenced, strategy set to "max"
 -- and the constraints set to nil.
+-- @method reset
 function constraint:reset()
     self._private.width = nil
     self._private.height = nil

lib/wibox/container/margin.lua

@@ -80,15 +80,10 @@ function margin:get_widget()
     return self._private.widget
 end
 
--- Get the number of children element
--- @treturn table The children
 function margin:get_children()
     return {self._private.widget}
 end
 
--- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function margin:set_children(children)
     self:set_widget(children[1])
 end
@@ -136,7 +131,7 @@ function margin:get_color()
 end
 
 --- Draw the margin even if the content size is 0x0 (default: true)
--- @function draw_empty
+-- @method draw_empty
 -- @tparam boolean draw_empty Draw nothing is content is 0x0 or draw the margin anyway
 
 function margin:set_draw_empty(draw_empty)
@@ -150,6 +145,7 @@ end
 
 --- Reset this layout. The widget will be unreferenced, the margins set to 0
 -- and the color erased
+-- @method reset
 function margin:reset()
     self:set_widget(nil)
     self:set_margins(0)

lib/wibox/container/mirror.lua

@@ -61,20 +61,16 @@ function mirror:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function mirror:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function mirror:set_children(children)
     self:set_widget(children[1])
 end
 
 --- Reset this layout. The widget will be removed and the axes reset.
+-- @method reset
 function mirror:reset()
     self._private.horizontal = false
     self._private.vertical = false

lib/wibox/container/place.lua

@@ -61,10 +61,6 @@ function place:fit(context, width, height)
         and height or h
 end
 
---- The widget to be placed.
--- @property widget
--- @tparam widget widget The widget
-
 function place:set_widget(widget)
     if widget then
         base.check_widget(widget)
@@ -77,20 +73,20 @@ function place:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
+--- Get or set the children elements.
--- @treturn table The children
+-- @property children
+-- @tparam table The children
+
 function place:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function place:set_children(children)
     self:set_widget(children[1])
 end
 
 --- Reset this layout. The widget will be removed and the rotation reset.
+-- @method reset
 function place:reset()
     self:set_widget(nil)
 end

lib/wibox/container/radialprogressbar.lua

@@ -134,21 +134,17 @@ function radialprogressbar:set_widget(widget)
     self:emit_signal("widget::layout_changed")
 end
 
---- Get the children elements
--- @treturn table The children
 function radialprogressbar:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function radialprogressbar:set_children(children)
     self._private.widget = children and children[1]
     self:emit_signal("widget::layout_changed")
 end
 
 --- Reset this container.
+-- @method reset
 function radialprogressbar:reset()
     self:set_widget(nil)
 end

lib/wibox/container/rotate.lua

@@ -74,20 +74,16 @@ function rotate:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function rotate:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function rotate:set_children(children)
     self:set_widget(children[1])
 end
 
 --- Reset this layout. The widget will be removed and the rotation reset.
+-- @method reset
 function rotate:reset()
     self._private.direction = nil
     self:set_widget(nil)
@@ -125,7 +121,7 @@ function rotate:set_direction(dir)
     self:emit_signal("widget::layout_changed")
 end
 
---- Get the direction of this rotating layout
+-- Get the direction of this rotating layout
 function rotate:get_direction()
     return self._private.direction or "north"
 end

lib/wibox/container/scroll.lua

@@ -220,6 +220,7 @@ _need_scroll_redraw = function(self)
 end
 
 --- Pause the scrolling animation.
+-- @method pause
 -- @see continue
 function scroll:pause()
     if self._private.paused then
@@ -230,6 +231,7 @@ function scroll:pause()
 end
 
 --- Continue the scrolling animation.
+-- @method continue
 -- @see pause
 function scroll:continue()
     if not self._private.paused then
@@ -244,6 +246,7 @@ end
 -- For must scroll step functions, the effect of this function should be to
 -- display the widget without any scrolling applied.
 -- This function does not undo the effect of @{pause}.
+-- @method reset_scrolling
 function scroll:reset_scrolling()
     self._private.timer:start()
     if self._private.paused then
@@ -252,6 +255,7 @@ function scroll:reset_scrolling()
 end
 
 --- Set the direction in which this widget scroll.
+-- @method set_direction
 -- @param dir Either "h" for horizontal scrolling or "v" for vertical scrolling
 function scroll:set_direction(dir)
     if dir == self._private.dir then
@@ -285,20 +289,16 @@ function scroll:get_widget()
     return self._private.widget
 end
 
---- Get the number of children element
--- @treturn table The children
 function scroll:get_children()
     return {self._private.widget}
 end
 
---- Replace the layout children
--- This layout only accept one children, all others will be ignored
--- @tparam table children A table composed of valid widgets
 function scroll:set_children(children)
     self:set_widget(children[1])
 end
 
 --- Specify the expand mode that is used for extra space.
+-- @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.
 -- @see set_extra_space
@@ -311,6 +311,7 @@ function scroll:set_expand(expand)
 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
 function scroll:set_fps(fps)
     if fps == self._private.fps then
@@ -323,6 +324,7 @@ end
 
 --- Set the amount of extra space that should be included in the scrolling. This
 -- 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
 -- @see set_expand
 function scroll:set_extra_space(extra_space)
@@ -336,6 +338,7 @@ end
 --- Set the speed of the scrolling animation. The exact meaning depends on the
 -- step function that is used, but for the simplest step functions, this will be
 -- in pixels per second.
+-- @method set_speed
 -- @tparam number speed The speed for the animation
 function scroll:set_speed(speed)
     if speed == self._private.speed then
@@ -349,6 +352,7 @@ end
 -- @{set_direction}. If the child widget is smaller than this size, no scrolling
 -- is done. If the child widget is larger, then only this size will be visible
 -- 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.
 function scroll:set_max_size(max_size)
     if max_size == self._private.max_size then
@@ -373,6 +377,7 @@ end
 --
 -- The step function should return a single number. This number is the offset at
 -- 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.
 -- @see step_functions
 function scroll:set_step_function(step_function)
@@ -387,6 +392,7 @@ end
 
 --- Set an upper limit for the space for scrolling.
 -- This restricts the child widget's maximal size.
+-- @method set_space_for_scrolling
 -- @tparam number space_for_scrolling The space for scrolling
 function scroll:set_space_for_scrolling(space_for_scrolling)
     if space_for_scrolling == self._private.space_for_scrolling then
@@ -419,6 +425,7 @@ local function get_layout(dir, widget, fps, speed, extra_space, expand, max_size
 end
 
 --- Get a new horizontal scrolling container.
+-- @function wibox.container.scroll.horizontal
 -- @param[opt] widget The widget that should be scrolled
 -- @param[opt=20] fps The number of frames per second
 -- @param[opt=10] speed The speed of the animation
@@ -433,6 +440,7 @@ function scroll.horizontal(widget, fps, speed, extra_space, expand, max_size, st
 end
 
 --- Get a new vertical scrolling container.
+-- @function wibox.container.scroll.vertical
 -- @param[opt] widget The widget that should be scrolled
 -- @param[opt=20] fps The number of frames per second
 -- @param[opt=10] speed The speed of the animation
@@ -452,18 +460,21 @@ scroll.step_functions = {}
 
 --- A step function that scrolls the widget in an increasing direction with
 -- constant speed.
+-- @callback scroll.step_functions.linear_increase
 function scroll.step_functions.linear_increase(elapsed, size, _, speed, extra_space)
     return (elapsed * speed) % (size + extra_space)
 end
 
 --- A step function that scrolls the widget in an decreasing direction with
 -- constant speed.
+-- @callback scroll.step_functions.linear_decrease
 function scroll.step_functions.linear_decrease(elapsed, size, _, speed, extra_space)
     return (-elapsed * speed) % (size + extra_space)
 end
 
 --- A step function that scrolls the widget to its end and back to its
 -- beginning, then back to its end, etc. The speed is constant.
+-- @callback scroll.step_functions.linear_back_and_forth
 function scroll.step_functions.linear_back_and_forth(elapsed, size, visible_size, speed)
     local state = ((elapsed * speed) % (2 * size)) / size
     state = state <= 1 and state or 2 - state
@@ -473,6 +484,7 @@ end
 --- A step function that scrolls the widget to its end and back to its
 -- beginning, then back to its end, etc. The speed is null at the ends and
 -- maximal in the middle.
+-- @callback scroll.step_functions.nonlinear_back_and_forth
 function scroll.step_functions.nonlinear_back_and_forth(elapsed, size, visible_size, speed)
     local state = ((elapsed * speed) % (2 * size)) / size
     local negate = false
@@ -501,6 +513,7 @@ end
 --- A step function that scrolls the widget to its end and back to its
 -- beginning, then back to its end, etc. The speed is null at the ends and
 -- maximal in the middle. At both ends the widget stands still for a moment.
+-- @callback scroll.step_functions.waiting_nonlinear_back_and_forth
 function scroll.step_functions.waiting_nonlinear_back_and_forth(elapsed, size, visible_size, speed)
     local state = ((elapsed * speed) % (2 * size)) / size
     local negate = false

lib/wibox/init.lua

@@ -65,6 +65,7 @@ end
 
 --- Create a widget that reflects the current state of this wibox.
 -- @treturn widget A new widget.
+-- @method to_widget
 function wibox:to_widget()
     local bw = self.border_width or beautiful.border_width or 0
     return wibox.widget {
@@ -88,6 +89,7 @@ end
 --- Save a screenshot of the wibox to `path`.
 -- @tparam string path The path.
 -- @tparam[opt=nil] table context A widget context.
+-- @method save_to_svg
 function wibox:save_to_svg(path, context)
     wibox.widget.draw_to_svg_file(
         self:to_widget(), path, self:geometry().width, self:geometry().height, context
@@ -350,7 +352,7 @@ end
 --- Redraw a wibox. You should never have to call this explicitely because it is
 -- automatically called when needed.
 -- @param wibox
--- @function draw
+-- @method draw
 
 function wibox.mt:__call(...)
     return new(...)

lib/wibox/layout/fixed.lua

@@ -62,7 +62,8 @@ function fixed:layout(context, width, height)
     return result
 end
 
---- Add some widgets to the given fixed layout
+--- Add some widgets to the given layout
+-- @method add
 -- @param ... Widgets that should be added (must at least be one)
 function fixed:add(...)
     -- No table.pack in Lua 5.1 :-(
@@ -77,6 +78,7 @@ end
 
 
 --- Remove a widget from the layout
+-- @method remove
 -- @tparam number index The widget index to remove
 -- @treturn boolean index If the operation is successful
 function fixed:remove(index)
@@ -92,6 +94,7 @@ end
 --- Remove one or more widgets from the layout
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
+-- @method remove_widgets
 -- @param widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
 function fixed:remove_widgets(...)
@@ -128,6 +131,7 @@ function fixed:set_children(children)
 end
 
 --- Replace the first instance of `widget` in the layout with `widget2`
+-- @method replace_widget
 -- @param widget The widget to replace
 -- @param widget2 The widget to replace `widget` with
 -- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
@@ -219,8 +223,9 @@ function fixed:set_spacing_widget(wdg)
     self:emit_signal("widget::layout_changed")
 end
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
 -- **Signal:** widget::inserted The arguments are the widget and the index
+-- @method insert
 -- @tparam number index The position
 -- @param widget The widget
 -- @treturn boolean If the operation is successful
@@ -235,7 +240,7 @@ function fixed:insert(index, widget)
     return true
 end
 
--- Fit the fixed layout into the given space
+-- Fit the fixed layout into the given space.
 -- @param context The context in which we are fit.
 -- @param orig_width The available width.
 -- @param orig_height The available height.

lib/wibox/layout/flex.lua

@@ -17,37 +17,28 @@ local flex = {}
 
 --@DOC_fixed_COMMON@
 
---- Replace the layout children
--- @tparam table children A table composed of valid widgets
--- @name set_children
--- @class function
-
 --- Add some widgets to the given fixed layout
 -- @param layout The layout you are modifying.
 -- @tparam widget ... Widgets that should be added (must at least be one)
--- @name add
+-- @method add
--- @class function
 
 --- Remove a widget from the layout
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
--- @name remove
+-- @method remove
--- @class function
 
 --- Remove one or more widgets from the layout
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
 -- @param widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
--- @name remove_widgets
+-- @method remove_widgets
--- @class function
 
 --- Insert a new widget in the layout at position `index`
 -- @tparam number index The position
 -- @param widget The widget
 -- @treturn boolean If the operation is successful
--- @name insert
+-- @method insert
--- @class function
 
 --- The widget used to fill the spacing between the layout elements.
 --

lib/wibox/layout/grid.lua

@@ -222,6 +222,7 @@ local function find_widget(widgets_table, widget)
 end
 
 --- Get the number of rows and columns occupied by the widgets in the grid.
+-- @method get_dimension
 -- @treturn number,number The number of rows and columns
 function grid:get_dimension()
     return self._private.num_rows, self._private.num_cols
@@ -248,6 +249,7 @@ end
 
 --- Find the next available cell to insert a widget.
 -- The grid is browsed according to the `orientation`.
+-- @method get_next_empty
 -- @tparam[opt=1] number hint_row The row coordinate of the last occupied cell.
 -- @tparam[opt=1] number hint_column The column coordinate of the last occupied cell.
 -- @return number,number The row,column coordinate of the next empty cell
@@ -281,7 +283,10 @@ end
 
 
 --- Add some widgets to the given grid layout.
--- The widgets are assumed to span one cell
+--
+-- The widgets are assumed to span one cell.
+--
+-- @method add
 -- @param ... Widgets that should be added (must at least be one)
 function grid:add(...)
     local args = { n=select('#', ...), ... }
@@ -298,6 +303,8 @@ end
 --- Add a widget to the grid layout at specific coordinate.
 --
 --@DOC_wibox_layout_grid_add_EXAMPLE@
+--
+-- @method add_widget_at
 -- @param child Widget that should be added
 -- @tparam number row Row number for the top left corner of the widget
 -- @tparam number col Column number for the top left corner of the widget
@@ -341,6 +348,7 @@ function grid:add_widget_at(child, row, col, row_span, col_span)
 end
 
 --- Remove one or more widgets from the layout.
+-- @method remove
 -- @param ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
 function grid:remove(...)
@@ -366,6 +374,8 @@ end
 --- Remove widgets at the coordinates.
 --
 --@DOC_wibox_layout_grid_remove_EXAMPLE@
+--
+-- @method remove_widgets_at
 -- @tparam number row The row coordinate of the widget to remove
 -- @tparam number col The column coordinate of the widget to remove
 -- @tparam[opt=1] number row_span The number of rows the area to remove spans.
@@ -388,6 +398,7 @@ function grid:remove_widgets_at(row, col, row_span, col_span)
 end
 
 --- Return the coordinates of the widget.
+-- @method get_widget_position
 -- @param widget The widget
 -- @treturn table The `position` table of the coordinates in the grid, with
 -- fields `row`, `col`, `row_span` and `col_span`.
@@ -405,6 +416,7 @@ end
 
 
 --- Return the widgets at the coordinates.
+-- @method get_widgets_at
 -- @tparam number row The row coordinate of the widget
 -- @tparam number col The column coordinate of the widget
 -- @tparam[opt=1] number row_span The number of rows to span.
@@ -427,6 +439,7 @@ function grid:get_widgets_at(row, col, row_span, col_span)
 end
 
 --- Replace old widget by new widget, spanning the same columns and rows.
+-- @method replace_widget
 -- @param old The widget to remove
 -- @param new The widget to add
 -- @treturn boolean If the operation is successful (widget found)
@@ -494,6 +507,8 @@ end
 --- Insert column at index.
 --
 --@DOC_wibox_layout_grid_insert_column_EXAMPLE@
+--
+-- @method insert_column
 -- @tparam number|nil index Insert the new column at index. If `nil`, the column is added at the end.
 -- @treturn number The index of the inserted column
 function grid:insert_column(index)
@@ -508,8 +523,9 @@ function grid:insert_column(index)
 end
 
 --- Extend column at index.
---
 --@DOC_wibox_layout_grid_extend_column_EXAMPLE@
+--
+-- @method extend_column
 -- @tparam number|nil index Extend the column at index. If `nil`, the last column is extended.
 -- @treturn number The index of the extended column
 function grid:extend_column(index)
@@ -526,6 +542,8 @@ end
 --- Remove column at index.
 --
 --@DOC_wibox_layout_grid_remove_column_EXAMPLE@
+--
+-- @method remove_column
 -- @tparam number|nil index Remove column at index. If `nil`, the last column is removed.
 -- @treturn number The index of the removed column
 function grid:remove_column(index)
@@ -542,6 +560,8 @@ end
 --- Insert row at index.
 --
 -- see `insert_column`
+--
+-- @method insert_row
 -- @tparam number|nil index Insert the new row at index. If `nil`, the row is added at the end.
 -- @treturn number The index of the inserted row
 function grid:insert_row(index)
@@ -558,6 +578,8 @@ end
 --- Extend row at index.
 --
 -- see `extend_column`
+--
+-- @method extend_row
 -- @tparam number|nil index Extend the row at index. If `nil`, the last row is extended.
 -- @treturn number The index of the extended row
 function grid:extend_row(index)
@@ -574,6 +596,8 @@ end
 --- Remove row at index.
 --
 -- see `remove_column`
+--
+-- @method remove_row
 -- @tparam number|nil index Remove row at index. If `nil`, the last row is removed.
 -- @treturn number The index of the removed row
 function grid:remove_row(index)
@@ -597,7 +621,7 @@ function grid:get_children()
     return ret
 end
 
--- Add list of children to the layout
+-- Add list of children to the layout.
 function grid:set_children(children)
     self:reset()
     if #children > 0 then
@@ -837,6 +861,7 @@ end
 -- Remove all widgets and reset row and column counts
 --
 -- **Signal:** widget::reset
+-- @method reset
 function grid:reset()
     self._private.widgets = {}
     -- reset the number of columns and rows to the forced value or to 0

lib/wibox/layout/manual.lua

@@ -15,24 +15,24 @@ local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility
 
 local manual_layout = {}
 
---- Add some widgets to the given stack layout
+--- Add some widgets to the given stack layout.
+--
+-- @method add
 -- @param layout The layout you are modifying.
 -- @tparam widget ... Widgets that should be added
--- @name add
--- @class function
 
---- Remove a widget from the layout
+--- Remove a widget from the layout.
+--
+-- @method remove
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
--- @name remove
--- @class function
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
+--
+-- @method insert
 -- @tparam number index The position
 -- @param widget The widget
 -- @treturn boolean If the operation is successful
--- @name insert
--- @class function
 function manual_layout:insert(index, widget)
     table.insert(self._private.widgets, index, widget)
 
@@ -44,13 +44,14 @@ function manual_layout:insert(index, widget)
     self:emit_signal("widget::layout_changed")
 end
 
---- Remove one or more widgets from the layout
+--- Remove one or more widgets from the layout.
+--
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
+--
+-- @method remove_widgets
 -- @param widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
--- @name remove_widgets
--- @class function
 
 
 function manual_layout:fit(_, width, height)
@@ -145,6 +146,8 @@ end
 --           The function is compatible with the `awful.placement` prototype.
 --
 --@DOC_wibox_layout_manual_add_at_EXAMPLE@
+--
+-- @method add_at
 -- @tparam widget widget The widget.
 -- @tparam table|function point Either an `{x=x,y=y}` table or a function
 --  returning the new geometry.
@@ -167,6 +170,7 @@ function manual_layout:add_at(widget, point)
 end
 
 --- Move a widget (by index).
+-- @method move
 -- @tparam number index The widget index.
 -- @tparam table|function point A new point value.
 -- @see add_at
@@ -179,6 +183,8 @@ end
 --- Move a widget.
 --
 --@DOC_wibox_layout_manual_move_widget_EXAMPLE@
+--
+-- @method move_widget
 -- @tparam widget widget The widget.
 -- @tparam table|function point A new point value.
 -- @see add_at
@@ -206,7 +212,9 @@ function manual_layout:reset()
 end
 
 --- Create a manual layout.
+-- @function wibox.layout.manual
 -- @tparam table ... Widgets to add to the layout.
+
 local function new_manual(...)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 

lib/wibox/layout/ratio.lua

@@ -38,7 +38,7 @@ local ratio = {}
 -- @property spacing
 -- @tparam number spacing Spacing between widgets.
 
--- Compute the sum of all ratio (ideally, it should be 1)
+-- Compute the sum of all ratio (ideally, it should be 1).
 local function gen_sum(self, i_s, i_e)
     local sum, new_w = 0,0
 
@@ -201,12 +201,13 @@ function ratio:layout(context, width, height)
     return result
 end
 
---- Increase the ratio of "widget"
+--- Increase the ratio of "widget".
 -- If the increment produce an invalid ratio (not between 0 and 1), the method
 -- do nothing.
 --
 --@DOC_wibox_layout_ratio_inc_ratio_EXAMPLE@
 --
+-- @method inc_ratio
 -- @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
@@ -221,9 +222,11 @@ function ratio:inc_ratio(index, increment)
     self:set_ratio(index, self._private.ratios[index] + increment)
 end
 
---- Increment the ratio of the first instance of `widget`
+--- Increment the ratio of the first instance of `widget`.
 -- If the increment produce an invalid ratio (not between 0 and 1), the method
 -- do nothing.
+--
+-- @method inc_widget_ratio
 -- @param widget The widget to ajust
 -- @tparam number increment An floating point value between -1 and 1 where the
 --   end result is within 0 and 1
@@ -235,7 +238,9 @@ function ratio:inc_widget_ratio(widget, increment)
     self:inc_ratio(index, increment)
 end
 
---- Set the ratio of the widget at position `index`
+--- Set the ratio of the widget at position `index`.
+--
+-- @method set_ratio
 -- @tparam number index The index of the widget to change
 -- @tparam number percent An floating point value between 0 and 1
 function ratio:set_ratio(index, percent)
@@ -263,6 +268,8 @@ function ratio:set_ratio(index, percent)
 end
 
 --- Get the ratio at `index`.
+--
+-- @method get_ratio
 -- @tparam number index The widget index to query
 -- @treturn number The index (between 0 and 1)
 function ratio:get_ratio(index)
@@ -271,6 +278,8 @@ function ratio:get_ratio(index)
 end
 
 --- Set the ratio of `widget` to `percent`.
+--
+-- @method set_widget_ratio
 -- @tparam widget widget The widget to ajust.
 -- @tparam number percent A floating point value between 0 and 1.
 function ratio:set_widget_ratio(widget, percent)
@@ -284,6 +293,7 @@ end
 --
 --@DOC_wibox_layout_ratio_ajust_ratio_EXAMPLE@
 --
+-- @method ajust_ratio
 -- @tparam number index The index of the widget to change
 -- @tparam number before The sum of the ratio before the widget
 -- @tparam number itself The ratio for "widget"
@@ -323,7 +333,9 @@ function ratio:ajust_ratio(index, before, itself, after)
     self:emit_signal("widget::layout_changed")
 end
 
---- Update all widgets to match a set of a ratio
+--- Update all widgets to match a set of a ratio.
+--
+-- @method ajust_widget_ratio
 -- @param widget The widget to ajust
 -- @tparam number before The sum of the ratio before the widget
 -- @tparam number itself The ratio for "widget"
@@ -333,8 +345,10 @@ function ratio:ajust_widget_ratio(widget, before, itself, after)
     self:ajust_ratio(index, before, itself, after)
 end
 
---- Add some widgets to the given fixed layout
+--- Add some widgets to the given fixed layout.
+--
 -- **Signal:** widget::added The argument are the widgets
+-- @method add
 -- @tparam widget ... Widgets that should be added (must at least be one)
 function ratio:add(...)
     -- No table.pack in Lua 5.1 :-(
@@ -350,8 +364,10 @@ function ratio:add(...)
     self:emit_signal("widget::added", ...)
 end
 
---- Remove a widget from the layout
+--- Remove a widget from the layout.
+--
 -- **Signal:** widget::removed The arguments are the widget and the index
+-- @method remove
 -- @tparam number index The widget index to remove
 -- @treturn boolean index If the operation is successful
 function ratio:remove(index)
@@ -370,8 +386,10 @@ function ratio:remove(index)
     return true
 end
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
 -- **Signal:** widget::inserted The arguments are the widget and the index
+--
+-- @method insert
 -- @tparam number index The position
 -- @param widget The widget
 function ratio:insert(index, widget)
@@ -437,15 +455,17 @@ local function get_layout(dir, widget1, ...)
     return ret
 end
 
---- Returns a new horizontal ratio layout. A ratio layout shares the available space
+--- Returns a new horizontal ratio layout. A ratio layout shares the available space.
 -- equally among all widgets. Widgets can be added via :add(widget).
+-- @function wibox.layout.ratio.horizontal
 -- @tparam widget ... Widgets that should be added to the layout.
 function ratio.horizontal(...)
     return get_layout("horizontal", ...)
 end
 
---- Returns a new vertical ratio layout. A ratio layout shares the available space
+--- Returns a new vertical ratio layout. A ratio layout shares the available space.
 -- equally among all widgets. Widgets can be added via :add(widget).
+-- @function wibox.layout.ratio.vertical
 -- @tparam widget ... Widgets that should be added to the layout.
 function ratio.vertical(...)
     return get_layout("vertical", ...)

lib/wibox/layout/stack.lua

@@ -24,32 +24,28 @@ local stack = {mt={}}
 
 --@DOC_fixed_COMMON@
 
---- Add some widgets to the given stack layout
+--- Add some widgets to the given stack layout.
 -- @param layout The layout you are modifying.
 -- @tparam widget ... Widgets that should be added (must at least be one)
--- @name add
+-- @method add
--- @class function
 
 --- Remove a widget from the layout
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
--- @name remove
+-- @method remove
--- @class function
 
---- Insert a new widget in the layout at position `index`
+--- Insert a new widget in the layout at position `index`.
 -- @tparam number index The position
 -- @param widget The widget
 -- @treturn boolean If the operation is successful
--- @name insert
+-- @method insert
--- @class function
 
---- Remove one or more widgets from the layout
+--- Remove one or more widgets from the layout.
 -- The last parameter can be a boolean, forcing a recursive seach of the
 -- widget(s) to remove.
 -- @param widget ... Widgets that should be removed (must at least be one)
 -- @treturn boolean If the operation is successful
--- @name remove_widgets
+-- @method remove_widgets
--- @class function
 
 --- Add spacing around the widget, similar to the margin container.
 --@DOC_wibox_layout_stack_spacing_EXAMPLE@
@@ -86,7 +82,7 @@ function stack:fit(context, orig_width, orig_height)
     return math.min(max_w, orig_width), math.min(max_h, orig_height)
 end
 
---- If only the first stack widget is drawn
+--- If only the first stack widget is drawn.
 -- @property top_only
 
 function stack:get_top_only()
@@ -97,7 +93,8 @@ function stack:set_top_only(top_only)
     self._private.top_only = top_only
 end
 
---- Raise a widget at `index` to the top of the stack
+--- Raise a widget at `index` to the top of the stack.
+-- @method raise
 -- @tparam number index the widget index to raise
 function stack:raise(index)
     if (not index) or self._private.widgets[index] then return end
@@ -109,7 +106,8 @@ function stack:raise(index)
     self:emit_signal("widget::layout_changed")
 end
 
---- Raise the first instance of `widget`
+--- Raise the first instance of `widget`.
+-- @method raise_widget
 -- @param widget The widget to raise
 -- @tparam[opt=false] boolean recursive Also look deeper in the hierarchy to
 --   find the widget

lib/wibox/widget/checkbox.lua

@@ -224,6 +224,12 @@ function checkbox:set_paddings(val)
     self:emit_signal("widget::redraw_needed")
 end
 
+--- Create a new checkbox.
+-- @function wibox.widget.checkbox
+-- @tparam[opt=false] boolean checked
+-- @tparam[opt] table args
+-- @tparam gears.color args.color The color.
+
 local function new(checked, args)
     checked, args = checked or false, args or {}
 

lib/wibox/widget/graph.lua

@@ -231,6 +231,7 @@ end
 
 --- Add a value to the graph
 --
+-- @method add_value
 -- @param value The value to be added to the graph
 -- @param group The stack color group index.
 function graph:add_value(value, group)
@@ -265,6 +266,7 @@ function graph:add_value(value, group)
 end
 
 --- Clear the graph.
+-- @method clear
 function graph:clear()
     self._private.values = {}
     self:emit_signal("widget::redraw_needed")
@@ -272,7 +274,9 @@ function graph:clear()
 end
 
 --- Set the graph height.
--- @param height The height to set.
+-- @property height
+-- @param number The height to set.
+
 function graph:set_height(height)
     if height >= 5 then
         self._private.height = height
@@ -282,7 +286,9 @@ function graph:set_height(height)
 end
 
 --- Set the graph width.
--- @param width The width to set.
+-- @property width
+-- @param number The width to set.
+
 function graph:set_width(width)
     if width >= 5 then
         self._private.width = width

lib/wibox/widget/imagebox.lua

@@ -119,7 +119,7 @@ end
 -- is trimmed.
 --
 -- @property clip_shape
--- @param clip_shape A `gears_shape` compatible shape function
+-- @tparam function clip_shape A `gears_shape` compatible shape function
 -- @see gears.shape
 -- @see set_clip_shape
 
@@ -129,7 +129,8 @@ end
 --
 -- Any other parameters will be passed to the clip shape function
 --
--- @param clip_shape A `gears_shape` compatible shape function
+-- @tparam function clip_shape A `gears_shape` compatible shape function.
+-- @method set_clip_shape
 -- @see gears.shape
 -- @see clip_shape
 function imagebox:set_clip_shape(clip_shape, ...)

lib/wibox/widget/piechart.lua

@@ -218,6 +218,10 @@ function piechart:get_data()
     return list
 end
 
+--- Create a new piechart.
+-- @function wibox.widget.piechart
+-- @tparam table data_list The data.
+
 local function new(data_list)
 
     local ret = base.make_widget(nil, nil, {

lib/wibox/widget/progressbar.lua

@@ -368,7 +368,9 @@ function progressbar:fit(_, width, height)
 end
 
 --- Set the progressbar value.
--- @param value The progress bar value between 0 and 1.
+-- @property value
+-- @param number The progress bar value between 0 and 1.
+
 function progressbar:set_value(value)
     value = value or 0
 

lib/wibox/widget/separator.lua

@@ -185,6 +185,10 @@ for _, prop in ipairs {"orientation", "color", "thickness", "span_ratio",
     end
 end
 
+--- Create a new separator.
+-- @function wibox.widget.separator
+-- @tparam table args The arguments (all properties are available).
+
 local function new(args)
     local ret = base.make_widget(nil, nil, {
         enable_properties = true,

lib/wibox/widget/systray.lua

@@ -116,7 +116,9 @@ end
 --- Set the size of a single icon.
 -- If this is set to nil, then the size is picked dynamically based on the
 -- available space. Otherwise, any single icon has a size of `size`x`size`.
+-- @property base_size
 -- @tparam integer|nil size The base size
+
 function systray:set_base_size(size)
     base_size = get_args(self, size)
     if instance then
@@ -125,7 +127,9 @@ function systray:set_base_size(size)
 end
 
 --- Decide between horizontal or vertical display.
+-- @property horizontal
 -- @tparam boolean horiz Use horizontal mode?
+
 function systray:set_horizontal(horiz)
     horizontal = get_args(self, horiz)
     if instance then
@@ -134,7 +138,9 @@ function systray:set_horizontal(horiz)
 end
 
 --- Should the systray icons be displayed in reverse order?
--- @tparam boolean rev Display in reverse order
+-- @property reverse
+-- @tparam boolean rev Display in reverse order.
+
 function systray:set_reverse(rev)
     reverse = get_args(self, rev)
     if instance then
@@ -146,7 +152,9 @@ end
 -- This can either be a screen, in which case the systray will be displayed on
 -- exactly that screen, or the string `"primary"`, in which case it will be
 -- visible on the primary screen. The default value is "primary".
+-- @property screen
 -- @tparam screen|"primary" s The screen to display on.
+
 function systray:set_screen(s)
     display_on_screen = get_args(self, s)
     if instance then

lib/wibox/widget/textbox.lua

@@ -70,6 +70,7 @@ end
 --- Get the preferred size of a textbox.
 -- This returns the size that the textbox would use if infinite space were
 -- available.
+-- @method get_preferred_size
 -- @tparam integer|screen s The screen on which the textbox will be displayed.
 -- @treturn number The preferred width.
 -- @treturn number The preferred height.
@@ -88,6 +89,7 @@ end
 --- Get the preferred height of a textbox at a given width.
 -- This returns the height that the textbox would use when it is limited to the
 -- given width.
+-- @method get_height_for_width
 -- @tparam number width The available width.
 -- @tparam integer|screen s The screen on which the textbox will be displayed.
 -- @treturn number The needed height.
@@ -105,6 +107,7 @@ end
 --- Get the preferred size of a textbox.
 -- This returns the size that the textbox would use if infinite space were
 -- available.
+-- @method get_preferred_size_at_dpi
 -- @tparam number dpi The DPI value to render at.
 -- @treturn number The preferred width.
 -- @treturn number The preferred height.
@@ -119,6 +122,7 @@ end
 --- Get the preferred height of a textbox at a given width.
 -- This returns the height that the textbox would use when it is limited to the
 -- given width.
+-- @method get_height_for_width_at_dpi
 -- @tparam number width The available width.
 -- @tparam number dpi The DPI value to render at.
 -- @treturn number The needed height.
@@ -136,6 +140,7 @@ end
 -- @tparam string text The text to set. This can contain pango markup (e.g.
 --   `<b>bold</b>`). You can use `gears.string.escape` to escape
 --   parts of it.
+-- @method set_markup_silently
 -- @treturn[1] boolean true
 -- @treturn[2] boolean false
 -- @treturn[2] string Error message explaining why the markup was invalid.

lib/wibox/widget/textclock.lua

@@ -69,6 +69,7 @@ function textclock:get_refresh()
 end
 
 --- Force a textclock to update now.
+-- @method force_update
 function textclock:force_update()
     self._timer:emit_signal("timeout")
 end

objects/client.c

@@ -919,14 +919,14 @@
  *
  * @param struts A table with new strut values, or none.
  * @return A table with strut values.
- * @function struts
+ * @method struts
  */
 
 /** Get or set mouse buttons bindings for a client.
  *
  * @param buttons_table An array of mouse button bindings objects, or nothing.
  * @return A table with all buttons.
- * @function buttons
+ * @method buttons
  */
 
 /** Get the number of instances.
@@ -2467,7 +2467,7 @@ luaA_client_get(lua_State *L)
 /** Check if a client is visible on its screen.
  *
  * @return A boolean value, true if the client is visible, false otherwise.
- * @function isvisible
+ * @method isvisible
  */
 static int
 luaA_client_isvisible(lua_State *L)
@@ -2577,7 +2577,7 @@ out:
 
 /** Kill a client.
  *
- * @function kill
+ * @method kill
  */
 static int
 luaA_client_kill(lua_State *L)
@@ -2589,7 +2589,7 @@ luaA_client_kill(lua_State *L)
 
 /** Swap a client with another one in global client list.
  * @client c A client to swap with.
- * @function swap
+ * @method swap
  */
 static int
 luaA_client_swap(lua_State *L)
@@ -2639,7 +2639,7 @@ luaA_client_swap(lua_State *L)
  * @tparam table tags_table A table with tags to set, or `nil` to get the
  *   current tags.
  * @treturn table A table with all tags.
- * @function tags
+ * @method tags
  */
 static int
 luaA_client_tags(lua_State *L)
@@ -2708,7 +2708,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.
  *
- * @function raise
+ * @method raise
  */
 static int
 luaA_client_raise(lua_State *L)
@@ -2729,7 +2729,7 @@ luaA_client_raise(lua_State *L)
 
 /** Lower a client on bottom of others which are on the same layer.
  *
- * @function lower
+ * @method lower
  */
 static int
 luaA_client_lower(lua_State *L)
@@ -2756,7 +2756,7 @@ luaA_client_lower(lua_State *L)
 
 /** Stop managing a client.
  *
- * @function unmanage
+ * @method unmanage
  */
 static int
 luaA_client_unmanage(lua_State *L)
@@ -2986,7 +2986,7 @@ HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT)
  *
  * @tparam table|nil geo A table with new coordinates, or nil.
  * @treturn table A table with client geometry and coordinates.
- * @function geometry
+ * @method geometry
  */
 static int
 luaA_client_geometry(lua_State *L)
@@ -3023,7 +3023,7 @@ luaA_client_geometry(lua_State *L)
  * @param height Desired height of client
  * @return Actual width of client
  * @return Actual height of client
- * @function apply_size_hints
+ * @method apply_size_hints
  */
 static int
 luaA_client_apply_size_hints(lua_State *L)
@@ -3640,7 +3640,7 @@ luaA_client_set_shape_input(lua_State *L, client_t *c)
  *
  * @param keys_table An array of key bindings objects, or nothing.
  * @return A table with all keys.
- * @function keys
+ * @method keys
  */
 static int
 luaA_client_keys(lua_State *L)
@@ -3690,7 +3690,7 @@ luaA_client_get_icon_sizes(lua_State *L, client_t *c)
  * @tparam interger index The index in the list of icons to get.
  * @treturn surface A lightuserdata for a cairo surface. This reference must be
  * destroyed!
- * @function get_icon
+ * @method get_icon
  */
 static int
 luaA_client_get_some_icon(lua_State *L)

objects/drawable.c

@@ -188,7 +188,7 @@ luaA_drawable_get_surface(lua_State *L, drawable_t *drawable)
 /** Refresh a drawable's content. This has to be called whenever some drawing to
  * the drawable's surface has been done and should become visible.
  *
- * @function refresh
+ * @method refresh
  */
 static int
 luaA_drawable_refresh(lua_State *L)
@@ -203,7 +203,7 @@ luaA_drawable_refresh(lua_State *L)
 /** Get drawable geometry. The geometry consists of x, y, width and height.
  *
  * @treturn table A table with drawable coordinates and geometry.
- * @function geometry
+ * @method geometry
  */
 static int
 luaA_drawable_geometry(lua_State *L)

objects/screen.c

@@ -1199,7 +1199,7 @@ luaA_screen_fake_add(lua_State *L)
 }
 
 /** Remove a screen.
- * @function fake_remove
+ * @method fake_remove
  */
 static int
 luaA_screen_fake_remove(lua_State *L)
@@ -1231,7 +1231,7 @@ luaA_screen_fake_remove(lua_State *L)
  * @tparam integer y The new Y-coordinate for screen.
  * @tparam integer width The new width for screen.
  * @tparam integer height The new height for screen.
- * @function fake_resize
+ * @method fake_resize
  */
 static int
 luaA_screen_fake_resize(lua_State *L)
@@ -1258,7 +1258,7 @@ luaA_screen_fake_resize(lua_State *L)
 
 /** Swap a screen with another one in global screen list.
  * @client s A screen to swap with.
- * @function swap
+ * @method swap
  */
 static int
 luaA_screen_swap(lua_State *L)