From 11d7a614d9f0e78a1f72120280377038a0c7e80a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 7 Jun 2019 14:59:34 -0400 Subject: [PATCH] doc: Add a constructor stereotype for everything. This forces the constructor functions to be at the top of the API documentation rather than in a random position. --- docs/config.ld | 12 ++++++++++-- lib/awful/hotkeys_popup/widget.lua | 1 + lib/awful/keygrabber.lua | 2 +- lib/awful/popup.lua | 2 +- lib/awful/tag.lua | 2 +- lib/awful/titlebar.lua | 2 +- lib/awful/tooltip.lua | 2 +- lib/awful/wibar.lua | 2 +- lib/awful/widget/button.lua | 1 + lib/awful/widget/calendar_popup.lua | 4 ++-- lib/awful/widget/clienticon.lua | 2 +- lib/awful/widget/keyboardlayout.lua | 6 +++++- lib/awful/widget/launcher.lua | 1 + lib/awful/widget/layoutbox.lua | 1 + lib/awful/widget/layoutlist.lua | 2 +- lib/awful/widget/only_on_screen.lua | 2 +- lib/awful/widget/prompt.lua | 2 +- lib/awful/widget/taglist.lua | 2 +- lib/awful/widget/tasklist.lua | 2 +- lib/awful/widget/watch.lua | 1 + lib/gears/cache.lua | 1 + lib/gears/matrix.lua | 5 +++++ lib/gears/timer.lua | 4 +++- lib/naughty/action.lua | 4 +++- lib/naughty/notification.lua | 2 +- lib/wibox/container/arcchart.lua | 2 +- lib/wibox/container/background.lua | 2 +- lib/wibox/container/constraint.lua | 2 +- lib/wibox/container/margin.lua | 2 +- lib/wibox/container/mirror.lua | 2 +- lib/wibox/container/place.lua | 2 +- lib/wibox/container/radialprogressbar.lua | 2 +- lib/wibox/container/rotate.lua | 2 +- lib/wibox/container/scroll.lua | 4 ++-- lib/wibox/init.lua | 2 +- lib/wibox/layout/align.lua | 2 ++ lib/wibox/layout/fixed.lua | 4 ++-- lib/wibox/layout/flex.lua | 4 ++-- lib/wibox/layout/grid.lua | 6 +++--- lib/wibox/layout/manual.lua | 2 +- lib/wibox/layout/ratio.lua | 4 ++-- lib/wibox/layout/stack.lua | 2 +- lib/wibox/widget/calendar.lua | 4 ++-- lib/wibox/widget/checkbox.lua | 2 +- lib/wibox/widget/graph.lua | 2 +- lib/wibox/widget/imagebox.lua | 2 +- lib/wibox/widget/init.lua | 2 +- lib/wibox/widget/piechart.lua | 2 +- lib/wibox/widget/progressbar.lua | 2 +- lib/wibox/widget/separator.lua | 2 +- lib/wibox/widget/slider.lua | 2 +- lib/wibox/widget/systray.lua | 2 +- lib/wibox/widget/textbox.lua | 2 +- lib/wibox/widget/textclock.lua | 2 +- objects/screen.c | 2 +- 55 files changed, 85 insertions(+), 56 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 7883fa5ec..8a0494569 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -52,6 +52,8 @@ tparam_alias('tab', 'table') tparam_alias('screen', 'screen') tparam_alias('screen_or_idx', 'screen|int') +-- The first stereotype are the constructors. +new_type("constructorfct", "Constructors", false, "Parameters") -- Hack to get the functions on top of the signals and properties new_type("function", "Functions", false, "Parameters") -- Documentation for objects properties @@ -223,8 +225,14 @@ custom_display_name_handler = function(item, default_handler) -- more consistent. Right now some have their full awful.foo.bar while other -- have "just" `bar`. Given we use constructors from metatables, we have no -- choice but to use the full function name. It also makes copy/paste easier. - if item.type == "function" and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then - return item.module.name .. "." .. ret + if (item.type == "function" or item.type == "constructorfct") + and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then + ret = item.module.name .. "." .. ret + end + + -- It isn't there by default. + if item.type == "constructorfct" then + ret = ret .. " " .. item.args end return ret diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index 044deae5f..a92787451 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -125,6 +125,7 @@ widget.merge_duplicates = true -- @tparam[opt] table args.labels Labels used for displaying human-readable keynames. -- @tparam[opt] table args.group_rules Rules for showing 3rd-party hotkeys. @see `awful.hotkeys_popup.keys.vim`. -- @return Widget instance. +-- @constructorfct awful.widget.hotkeys_popup.widget.new function widget.new(args) args = args or {} local widget_instance = { diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index 5036b0688..65b7629cb 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -663,7 +663,7 @@ end -- @tparam[opt=false] boolean args.autostart Start the grabbing immediately -- @tparam[opt=false] boolean args.mask_modkeys Do not call the callbacks on -- modifier keys (like `Control` or `Mod4`) events. --- @function awful.keygrabber +-- @constructorfct awful.keygrabber function keygrab.run_with_keybindings(args) args = args or {} diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index 66efbf134..c9e97e8f8 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -394,7 +394,7 @@ end -- @tparam table|number args.offset The X and Y offset compared to the parent object -- @tparam boolean args.hide_on_right_click Whether or not to hide the popup on -- right clicks. --- @function awful.popup +-- @constructorfct awful.popup local function create_popup(_, args) assert(args) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 6b7439395..9066f5d3f 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -259,7 +259,7 @@ end -- layout = awful.layout.suit.max, -- }) -- --- @function awful.tag.add +-- @constructorfct awful.tag.add -- @param name The tag name, a string -- @param props The tags inital properties, a table -- @return The created tag diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 793abf204..85d318144 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -502,7 +502,7 @@ end -- @tparam[opt=top] string args.fg_normal -- @tparam[opt=top] string args.fg_focus -- @tparam[opt=top] string args.font --- @function awful.titlebar +-- @constructorfct awful.titlebar local function new(c, args) args = args or {} local position = args.position or "top" diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index 5cfbad24e..0420eb72c 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -577,7 +577,7 @@ end -- @see text -- @see markup -- @see align --- @function awful.tooltip +-- @constructorfct awful.tooltip function tooltip.new(args) -- gears.object, properties are linked to set_/get_ functions local self = object { diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index bb7da67e0..84846be72 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -344,7 +344,7 @@ end -- @tparam string args.stretch If the wibar need to be stretched to fill the screen. --@DOC_wibox_constructor_COMMON@ -- @return The new wibar --- @function awful.wibar +-- @constructorfct awful.wibar function awfulwibar.new(args) args = args or {} local position = args.position or "top" diff --git a/lib/awful/widget/button.lua b/lib/awful/widget/button.lua index db6629a22..4a4b398b7 100644 --- a/lib/awful/widget/button.lua +++ b/lib/awful/widget/button.lua @@ -24,6 +24,7 @@ local button = { mt = {} } --- Create a button widget. When clicked, the image is deplaced to make it like -- a real button. -- +-- @constructorfct awful.widget.button -- @param args Widget arguments. "image" is the image to display. -- @return A textbox widget configured as a button. function button.new(args) diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index fe3fdc78d..566218768 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -371,7 +371,7 @@ end -- @tparam table args.style_normal Cell style for the normal day cells (see `cell_properties`) -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`) -- @treturn wibox A wibox containing the calendar --- @function awful.widget.calendar_popup.month +-- @constructorfct awful.widget.calendar_popup.month function calendar_popup.month(args) return get_cal_wibox("month", args) end @@ -407,7 +407,7 @@ end -- @tparam table args.style_normal Cell style for the normal day cells (see `cell_properties`) -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`) -- @treturn wibox A wibox containing the calendar --- @function awful.widget.calendar_popup.year +-- @constructorfct awful.widget.calendar_popup.year function calendar_popup.year(args) return get_cal_wibox("year", args) end diff --git a/lib/awful/widget/clienticon.lua b/lib/awful/widget/clienticon.lua index bafda1d2c..69e53aca5 100644 --- a/lib/awful/widget/clienticon.lua +++ b/lib/awful/widget/clienticon.lua @@ -99,7 +99,7 @@ end --- Returns a new clienticon. -- @tparam client c The client whose icon should be displayed. -- @treturn widget A new `widget` --- @function awful.widget.clienticon +-- @constructorfct awful.widget.clienticon local function new(c) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index 35f8a81a4..3c15799c6 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -252,7 +252,11 @@ local function update_layout(self) update_status(self) end ---- Create a keyboard layout widget. It shows current keyboard layout name in a textbox. +--- Create a keyboard layout widget. +-- +-- It shows current keyboard layout name in a textbox. +-- +-- @constructorfct awful.widget.keyboardlayout -- @return A keyboard layout widget. function keyboardlayout.new() local widget = textbox() diff --git a/lib/awful/widget/launcher.lua b/lib/awful/widget/launcher.lua index e8c6959e1..4c2ff0c47 100644 --- a/lib/awful/widget/launcher.lua +++ b/lib/awful/widget/launcher.lua @@ -16,6 +16,7 @@ local launcher = { mt = {} } -- @param args Standard widget table arguments, plus image for the image path -- and command for the command to run on click, or either menu to create menu. -- @return A launcher widget. +-- @constructorfct awful.widget.launcher function launcher.new(args) if not args.command and not args.menu then return end local w = wbutton(args) diff --git a/lib/awful/widget/layoutbox.lua b/lib/awful/widget/layoutbox.lua index 56e671a3b..5583e6836 100644 --- a/lib/awful/widget/layoutbox.lua +++ b/lib/awful/widget/layoutbox.lua @@ -44,6 +44,7 @@ end -- symbol of the current tag. -- @param screen The screen number that the layout will be represented for. -- @return An imagebox widget configured as a layoutbox. +-- @constructorfct awful.widget.layoutbox function layoutbox.new(screen) screen = get_screen(screen or 1) diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index 1d2d5be48..6cb3ff18e 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -382,7 +382,7 @@ end -- @tparam string|pattern args.style.shape_border_width_selected -- @tparam string|pattern args.style.shape_border_color_selected -- @treturn widget The action widget. --- @function awful.widget.layoutlist +-- @constructorfct awful.widget.layoutlist local is_connected, instances = false, setmetatable({}, {__mode = "v"}) diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua index 95bec1661..37ce050df 100644 --- a/lib/awful/widget/only_on_screen.lua +++ b/lib/awful/widget/only_on_screen.lua @@ -91,7 +91,7 @@ end -- @param[opt] widget The widget to display. -- @param[opt] s The screen to display on. -- @treturn table A new only_on_screen container --- @function wibox.container.only_on_screen +-- @constructorfct awful.widget.only_on_screen local function new(widget, s) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/awful/widget/prompt.lua b/lib/awful/widget/prompt.lua index 13853f29a..e58d8eeaa 100644 --- a/lib/awful/widget/prompt.lua +++ b/lib/awful/widget/prompt.lua @@ -113,7 +113,7 @@ end -- for the matching modifiers + key. See @{awful.prompt.run} for details. -- @return An instance of prompt widget, inherits from -- `wibox.container.background`. --- @function awful.widget.prompt +-- @constructorfct awful.widget.prompt function widgetprompt.new(args) args = args or {} local promptbox = background() diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index 8e6d40507..8be36dc5d 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -462,7 +462,7 @@ end -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function -- @param base_widget **DEPRECATED** use args.base_widget --- @function awful.widget.taglist +-- @constructorfct awful.widget.taglist function taglist.new(args, filter, buttons, style, update_function, base_widget) local screen = nil diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 240a59839..89942037d 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -518,7 +518,7 @@ end -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function -- @param base_widget **DEPRECATED** use args.base_widget --- @function awful.tasklist +-- @constructorfct awful.widget.tasklist function tasklist.new(args, filter, buttons, style, update_function, base_widget) local screen = nil diff --git a/lib/awful/widget/watch.lua b/lib/awful/widget/watch.lua index 42e0c3649..03926c14e 100644 --- a/lib/awful/widget/watch.lua +++ b/lib/awful/widget/watch.lua @@ -64,6 +64,7 @@ local watch = { mt = {} } -- -- @return The widget used by this watch. -- @return Its gears.timer. +-- @constructorfct awful.widget.watch function watch.new(command, timeout, callback, base_widget) timeout = timeout or 5 base_widget = base_widget or textbox() diff --git a/lib/gears/cache.lua b/lib/gears/cache.lua index dc5add5fc..9fb1d908b 100644 --- a/lib/gears/cache.lua +++ b/lib/gears/cache.lua @@ -37,6 +37,7 @@ end -- garbage-collected at any time, but might be useful to keep. -- @param creation_cb Callback that is used for creating missing cache entries. -- @return A new cache object. +-- @constructorfct gears.cache function cache.new(creation_cb) return setmetatable({ _cache = setmetatable({}, { __mode = "v" }), diff --git a/lib/gears/matrix.lua b/lib/gears/matrix.lua index a6bc97554..f66a40046 100644 --- a/lib/gears/matrix.lua +++ b/lib/gears/matrix.lua @@ -20,6 +20,7 @@ local matrix_mt = {} -- @tparam number x0 The x0 transformation part. -- @tparam number y0 The y0 transformation part. -- @return A new matrix describing the given transformation. +-- @constructorfct create function matrix.create(xx, yx, xy, yy, x0, y0) return setmetatable({ xx = xx, xy = xy, x0 = x0, @@ -31,6 +32,7 @@ end -- @tparam number x The translation in x direction. -- @tparam number y The translation in y direction. -- @return A new matrix describing the given transformation. +-- @constructorfct create_translate function matrix.create_translate(x, y) return matrix.create(1, 0, 0, 1, x, y) end @@ -39,6 +41,7 @@ end -- @tparam number sx The scaling in x direction. -- @tparam number sy The scaling in y direction. -- @return A new matrix describing the given transformation. +-- @constructorfct create_scale function matrix.create_scale(sx, sy) return matrix.create(sx, 0, 0, sy, 0, 0) end @@ -46,6 +49,7 @@ end --- Create a new rotation matrix -- @tparam number angle The angle of the rotation in radians. -- @return A new matrix describing the given transformation. +-- @constructorfct create_rotate function matrix.create_rotate(angle) local c, s = math.cos(angle), math.sin(angle) return matrix.create(c, s, -s, c, 0, 0) @@ -56,6 +60,7 @@ end -- @tparam number y The vertical rotation point -- @tparam number angle The angle of the rotation in radians. -- @return A new matrix describing the given transformation. +-- @constructorfct create_rotate_at function matrix.create_rotate_at(x, y, angle) return matrix.create_translate( -x, -y ) * matrix.create_rotate ( angle ) diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index f7c39db1b..ab51e006f 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -157,7 +157,7 @@ local timer_instance_mt = { -- "timeout" signal. -- @tparam[opt=false] boolean args.single_shot Run only once then stop. -- @treturn timer --- @function gears.timer +-- @constructorfct gears.timer function timer.new(args) args = args or {} local ret = object() @@ -257,6 +257,8 @@ function timer.mt.__call(_, ...) return timer.new(...) end +--@DOC_object_COMMON@ + return setmetatable(timer, timer.mt) -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index a16a95706..bf98e712f 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -14,7 +14,7 @@ local gobject = require("gears.object") local action = {} --- Create a new action. --- @function naughty.action +-- @constructorfct naughty.action -- @tparam table args The arguments. -- @tparam string args.name The name. -- @tparam string args.position The position. @@ -124,4 +124,6 @@ local function new(_, args) return ret end +--@DOC_object_COMMON@ + return setmetatable(action, {__call = new}) diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 2a355cb3c..4e00d58f1 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -451,7 +451,7 @@ end -- @usage naughty.notify({ title = "Achtung!", message = "You're idling", timeout = 0 }) -- @treturn ?table The notification object, or nil in case a notification was -- not displayed. --- @function naughty.notification +-- @constructorfct naughty.notification local function create(args) if cst.config.notify_callback then args = cst.config.notify_callback(args) diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index 281753378..5b5f495a1 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -316,7 +316,7 @@ end --- Returns a new arcchart layout. -- @param[opt] widget The widget to display. --- @function wibox.container.arcchart +-- @constructorfct wibox.container.arcchart local function new(widget) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index 73d89dd56..455fe0477 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -385,7 +385,7 @@ end -- @param[opt] widget The widget to display. -- @param[opt] bg The background to use for that widget. -- @param[opt] shape A `gears.shape` compatible shape function --- @function wibox.container.background +-- @constructorfct wibox.container.background local function new(widget, bg, shape) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index 8fd84dc24..0d9377071 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -136,7 +136,7 @@ end -- @param[opt] width The maximum width of the widget. nil for no limit. -- @param[opt] height The maximum height of the widget. nil for no limit. -- @treturn table A new constraint container --- @function wibox.container.constraint +-- @constructorfct wibox.container.constraint local function new(widget, strategy, width, height) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index 9a5fcd4f1..78d74cc1a 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -190,7 +190,7 @@ end -- @param[opt] color A color for the margins. -- @param[opt] draw_empty whether or not to draw the margin when the content is empty -- @treturn table A new margin container --- @function wibox.container.margin +-- @constructorfct wibox.container.margin local function new(widget, left, right, top, bottom, color, draw_empty) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua index ac41d41d6..fa86ec867 100644 --- a/lib/wibox/container/mirror.lua +++ b/lib/wibox/container/mirror.lua @@ -108,7 +108,7 @@ end -- @param[opt] widget The widget to display. -- @param[opt] reflection A table describing the reflection to apply. -- @treturn table A new mirror container --- @function wibox.container.mirror +-- @constructorfct wibox.container.mirror local function new(widget, reflection) local ret = base.make_widget(nil, nil, {enable_properties = true}) ret._private.horizontal = false diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua index 86c7b5fe7..fca974191 100644 --- a/lib/wibox/container/place.lua +++ b/lib/wibox/container/place.lua @@ -172,7 +172,7 @@ end -- @tparam[opt="center"] string halign The horizontal alignment -- @tparam[opt="center"] string valign The vertical alignment -- @treturn table A new place container. --- @function wibox.container.place +-- @constructorfct wibox.container.place local function new(widget, halign, valign) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index 766ec8180..3d698792c 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -233,7 +233,7 @@ end --- Returns a new radialprogressbar layout. A radialprogressbar layout -- radialprogressbars a given widget. Use `.widget` to set the widget. -- @param[opt] widget The widget to display. --- @function wibox.container.radialprogressbar +-- @constructorfct wibox.container.radialprogressbar local function new(widget) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index a0f2775a3..5a3f784cd 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -133,7 +133,7 @@ end -- @param[opt] widget The widget to display. -- @param[opt] dir The direction to rotate to. -- @treturn table A new rotate container. --- @function wibox.container.rotate +-- @constructorfct wibox.container.rotate local function new(widget, dir) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua index 4f63377d5..06413078f 100644 --- a/lib/wibox/container/scroll.lua +++ b/lib/wibox/container/scroll.lua @@ -425,7 +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 +-- @constructorfct 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 @@ -440,7 +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 +-- @constructorfct 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 diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index 3f72b82b1..f55a899e3 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -253,7 +253,7 @@ end -- @tparam[opt=nil] table args --@DOC_wibox_constructor_COMMON@ -- @treturn wibox The new wibox --- @function .wibox +-- @constructorfct wibox local function new(args) args = args or {} diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index 1271b7e4a..283a395e4 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -279,6 +279,7 @@ end -- three widgets. The widget set via :set_left() is left-aligned. :set_right() -- sets a widget which will be right-aligned. The remaining space between those -- two will be given to the widget set via :set_middle(). +-- @constructorfct wibox.layout.align.horizontal -- @tparam[opt] widget left Widget to be put to the left. -- @tparam[opt] widget middle Widget to be put to the middle. -- @tparam[opt] widget right Widget to be put to the right. @@ -296,6 +297,7 @@ end -- three widgets. The widget set via :set_top() is top-aligned. :set_bottom() -- sets a widget which will be bottom-aligned. The remaining space between those -- two will be given to the widget set via :set_middle(). +-- @constructorfct wibox.layout.align.vertical -- @tparam[opt] widget top Widget to be put to the top. -- @tparam[opt] widget middle Widget to be put to the middle. -- @tparam[opt] widget bottom Widget to be put to the right. diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index a6f5ca2a0..aedfbeac3 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -322,7 +322,7 @@ end -- Note that widgets ignore `forced_height`. They will use the preferred/minimum width -- on the horizontal axis, and a stretched height on the vertical axis. -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.fixed.horizontal +-- @constructorfct wibox.layout.fixed.horizontal function fixed.horizontal(...) return get_layout("x", ...) end @@ -333,7 +333,7 @@ end -- Note that widgets ignore `forced_width`. They will use the preferred/minimum height -- on the vertical axis, and a stretched width on the horizontal axis. -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.fixed.vertical +-- @constructorfct wibox.layout.fixed.vertical function fixed.vertical(...) return get_layout("y", ...) end diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index 59815c433..c37d81763 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -170,7 +170,7 @@ end --- Returns a new horizontal flex layout. A flex layout shares the available space -- equally among all widgets. Widgets can be added via :add(widget). -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.flex.horizontal +-- @constructorfct wibox.layout.flex.horizontal function flex.horizontal(...) return get_layout("horizontal", ...) end @@ -178,7 +178,7 @@ end --- Returns a new vertical flex layout. A flex layout shares the available space -- equally among all widgets. Widgets can be added via :add(widget). -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.flex.vertical +-- @constructorfct wibox.layout.flex.vertical function flex.vertical(...) return get_layout("vertical", ...) end diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index 483852042..1322a6e9e 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -885,7 +885,7 @@ end -- -- A grid layout sets widgets in a grids of custom number of rows and columns. -- @tparam[opt="y"] string orientation The preferred grid extension direction. --- @function wibox.layout.grid +-- @constructorfct wibox.layout.grid local function new(orientation) -- Preference for vertical direction: fill rows first, extend grid with new row local dir = (orientation == "horizontal"or orientation == "vertical") @@ -924,7 +924,7 @@ end -- up to `forced_num_rows`. Then the next column is filled, creating it if it doesn't exist. -- @tparam number|nil forced_num_rows Forced number of rows (`nil` for automatic). -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.grid.horizontal +-- @constructorfct wibox.layout.grid.horizontal function grid.horizontal(forced_num_rows, widget, ...) local ret = new("horizontal") ret:set_forced_num_rows(forced_num_rows) @@ -942,7 +942,7 @@ end -- up to `forced_num_cols`. Then the next row is filled, creating it if it doesn't exist. -- @tparam number|nil forced_num_cols Forced number of columns (`nil` for automatic). -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.grid.vertical +-- @constructorfct wibox.layout.grid.vertical function grid.vertical(forced_num_cols, widget, ...) local ret = new("vertical") ret:set_forced_num_cols(forced_num_cols) diff --git a/lib/wibox/layout/manual.lua b/lib/wibox/layout/manual.lua index 6fa617eee..d263141b2 100644 --- a/lib/wibox/layout/manual.lua +++ b/lib/wibox/layout/manual.lua @@ -212,7 +212,7 @@ function manual_layout:reset() end --- Create a manual layout. --- @function wibox.layout.manual +-- @constructorfct wibox.layout.manual -- @tparam table ... Widgets to add to the layout. local function new_manual(...) diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua index 9055392a9..0e8f18ac6 100644 --- a/lib/wibox/layout/ratio.lua +++ b/lib/wibox/layout/ratio.lua @@ -457,7 +457,7 @@ end --- 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 +-- @constructorfct wibox.layout.ratio.horizontal -- @tparam widget ... Widgets that should be added to the layout. function ratio.horizontal(...) return get_layout("horizontal", ...) @@ -465,7 +465,7 @@ end --- 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 +-- @constructorfct 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 510a79504..e55930db9 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -156,7 +156,7 @@ function stack:set_vertical_offset(value) end --- Create a new stack layout. --- @function wibox.layout.stack +-- @constructorfct wibox.layout.stack -- @treturn widget A new stack layout local function new(...) diff --git a/lib/wibox/widget/calendar.lua b/lib/wibox/widget/calendar.lua index 932c21dda..3aef7c33c 100644 --- a/lib/wibox/widget/calendar.lua +++ b/lib/wibox/widget/calendar.lua @@ -352,7 +352,7 @@ end -- @tparam number|nil date.day Date day -- @tparam[opt="Monospace 10"] string font Font of the calendar -- @treturn widget The month calendar widget --- @function wibox.widget.calendar.month +-- @constructorfct wibox.widget.calendar.month function calendar.month(date, font) return get_calendar("month", date, font) end @@ -368,7 +368,7 @@ end -- @tparam number|nil date.day Date day -- @tparam[opt="Monospace 10"] string font Font of the calendar -- @treturn widget The year calendar widget --- @function wibox.widget.calendar.year +-- @constructorfct wibox.widget.calendar.year function calendar.year(date, font) return get_calendar("year", date, font) end diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index 10df7e2d3..efe10ec44 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -225,7 +225,7 @@ function checkbox:set_paddings(val) end --- Create a new checkbox. --- @function wibox.widget.checkbox +-- @constructorfct wibox.widget.checkbox -- @tparam[opt=false] boolean checked -- @tparam[opt] table args -- @tparam gears.color args.color The color. diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index a8cb54802..0482969f1 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -319,7 +319,7 @@ end -- @param args Standard widget() arguments. You should add width and height -- key to set graph geometry. -- @return A new graph widget. --- @function wibox.widget.graph +-- @constructorfct wibox.widget.graph function graph.new(args) args = args or {} diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index cb121fc2b..61e35f8c3 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -157,7 +157,7 @@ end -- to fit into the available space. -- @param clip_shape A `gears.shape` compatible function -- @treturn table A new `imagebox` --- @function wibox.widget.imagebox +-- @constructorfct wibox.widget.imagebox local function new(image, resize_allowed, clip_shape) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index 4793206f1..d151e8de3 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.widget +-- @module wibox.widget --------------------------------------------------------------------------- local cairo = require("lgi").cairo diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 7f22a7c21..2e57e9522 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -219,7 +219,7 @@ function piechart:get_data() end --- Create a new piechart. --- @function wibox.widget.piechart +-- @constructorfct wibox.widget.piechart -- @tparam table data_list The data. local function new(data_list) diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index d2eacaccc..d6497476e 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -427,7 +427,7 @@ end -- @param args Standard widget() arguments. You should add width and height -- key to set progressbar geometry. -- @return A progressbar widget. --- @function wibox.widget.progressbar +-- @constructorfct wibox.widget.progressbar function progressbar.new(args) args = args or {} diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index c02c9c8a5..a02e8433a 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -186,7 +186,7 @@ for _, prop in ipairs {"orientation", "color", "thickness", "span_ratio", end --- Create a new separator. --- @function wibox.widget.separator +-- @constructorfct wibox.widget.separator -- @tparam table args The arguments (all properties are available). local function new(args) diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua index 15d418139..63a10f746 100644 --- a/lib/wibox/widget/slider.lua +++ b/lib/wibox/widget/slider.lua @@ -475,7 +475,7 @@ end --- Create a slider widget. -- @tparam[opt={}] table args --- @function wibox.widget.slider +-- @constructorfct wibox.widget.slider 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 d9ca261e0..59b715d3e 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -166,7 +166,7 @@ end -- Note that this widget can only exist once. -- @tparam boolean revers Show in the opposite direction -- @treturn table The new `systray` widget --- @function wibox.widget.systray +-- @constructorfct wibox.widget.systray local function new(revers) local ret = wbase.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index fd86832de..6c70d6eb2 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -280,7 +280,7 @@ end -- @tparam[opt=""] string text The textbox content -- @tparam[opt=false] boolean ignore_markup Ignore the pango/HTML markup -- @treturn table A new textbox widget --- @function wibox.widget.textbox +-- @constructorfct wibox.widget.textbox local function new(text, ignore_markup) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index fa1035caa..99f255efe 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -88,7 +88,7 @@ end -- e.g. "Z" for UTC, "±hh:mm" or "Europe/Amsterdam". See -- https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new. -- @treturn table A textbox widget. --- @function wibox.widget.textclock +-- @constructorfct wibox.widget.textclock local function new(format, refresh, tzid) local w = textbox() gtable.crush(w, textclock, true) diff --git a/objects/screen.c b/objects/screen.c index 2f509315b..b3e4f81fd 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -1173,7 +1173,7 @@ luaA_screen_count(lua_State *L) * @tparam integer width width for screen. * @tparam integer height height for screen. * @return The new screen. - * @function fake_add + * @constructorfct fake_add */ static int luaA_screen_fake_add(lua_State *L)