diff --git a/docs/common/fixed.ldoc b/docs/common/fixed.ldoc
index 6596b7d2..79098bcc 100644
--- a/docs/common/fixed.ldoc
+++ b/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
--- @class function
+-- @method set
--- 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
--- @class function
+-- @method replace_widget
--- 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
--- @class function
+-- @method swap
--- 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
--- @class function
+-- @method swap_widgets
--- 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
--- @class function
+-- @method reset
diff --git a/docs/common/object.ldoc b/docs/common/object.ldoc
index b75fe61c..df722763 100644
--- a/docs/common/object.ldoc
+++ b/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
diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc
index 050bb2b8..b60cb511 100644
--- a/docs/common/wibox.ldoc
+++ b/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
--- @class function
+-- @method setup
--- 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
--- @class function
+-- @method find_widgets
diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc
index 81c88a76..bab76351 100644
--- a/docs/common/widget.ldoc
+++ b/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
--- @function get_all_children
+-- @property 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()`
diff --git a/docs/config.ld b/docs/config.ld
index 75892c65..7883fa5e 100644
--- a/docs/config.ld
+++ b/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) .. " [deprecated]"
end
+ if item.type == "method" then
+ return render_methods(item)
+ end
+
local ret = default_handler(item)
-- Get rid of the "module:" in front of method names. It is either wrong or
diff --git a/lib/awful/client.lua b/lib/awful/client.lua
index b3d4c885..e45381de 100644
--- a/lib/awful/client.lua
+++ b/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
diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua
index 82e1038e..5036b068 100644
--- a/lib/awful/keygrabber.lua
+++ b/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`
diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua
index a998a467..ae0a5f84 100644
--- a/lib/awful/screen.lua
+++ b/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
diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 631914d5..6b743939 100644
--- a/lib/awful/tag.lua
+++ b/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
--- @function tag.swap
+--- Swap 2 tags.
+-- @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
diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua
index c7494a6a..95bec166 100644
--- a/lib/awful/widget/only_on_screen.lua
+++ b/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
diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua
index a955472b..f7c39db1 100644
--- a/lib/gears/timer.lua
+++ b/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()
diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua
index 4be3b164..2a355cb3 100644
--- a/lib/naughty/notification.lua
+++ b/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})
diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua
index 4b778391..28175337 100644
--- a/lib/wibox/container/arcchart.lua
+++ b/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
diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua
index a1d01495..73d89dd5 100644
--- a/lib/wibox/container/background.lua
+++ b/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
diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua
index e54fe266..8fd84dc2 100644
--- a/lib/wibox/container/constraint.lua
+++ b/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
diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua
index bcd4b072..9a5fcd4f 100644
--- a/lib/wibox/container/margin.lua
+++ b/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)
diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua
index 52d6fe79..ac41d41d 100644
--- a/lib/wibox/container/mirror.lua
+++ b/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
diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua
index 34c79cb8..86c7b5fe 100644
--- a/lib/wibox/container/place.lua
+++ b/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
--- @treturn table The children
+--- Get or set the children elements.
+-- @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
diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua
index 1507c755..766ec818 100644
--- a/lib/wibox/container/radialprogressbar.lua
+++ b/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
diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua
index d3b08f51..a0f2775a 100644
--- a/lib/wibox/container/rotate.lua
+++ b/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
diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua
index fbd41b78..4f63377d 100644
--- a/lib/wibox/container/scroll.lua
+++ b/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
diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua
index 8335badf..3f72b82b 100644
--- a/lib/wibox/init.lua
+++ b/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(...)
diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua
index 5eec5861..a6f5ca2a 100644
--- a/lib/wibox/layout/fixed.lua
+++ b/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.
diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua
index 490ff421..59815c43 100644
--- a/lib/wibox/layout/flex.lua
+++ b/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
--- @class function
+-- @method add
--- Remove a widget from the layout
-- @tparam index The widget index to remove
-- @treturn boolean index If the operation is successful
--- @name remove
--- @class function
+-- @method remove
--- 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
--- @class function
+-- @method remove_widgets
--- 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
--- @class function
+-- @method insert
--- The widget used to fill the spacing between the layout elements.
--
diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua
index 37bccc53..48385204 100644
--- a/lib/wibox/layout/grid.lua
+++ b/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
diff --git a/lib/wibox/layout/manual.lua b/lib/wibox/layout/manual.lua
index d16a0bb5..6fa617ee 100644
--- a/lib/wibox/layout/manual.lua
+++ b/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})
diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua
index de79be27..9055392a 100644
--- a/lib/wibox/layout/ratio.lua
+++ b/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", ...)
diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua
index 4cc8d6c2..510a7950 100644
--- a/lib/wibox/layout/stack.lua
+++ b/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
--- @class function
+-- @method add
--- Remove a widget from the layout
-- @tparam index The widget index to remove
-- @treturn boolean index If the operation is successful
--- @name remove
--- @class function
+-- @method remove
---- 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
--- @class function
+-- @method insert
---- 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
--- @class function
+-- @method remove_widgets
--- 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
diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua
index e5eb9f87..10df7e2d 100644
--- a/lib/wibox/widget/checkbox.lua
+++ b/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 {}
diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua
index a5ceb086..a8cb5480 100644
--- a/lib/wibox/widget/graph.lua
+++ b/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
diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua
index f8e28b48..cb121fc2 100644
--- a/lib/wibox/widget/imagebox.lua
+++ b/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, ...)
diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua
index 0cd7adfe..7f22a7c2 100644
--- a/lib/wibox/widget/piechart.lua
+++ b/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, {
diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua
index 56eb5ac5..d2eacacc 100644
--- a/lib/wibox/widget/progressbar.lua
+++ b/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
diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua
index 67b1fff4..c02c9c8a 100644
--- a/lib/wibox/widget/separator.lua
+++ b/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,
diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua
index b06294b0..d9ca261e 100644
--- a/lib/wibox/widget/systray.lua
+++ b/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
diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua
index 4264be48..fd86832d 100644
--- a/lib/wibox/widget/textbox.lua
+++ b/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.
-- `bold`). 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.
diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua
index dce46865..fa1035ca 100644
--- a/lib/wibox/widget/textclock.lua
+++ b/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
diff --git a/objects/client.c b/objects/client.c
index 40ba1525..65d9061d 100644
--- a/objects/client.c
+++ b/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)
diff --git a/objects/drawable.c b/objects/drawable.c
index 89e750d6..07d15aea 100644
--- a/objects/drawable.c
+++ b/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)
diff --git a/objects/screen.c b/objects/screen.c
index cbc57c53..2f509315 100644
--- a/objects/screen.c
+++ b/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)