From 4bd90f0f35d0f93235f0bcf207ca16baa174f8a1 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 20 Dec 2021 21:54:15 -0800 Subject: [PATCH] doc: Add documentation linting and fix all issues it found. --- dbus.c | 17 +- docs/05-awesomerc.md.lua | 2 + docs/common/client_theme.ldoc | 66 +- docs/common/notification_rules_index.ldoc | 1 + docs/common/wibox.ldoc | 71 +- docs/common/widget.ldoc | 20 +- docs/config.ld | 759 ++++++++++++++++++++-- docs/ldoc.css | 4 +- docs/ldoc.ltp | 19 +- lib/awful/button.lua | 13 +- lib/awful/client.lua | 24 +- lib/awful/completion.lua | 16 +- lib/awful/hotkeys_popup/init.lua | 2 +- lib/awful/hotkeys_popup/widget.lua | 23 +- lib/awful/key.lua | 12 +- lib/awful/keygrabber.lua | 18 +- lib/awful/layout/init.lua | 26 +- lib/awful/layout/suit/corner.lua | 4 + lib/awful/layout/suit/fair.lua | 2 + lib/awful/layout/suit/floating.lua | 1 + lib/awful/layout/suit/magnifier.lua | 1 + lib/awful/layout/suit/max.lua | 2 + lib/awful/layout/suit/spiral.lua | 2 + lib/awful/layout/suit/tile.lua | 4 + lib/awful/menu.lua | 52 +- lib/awful/mouse/client.lua | 4 +- lib/awful/mouse/init.lua | 14 +- lib/awful/mouse/resize.lua | 10 +- lib/awful/mouse/snap.lua | 4 + lib/awful/permissions/init.lua | 29 +- lib/awful/prompt.lua | 18 +- lib/awful/screen.lua | 10 +- lib/awful/spawn.lua | 2 +- lib/awful/tag.lua | 30 +- lib/awful/titlebar.lua | 341 +++++++--- lib/awful/tooltip.lua | 44 +- lib/awful/util.lua | 51 +- lib/awful/wallpaper.lua | 2 + lib/awful/wibar.lua | 13 + lib/awful/widget/button.lua | 2 +- lib/awful/widget/calendar_popup.lua | 3 +- lib/awful/widget/clienticon.lua | 2 +- lib/awful/widget/common.lua | 6 + lib/awful/widget/keyboardlayout.lua | 7 +- lib/awful/widget/layoutlist.lua | 53 +- lib/awful/widget/only_on_screen.lua | 2 +- lib/awful/widget/prompt.lua | 12 +- lib/awful/widget/taglist.lua | 71 +- lib/awful/widget/tasklist.lua | 89 +-- lib/awful/widget/watch.lua | 33 +- lib/beautiful/init.lua | 48 +- lib/gears/debug.lua | 4 +- lib/gears/filesystem.lua | 5 +- lib/gears/math.lua | 2 + lib/gears/protected_call.lua | 5 + lib/gears/shape.lua | 6 +- lib/gears/sort/init.lua | 2 +- lib/gears/string.lua | 6 +- lib/gears/surface.lua | 9 +- lib/gears/table.lua | 4 +- lib/gears/timer.lua | 17 +- lib/menubar/icon_theme.lua | 1 + lib/menubar/init.lua | 7 + lib/menubar/utils.lua | 4 +- lib/naughty/action.lua | 6 +- lib/naughty/container/background.lua | 3 +- lib/naughty/init.lua | 2 + lib/naughty/layout/box.lua | 2 +- lib/naughty/layout/legacy.lua | 2 +- lib/naughty/notification.lua | 64 +- lib/naughty/widget/icon.lua | 10 +- lib/naughty/widget/message.lua | 3 +- lib/naughty/widget/title.lua | 3 +- lib/ruled/client.lua | 2 +- lib/ruled/notification.lua | 2 +- lib/wibox/container/arcchart.lua | 29 +- lib/wibox/container/background.lua | 8 +- lib/wibox/container/margin.lua | 18 +- lib/wibox/container/radialprogressbar.lua | 2 +- lib/wibox/container/rotate.lua | 2 +- lib/wibox/container/tile.lua | 16 +- lib/wibox/drawable.lua | 2 +- lib/wibox/init.lua | 2 + lib/wibox/layout/align.lua | 2 +- lib/wibox/layout/fixed.lua | 2 + lib/wibox/layout/flex.lua | 5 +- lib/wibox/layout/grid.lua | 40 +- lib/wibox/layout/stack.lua | 6 +- lib/wibox/widget/background.lua | 2 +- lib/wibox/widget/base.lua | 20 +- lib/wibox/widget/calendar.lua | 31 +- lib/wibox/widget/checkbox.lua | 4 +- lib/wibox/widget/graph.lua | 4 +- lib/wibox/widget/imagebox.lua | 2 +- lib/wibox/widget/init.lua | 2 + lib/wibox/widget/piechart.lua | 2 +- lib/wibox/widget/progressbar.lua | 32 +- lib/wibox/widget/separator.lua | 11 +- lib/wibox/widget/slider.lua | 30 +- lib/wibox/widget/systray.lua | 24 +- lib/wibox/widget/textbox.lua | 13 +- lib/wibox/widget/textclock.lua | 2 +- luaa.c | 2 +- mouse.c | 2 +- mousegrabber.c | 2 +- objects/client.c | 27 +- objects/drawable.c | 7 +- objects/screen.c | 11 +- objects/tag.c | 2 +- root.c | 15 +- xkb.c | 2 +- 111 files changed, 1891 insertions(+), 724 deletions(-) diff --git a/dbus.c b/dbus.c index f339fcddc..97069858c 100644 --- a/dbus.c +++ b/dbus.c @@ -19,7 +19,14 @@ * */ -/** awesome D-Bus API +/** A deprecated low-level D-Bus API **DO NOT USE**. + * + * `lgi.GDBus` is always better. This module will eventually be removed. + * If it ever breaks due to an upstream API change, it wont be fixed. + * + * It still exists for compatibility reasons since some user have used it + * in the past. + * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @module dbus @@ -798,10 +805,10 @@ luaA_dbus_disconnect_signal(lua_State *L) * @param path A string with the dbus path. * @param interface A string with the dbus interface. * @param method A string with the dbus method name. - * @param type_1st_arg type of 1st argument - * @param value_1st_arg value of 1st argument - * @param type_2nd_arg type of 2nd argument - * @param value_2nd_arg value of 2nd argument + * @param type_1st_arg Type of 1st argument + * @param value_1st_arg Value of 1st argument + * @param type_2nd_arg Type of 2nd argument + * @param value_2nd_arg Value of 2nd argument * ... etc * @function emit_signal */ diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index 50965a470..d49fee9cb 100644 --- a/docs/05-awesomerc.md.lua +++ b/docs/05-awesomerc.md.lua @@ -324,6 +324,8 @@ rc_lua:close() table.insert(output_script, "-- @script rc.lua") +table.insert(output_script, "-- @usebeautiful beautiful.awesome_icon") +table.insert(output_script, "-- @usebeautiful beautiful.wallpaper") rc_script = assert(io.open(rc_script, "w")) rc_script:write(table.concat(output_script, "\n")) diff --git a/docs/common/client_theme.ldoc b/docs/common/client_theme.ldoc index 672b41b37..f62085619 100644 --- a/docs/common/client_theme.ldoc +++ b/docs/common/client_theme.ldoc @@ -344,6 +344,21 @@ * @see request::border */ +/** + * The client border width for the fullscreen clients. + * + * This is the fallback if the more stateful version, like + * `beautiful.border_width_fullscreen_urgent` isn't set. + * + * @beautiful beautiful.border_width_fullscreen + * @param integer + * @see request::border + * @see beautiful.border_width_fullscreen_active + * @see beautiful.border_width_fullscreen_normal + * @see beautiful.border_width_fullscreen_urgent + * @see beautiful.border_width_fullscreen_new + */ + /** * The client opacity for the normal clients. * @@ -391,7 +406,6 @@ * * @beautiful beautiful.opacity_floating_normal * @param[opt=1] number - * @see request::border */ /** @@ -424,6 +438,21 @@ * @see request::border */ +/** + * The client opacity for the floating clients. + * + * A number between 0 and 1. This is the fallback if the more stateful + * variables, like `beautiful.opacity_floating_new` are not set. + * + * @beautiful beautiful.opacity_floating + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_floating_normal + * @see beautiful.opacity_floating_active + * @see beautiful.opacity_floating_urgent + * @see beautiful.opacity_floating_new + */ + /** * The client opacity for the normal maximized clients. * @@ -431,7 +460,6 @@ * * @beautiful beautiful.opacity_maximized_normal * @param[opt=1] number - * @see request::border */ /** @@ -463,6 +491,22 @@ * @param[opt=1] number * @see request::border */ + +/** + * The client opacity for the maximized clients. + * + * A number between 0 and 1. This is the fallback if a more stateful + * variable, like `beautiful.opacity_maximized_urgent`, isn't set. + * + * @beautiful beautiful.opacity_maximized + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_maximized_normal + * @see beautiful.opacity_maximized_active + * @see beautiful.opacity_maximized_urgent + * @see beautiful.opacity_maximized_new + */ + /** * The client opacity for the normal fullscreen clients. * @@ -470,7 +514,6 @@ * * @beautiful beautiful.opacity_fullscreen_normal * @param[opt=1] number - * @see request::border */ /** @@ -503,4 +546,21 @@ * @see request::border */ +/** + * The client opacity for the fullscreen clients. + * + * A number between 0 and 1. This is the fallback if the variables + * for more stateful versions, like `beautiful.opacity_fullscreen_urgent`, + * are not set. + * + * @beautiful beautiful.opacity_fullscreen + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_fullscreen_new + * @see beautiful.opacity_fullscreen_urgent + * @see beautiful.opacity_fullscreen_active + * @see beautiful.opacity_fullscreen_normal + */ + + /* diff --git a/docs/common/notification_rules_index.ldoc b/docs/common/notification_rules_index.ldoc index 35fc30f79..1387c2fdb 100644 --- a/docs/common/notification_rules_index.ldoc +++ b/docs/common/notification_rules_index.ldoc @@ -37,6 +37,7 @@ -- auto\_reset\_timeoutIf the timeout needs to be reset when a property changes -- ignore\_suspend -- clientsA list of clients associated with this notification +-- max\_widthThe maximum popup width -- app\_nameThe application name specified by the notification -- widget\_templateThe widget template used to represent the notification -- diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc index dc46c6ea8..b12440524 100644 --- a/docs/common/wibox.ldoc +++ b/docs/common/wibox.ldoc @@ -2,7 +2,7 @@ -- -- @baseclass wibox -- @property border_width --- @param integer +-- @tparam[opt=0] integer border_width -- @propemits false false --- Border color. @@ -25,21 +25,21 @@ -- -- @baseclass wibox -- @property border_color --- @param string +-- @tparam[opt=beautiful.fg_normal] string border_color -- @propemits false false --- On top of other windows. -- -- @baseclass wibox -- @property ontop --- @param boolean +-- @tparam[opt=false] boolean ontop -- @propemits false false --- The mouse cursor. -- -- @baseclass wibox -- @property cursor --- @param string +-- @tparam string cursor -- @see mouse -- @propemits false false @@ -47,7 +47,7 @@ -- -- @baseclass wibox -- @property visible --- @param boolean +-- @tparam boolean visible -- @propemits false false --- The opacity of the wibox, between 0 and 1. @@ -61,7 +61,7 @@ -- -- @baseclass wibox -- @property type --- @param string +-- @tparam string type -- @see client.type -- @propemits false false @@ -69,35 +69,35 @@ -- -- @baseclass wibox -- @property x --- @param integer +-- @tparam integer x -- @propemits false false --- The y coordinates. -- -- @baseclass wibox -- @property y --- @param integer +-- @tparam integer y -- @propemits false false --- The width of the wibox. -- -- @baseclass wibox -- @property width --- @param width +-- @tparam integer width -- @propemits false false --- The height of the wibox. -- -- @baseclass wibox -- @property height --- @param height +-- @tparam integer height -- @propemits false false --- The wibox screen. -- -- @baseclass wibox -- @property screen --- @param screen +-- @tparam screen screen -- @propemits true false --- The wibox's `drawable`. @@ -110,14 +110,14 @@ --- The widget that the `wibox` displays. -- @baseclass wibox -- @property widget --- @param widget +-- @tparam[opt=nil] wibox.widget widget -- @propemits true false --- The X window id. -- -- @baseclass wibox -- @property window --- @param string +-- @tparam string window -- @see client.window -- @propemits false false @@ -129,7 +129,7 @@ -- -- @baseclass wibox -- @property shape_bounding --- @param surface._native +-- @tparam surface._native shape_bounding -- @propemits false false -- @see shape @@ -140,7 +140,7 @@ -- -- @baseclass wibox -- @property shape_clip --- @param surface._native +-- @tparam surface._native shape_clip -- @propemits false false -- @see shape @@ -152,7 +152,7 @@ -- -- @baseclass wibox -- @property shape_input --- @param surface._native +-- @tparam surface._native shape_input -- @propemits false false -- @see input_passthrough @@ -174,7 +174,7 @@ -- -- @baseclass wibox -- @property input_passthrough --- @param[opt=false] boolean +-- @tparam[opt=false] boolean input_passthrough -- @see shape_input -- @propemits true false @@ -182,14 +182,15 @@ -- -- @baseclass wibox -- @property buttons --- @param buttons_table A table of buttons objects, or nothing. +-- @tparam table buttons A table of buttons objects, or nothing. -- @propemits false false --- Get or set wibox geometry. That's the same as accessing or setting the x, -- y, width or height properties of a wibox. -- -- @baseclass wibox --- @param A table with coordinates to modify. +-- @tparam[opt=nil] table|nil geo A table with coordinates to modify. If +-- nothing is specified, it only returns the current geometry. -- @return A table with wibox coordinates and geometry. -- @method geometry -- @emits property::geometry When the geometry change. @@ -205,31 +206,12 @@ -- the side of the screen). -- -- @baseclass wibox --- @param strut A table with new strut, or nothing -- @return The wibox strut in a table. -- @method struts +-- @tparam table struts A table with new strut, or nothing. -- @see client.struts -- @emits property::struts ---- The default background color. --- --- The background color can be transparent. If there is a --- compositing manager such as compton, then it will be --- real transparency and may include blur (provided by the --- compositor). When there is no compositor, it will take --- a picture of the wallpaper and blend it. --- --- @baseclass wibox --- @beautiful beautiful.bg_normal --- @param color --- @see bg - ---- The default foreground (text) color. --- @baseclass wibox --- @beautiful beautiful.fg_normal --- @param color --- @see fg - --- 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 @@ -246,8 +228,8 @@ -- -- @baseclass wibox -- @property bg --- @tparam c The background to use. This must either be a cairo pattern object, --- nil or a string that gears.color() understands. +-- @tparam[opt=beautiful.bg_normal] color bg The background to use. This +-- must either be a cairo pattern object, nil or a string that gears.color() understands. -- @see gears.color -- @propemits true false -- @usebeautiful beautiful.bg_normal The default (fallback) bg color. @@ -257,18 +239,17 @@ -- If `image` is a function, it will be called with `(context, cr, width, height)` -- as arguments. Any other arguments passed to this method will be appended. -- --- @tparam gears.suface|string|function image A background image or a function. -- @baseclass wibox -- @property bgimage +-- @tparam gears.suface|string|function bgimage A background image or a function. -- @see gears.surface -- @propemits true false --- The foreground (text) of the wibox. --- @tparam color c The foreground to use. This must either be a cairo pattern object, --- nil or a string that gears.color() understands. +-- -- @baseclass wibox -- @property fg --- @param color +-- @tparam[opt=beautiful.fg_normal] gears.color fg -- @see gears.color -- @propemits true false -- @usebeautiful beautiful.fg_normal The default (fallback) fg color. diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index 36e994d5f..a08fdc75c 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -19,23 +19,23 @@ -- Warning: This method it prone to stack overflow id the widget, or any of its -- children, contain (directly or indirectly) itself. -- @property all_children --- @tparam table children The children. +-- @tparam table all_children The children. -- @baseclass wibox.widget --- 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 +-- @tparam table args An array containing the widgets disposition -- @method setup -- @baseclass wibox.widget --- Force a widget height. -- @property forced_height --- @tparam number|nil height The height (`nil` for automatic) +-- @tparam number|nil forced_height The height (`nil` for automatic) -- @baseclass wibox.widget --- Force a widget width. -- @property forced_width --- @tparam number|nil width The width (`nil` for automatic) +-- @tparam number|nil forced_width The width (`nil` for automatic) -- @baseclass wibox.widget --- The widget opacity (transparency). @@ -45,7 +45,7 @@ --- The widget visibility. -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @baseclass wibox.widget --- The widget buttons. @@ -53,7 +53,7 @@ -- The table contains a list of `awful.button` objects. -- -- @property buttons --- @param table +-- @tparam table buttons -- @see awful.button -- @baseclass wibox.widget @@ -96,7 +96,7 @@ -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -127,7 +127,7 @@ -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -152,7 +152,7 @@ -- @signal mouse::enter -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -177,7 +177,7 @@ -- @signal mouse::leave -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. diff --git a/docs/config.ld b/docs/config.ld index fd12514e9..a92528d74 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -1,24 +1,27 @@ local args = ... +local ldoc = nil +-- luacheck: globals new_type -- Configuration file for ldoc -project='awesome' -title='awesome API documentation' -description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).' +project='awesome' -- luacheck: globals project +title='awesome API documentation' -- luacheck: globals title +description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).' -- luacheck: globals description --- More on it: https://github.com/stevedonovan/LDoc/blob/master/doc/doc.md#markdown-support -format='discount' -dir='../doc' +format='discount' -- luacheck: globals format +dir='../doc' -- luacheck: globals dir -- Make the docs prettier -pretty='lua' -style=true -template=true -backtick_references=true -merge=true -use_markdown_titles=true -wrap=true +pretty='lua' -- luacheck: globals pretty +style=true -- luacheck: globals style +template=true -- luacheck: globals template +backtick_references=true -- luacheck: globals backtick_references +merge=true -- luacheck: globals merge +use_markdown_titles=true -- luacheck: globals use_markdown_titles +wrap=true -- luacheck: globals wrap + + -- luacheck: globals full_description full_description = [[ Welcome to the documentation for the Awesome window manager. Below you find an overview of the individual parts which links to the full documentation. @@ -92,52 +95,327 @@ topics={ '89-NEWS.md', } +local databases, named_tags, item_id, is_init = {}, {}, 1, false +local all_theme_vars, delayed_collect = nil, {} + +local function collect_item_common(tab, mod, item) + tab[item.name] = tab[item.name] or {} + + local var = tab[item.name] + var[mod.name] = var[mod.name] or {} + var[mod.name][#var[mod.name] + 1] = item +end + +--- Add another custom tag **value** to an existing item. +-- @tparam string tag_data The raw/unparsed string for the +-- tag. It will be parsed like any other tags. +local function add_custom_tag_common(item, tag_name, meta_tag, tag_data) + item.tags = item.tags or {} + + item.tags[tag_name] = item.tags[tag_name] or {} + + item.tags[tag_name][#item.tags[tag_name] + 1] = tag_data + + if meta_tag.collect_callback then + delayed_collect[#delayed_collect+1] = {item, item.module, tag_name, tag_data} + end +end + +-- Wrap the global `new_type` to allow us to extend what types can do, the +-- same is done below for custom tags. +local function create_type(args) + new_type(args.name, args.title, args.project_level, args.subfield_title) + + databases[args.name] = databases[args.name] or {} + databases[args.name].collect = args.collect_callback + databases[args.name].finish = args.finish_callback + + return args +end + +-- Add the @usebeautiful from the optional/default value. +local function auto_add_usebeautiful(item) + local vars, var_names = {}, {} + + -- Datamine the default values to autogenerate the @usebeautiful. + for parm in ldoc.modules.iter(item.params) do + for p in ldoc.modules.iter(item:subparam(parm)) do + local def = item:default_of_param(p) + + if def and def ~= true then + for var in def:gmatch("beautiful[.][a-z_]+") do + if not var_names[var] then + vars[#vars+1] = var + end + var_names[var] = true + end + end + end + end + + for _, var in ipairs(vars) do + named_tags.usebeautiful:add_to_item(item, var) + end + end + -- The first stereotype are the constructors. -new_type("constructorfct", "Constructors", false, "Parameters") -new_type("constructorfct2", "ldoc_skip", false, "Parameters") +create_type { + name = "constructorfct", + title = "Constructors", + project_level = false, + subfield_title = "Parameters", + collect_callback = auto_add_usebeautiful, +} + +-- Some constructors like `awful.key` have both a named parameter +-- syntax and a multiple function parameter syntax. +create_type { + name = "constructorfct2", + title = "ldoc_skip", + project_level = false, + subfield_title = "Parameters", +} + -- Hack to get the functions on top of the signals and properties -new_type("function", "Functions", false, "Parameters") +create_type { + name = "function", + title = "Functions", + project_level = false, + subfield_title = "Parameters", +} + -- For "classes", use an explicit type for static functions. This allows -- @function and its implicit cousin to be banned in the CI. -new_type("staticfct", "Static module functions", false, "Parameters") +create_type { + name = "staticfct", + title = "Static module functions", + project_level = false, + subfield_title = "Parameters", +} + -- Documentation for objects properties -new_type("property", "Object properties", false, "Type constraints") +create_type { + name = "property", + title = "Object properties", + project_level = false, + subfield_title = "Type constraints", + collect_callback = auto_add_usebeautiful, + finish_callback = function(item) + -- All properties need to have a type. Otherwise they don't render + -- properly. Also, because typed properties are kind of the point of + -- switching to ldoc in the first place. + if (not item.params) or not item.params[1] then + print( + "WARNING: The ".. item.name .." property from "..item.module.name.." is missing it's type." + ) + return + end + + local param = item:subparam(item.params[1]) + local type = item:type_of_param(param[1]) + + -- Force people to use @tparam because it is easier to lint and allows + -- multiple types. + if (not type) or type == "" then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.." either ".. + " doesn't have a type or uses @param instead of @tparam. @tparam is required".. + " because it allows multi-type and better default value handling." + ) + end + + -- One of the repeated problem we have is the first word of the + -- description being removed because it is used as the property name. + -- This "rule" might be stupid, but it prevents it from accidentally + -- happening again. + if item.params[1] ~= item.name:match("[.]?("..item.params[1]..")$") then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.." @tparam name".. + " doesn't match the property name. For linting purpose, please fix this." + ) + end + end +} + -- Documentation for objects deprecated properties -new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints") +create_type { + name = "deprecatedproperty", + title = "Deprecated object properties", + project_level = false, + subfield_title = "Type constraints", +} + -- Documentation for objects deprecated methods -new_type("deprecatedmethod", "Deprecated object methods", false, "Parameters") +create_type { + name = "deprecatedmethod", + title = "Deprecated object methods", + project_level = false, + subfield_title = "Parameters", +} + -- 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") +create_type { + name = "method", + title = "Object methods ", + project_level = false, + subfield_title = "Parameters", +} + +-- New type for signals. +local all_signals +all_signals = create_type { + name = "signal", + title = "Signals", + project_level = false, + subfield_title = "Arguments", + collection = {}, + collect_callback = function(item, mod) + collect_item_common(all_signals.collection, mod, item) + end, +} + -- Deprecated signals. -new_type("deprecatedsignal", "Deprecated signals", false, "Arguments") +create_type { + name = "deprecatedsignal", + title = "Deprecated signals", + project_level = false, + subfield_title = "Arguments", +} + -- New type for signals connections -new_type("signalhandler", "Request handlers", false, "Arguments") +create_type { + name = "signalhandler", + title = "Request handlers", + project_level = false, + subfield_title = "Arguments", +} + -- Allow objects to define a set of beautiful properties affecting them -new_type("beautiful", "Theme variables", false, "Type constraints") +all_theme_vars = create_type { + name = "beautiful", + title = "Theme variables", + project_level = false, + subfield_title = "Type constraints", + collection = {}, + collect_callback = function(item, mod) + if item.name:sub(1,4) ~= "beau" then + -- This would be a bug. + if item.name:match("[.]") then + print("WANRING: A beautiful variable is called `", item.name, "`. This name is invalid.") + end + + -- This happens because the `ldoc` messes with the name. All variables + if item.module.name == "beautiful" then + item.name = "beautiful." .. item.name + else + print( + "WARNING: All theme variable need a `beautiful.` prefix. It appears", + item.name, + " lacks it" + ) + end + end + + collect_item_common(all_theme_vars.collection, mod, item) + + -- Those are global variables, there can be only one per name. + if all_theme_vars.collection[item.name] then + local mod = pairs(all_theme_vars.collection[item.name])(all_theme_vars.collection[item.name]) + + if mod ~= item.module.name then + print("ERROR: "..item.name, "from", item.module.name, "is already defined in module ", mod) + end + end + end, + finish_callback = function(item) + if item.tags["beautiful_used_by"] then return end + + -- Every variable should be consumed by something. Better "park" some + -- variable in the constructors than leave them disconnected from the + -- global model. + print("WARNING: ", item.name, "is not used by anything, add @usebeautiful or @propbeautiful") + end +} + -- Put deprecated methods in their own section -new_type("deprecated", "Deprecated functions", false, "Parameters") +create_type { + name = "deprecated", + title = "Deprecated functions", + project_level = false, + subfield_title = "Parameters", +} + -- For the legacy stateless layout related functions -new_type("legacylayout", "Layout related functions", false, "Parameters") +create_type { + name = "legacylayout", + title = "Layout related functions", + project_level = false, + subfield_title = "Parameters", +} + -- Have a category for the client layouts -new_type("clientlayout", "Client layouts", false, "Parameters") +create_type { + name = "clientlayout", + title = "Client layouts", + project_level = false, + subfield_title = "Parameters", +} + -- Source functions for the taglist/tasklist/layoutlist -new_type("sourcefunction", "List source functions", false) +create_type { + name = "sourcefunction", + title = "List source functions", + project_level = false, +} + -- Document some callback prototypes -new_type("callback", "Callback functions prototype", false, "Parameters") +create_type { + name = "callback", + title = "Callback functions prototype", + project_level = false, + subfield_title = "Parameters", +} + -- gears.matcher / awful.rules sources -new_type("rulesources", "Rule sources", false, "Parameters") +create_type { + name = "rulesources", + title = "Rule sources", + project_level = false, + subfield_title = "Parameters", +} + -- gears.matcher / awful.rules rule components -new_type("rulecomponent", "Rule components", false, "Type") +create_type { + name = "rulecomponent", + title = "Rule components", + project_level = false, + subfield_title = "Type", +} + -- Filter functions for the taglist/tasklist/layoutlist -new_type("filterfunction", "List filters", false) +create_type { + name = "filterfunction", + title = "List filters", + project_level = false, +} + -- Extra client properties available only in awful.rules/spawn constructs -new_type("clientruleproperty", "Extra properties available in the rules", false, "Type") +create_type { + name = "clientruleproperty", + title = "Extra properties available in the rules", + project_level = false, + subfield_title = "Type", +} + -- Extra *matching* properties for rules. -new_type("matchingproperty", "Extra matching properties used in rules", false, "Type") +create_type { + name = "matchingproperty", + title = "Extra matching properties used in rules", + project_level = false, + subfield_title = "Type", +} -- Simulate the default "params" parser format, except the optional "[]" section -- needs a space. @@ -224,16 +502,18 @@ local function default_format_callback(self, params, _, md) end -- Generate a format function. -local function default_format(self, callback) +local function default_format(self, callback, name) return function(raw, item, md) - return (callback or default_format_callback)( - self, parse_custom_tags(raw, self.params or {}), item, md - ) + local p = name and item.parsed_tags and item.parsed_tags[name] and item.parsed_tags[name][raw] + + if not p then + p = parse_custom_tags(raw, self.params or {}) + end + + return (callback or default_format_callback)(self, p, item, md) end end -local named_tags, item_id = {}, 1 - -- Add a new @something which can be used in any types. -- @tparam table args -- @tparam string args.name The name. @@ -250,9 +530,26 @@ add_custom_tag = function(args) custom_tags = custom_tags or {} + databases[name] = databases[name] or {} + databases[name].collect = args.collect_callback + local f = args.format - args.format = default_format(args, f) + args.format = default_format(args, f, name) + + function args:add_to_item(item, tag_value) + add_custom_tag_common(item, name, args, tag_value) + + local parsed = parse_custom_tags(tag_value, args.params or {}) + + if parsed then + item.parsed_tags = item.parsed_tags or {} + item.parsed_tags[name] = item.parsed_tags[name] or {} + item.parsed_tags[name][tag_value] = parsed + end + + item.has_show_more = item.has_show_more or (not args.hidden) + end custom_tags[#custom_tags+1] = args named_tags[name] = args @@ -288,7 +585,17 @@ add_custom_tag { { name = "name" } - } + }, + collect_callback = function(item, mod, tag, value) + local parsed = parse_custom_tags(value, named_tags.emits.params) + + all_signals.collection[parsed.name.value] = all_signals.collection[parsed.name.value] or {} + + local var = all_signals.collection[parsed.name.value] + + var[mod.name] = var[mod.name] or {} + var[mod.name][#var[mod.name] + 1] = item + end } -- Avoid repetitive boilerplate code for property signals. @@ -349,7 +656,25 @@ add_custom_tag { name = "name", markdown = true, } - } + }, + collect_callback = function(item, mod, tag, value) + local params = parse_custom_tags(value, named_tags.usebeautiful.params) + + if all_theme_vars.collection[params.name.value] then + local sig_mods = all_theme_vars.collection[params.name.value] + local _, themed_items = pairs(sig_mods)(sig_mods) + local themed_item = themed_items[1] + + named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary) + + -- Auto fill the description if its empty. + if (not params.description) or params.description == "" then + params.description = themed_item.summary + end + else + print("WARNING: Could not find theme variable", params.name.value) + end + end } -- For all properties which have a standard `@beautiful` variable for them @@ -380,6 +705,18 @@ add_custom_tag { end return ret + end, + finish_callback = function(item, raw, params, modules) + local modname = item.module.name:gmatch("[^.]+$")() + local name = "beautiful."..(modname.."_"..item.name):gsub("[.]", "_") + + if all_theme_vars.collection[name] then + local sig_mods = all_theme_vars.collection[name] + local _, themed_items = pairs(sig_mods)(sig_mods) + local themed_item = themed_items[1] + + named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary) + end end } @@ -476,7 +813,6 @@ add_custom_tag { add_custom_tag { name = "hidden", hidden = true, - auto_subtags = false } -- Mark the item as readonly. @@ -487,6 +823,87 @@ add_custom_tag { hidden = true, auto_subtags = false } + +add_custom_tag { + name = "signalhandler", + hidden = false, + title = "Request handler", + auto_subtags = false, + params = { + { name = "source" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description + end +} + +add_custom_tag { + name = "beautiful_used_by", + hidden = false, + title = "Used by", + auto_subtags = false, + params = { + { name = "source" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description + end +} + +-- Auto generate some code for replacing request handlers. +add_custom_tag { + name = "sourcesignal", + title = "Source signal", + hidden = false, + params = { + { name = "class" }, + { name = "signal" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.signal.value.."` from the `"..params.class.value.."` module.").. + " This code allows to disconnect this handler and implement your own:" + end, + finish_callback = function(item, raw, params, modules) + if all_signals.collection[params.signal.value] then + local sig_mods = all_signals.collection[params.signal.value] + local _, signal_items = pairs(sig_mods)(sig_mods) + local signal_item = signal_items[1] + + -- Auto generate some code. + local code = "-- Disconnect the original handler.\n" + code = code .. signal_item.module.name .. ".disconnect_signal('".. params.signal.value .."', "..item.name..")\n\n" + code = code .. "-- Connect a custom handler.\n" + code = code .. signal_item.module.name .. ".connect_signal('".. params.signal.value .."', function(" + + + if signal_item.type == "signal" then + for idx, parm in ipairs(signal_item.params) do + code = code .. parm .. (idx == #signal_item.params and "" or ", ") + end + + code = code .. ")\n -- code here\nend)" + + named_tags.signalhandler:add_to_item(signal_item, item.name.." "..item.summary) + end + + item.tag_extra_data = item.tag_extra_data or {} + item.tag_extra_data["sourcesignal"] = item.tag_extra_data["sourcesignal"] or {} + item.tag_extra_data["sourcesignal"][raw] = item.tag_extra_data["sourcesignal"][raw] or {} + item.tag_extra_data["sourcesignal"][raw].usage = ldoc.prettify(code) + + item.has_show_more = true + end + end +} + +-- @rangestart +-- @rangeend +-- @minimumvalue +-- @maximumvalue +-- @tenumvalue +-- @increments +-- @tablekey or not? + -- More fitting section names kind_names={topic='Documentation', module='Libraries', script='Sample files'} @@ -514,7 +931,6 @@ file = { '../selection.c', '../spawn.c', '../xkb.c', - '../common/luaobject.c', '../objects/client.c', '../objects/drawable.c', '../objects/screen.c', @@ -573,6 +989,7 @@ file = { '../lib/wibox/layout/rotate.lua', '../lib/wibox/layout/scroll.lua', '../lib/wibox/widget/background.lua', + '../lib/wibox/drawable.lua', } } @@ -585,10 +1002,16 @@ local function wrap_modname(str, item) end local named_args = { - [ "(args)" ] = true, - [ "([args])" ] = true, - [ "([args=nil])" ] = true, - [ "([args={}])" ] = true + [ "(args)" ] = true, + [ "([args])" ] = true, + [ "([args=nil])" ] = true, + [ "([args={}])" ] = true, + [ '(args)' ] = true, +} + +local param_name_whitelist = { + Mod2 = true, + Lock = true, } -- Sections which are hidden by default, but visible when clicked. @@ -607,6 +1030,27 @@ local delimiter_for_tag = { usebeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}}, propbeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}}, request = { "table class='widget_list' border=1", "table", "tr", "tr", {"Class", "Permission", "Context", "Default", "Description"}}, + sourcesignal = { "div", "div", "span", "span" } +} + +--- If the title is short and descritive, there is no point to bloat it. +-- +-- That test is mostly to catch empty or lazy description (such as the module +-- name and nothing else). +local short_title_whitelist = { + [ "rc.lua" ] = true, + [ "naughty.action" ] = true, + [ "naughty.layout.box" ] = true, + [ "naughty.widget.title" ] = true, + [ "theme.lua" ] = true, + [ "wibox.container.margin" ] = true, + [ "wibox.container.arcchart"] = true, + [ "wibox.widget.checkbox" ] = true, + [ "wibox.widget.imagebox" ] = true, + [ "wibox.widget.separator" ] = true, + [ "wibox.widget.progressbar"] = true, + [ "naughty" ] = true, + [ "xproperties" ] = true, } -- Use the first word of the subtag content to map it to its tag. @@ -636,7 +1080,7 @@ local function generate_summary(item) end end - local ret, has_show_more = {}, false + local ret, has_show_more = {}, item.has_show_more or false for k, v in ipairs(tgs) do if v.count > 0 then @@ -719,20 +1163,26 @@ local function init_custom_types(item) -- Allow the template to fetch the right sub-tags. function item.get_auto_params(tag, value) + local extra = (item.tag_extra_data and item.tag_extra_data[tag] and item.tag_extra_data[tag][value]) or {} + -- Makes auto-generated subtags easier to implement. if item.auto_params[tag.."tparam_override"] then - return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"] + return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"], extra end - if not item.auto_params[tag.."tparam"] then return nil, nil end + local parsed = nil - local parsed = parse_custom_tags(value, named_tags[tag].params) + if item.parsed_tags and item.parsed_tags[tag] and item.parsed_tags[tag][value] then + parsed = item.parsed_tags[tag][value] + end + + if not item.auto_params[tag.."tparam"] then return nil, nil, extra end if parsed.name and item.auto_params[tag.."tparam"][parsed.name.value] then - return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"] + return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"], extra end - return nil, nil + return nil, nil, extra end item.is_init = true @@ -780,8 +1230,7 @@ local function pipe_to_or(s) end -- Parse the magic parameters to type in something the template eats. -local function sanitize_type(item, ldoc) - +local function sanitize_type(item) for parm in ldoc.modules.iter(item.params) do local t = item:type_of_param(parm) @@ -810,9 +1259,37 @@ local function sanitize_type(item, ldoc) item.display_type = "N/A" end +-- Detect error prone markdown formatting. +local function detect_markdown_footguns(string) + for line in string:gmatch("[^\n]*") do + if line:sub(1,4) ~= " " then + local is_tick = false + + -- Detect unquoted code with 2 underscores. They will render as italic, + -- which is definitively not wanted. Add "`" to fix. + for part in line:gmatch("[^`]*") do + if not is_tick then + local count = 0 + + for under in part:gmatch("[^\\]_") do + count = count + 1 + end + + if count > 1 then + return false + end + end + + is_tick = not is_tick + end + end + end + + return true +end -- Add parentheses when there is alternative return types. -local function generate_return_tuple(item, group, ldoc) +local function generate_return_tuple(item, group) local tuple = {} for r in group:iter() do @@ -843,7 +1320,7 @@ local function generate_return_tuple(item, group, ldoc) end -- Create a return type string. -local function sanitize_return_type(item, ldoc) +local function sanitize_return_type(item) local groups = item.retgroups @@ -870,6 +1347,164 @@ local function sanitize_return_type(item, ldoc) item.compact_signature = true end +-- Traverse the entire doc and reverse-map the links between our custom +-- tags and the content it is pointing toward. From that, we add some +-- "consumers"/"providers" tables to each (relevant) item. +local function global_init(_ldoc) + ldoc = _ldoc + + if is_init then return end + is_init = true + + local module_by_name = {} + + -- First pass, gather the providers. + for _, mod in ipairs(ldoc.modules) do + module_by_name[mod.name] = mod + + if mod.type ~= "topic" and ((not mod.summary) or mod.summary == "" or mod.summary:lower():sub(1,8) == "awesome") then + print("WARNING: Each module needs a good summary as its first line", mod.name, "doesn't") + end + + local sum_count = 0 + + for line in (mod.summary or ""):gmatch("[^\n]*") do + sum_count = sum_count + 1 + end + + if sum_count > 1 and #mod.summary > 120 then + print("WARNING:", mod.name, "summary has to be only 1 line.") + end + + if mod.summary and #mod.summary < 30 and not short_title_whitelist[mod.name] then + print("WARNING:", mod.name, "summary is too short.") + end + + for tag, values in pairs(mod.tags) do + for _, value in ipairs(values.gmatch and {values} or values) do + -- Collect instances of some types. + if databases[tag] and databases[tag].collect then + delayed_collect[#delayed_collect+1] = {mod, mod, tag, value} + end + end + end + + for kind, items in mod.kinds() do + for item in items() do + -- Decorate the item with our customizations. + init_custom_types(item) + + -- print(item.description) + + if item.summary and not detect_markdown_footguns(item.summary) then + print( + "WARNING: "..item.name.." from "..item.module.name.." seems to have".. + " ambiguous markdown in its summary, probably underscores. Please either".. + " use '`' or HTML." + ) + end + + -- Collect instances of some types. + if databases[item.type] and databases[item.type].collect then + databases[item.type].collect(item, mod) + end + + for tag, values in pairs(item.tags) do + for _, value in ipairs(values.gmatch and {values} or values) do + -- Collect instances of some types. + if databases[tag] and databases[tag].collect then + delayed_collect[#delayed_collect+1] = {item, mod, tag, value} + end + end + end + + -- Lint the parameters too. + for parm in ldoc.modules.iter(item.params) do + local first = parm:match("^[ ]*(.)") + + -- If the first letter of a parameter is capital, the type is probably missing. + -- That's what happen if you rename @param to @tparam without actually adding the type. + if first and first ~= first:lower() and parm:upper() ~= parm and not param_name_whitelist[parm] then + print( + "ERROR: Parameter "..parm.." from ".. item.name .. " ".. item.module.name.. + " starts with a capital letter. This is forbidden." + ) + end + + for p in ldoc.modules.iter(item:subparam(parm)) do + local desc = item.params.map[p] + + if not detect_markdown_footguns(desc) then + print( + "WARNING: Always use '`' to encapsulate code in the parameters." .. + p .. " from " .. item.name .. " " .. item.module.name .. " contains " .. + "some ambiguous markup. If this is a false positive, use HTML." + ) + end + + -- It *sometime* works, but is at risk if being interpreted as code by markdown. + if desc:match("^ [ ]+") then + print( + "WARNING: ", item.name, "from", item.module.name, "has a parameter description ".. + "with leading spaces. This will not render correctly", "'"..desc.."'" + ) + end + + first = desc:match("^[ ]*([a-z])") + + if first and first ~= first:upper() then + print("WARNING: Sentences starts with a capital letter. Please fix", item.module.name, item.name) + end + + --TODO convert @propbeautiful to @usebeautiful and lint them + --TODO check the module summary. + end + end + end + end + end + + -- Second pass, collect the custom tags. This is delayed because + -- the tags depend on the items. Not all items have been processed if + -- this was called during the first pass. Also, collect callbacks can + -- themselves create more delayed_collect entries recursively. + for _, to_collect in ipairs(delayed_collect) do + databases[to_collect[3]].collect(to_collect[1], to_collect[2], to_collect[3], to_collect[4]) + end + + -- Third pass, parse every custom tags and fill the consumers tables. + for _, mod in ipairs(ldoc.modules) do + for kind, items in mod.kinds() do + for item in items() do + for tag_name, values in pairs(item.tags) do + for _, tag in ipairs(values.gmatch and {values} or values) do + local parsed = named_tags[tag_name] + and named_tags[tag_name].params + and parse_custom_tags(tag, named_tags[tag_name].params) + + -- Allow the tags to, ie, auto-generate some extra content. + if named_tags[tag_name] and named_tags[tag_name].finish_callback then + named_tags[tag_name].finish_callback(item, tag, parsed, module_by_name) + end + + -- Save the parsed content to be used in get_auto_params. + if parsed then + item.parsed_tags = item.parsed_tags or {} + item.parsed_tags[tag_name] = item.parsed_tags[tag_name] or {} + item.parsed_tags[tag_name][tag] = parsed + end + end + end + + -- Mostly for linting. + if databases[item.type] and databases[item.type].finish then + databases[item.type].finish(item, mod, module_by_name) + end + end + end + end +end + -- Work around the fact that tag/awful.tag client/awful.client pages -- are merged. local function compare_module_name(input, module) @@ -956,6 +1591,8 @@ local is_deprecated = { } custom_display_name_handler = function(item, default_handler) + item.global_init = global_init + if is_deprecated[item.type] then item.tags.is_deprecated = {true} end diff --git a/docs/ldoc.css b/docs/ldoc.css index 9451f6f35..4c1397014 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -190,11 +190,11 @@ span.default_value, border-bottom: solid 1px #bcd; } -#content pre { +#content pre, .auto_genenerated_code { margin: 15px; } -pre { +pre, .auto_genenerated_code { background-color: rgb(50, 55, 68); color: white; border-radius: 3px; diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 93497ac32..a054d99cd 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -37,6 +37,15 @@ # local no_underscores = function(s) return s:gsub("_", " ") end # local get_item = function(mod, name) for item in iter(mod.items) do if item.name == name then return item end end; return name == "" and mod or nil end +# -- Poke a hole to allow config.ld code to have a global initialization. +# for m in iter(ldoc.modules) do +# if #m.items > 0 then +# display_name(m.items[1]) +# m.items[1].global_init(ldoc) +# break +# end +# end + # --------- modules hierarchy ------------- # local hierarchy = {} # local curr = module @@ -67,7 +76,7 @@ # local myitems = {} # for item in items() do # myitems[#myitems + 1] = item -# end +# end # all_module_kinds[#all_module_kinds + 1] = { kind = kind, items = myitems } # end # local filtered_kinds = { "Constructors", "Static module functions", @@ -532,7 +541,7 @@ # end -- if group_header then # for value in iter(tag) do <$(row_type_begin)>$(custom.format and custom.format(value, item, M) or M(value)) -# local sub_values, sub_custom = item.get_auto_params(custom[1], value) +# local sub_values, sub_custom, extra_data = item.get_auto_params(custom[1], value) # if sub_values then # end -- if item.auto_params +# if extra_data.usage then +
+

+ 

$(extra_data.usage)
+# end -- extra_data.usage + # end -- for # end -- if tag diff --git a/lib/awful/button.lua b/lib/awful/button.lua index cf3bf1c7d..21c46c7f7 100644 --- a/lib/awful/button.lua +++ b/lib/awful/button.lua @@ -70,38 +70,39 @@ button.names = { -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock). -- -- @property modifiers +-- @tparam table modifiers --- The mouse button identifier. -- -- ![Mouse buttons](../images/mouse.svg) -- -- @property button --- @param integer +-- @tparam integer button --- The button description. -- -- @property description --- @param string +-- @tparam string description --- The button name. -- -- @property name --- @param string +-- @tparam string name --- The button group. -- -- @property group --- @param string +-- @tparam string group --- The callback when this button is pressed. -- -- @property on_press --- @param function +-- @tparam function on_press --- The callback when this button is released. -- -- @property on_release --- @param function +-- @tparam function on_release --- Execute this mousebinding. -- @method :trigger diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 98f41b6bf..28df06d51 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -157,7 +157,7 @@ client.focus = require("awful.client.focus") -- -- @deprecated awful.client.jumpto -- @see client.jump_to --- @tparam client c the client to jump to +-- @tparam client c The client to 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 @@ -1153,7 +1153,7 @@ end -- @DOC_screen_wfact4_EXAMPLE@ -- -- @legacylayout awful.client.idx --- @tparam client c the client +-- @tparam client c The client -- @treturn table data A table with "col", "idx" and "num" keys. -- @treturn integer data.col The column number. -- @treturn integer data.idx Index of the client in the column. @@ -1224,8 +1224,8 @@ end -- @DOC_screen_wfact3_EXAMPLE@ -- -- @legacylayout awful.client.setwfact --- @tparam number wfact the window factor value --- @tparam client c the client +-- @tparam number wfact The window factor value +-- @tparam client c The client -- @emits property::windowfact Emitted on the c.first_tag object. -- @see tag.master_width_factor function client.setwfact(wfact, c) @@ -1291,7 +1291,7 @@ end -- @tparam number add Amount to increase/decrease the client's window factor by. -- Should be between `-current_window_factor` and something close to -- infinite. Normalisation then ensures that the sum of all factors is 1. --- @tparam[opt=client.focus] client c the client. +-- @tparam[opt=client.focus] client c The client. -- @emits property::windowfact function client.incwfact(add, c) c = c or capi.client.focus @@ -1462,10 +1462,10 @@ end -- Starting from the client in focus or the given index, all clients that match -- a given criteria. -- --- @tparam function filter a function that returns true to indicate a positive match. --- @tparam integer start what index to start iterating from. Defaults to using the +-- @tparam function filter A function that returns true to indicate a positive match. +-- @tparam integer start What index to start iterating from. Defaults to using the -- index of the currently focused client. --- @tparam[opt=nil] screen s which screen to use. nil means all screens. +-- @tparam[opt=nil] screen s Which screen to use. nil means all screens. -- -- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances @@ -1487,8 +1487,8 @@ end -- If multiple clients match the given condition then the next one is -- focused. -- --- @tparam string cmd the command to execute --- @tparam function matcher a function that returns true to indicate a matching client +-- @tparam string cmd The command to execute +-- @tparam function matcher A function that returns true to indicate a matching client -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client as argument. @@ -1611,7 +1611,7 @@ end, true, true, "keybinding") -- @DOC_awful_client_shape1_EXAMPLE@ -- -- @property shape --- @tparam gears.shape A gears.shape compatible function. +-- @tparam gears.shape shape A gears.shape compatible function. -- @propemits true false -- @see gears.shape function client.object.set_shape(self, shape) @@ -1811,6 +1811,7 @@ end) --- Emitted when a client need to get a titlebar. -- @signal request::titlebars +-- @tparam client c The client. -- @tparam[opt=nil] string content The context (like "rules") -- @tparam[opt=nil] table hints Some hints. -- @classsignal @@ -1834,6 +1835,7 @@ end) -- * **floating**: When the floating or maximization state changes. -- -- @signal request::border +-- @tparam client c The client. -- @tparam string context The context. -- @tparam table hints The hints. -- @classsignal diff --git a/lib/awful/completion.lua b/lib/awful/completion.lua index f374c9094..45ca4598d 100644 --- a/lib/awful/completion.lua +++ b/lib/awful/completion.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Completion module. +--- Helper utilities for bash-like completion lists. -- -- This module store a set of function using shell to complete commands name. -- @@ -31,7 +31,7 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion" --- Enable programmable bash completion in awful.completion.bash at the price of -- a slight overhead. --- @param src The bash completion source file, /etc/bash_completion by default. +-- @tparam string src The bash completion source file, `/etc/bash_completion` by default. -- @staticfct awful.completion.bashcomp_load function completion.bashcomp_load(src) if src then bashcomp_src = src end @@ -189,11 +189,13 @@ end --- Run a generic completion. -- For this function to run properly the awful.completion.keyword table should -- be fed up with all keywords. The completion is run against these keywords. --- @param text The current text the user had typed yet. --- @param cur_pos The current cursor position. --- @param ncomp The number of yet requested completion using current text. --- @param keywords The keywords table uised for completion. --- @return The new match, the new cursor position, the table of all matches. +-- @tparam string text The current text the user had typed yet. +-- @tparam number cur_pos The current cursor position. +-- @tparam number ncomp The number of yet requested completion using current text. +-- @tparam table keywords The keywords table uised for completion. +-- @treturn string The new match. +-- @treturn number The new cursor position. +-- @treturn table The table of all matches. -- @staticfct awful.completion.generic function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args -- The keywords table may be empty diff --git a/lib/awful/hotkeys_popup/init.lua b/lib/awful/hotkeys_popup/init.lua index 8aaa75445..4cb6e4772 100644 --- a/lib/awful/hotkeys_popup/init.lua +++ b/lib/awful/hotkeys_popup/init.lua @@ -10,7 +10,7 @@ local hotkeys_popup = { widget = require("awful.hotkeys_popup.widget"), } ---- This is the same as awful.hotkeys_popup.widget.show_help. +--- This is the same as `awful.hotkeys_popup.widget.show_help`. -- -- example usage: -- diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index 144f2b0ed..e0d5a5613 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -249,6 +249,21 @@ widget.labels = { -- @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 +-- @usebeautiful beautiful.hotkeys_fg +-- @usebeautiful beautiful.hotkeys_bg +-- @usebeautiful beautiful.hotkeys_border_width +-- @usebeautiful beautiful.hotkeys_border_color +-- @usebeautiful beautiful.hotkeys_shape +-- @usebeautiful beautiful.hotkeys_modifiers_fg +-- @usebeautiful beautiful.hotkeys_label_bg +-- @usebeautiful beautiful.hotkeys_label_fg +-- @usebeautiful beautiful.hotkeys_font +-- @usebeautiful beautiful.hotkeys_description_font +-- @usebeautiful beautiful.hotkeys_group_margin +-- @usebeautiful beautiful.bg_normal Fallback. +-- @usebeautiful beautiful.fg_normal Fallback. +-- @usebeautiful beautiful.fg_minimize Fallback. +-- @usebeautiful beautiful.border_width Fallback. function widget.new(args) args = args or {} local widget_instance = { @@ -755,8 +770,8 @@ function widget.new(args) end --- Add hotkey group rules for third-party applications. - -- @tparam string group hotkeys group name, - -- @tparam table data rule data for the group + -- @tparam string group Hotkeys group name, + -- @tparam table data Rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. -- @method add_group_rules function widget_instance:add_group_rules(group, data) @@ -795,8 +810,8 @@ end --- Add hotkey group rules for third-party applications -- (default widget instance will be used). --- @tparam string group rule group name, --- @tparam table data rule data for the group +-- @tparam string group Rule group name, +-- @tparam table data Rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. -- @staticfct awful.hotkeys_popup.widget.add_group_rules function widget.add_group_rules(group, data) diff --git a/lib/awful/key.lua b/lib/awful/key.lua index ec111ce52..efb07a52e 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -43,7 +43,7 @@ local gobject = require("gears.object") -- keycode such as `#65`. -- -- @property key --- @param string +-- @tparam string key --- The table of modifier keys. -- @@ -75,31 +75,31 @@ local gobject = require("gears.object") -- This is used, for example, by `awful.hotkeys_popup`. -- -- @property description --- @param string +-- @tparam string description --- The key name. -- -- This can be useful when searching for keybindings by keywords. -- -- @property name --- @param string +-- @tparam string name --- The key group bound to a function in a key binding. -- -- This is used, for example, by `awful.hotkeys_popup`. -- -- @property group --- @param string +-- @tparam string group --- The callback when this key is pressed. -- -- @property on_press --- @param function +-- @tparam function on_press --- The callback when this key is released. -- -- @property on_release --- @param function +-- @tparam function on_release local key = { mt = {}, hotkeys = {} } diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index e457f53c4..f28cce404 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -296,7 +296,7 @@ end -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@ -- -- @property timeout --- @param number +-- @tparam number timeout -- @see gears.timer -- @see timeout_callback @@ -321,7 +321,7 @@ end -- their corresponding key names such as `Control_L`. -- -- @property stop_key --- @param[opt=nil] string|table stop_key +-- @tparam[opt=nil] string|table stop_key -- @see stop_event --- The event on which the keygrabbing will be terminated. @@ -332,7 +332,7 @@ end -- * "release" -- -- @property stop_event --- @param string +-- @tparam string stop_event -- @see stop_key --- Whether or not to execute the key press/release callbacks when keybindings are called. @@ -344,14 +344,14 @@ end -- By default, keybindings block those callbacks from being executed. -- -- @property mask_event_callback --- @param[opt=true] boolean +-- @tparam[opt=true] boolean mask_event_callback -- @see keybindings -- @see keyreleased_callback -- @see keypressed_callback --- Do not call the callbacks on modifier keys (like `Control` or `Mod4`) events. -- @property mask_modkeys --- @param[opt=false] boolean +-- @tparam[opt=false] boolean mask_modkeys -- @see mask_event_callback --- Export all keygrabber keybindings as root (global) keybindings. @@ -365,7 +365,7 @@ end -- have a single instance. -- -- @property export_keybindings --- @param[opt=false] boolean +-- @tparam[opt=false] boolean export_keybindings --- The root (global) keybinding to start this keygrabber. -- @@ -376,7 +376,7 @@ end -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@ -- -- @property root_keybindings --- @param table +-- @tparam table root_keybindings -- @see export_keybindings -- @see keybindings @@ -385,7 +385,7 @@ end -- This property contains a table of `awful.key` objects. -- -- @property keybindings --- @param table +-- @tparam table keybindings -- @see export_keybindings -- @see root_keybindings -- @see awful.key @@ -415,7 +415,7 @@ end -- @DOC_text_awful_keygrabber_autostart_EXAMPLE@ -- -- @property sequence --- @param string +-- @tparam string sequence -- --- The current (running) instance of this keygrabber. diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua index fc8af8ec9..ba7106234 100644 --- a/lib/awful/layout/init.lua +++ b/lib/awful/layout/init.lua @@ -1,5 +1,29 @@ --------------------------------------------------------------------------- ---- Layout module for awful. +--- Deterministically lay the clients in a screen workarea. +-- +-- The `awful.layout` module contains many sub-modules. Each of them contain +-- one or more layout. `awful.layout` offers static layouts rather than +-- tree based like other WMs. The layout have a small number of configuration +-- variables: +-- +-- * `master_width_factor`: The ratio between the main (master) section of the +-- layout and a sub-section. For example, in the `tile.left` layout, the main +-- (master) part contains `master_count` clients and the secondary part contains +-- all other clients. +-- * `master_count`: The number of clients which belong to the main (master) area. +-- * `column_count`: The number of columns to store the clients in the secondary +-- area. +-- * `master_fill_policy`: When the number of clients is below `master_count`, +-- how is the remaining space used. +-- * `gaps`: The empty space between the clients. +-- * `gap_single_client`: Same as gap, but when there is a single client. Gaps +-- are often useful as a visual cue to know where a client starts and ends. +-- This makes no sense when there is only one. +-- +-- Not all layouts make use of all variables. Having such an overloaded meaning +-- to a small set of variable is useful to attach those values to keybindings +-- without having special logic for each layouts. AwesomeWM keybindings are not +-- modal, so such "limitation" actually improves usability. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou diff --git a/lib/awful/layout/suit/corner.lua b/lib/awful/layout/suit/corner.lua index be6e82002..60029b35e 100644 --- a/lib/awful/layout/suit/corner.lua +++ b/lib/awful/layout/suit/corner.lua @@ -171,6 +171,7 @@ end -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.nw +-- @usebeautiful beautiful.layout_cornernw corner.nw = { name = "cornernw", arrange = function (p) return do_corner(p, "NW") end, @@ -181,6 +182,7 @@ corner.nw = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.ne +-- @usebeautiful beautiful.layout_cornerne corner.ne = { name = "cornerne", arrange = function (p) return do_corner(p, "NE") end, @@ -191,6 +193,7 @@ corner.ne = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.sw +-- @usebeautiful beautiful.layout_cornersw corner.sw = { name = "cornersw", arrange = function (p) return do_corner(p, "SW") end, @@ -201,6 +204,7 @@ corner.sw = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.se +-- @usebeautiful beautiful.layout_cornerse corner.se = { name = "cornerse", arrange = function (p) return do_corner(p, "SE") end, diff --git a/lib/awful/layout/suit/fair.lua b/lib/awful/layout/suit/fair.lua index 6930a09e7..c01c4a153 100644 --- a/lib/awful/layout/suit/fair.lua +++ b/lib/awful/layout/suit/fair.lua @@ -107,10 +107,12 @@ end --- The fair layout. -- Try to give all clients the same size. -- @clientlayout awful.layout.suit.fair +-- @usebeautiful beautiful.layout_fairv --- The horizontal fair layout. -- Try to give all clients the same size. -- @clientlayout awful.layout.suit.fair.horizontal +-- @usebeautiful beautiful.layout_fairh return fair diff --git a/lib/awful/layout/suit/floating.lua b/lib/awful/layout/suit/floating.lua index f3a9a9b7e..e65ccfa92 100644 --- a/lib/awful/layout/suit/floating.lua +++ b/lib/awful/layout/suit/floating.lua @@ -114,6 +114,7 @@ end --- The floating layout. -- @clientlayout awful.layout.suit.floating +-- @usebeautiful beautiful.layout_floating floating.name = "floating" diff --git a/lib/awful/layout/suit/magnifier.lua b/lib/awful/layout/suit/magnifier.lua index c2c56883d..23acddcf3 100644 --- a/lib/awful/layout/suit/magnifier.lua +++ b/lib/awful/layout/suit/magnifier.lua @@ -143,6 +143,7 @@ end --- The magnifier layout. -- @clientlayout awful.layout.suit.magnifier +-- @usebeautiful beautiful.layout_magnifier magnifier.name = "magnifier" diff --git a/lib/awful/layout/suit/max.lua b/lib/awful/layout/suit/max.lua index 731c7a8ea..1d27856ca 100644 --- a/lib/awful/layout/suit/max.lua +++ b/lib/awful/layout/suit/max.lua @@ -43,6 +43,7 @@ end --- Maximized layout. -- @clientlayout awful.layout.suit.max +-- @usebeautiful beautiful.layout_max max.name = "max" function max.arrange(p) return fmax(p, false) @@ -53,6 +54,7 @@ end --- Fullscreen layout. -- @clientlayout awful.layout.suit.max.fullscreen +-- @usebeautiful beautiful.layout_fullscreen max.fullscreen = {} max.fullscreen.name = "fullscreen" max.fullscreen.skip_gap = max.skip_gap diff --git a/lib/awful/layout/suit/spiral.lua b/lib/awful/layout/suit/spiral.lua index 629d9828a..fe608dfa2 100644 --- a/lib/awful/layout/suit/spiral.lua +++ b/lib/awful/layout/suit/spiral.lua @@ -71,6 +71,7 @@ end --- Dwindle layout. -- @clientlayout awful.layout.suit.spiral.dwindle +-- @usebeautiful beautiful.layout_dwindle spiral.dwindle = {} spiral.dwindle.name = "dwindle" function spiral.dwindle.arrange(p) @@ -79,6 +80,7 @@ end --- Spiral layout. -- @clientlayout awful.layout.suit.spiral.name +-- @usebeautiful beautiful.layout_spiral spiral.name = "spiral" function spiral.arrange(p) return do_spiral(p, true) diff --git a/lib/awful/layout/suit/tile.lua b/lib/awful/layout/suit/tile.lua index 4609a0579..85922c8b9 100644 --- a/lib/awful/layout/suit/tile.lua +++ b/lib/awful/layout/suit/tile.lua @@ -312,6 +312,7 @@ end --- The main tile algo, on the right. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.right +-- @usebeautiful beautiful.layout_tile tile.right = {} tile.right.name = "tile" tile.right.arrange = do_tile @@ -323,6 +324,7 @@ end --- The main tile algo, on the left. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.left +-- @usebeautiful beautiful.layout_tileleft tile.left = {} tile.left.name = "tileleft" tile.left.skip_gap = tile.skip_gap @@ -336,6 +338,7 @@ end --- The main tile algo, on the bottom. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.bottom +-- @usebeautiful beautiful.layout_tilebottom tile.bottom = {} tile.bottom.name = "tilebottom" tile.bottom.skip_gap = tile.skip_gap @@ -349,6 +352,7 @@ end --- The main tile algo, on the top. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.top +-- @usebeautiful beautiful.layout_tiletop tile.top = {} tile.top.name = "tiletop" tile.top.skip_gap = tile.skip_gap diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index 4e87ee232..33caa8ceb 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -1,5 +1,5 @@ -------------------------------------------------------------------------------- ---- A menu for awful. +--- Create context menus, optionally with sub-menus. -- -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> @@ -93,7 +93,7 @@ end -- @param color -- @see gears.color ---- The default sub-menu indicator if no menu_submenu_icon is provided. +--- The default sub-menu indicator if no `menu_submenu_icon` is provided. -- @beautiful beautiful.menu_submenu -- @tparam[opt="▶"] string menu_submenu The sub-menu text. -- @see beautiful.menu_submenu_icon @@ -357,8 +357,9 @@ end --- Show a menu. --- @param args The arguments --- @param args.coords Menu position defaulting to mouse.coords() +-- @tparam[opt={}] table args The arguments +-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with +-- `x` and `y` as keys and position (in pixels) as values. -- @method show function menu:show(args) args = args or {} @@ -390,8 +391,9 @@ function menu:hide() end --- Toggle menu visibility. --- @param args The arguments --- @param args.coords Menu position {x,y} +-- @tparam table args The arguments. +-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with +-- `x` and `y` as keys and position (in pixels) as values. -- @method toggle function menu:toggle(args) if self.wibox.visible then @@ -419,10 +421,10 @@ end --- Add a new menu entry. -- args.* params needed for the menu entry constructor. --- @param args The item params --- @param args.new (Default: awful.menu.entry) The menu entry constructor. --- @param[opt] args.theme The menu entry theme. --- @param[opt] index The index where the new entry will inserted. +-- @tparam table args The item params. +-- @tparam[opt=awful.menu.entry] function args.new The menu entry constructor. +-- @tparam[opt] table args.theme The menu entry theme. +-- @tparam[opt] number index The index where the new entry will inserted. -- @method add function menu:add(args, index) if not args then return end @@ -479,7 +481,7 @@ function menu:add(args, index) end --- Delete menu entry at given position. --- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself. +-- @tparam table|number num The index in the table of the menu entry to be deleted; can be also the menu entry itself. -- @method delete function menu:delete(num) if type(num) == "table" then @@ -580,8 +582,8 @@ end --- Default awful.menu.entry constructor. -- @param parent The parent menu (TODO: This is apparently unused) --- @param args the item params --- @return table with 'widget', 'cmd', 'akey' and all the properties the user wants to change +-- @param args The item params +-- @return table With 'widget', 'cmd', 'akey' and all the properties the user wants to change -- @constructorfct awful.menu.entry function menu.entry(parent, args) -- luacheck: no unused args args = args or {} @@ -673,14 +675,24 @@ end -------------------------------------------------------------------------------- --- Create a menu popup. --- @param args Table containing the menu information. --- --- * Key items: Table containing the displayed items. Each element is a table by default (when element 'new' is --- awful.menu.entry) containing: item name, triggered action (submenu table or function), item icon (optional). --- * Keys theme.[fg|bg]_[focus|normal], theme.border_color, theme.border_width, theme.submenu_icon, theme.height --- and theme.width override the default display for your menu and/or of your menu entry, each of them are optional. --- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false. -- +-- @tparam table args Table containing the menu information. +-- @tparam[opt=true] boolean args.auto_expand Controls the submenu auto expand behaviour. +-- @tparam table args.items Table containing the displayed items. Each element is a +-- table by default (when element 'new' is awful.menu.entry) containing: item +-- name, triggered action (submenu table or function), item icon (optional). +-- @tparam table args.theme +-- @tparam[opt=beautiful.menu_fg_normal] color args.theme.fg_normal +-- @tparam[opt=beautiful.menu_bg_normal] color args.theme.bg_normal +-- @tparam[opt=beautiful.menu_fg_focus] color args.theme.fg_focus +-- @tparam[opt=beautiful.menu_bg_focus] color args.theme.bg_focus +-- @tparam[opt=beautiful.menu_border_color] color args.theme.border +-- @tparam[opt=beautiful.menu_border_width] integer args.theme.border_width +-- @tparam[opt=beautiful.menu_height] integer args.theme.height +-- @tparam[opt=beautiful.menu_width] integer args.theme.width +-- @tparam[opt=beautiful.menu_font] string args.theme.font +-- @tparam[opt=beautiful.menu_submenu_icon] gears.surface|string args.theme.submenu_icon +-- @tparam[opt=beautiful.menu_submenu] string args.theme.submenu -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user. -- @constructorfct awful.menu -- @usage -- The following function builds and shows a menu of clients that match diff --git a/lib/awful/mouse/client.lua b/lib/awful/mouse/client.lua index d6191b723..5170eb3a1 100644 --- a/lib/awful/mouse/client.lua +++ b/lib/awful/mouse/client.lua @@ -69,8 +69,8 @@ end --- Get a client corner coordinates. -- @deprecated awful.mouse.client.corner -- @tparam[opt=client.focus] client c The client to get corner from, focused one by default. --- @tparam string corner The corner to use: auto, top_left, top_right, bottom_left, --- bottom_right, left, right, top bottom. Default is auto, and auto find the +-- @tparam string corner The corner to use: `auto`, `top_left`, `top_right`, `bottom_left`, +-- `bottom_right`, `left`, `right`, `top` or `bottom`. Default is `auto`. `auto` finds the -- nearest corner. -- @treturn string The corner name -- @treturn number x The horizontal position diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index 92c9ac462..b4d620360 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -116,7 +116,7 @@ end, "mouse.resize") --- Get the client currently under the mouse cursor. -- @property current_client --- @tparam client|nil The client +-- @tparam client|nil current_client The client function mouse.object.get_current_client() local obj = capi.mouse.object_under_pointer() @@ -127,7 +127,7 @@ end --- Get the wibox currently under the mouse cursor. -- @property current_wibox --- @tparam wibox|nil The wibox +-- @tparam wibox|nil current_wibox The wibox function mouse.object.get_current_wibox() local obj = capi.mouse.object_under_pointer() @@ -139,7 +139,7 @@ end --- Get the widgets currently under the mouse cursor. -- -- @property current_widgets --- @tparam nil|table list The widget list +-- @tparam nil|table current_widgets The widget list -- @treturn table The list of widgets.The first element is the biggest -- container while the last is the topmost widget. The table contains *x*, *y*, -- *width*, *height* and *widget*. @@ -164,7 +164,7 @@ end --- Get the topmost widget currently under the mouse cursor. -- @property current_widget --- @tparam widget|nil widget The widget +-- @tparam widget|nil current_widget The widget -- @treturn ?widget The widget -- @see current_widget_geometry @@ -178,7 +178,7 @@ end --- Get the current widget geometry. -- @property current_widget_geometry --- @tparam ?table The geometry. +-- @tparam ?table current_widget_geometry The geometry. -- @see current_widget function mouse.object.get_current_widget_geometry() @@ -189,7 +189,7 @@ end --- Get the current widget geometries. -- @property current_widget_geometries --- @tparam ?table A list of geometry tables. +-- @tparam ?table current_widget_geometries A list of geometry tables. -- @see current_widgets function mouse.object.get_current_widget_geometries() @@ -238,7 +238,7 @@ end --- True if the middle mouse button is pressed. -- @property is_middle_mouse_button_pressed --- @tparam boolean is_right_mouse_button_pressed +-- @tparam boolean is_middle_mouse_button_pressed --- Add an `awful.button` based mousebinding to the global set. -- diff --git a/lib/awful/mouse/resize.lua b/lib/awful/mouse/resize.lua index a685bc599..e1ca82281 100644 --- a/lib/awful/mouse/resize.lua +++ b/lib/awful/mouse/resize.lua @@ -52,7 +52,7 @@ end -- This callback will be executed before the mouse grabbing starts. -- @function awful.mouse.resize.add_enter_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_enter_callback(cb, context) context = context or "other" callbacks.enter[context] = callbacks.enter[context] or {} @@ -64,7 +64,7 @@ end -- applying the operation. -- @function awful.mouse.resize.add_move_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_move_callback(cb, context) context = context or "other" callbacks.move[context] = callbacks.move[context] or {} @@ -75,7 +75,7 @@ end -- This callback is executed just before the `mousegrabber` stop -- @function awful.mouse.resize.add_leave_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_leave_callback(cb, context) context = context or "other" callbacks.leave[context] = callbacks.leave[context] or {} @@ -93,9 +93,11 @@ end -- -- @function awful.mouse.resize -- @tparam client client A client. --- @tparam[default=mouse.resize] string context The resizing context. +-- @tparam[opt=mouse.resize] string context The resizing context. -- @tparam[opt={}] table args A set of `awful.placement` arguments. -- @request wibox geometry mouse.resize granted Requests to resize the wibox. +-- @usebeautiful beautiful.cursor_mouse_move +-- @usebeautiful beautiful.cursor_mouse_resize local function handler(_, client, context, args) --luacheck: no unused_args args = args or {} context = context or "mouse.resize" diff --git a/lib/awful/mouse/snap.lua b/lib/awful/mouse/snap.lua index 843425687..0b7a05fad 100644 --- a/lib/awful/mouse/snap.lua +++ b/lib/awful/mouse/snap.lua @@ -200,6 +200,10 @@ end -- @tparam boolean fixed_x True if the client isn't allowed to move in the x direction. -- @tparam boolean fixed_y True if the client isn't allowed to move in the y direction. -- @treturn table The new geometry. +-- @usebeautiful beautiful.snap_bg +-- @usebeautiful beautiful.snap_border_width +-- @usebeautiful beautiful.snap_shape +-- @usebeautiful beautiful.snapper_gap function module.snap(c, snap, x, y, fixed_x, fixed_y) snap = snap or module.default_distance c = c or capi.client.focus diff --git a/lib/awful/permissions/init.lua b/lib/awful/permissions/init.lua index 93be8eb95..5b59b8e1a 100644 --- a/lib/awful/permissions/init.lua +++ b/lib/awful/permissions/init.lua @@ -1,5 +1,19 @@ --------------------------------------------------------------------------- ---- Implements EWMH requests handling. +--- Default implementation of the various requests handers. +-- +-- AwesomeWM has many `request::` signals across the core APIs. They help +-- decouple the default behavior from the core API. The request handlers +-- can be disconnected and replaced by module or `rc.lua` to alter +-- AwesomeWM behavior. +-- +-- This module provides the default implementation of those request handlers. +-- Beside some legacy signals, most request handlers have a main object, a +-- named context and a table containing any low-level hints the core code is +-- aware of. Each default handler implement a context based filter mechanism. +-- This filter is called the "permissions". It allows requests to be denied. +-- For example, if a tiled client asks to be resized or moved, the permission +-- and deny it. In the documentation, many objects and properties have a +-- "permissions" section you can display by clicking "show more". -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou @@ -143,12 +157,13 @@ end -- @tparam client c A client to use -- @tparam string context The context where this signal was used. -- @tparam[opt] table hints A table with additional hints: --- @tparam[opt=false] boolean hints.raise should the client be unminimized +-- @tparam[opt=false] boolean hints.raise Should the client be unminimized -- and raised? --- @tparam[opt=false] boolean hints.switch_to_tag should the client's first tag +-- @tparam[opt=false] boolean hints.switch_to_tag Should the client's first tag -- be selected if none of the client's tags are selected? -- @tparam[opt=false] boolean hints.switch_to_tags Select all tags associated -- with the client. +-- @sourcesignal client request::activate function permissions.activate(c, context, hints) -- luacheck: no unused args if not pcommon.check(c, "client", "activate", context) then return end @@ -291,6 +306,7 @@ end -- @tparam[opt] tag|boolean t A tag to use. If `true`, then the client is made `sticky`. -- @tparam[opt={}] table hints Extra information. -- @tparam[opt=nil] nil|string hints.reason Why the tag is being changed. +-- @sourcesignal client request::tag function permissions.tag(c, t, hints) --luacheck: no unused -- There is nothing to do if not t and #get_valid_tags(c, c.screen) > 0 then return end @@ -317,6 +333,7 @@ end -- @signalhandler awful.permissions.urgent -- @tparam client c A client -- @tparam boolean urgent If the client should be urgent +-- @sourcesignal client request::urgent function permissions.urgent(c, urgent) if c ~= client.focus and not aclient.property.get(c,"ignore_urgent") then c.urgent = urgent @@ -343,6 +360,7 @@ local context_mapper = { -- previous geometry in case it has to be restored. -- @tparam[opt=true] boolean hints.honor_workarea Avoid overlapping the `wibar`s -- or other desktop decoration when applying the geometry. +-- @sourcesignal client request::geometry function permissions.geometry(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -416,6 +434,7 @@ end -- @tparam[opt] integer hints.y The vertical position. -- @tparam[opt] integer hints.width The wibox width. -- @tparam[opt] integer hints.height The wibox height. +-- @sourcesignal client request::geometry function permissions.wibox_geometry(w, context, hints) if not pcommon.check(w, "wibox", "geometry", context) then return end @@ -435,6 +454,7 @@ end -- @tparam[opt={}] table hints The hints to pass to the handler. -- @tparam[opt=false] boolean hints.toggle Toggle the maximization state rather -- than set it to `true`. +-- @sourcesignal client request::geometry function permissions.merge_maximization(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -522,6 +542,7 @@ end -- @tparam[opt] integer hints.y The vertical position. -- @tparam[opt] integer hints.width The client width. -- @tparam[opt] integer hints.height The client height. +-- @sourcesignal client request::geometry function permissions.client_geometry_requests(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -563,6 +584,7 @@ end, "mouse_enter") -- @signalhandler awful.permissions.update_border -- @tparam client c The client. -- @tparam string context Why is the border changed. +-- @sourcesignal client request::border -- @usebeautiful beautiful.border_color_marked -- @usebeautiful beautiful.border_color_active -- @usebeautiful beautiful.border_color_normal @@ -751,6 +773,7 @@ local activate_context_map = { -- @tparam client c The client. -- @tparam string context Why is the client auto-activated. -- @tparam[opt={}] table hints Extra arguments. +-- @sourcesignal client request::activated -- @see activate -- @see client:activate function permissions.autoactivate(c, context, args) diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index d559ca70e..caf3c57b0 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Prompt module for awful. +--- Convert a `wibox.widget.textbox` into an input prompt. -- -- **Keyboard navigation**: -- @@ -444,21 +444,21 @@ end -- return command -- end} -- } --- @param textbox The textbox to use for the prompt. [**DEPRECATED**] --- @param exe_callback The callback function to call with command as argument +-- @tparam wibox.widget.textbox textbox The textbox to use for the prompt. [**DEPRECATED**] +-- @tparam[opt] function|nil exe_callback The callback function to call with command as argument -- when finished. [**DEPRECATED**] --- @param completion_callback The callback function to call to get completion. +-- @tparam[opt] function completion_callback The callback function to call to get completion. -- [**DEPRECATED**] --- @param[opt] history_path File path where the history should be +-- @tparam[opt] string history_path File path where the history should be -- saved, set nil to disable history [**DEPRECATED**] --- @param[opt] history_max Set the maximum entries in history +-- @tparam[opt] number history_max Set the maximum entries in history -- file, 50 by default [**DEPRECATED**] --- @param[opt] done_callback The callback function to always call +-- @tparam[opt] function done_callback The callback function to always call -- without arguments, regardless of whether the prompt was cancelled. -- [**DEPRECATED**] --- @param[opt] changed_callback The callback function to call +-- @tparam[opt] function changed_callback The callback function to call -- with command as argument when a command was changed. [**DEPRECATED**] --- @param[opt] keypressed_callback The callback function to call +-- @tparam[opt] function keypressed_callback The callback function to call -- with mod table, key and command as arguments when a key was pressed. -- [**DEPRECATED**] -- @see gears.color diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index 346ed6b60..6d931bda3 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -380,7 +380,7 @@ end -- -- This method computes the different variants of the "usable" screen geometry. -- --- @staticfct screen.get_bounding_geometry +-- @method screen.get_bounding_geometry -- @tparam[opt={}] table args The arguments -- @tparam[opt=false] boolean args.honor_padding Whether to honor the screen's padding. -- @tparam[opt=false] boolean args.honor_workarea Whether to honor the screen's workarea. @@ -772,7 +772,7 @@ end -- the lowest of the resulting virtual DPIs. -- -- @property preferred_dpi --- @tparam number preferred_dpi the DPI value. +-- @tparam number preferred_dpi The DPI value. -- @readonly --- The maximum diagonal size in millimeters. @@ -953,6 +953,8 @@ end -- `request::remove` and `request::resize`. -- -- @signalhandler awful.screen.create_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::create -- @see request::create --- Default handler for `request::remove`. @@ -972,6 +974,8 @@ end -- end -- -- @signalhandler awful.screen.remove_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::remove -- @see request::remove --- Default handler for `request::resize`. @@ -993,6 +997,8 @@ end -- end -- -- @signalhandler awful.screen.resize_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::resize -- @see request::resize -- Add the DPI properties. diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua index ecada47b9..beae02d0a 100644 --- a/lib/awful/spawn.lua +++ b/lib/awful/spawn.lua @@ -1,7 +1,7 @@ --luacheck: no max line length --------------------------------------------------------------------------- ---- Spawning of programs. +--- Spawn sub-processes and optionally get their output. -- -- This module provides methods to start programs and supports startup -- notifications, which allows for callbacks and applying properties to the diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index d5ceeee5f..958da3937 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -637,7 +637,7 @@ end -- @deprecated awful.tag.setscreen -- @see screen -- @tparam screen s Screen --- @tparam tag t tag object +-- @tparam tag t The tag object function tag.setscreen(s, t) -- For API consistency, the arguments have been swapped for Awesome 3.6 -- this method is already deprecated, so be silent and swap the args @@ -653,7 +653,7 @@ end --- Get a tag's screen -- @deprecated awful.tag.getscreen -- @see screen --- @tparam[opt] tag|nil t tag object +-- @tparam[opt=awful.screen.focused().selected_taga] tag|nil t Tag object -- @treturn screen The tag screen. function tag.getscreen(t) gdebug.deprecate("Use t.screen instead of awful.tag.getscreen(t)", {deprecated_in=4}) @@ -713,7 +713,7 @@ end -- @DOC_screen_mwfact2_EXAMPLE@ -- -- @property master_width_factor --- @tparam number master_width_factor Between 0 and 1 +-- @tparam[opt=beautiful.master_width_factor] number master_width_factor Between 0 and 1 -- @emits property::mwfact When the value changes (deprecated). -- @emits property::master_width_factor When the value changes. -- @see master_count @@ -1006,7 +1006,7 @@ end --- Set layout. -- @deprecated awful.tag.setlayout -- @see layout --- @param layout a layout table or a constructor function +-- @param layout A layout table or a constructor function -- @tparam tag t The tag to modify -- @return The layout function tag.setlayout(layout, t) @@ -1096,7 +1096,7 @@ end -- @DOC_screen_gaps2_EXAMPLE@ -- -- @property gap --- @tparam number gap The value has to be greater than zero. +-- @tparam[opt=beautiful.useless_gap] number gap The value has to be greater than zero. -- @emits property::useless_gap When the gap changes. -- @see gap_single_client -- @see awful.tag.incgap @@ -1158,7 +1158,7 @@ end -- @DOC_screen_gap_single_client_false_EXAMPLE@ -- -- @property gap_single_client --- @tparam boolean gap_single_client Enable gaps for a single client +-- @tparam[opt=beautiful.gap_single_client] boolean gap_single_client Enable gaps for a single client -- @propemits false false -- @see awful.tag.incgap @@ -1230,7 +1230,7 @@ end -- redistributed on both side. -- -- @property master_fill_policy --- @tparam string master_fill_policy "expand" or "master\_width\_factor" +-- @tparam[opt=beautiful.master_fill_policy] string master_fill_policy "expand" or "master\_width\_factor" -- @propemits false false -- @see awful.tag.togglemfpol @@ -1245,7 +1245,7 @@ end -- @see master_fill_policy -- @tparam string policy Can be set to -- "expand" (fill all the available workarea) or --- "master_width_factor" (fill only an area inside the master width factor) +-- `master_width_factor` (fill only an area inside the master width factor) -- @tparam[opt=tag.selected()] tag t The tag to modify function tag.setmfpol(policy, t) gdebug.deprecate("Use t.master_fill_policy = policy instead of awful.tag.setmfpol", {deprecated_in=4}) @@ -1296,7 +1296,7 @@ end -- @DOC_sequences_tag_master_count_EXAMPLE@ -- -- @property master_count --- @tparam integer master_count nmaster Only positive values are accepted +-- @tparam[opt=beautiful.master_count] integer master_count Only positive values are accepted -- @emits property::nmaster Deprecated. -- @emits property::master_count When the value changes. -- @see awful.tag.incnmaster @@ -1317,7 +1317,7 @@ end --- The number of master clients. -- @deprecated awful.tag.setnmaster -- @see master_count --- @tparam nmaster The number of master windows. +-- @tparam number nmaster The number of master windows. -- @tparam[opt] tag t The tag. function tag.setnmaster(nmaster, t) gdebug.deprecate("Use t.master_count = nmaster instead of awful.tag.setnmaster", {deprecated_in=4}) @@ -1379,9 +1379,9 @@ end --- Set the tag icon -- @deprecated awful.tag.seticon +-- @tparam gears.surface|string icon The icon to set, either path or image object +-- @tparam tag tag The tag -- @see icon --- @tparam gears.surface|string icon the icon to set, either path or image object --- @tparam tag tag the tag function tag.seticon(icon, _tag) gdebug.deprecate("Use t.icon = icon instead of awful.tag.seticon", {deprecated_in=4}) @@ -1392,7 +1392,7 @@ end --- Get the tag icon -- @deprecated awful.tag.geticon -- @see icon --- @tparam tag tag the tag +-- @tparam tag tag The tag function tag.geticon(_tag) gdebug.deprecate("Use t.icon instead of awful.tag.geticon", {deprecated_in=4}) @@ -1411,7 +1411,7 @@ end -- @DOC_sequences_tag_column_count_EXAMPLE@ -- -- @property column_count --- @tparam integer ncol Has to be greater than 1 +-- @tparam[opt=beautiful.column_count or 1] integer column_count Has to be greater than 1 -- @emits property::ncol Deprecated. -- @emits property::column_count When the value changes. -- @see awful.tag.incncol @@ -1739,7 +1739,7 @@ end -- @staticfct awful.tag.attached_connect_signal -- @tparam screen|nil screen The screen concerned, or all if `nil`. -- @tparam string signal The signal name. --- @tparam function Callback +-- @tparam function callback function tag.attached_connect_signal(screen, ...) if screen then attached_connect_signal_screen(screen, ...) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 5345851f6..db59510c0 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Titlebars for awful. +--- Create widget area on the edge of a client. -- -- Create a titlebar -- ================= @@ -41,417 +41,499 @@ local titlebar = { --- Show tooltips when hover on titlebar buttons. +-- -- @tfield[opt=true] boolean awful.titlebar.enable_tooltip -- @param boolean --- Title to display if client name is not set. +-- -- @field[opt='\'] awful.titlebar.fallback_name -- @tparam[opt='\'] string fallback_name - --- The titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_normal -- @param color -- @see gears.color --- The titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_normal -- @param color -- @see gears.color --- The titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage_normal -- @tparam gears.surface|string path -- @see gears.surface --- The titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg -- @param color -- @see gears.color --- The titlebar background color. +-- -- @beautiful beautiful.titlebar_bg -- @param color -- @see gears.color --- The titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage -- @tparam gears.surface|string path -- @see gears.surface --- The focused titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_focus -- @param color -- @see gears.color --- The focused titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_focus -- @param color -- @see gears.color --- The focused titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage_focus -- @tparam gears.surface|string path -- @see gears.surface --- The urgent titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_urgent -- @param color -- @see gears.color --- The urgent titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_urgent -- @param color -- @see gears.color ---- The urgent titlebar background image image. +--- The urgent titlebar background image. +-- -- @beautiful beautiful.titlebar_bgimage_urgent -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal. +--- The normal non-floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal. +--- The normal non-maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal. +--- The normal minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal_hover. +--- The hovered minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal_hover -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal_press. +--- The pressed minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal_press -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal. +--- The normal close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal_hover. +--- The hovered close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal_hover -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal_press. +--- The pressed close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal. +--- The normal non-ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal. +--- The normal non-sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus. +--- The focused client non-floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus. +--- The focused client non-maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus. +--- The focused client minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus_hover. +--- The hovered+focused client minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus_hover -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus_press. +--- The pressed+focused minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus_press -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus. +--- The focused client close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus_hover. +--- The hovered+focused close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus_hover -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus_press. +--- The pressed+focused close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus. +--- The focused client non-ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus. +--- The focused client sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active. +--- The normal floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active_hover. +--- The hovered floating client button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active_press. +--- The pressed floating client button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active. +--- The maximized client button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active_hover. +--- The hozered+maximized client button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active_press. +--- The pressed+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active. +--- The ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active_hover. +--- The hovered+ontop client button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active_press. +--- The pressed+ontop client button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active. +--- The sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active_hover. +--- The hovered+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active_press. +--- The pressed+sticky client button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active. +--- The floating+focused client button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active_hover. +--- The hovered+floating+focused button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active_press. +--- The pressed+floating+focused button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active. +--- The maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active_hover. +--- The hovered+maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active_press. +--- The pressed+maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active. +--- The ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active_hover. +--- The hovered+ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active_press. +--- The pressed+ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active. +--- The sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active_hover. +--- The hovered+sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active_press. +--- The pressed+sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive. +--- The inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive_hover. +--- The hovered+inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive_press. +--- The pressed+inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive. +--- The inactive+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive_hover. +--- The hovered+inactive+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive_press. +--- The pressed+maximized+inactive button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive. +--- The inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive_hover. +--- The hovered+inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive_press. +--- The pressed+inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive. +--- The inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive_hover. +--- The hovered+inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive_press. +--- The pressed+inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive. +--- The inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive_hover. +--- The hovered+inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive_press. +--- The pressed+inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive. +--- The inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive_hover. +--- The hovered+inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive_press. +--- The pressed+inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive. +--- The inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive_hover. +--- The hovered+inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive_press. +--- The pressed+inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive. +--- The inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive_hover. +--- The hovered+inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive_press. +--- The pressed+inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface --- 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 +-- @tparam table args An array containing the widgets disposition -- @method setup @@ -554,6 +636,18 @@ end -- @tparam[opt] string args.font -- @constructorfct awful.titlebar -- @treturn wibox.drawable The newly created titlebar object. +-- @usebeautiful beautiful.titlebar_fg_normal +-- @usebeautiful beautiful.titlebar_bg_normal +-- @usebeautiful beautiful.titlebar_bgimage_normal +-- @usebeautiful beautiful.titlebar_fg +-- @usebeautiful beautiful.titlebar_bg +-- @usebeautiful beautiful.titlebar_bgimage +-- @usebeautiful beautiful.titlebar_fg_focus +-- @usebeautiful beautiful.titlebar_bg_focus +-- @usebeautiful beautiful.titlebar_bgimage_focus +-- @usebeautiful beautiful.titlebar_fg_urgent +-- @usebeautiful beautiful.titlebar_bg_urgent +-- @usebeautiful beautiful.titlebar_bgimage_urgent local function new(c, args) args = args or {} local position = args.position or "top" @@ -616,7 +710,7 @@ local function new(c, args) end --- Show the client's titlebar. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.show @@ -632,7 +726,7 @@ function titlebar.show(c, position) end --- Hide the client's titlebar. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.hide @@ -642,7 +736,7 @@ function titlebar.hide(c, position) end --- Toggle the client's titlebar, hiding it if it is visible, otherwise showing it. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.toggle @@ -706,7 +800,7 @@ end -- Please note that this returns a textbox and all of textbox' API is available. -- This way, you can e.g. modify the font that is used. -- --- @param c The client for which a titlewidget should be created. +-- @tparam client c The client for which a titlewidget should be created. -- @return The title widget. -- @constructorfct awful.titlebar.widget.titlewidget function titlebar.widget.titlewidget(c) @@ -730,7 +824,7 @@ end -- Please note that this returns an imagebox and all of the imagebox' API is -- available. This way, you can e.g. disallow resizes. -- --- @param c The client for which an icon widget should be created. +-- @tparam client c The client for which an icon widget should be created. -- @return The icon widget. -- @constructorfct awful.titlebar.widget.iconwidget function titlebar.widget.iconwidget(c) @@ -747,12 +841,12 @@ end -- then found in the theme as `titlebar_[name]_button_[normal/focus]_[state]`. -- If that value does not exist, the focused state is ignored for the next try. -- --- @param c The client for which a button is created. +-- @tparam client c The client for which a button is created. -- @tparam string name Name of the button, used for accessing the theme and -- in the tooltip. --- @param selector A function that selects the image that should be displayed. --- @param action Function that is called when the button is clicked. --- @return The widget +-- @tparam function selector A function that selects the image that should be displayed. +-- @tparam function action Function that is called when the button is clicked. +-- @treturn wibox.widget The widget -- @constructorfct awful.titlebar.widget.button function titlebar.widget.button(c, name, selector, action) local ret = imagebox() @@ -840,8 +934,23 @@ function titlebar.widget.button(c, name, selector, action) end --- Create a new float button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.floatingbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_floating_button_normal +-- @usebeautiful beautiful.titlebar_floating_button_focus +-- @usebeautiful beautiful.titlebar_floating_button_normal_active +-- @usebeautiful beautiful.titlebar_floating_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_floating_button_normal_active_press +-- @usebeautiful beautiful.titlebar_floating_button_focus_active +-- @usebeautiful beautiful.titlebar_floating_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_floating_button_focus_active_press +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_press function titlebar.widget.floatingbutton(c) local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle) update_on_signal(c, "property::floating", widget) @@ -849,8 +958,23 @@ function titlebar.widget.floatingbutton(c) end --- Create a new maximize button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.maximizedbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_press +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_press +-- @usebeautiful beautiful.titlebar_maximized_button_normal +-- @usebeautiful beautiful.titlebar_maximized_button_focus +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_press function titlebar.widget.maximizedbutton(c) local widget = titlebar.widget.button(c, "maximized", function(cl) return cl.maximized @@ -862,8 +986,15 @@ function titlebar.widget.maximizedbutton(c) end --- Create a new minimize button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.minimizebutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_minimize_button_normal +-- @usebeautiful beautiful.titlebar_minimize_button_normal_hover +-- @usebeautiful beautiful.titlebar_minimize_button_normal_press +-- @usebeautiful beautiful.titlebar_minimize_button_focus +-- @usebeautiful beautiful.titlebar_minimize_button_focus_hover +-- @usebeautiful beautiful.titlebar_minimize_button_focus_press function titlebar.widget.minimizebutton(c) local widget = titlebar.widget.button(c, "minimize", function() return "" end, @@ -873,15 +1004,37 @@ function titlebar.widget.minimizebutton(c) end --- Create a new closing button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.closebutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_close_button_normal +-- @usebeautiful beautiful.titlebar_close_button_normal_hover +-- @usebeautiful beautiful.titlebar_close_button_normal_press +-- @usebeautiful beautiful.titlebar_close_button_focus +-- @usebeautiful beautiful.titlebar_close_button_focus_hover +-- @usebeautiful beautiful.titlebar_close_button_focus_press function titlebar.widget.closebutton(c) return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end) end --- Create a new ontop button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.ontopbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_ontop_button_normal +-- @usebeautiful beautiful.titlebar_ontop_button_focus +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_press +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_press +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_press function titlebar.widget.ontopbutton(c) local widget = titlebar.widget.button(c, "ontop", function(cl) return cl.ontop end, @@ -891,8 +1044,22 @@ function titlebar.widget.ontopbutton(c) end --- Create a new sticky button for a client. --- @param c The client for which the button is wanted. -- @constructorfct awful.titlebar.widget.stickybutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_sticky_button_normal +-- @usebeautiful beautiful.titlebar_sticky_button_focus +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_press +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_press +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_press function titlebar.widget.stickybutton(c) local widget = titlebar.widget.button(c, "sticky", function(cl) return cl.sticky end, diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index 2e4816cc7..e06ecbeaf 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -107,7 +107,7 @@ local offset = { --- The tooltip opacity. -- @beautiful beautiful.tooltip_opacity --- @param number opacity Between 0 and 1 +-- @tparam number opacity Between 0 and 1 --- The tooltip margins. -- @beautiful beautiful.tooltip_gaps @@ -206,7 +206,7 @@ end --- The wibox containing the tooltip widgets. -- @property wibox --- @param wibox +-- @tparam wibox wibox function tooltip:get_wibox() if self._private.wibox then @@ -229,7 +229,7 @@ end --- Is the tooltip visible? -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @propemits true false function tooltip:get_visible() @@ -269,7 +269,7 @@ end -- * top -- -- @property align --- @param string +-- @tparam string align -- @see mode -- @see preferred_positions -- @propemits true false @@ -277,7 +277,7 @@ end --- The default tooltip alignment. -- @beautiful beautiful.tooltip_align --- @param string +-- @tparam string tooltip_align -- @see align function tooltip:get_align() @@ -330,7 +330,7 @@ end -- * "outside": Outside of the widget -- -- @property mode --- @param string +-- @tparam string mode -- @propemits true false function tooltip:set_mode(mode) @@ -410,7 +410,7 @@ end -- {"front", "back", "middle"} -- -- @property preferred_alignments --- @param string +-- @tparam string preferred_alignments -- @propemits true false -- @see preferred_positions @@ -447,7 +447,7 @@ end --- Change displayed markup. -- -- @property markup --- @tparam string text New tooltip markup, passed to +-- @tparam string markup New tooltip markup, passed to -- `wibox.widget.textbox.set_markup`. -- @propemits true false -- @see wibox.widget.textbox @@ -479,7 +479,7 @@ end -- @DOC_awful_tooltip_margins_EXAMPLE@ -- -- @property margins --- @tparam number|table New margins value. +-- @tparam number|table margins New margins value. -- @propemits true false function tooltip:set_margins(val) @@ -492,7 +492,7 @@ end -- @DOC_awful_tooltip_border_width_EXAMPLE@ -- -- @property border_width --- @param number +-- @tparam[opt=0] number border_width -- @propemits true false -- @propbeautiful @@ -506,8 +506,10 @@ end -- @DOC_awful_tooltip_border_color_EXAMPLE@ -- -- @property border_color --- @param color +-- @tparam[opt=beautiful.tooltip_border_color or beautiful.border_color_normal or beautiful.fg_normal] +-- gears.color border_color -- @propemits true false +-- @propbeautiful function tooltip:set_border_color(val) self.widget.border_color = val @@ -519,7 +521,7 @@ end -- @DOC_awful_tooltip_margins_leftright_EXAMPLE@ -- -- @property margins_leftright --- @tparam number New margins value. +-- @tparam number margins_leftright New margins value. -- @propemits true false function tooltip:set_margin_leftright(val) @@ -538,7 +540,7 @@ end -- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@ -- -- @property margins_topbottom --- @tparam number New margins value. +-- @tparam number margins_topbottom New margins value. -- @propemits true false function tooltip:set_margin_topbottom(val) @@ -557,7 +559,7 @@ end -- @DOC_awful_tooltip_gaps_EXAMPLE@ -- -- @property gaps --- @tparam number|table New margins value. +-- @tparam number|table gaps New margins value. -- @propemits true false function tooltip:set_gaps(val) @@ -617,14 +619,14 @@ end -- @tparam[opt=apply_dpi(5)] integer args.margin_leftright The left/right margin for the text. -- @tparam[opt=apply_dpi(3)] integer args.margin_topbottom The top/bottom margin for the text. -- @tparam[opt=nil] gears.shape args.shape The shape. --- @tparam[opt] string args.bg The background color. --- @tparam[opt] string args.fg The foreground color. --- @tparam[opt] string args.border_color The tooltip border color. --- @tparam[opt] number args.border_width The tooltip border width. +-- @tparam[opt=beautiful.tooltip_bg] string args.bg The background color. +-- @tparam[opt=beautiful.tooltip_fg] string args.fg The foreground color. +-- @tparam[opt=beautiful.tooltip_border_color] string args.border_color The tooltip border color. +-- @tparam[opt=beautiful.tooltip_border_width] number args.border_width The tooltip border width. -- @tparam[opt] string args.align The horizontal alignment. --- @tparam[opt] string args.font The tooltip font. --- @tparam[opt] number args.opacity The tooltip opacity. --- @tparam[opt] table|number args.gaps The tooltip margins. +-- @tparam[opt=beautiful.tooltip_font] string args.font The tooltip font. +-- @tparam[opt=beautiful.tooltip_opacity] number args.opacity The tooltip opacity. +-- @tparam[opt=beautiful.tooltip_gaps] table|number args.gaps The tooltip margins. -- @treturn awful.tooltip The created tooltip. -- @see add_to_object -- @see timeout diff --git a/lib/awful/util.lua b/lib/awful/util.lua index 3d4677c7a..70ac0607b 100644 --- a/lib/awful/util.lua +++ b/lib/awful/util.lua @@ -1,5 +1,8 @@ --------------------------------------------------------------------------- ---- Utility module for awful. +--- Various small utility functions not worth putting into new modules. +-- +-- Most functions in this module are eventually moved into new modules are +-- deprecated. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou @@ -19,11 +22,7 @@ local gstring = require("gears.string") local grect = require("gears.geometry").rectangle local gcolor = require("gears.color") local gfs = require("gears.filesystem") -local capi = -{ - awesome = awesome, - mouse = mouse -} +local capi = { awesome = awesome } local gdebug = require("gears.debug") local gmath = require("gears.math") @@ -38,6 +37,7 @@ util.shell = os.getenv("SHELL") or "/bin/sh" -- This function implementation **has been removed** and no longer -- do anything. Use `awful.spawn.easy_async`. -- @deprecated awful.util.pread +-- @see awful.spawn.easy_async --- Display a deprecation notice, but only once per traceback. -- @deprecated deprecate @@ -99,6 +99,12 @@ function util.mkdir(dir) end --- Eval Lua code. +-- +-- It can either be "real" code or expressions like `2 ~= 3`. +-- If the expression cannot be interpreted or returns false, this +-- function calls `error`. +-- +-- @tparam string code The code to evaluate. -- @return The return value of Lua code. -- @staticfct awful.util.eval function util.eval(s) @@ -128,7 +134,7 @@ end --- Check if a file is a Lua valid file. -- This is done by loading the content and compiling it with loadfile(). --- @param path The file path. +-- @tparam string path The file path. -- @return A function if everything is alright, a string with the error -- otherwise. -- @staticfct awful.util.checkfile @@ -222,13 +228,16 @@ function util.getdir(d) end --- Search for an icon and return the full path. +-- -- It searches for the icon path under the given directories with respect to the -- given extensions for the icon filename. --- @param iconname The name of the icon to search for. --- @param exts Table of image extensions allowed, otherwise { 'png', gif' } --- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' } +-- @tparam string iconname The name of the icon to search for. +-- @tparam[opt={'png','gif'}] table exts Table of image extensions allowed. +-- @tparam[opt={'/usr/share/pixmaps/','/usr/share/icons/hicolor/'}] table dirs +-- Table of dirs to search. -- @tparam[opt] string size The size. If this is specified, subdirectories `x` -- of the dirs are searched first. +-- @treturn string|nil The icon path or `nil` if not found. -- @staticfct awful.util.geticonpath function util.geticonpath(iconname, exts, dirs, size) exts = exts or { 'png', 'gif' } @@ -326,8 +335,8 @@ end -- -- Note that this method doesn't copy entries found in `__index`. -- @deprecated util.table.crush --- @tparam table t the table to be overridden --- @tparam table set the table used to override members of `t` +-- @tparam table t The table to be overridden +-- @tparam table set The table used to override members of `t` -- @tparam[opt=false] boolean raw Use rawset (avoid the metatable) -- @treturn table t (for convenience) -- @see gears.table @@ -387,7 +396,7 @@ end --- Get a sorted table with all keys from a table. -- @deprecated util.table.keys --- @param t the table for which the keys to get +-- @param t The table for which the keys to get -- @return A table with keys -- @see gears.table function util.table.keys(t) @@ -398,7 +407,7 @@ end --- Filter a tables keys for certain content types -- @deprecated util.table.keys_filter -- @param t The table to retrieve the keys for --- @param ... the types to look for +-- @param ... The types to look for -- @return A filtered table with keys -- @see gears.table function util.table.keys_filter(t, ...) @@ -408,7 +417,7 @@ end --- Reverse a table -- @deprecated util.table.reverse --- @param t the table to reverse +-- @param t The table to reverse -- @return the reversed table -- @see gears.table function util.table.reverse(t) @@ -418,7 +427,7 @@ end --- Clone a table -- @deprecated util.table.clone --- @param t the table to clone +-- @param t The table to clone -- @param deep Create a deep clone? (default: true) -- @return a clone of t -- @see gears.table @@ -432,9 +441,9 @@ end -- given index, all elements of a table that match a given criteria. -- -- @deprecated util.table.iterate --- @param t the table to iterate --- @param filter a function that returns true to indicate a positive match --- @param start what index to start iterating from. Default is 1 (=> start of +-- @tparam table t The table to iterate. +-- @tparam function filter A function that returns true to indicate a positive match +-- @param start What index to start iterating from. Default is 1 (=> start of -- the table) -- @see gears.table function util.table.iterate(t, filter, start) @@ -445,8 +454,8 @@ end --- Merge items from the one table to another one -- @deprecated util.table.merge --- @tparam table t the container table --- @tparam table set the mixin table +-- @tparam table t The container table +-- @tparam table set The mixin table -- @treturn table Return `t` for convenience -- @see gears.table function util.table.merge(t, set) diff --git a/lib/awful/wallpaper.lua b/lib/awful/wallpaper.lua index e9374d1ba..19dd08c9f 100644 --- a/lib/awful/wallpaper.lua +++ b/lib/awful/wallpaper.lua @@ -470,6 +470,7 @@ end) -- -- @property bg -- @tparam gears.color bg +-- @usebeautiful beautiful.wallpaper_bg -- @see gears.color --- The foreground color. @@ -485,6 +486,7 @@ end) --- The default wallpaper background color. -- @beautiful beautiful.wallpaper_bg -- @tparam gears.color wallpaper_bg +-- @usebeautiful beautiful.wallpaper_fg -- @see bg --- The default wallpaper foreground color. diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index b3043a117..02377e292 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -537,6 +537,19 @@ end --@DOC_wibox_constructor_COMMON@ -- @return The new wibar -- @constructorfct awful.wibar +-- @usebeautiful beautiful.wibar_favor_vertical +-- @usebeautiful beautiful.wibar_border_width +-- @usebeautiful beautiful.wibar_border_color +-- @usebeautiful beautiful.wibar_ontop +-- @usebeautiful beautiful.wibar_cursor +-- @usebeautiful beautiful.wibar_opacity +-- @usebeautiful beautiful.wibar_type +-- @usebeautiful beautiful.wibar_width +-- @usebeautiful beautiful.wibar_height +-- @usebeautiful beautiful.wibar_bg +-- @usebeautiful beautiful.wibar_bgimage +-- @usebeautiful beautiful.wibar_fg +-- @usebeautiful beautiful.wibar_shape 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 c5b4282bd..c71dc8831 100644 --- a/lib/awful/widget/button.lua +++ b/lib/awful/widget/button.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A simple button widget. +-- A simple button widget based on a background image. -- -- @DOC_wibox_awidget_defaults_button_EXAMPLE@ -- diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 50f76ecb2..5ec6effa9 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A calendar popup wibox. +-- A popup wibox containing a `wibox.widget,calendar` widget. -- -- Display a month or year calendar popup using `calendar_popup.month` or `calendar_popup.year`. -- The calendar style can be tweaked by providing tables of style properties at creation: @@ -386,6 +386,7 @@ end -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`) -- @treturn wibox A wibox containing the calendar -- @constructorfct awful.widget.calendar_popup.month +-- @usebeautiful beautiful.calendar_style function calendar_popup.month(args) return get_cal_wibox("month", args) end diff --git a/lib/awful/widget/clienticon.lua b/lib/awful/widget/clienticon.lua index 1ddc3f1bb..a3151899b 100644 --- a/lib/awful/widget/clienticon.lua +++ b/lib/awful/widget/clienticon.lua @@ -86,7 +86,7 @@ end --- The widget's @{client}. -- -- @property client --- @param client +-- @tparam client client -- @propemits true false function clienticon:get_client() diff --git a/lib/awful/widget/common.lua b/lib/awful/widget/common.lua index c45143fa4..ef665229d 100644 --- a/lib/awful/widget/common.lua +++ b/lib/awful/widget/common.lua @@ -1,4 +1,10 @@ --------------------------------------------------------------------------- +-- This module contains helper functions to manage a layout widgets. +-- +-- This is the boilerplate code to manage a "list" of objects and display +-- them in a `wibox.layout`. It uses signals to detect when an object change +-- and its widget be updated. +-- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou -- @classmod awful.widget.common diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index ecb2a26e1..a512d9fdc 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -1,4 +1,7 @@ --------------------------------------------------------------------------- +-- Display the current keyboard layout name in a widget. +-- +-- -- @author Aleksey Fedotov <lexa@cfotr.com> -- @copyright 2015 Aleksey Fedotov -- @widgetmod awful.widget.keyboardlayout @@ -132,7 +135,7 @@ end -- Create an array whose element is a table consisting of the four fields: -- vendor, file, section and group_idx, which all correspond to the -- xkb_symbols pattern "vendor/file(section):group_idx". --- @tparam string group_names The string awesome.xkb_get_group_names() returns. +-- @tparam string group_names The string `awesome.xkb_get_group_names()` returns. -- @treturn table An array of tables whose keys are vendor, file, section, and group_idx. -- @staticfct awful.keyboardlayout.get_groups_from_group_names function keyboardlayout.get_groups_from_group_names(group_names) @@ -260,7 +263,7 @@ end -- It shows current keyboard layout name in a textbox. -- -- @constructorfct awful.widget.keyboardlayout --- @return A keyboard layout widget. +-- @treturn awful.widget.keyboardlayout A keyboard layout widget. function keyboardlayout.new() local widget = textbox() local self = widget_base.make_widget(widget, nil, {enable_properties=true}) diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index 9edc97e23..ba44437b9 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -178,33 +178,38 @@ end local layoutlist = {} --- The layoutlist default widget layout. +-- -- If no layout is specified, a `wibox.layout.fixed.vertical` will be created -- automatically. -- @property base_layout --- @param widget +-- @tparam[opt=wibox.layout.fixed.vertical] wibox.layout base_layout -- @propemits true false -- @see wibox.layout.fixed.vertical -- @see base_layout --- The delegate widget template. +-- -- @property widget_template --- @param table +-- @tparam[opt=nil] table widget_template -- @propemits true false --- The layoutlist screen. +-- -- @property screen --- @param screen +-- @tparam screen screen --- A function that returns the list of layout to display. -- -- @property source --- @param[opt=awful.widget.layoutlist.source.for_screen] function +-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function source --- The layoutlist filter function. +-- -- @property filter --- @param[opt=awful.widget.layoutlist.source.for_screen] function +-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function filter --- The default foreground (text) color. +-- -- @beautiful beautiful.layoutlist_fg_normal -- @tparam[opt=nil] string|pattern fg_normal -- @see gears.color @@ -276,17 +281,17 @@ local layoutlist = {} --- The currenly displayed layouts. -- @property layouts --- @param table +-- @tparam table layouts --- The currently selected layout. -- @property current_layout --- @param layout +-- @tparam layout current_layout --- The current number of layouts. -- -- @property count -- @readonly --- @tparam number The number of layouts. +-- @tparam number count The number of layouts. -- @propemits true false function layoutlist:get_layouts() @@ -395,22 +400,22 @@ end -- @tparam[opt] table args.widget_template A custom widget to be used for each action. -- @tparam[opt=ascreen.focused()] screen args.screen A screen -- @tparam[opt={}] table args.style Extra look and feel parameters --- @tparam boolean args.style.disable_icon --- @tparam boolean args.style.disable_name --- @tparam string|pattern args.style.fg_normal --- @tparam string|pattern args.style.bg_normal --- @tparam string|pattern args.style.fg_selected --- @tparam string|pattern args.style.bg_selected --- @tparam string args.style.font --- @tparam string args.style.font_selected --- @tparam string args.style.align *left*, *right* or *center* --- @tparam number args.style.spacing --- @tparam gears.shape args.style.shape --- @tparam number args.style.shape_border_width --- @tparam string|pattern args.style.shape_border_color --- @tparam gears.shape args.style.shape_selected --- @tparam string|pattern args.style.shape_border_width_selected --- @tparam string|pattern args.style.shape_border_color_selected +-- @tparam[opt=beautiful.layoutlist_disable_icon] boolean args.style.disable_icon +-- @tparam[opt=beautiful.layoutlist_disable_name] boolean args.style.disable_name +-- @tparam[opt=beautiful.layoutlist_fg_normal] string|pattern args.style.fg_normal +-- @tparam[opt=beautiful.layoutlist_bg_normal] string|pattern args.style.bg_normal +-- @tparam[opt=beautiful.layoutlist_fg_selected] string|pattern args.style.fg_selected +-- @tparam[opt=beautiful.layoutlist_bg_selected] string|pattern args.style.bg_selected +-- @tparam[opt=beautiful.layoutlist_font] string args.style.font +-- @tparam[opt=beautiful.layoutlist_font_selected] string args.style.font_selected +-- @tparam[opt=beautiful.layoutlist_align] string args.style.align *left*, *right* or *center* +-- @tparam[opt=beautiful.layoutlist_spacing] number args.style.spacing +-- @tparam[opt=beautiful.layoutlist_shape] gears.shape args.style.shape +-- @tparam[opt=beautiful.layoutlist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.layoutlist_shape_border_color] string|pattern args.style.shape_border_color +-- @tparam[opt=beautiful.layoutlist_shape_selected] gears.shape args.style.shape_selected +-- @tparam[opt=beautiful.layoutlist_shape_border_width_selected] string|pattern args.style.shape_border_width_selected +-- @tparam[opt=beautiful.layoutlist_shape_border_color_selected] string|pattern args.style.shape_border_color_selected -- @treturn widget The action widget. -- @constructorfct awful.widget.layoutlist diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua index 368a6add8..3dfa0519a 100644 --- a/lib/awful/widget/only_on_screen.lua +++ b/lib/awful/widget/only_on_screen.lua @@ -80,7 +80,7 @@ function only_on_screen:get_screen() return self._private.screen end ---- Returns a new only_on_screen container. +--- Returns a new `awful.widget.only_on_screen` container. -- This widget makes some other widget visible on just some screens. Use -- `:set_widget()` to set the widget and `:set_screen()` to set the screen. -- @param[opt] widget The widget to display. diff --git a/lib/awful/widget/prompt.lua b/lib/awful/widget/prompt.lua index 4dfaef49f..f1a38257d 100644 --- a/lib/awful/widget/prompt.lua +++ b/lib/awful/widget/prompt.lua @@ -73,7 +73,7 @@ end -- of `awful.spawn`. Depending on the amount of customization to your shell -- environment, this can increase startup time. -- @property with_shell --- @param[opt=false] boolean +-- @tparam[opt=false] boolean with_shell --- Create a prompt widget which will launch a command. -- For additional documentation about `args` parameter, please refer to @@ -85,10 +85,10 @@ end -- Prompt background color. -- @tparam[opt=`beautiful.prompt_fg` or `beautiful.fg_normal`] color args.fg -- Prompt foreground color. --- @tparam[opt] gears.color args.fg_cursor --- @tparam[opt] gears.color args.bg_cursor +-- @tparam[opt=beautiful.prompt_fg_cursor] gears.color args.fg_cursor +-- @tparam[opt=beautiful.prompt_bg_cursor] gears.color args.bg_cursor -- @tparam[opt] gears.color args.ul_cursor --- @tparam[opt] string args.font +-- @tparam[opt=beautiful.prompt_font] string args.font -- @tparam[opt] boolean args.autoexec -- @tparam[opt] function args.highlighter A function to add syntax highlighting -- to the command. @@ -116,6 +116,10 @@ end -- @return An instance of prompt widget, inherits from -- `wibox.container.background`. -- @constructorfct awful.widget.prompt +-- @usebeautiful beautiful.prompt_fg +-- @usebeautiful beautiful.prompt_bg +-- @usebeautiful beautiful.fg_normal When `beautiful.prompt_fg` isn't set. +-- @usebeautiful beautiful.bg_normal When `beautiful.prompt_bg` isn't set. 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 3b8f895f5..9894c35b9 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -431,7 +431,7 @@ end -- -- @property count -- @readonly --- @tparam number The number of tags. +-- @tparam number count The number of tags. -- @propemits true false function taglist:set_base_layout(layout) @@ -482,7 +482,7 @@ end -- API is very low level. -- -- @property update_function --- @tparam function update_function. +-- @tparam function update_function --- A function to restrict the content of the taglist. -- @@ -542,34 +542,45 @@ end -- function used to generate the list of tag. -- @tparam[opt] table args.widget_template A custom widget to be used for each tag -- @tparam[opt={}] table args.style The style overrides default theme. --- @tparam[opt=nil] string|pattern args.style.fg_focus --- @tparam[opt=nil] string|pattern args.style.bg_focus --- @tparam[opt=nil] string|pattern args.style.fg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_occupied --- @tparam[opt=nil] string|pattern args.style.fg_occupied --- @tparam[opt=nil] string|pattern args.style.bg_empty --- @tparam[opt=nil] string|pattern args.style.fg_empty --- @tparam[opt=nil] string|pattern args.style.bg_volatile --- @tparam[opt=nil] string|pattern args.style.fg_volatile --- @tparam[opt=nil] string args.style.squares_sel --- @tparam[opt=nil] string args.style.squares_unsel --- @tparam[opt=nil] string args.style.squares_sel_empty --- @tparam[opt=nil] string args.style.squares_unsel_empty --- @tparam[opt=nil] string args.style.squares_resize --- @tparam[opt=nil] string args.style.disable_icon --- @tparam[opt=nil] string args.style.font --- @tparam[opt=nil] number args.style.spacing The spacing between tags. --- @tparam[opt] string args.style.squares_sel A user provided image for selected squares. --- @tparam[opt] string args.style.squares_unsel A user provided image for unselected squares. --- @tparam[opt] string args.style.squares_sel_empty A user provided image for selected squares for empty tags. --- @tparam[opt] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags. --- @tparam[opt] boolean args.style.squares_resize True or false to resize squares. --- @tparam string|pattern args.style.bg_focus The background color for focused client. --- @tparam string|pattern args.style.fg_focus The foreground color for focused client. --- @tparam string|pattern args.style.bg_urgent The background color for urgent clients. --- @tparam string|pattern args.style.fg_urgent The foreground color for urgent clients. --- @tparam string args.style.font The font. +-- @tparam[opt=beautiful.taglist_fg_focus] string|pattern args.style.fg_focus +-- @tparam[opt=beautiful.taglist_bg_focus] string|pattern args.style.bg_focus +-- @tparam[opt=beautiful.taglist_fg_urgent] string|pattern args.style.fg_urgent +-- @tparam[opt=beautiful.taglist_bg_urgent] string|pattern args.style.bg_urgent +-- @tparam[opt=beautiful.taglist_bg_occupied] string|pattern args.style.bg_occupied +-- @tparam[opt=beautiful.taglist_fg_occupied] string|pattern args.style.fg_occupied +-- @tparam[opt=beautiful.taglist_bg_empty] string|pattern args.style.bg_empty +-- @tparam[opt=beautiful.taglist_fg_empty] string|pattern args.style.fg_empty +-- @tparam[opt=beautiful.taglist_bg_volatile] string|pattern args.style.bg_volatile +-- @tparam[opt=beautiful.taglist_fg_volatile] string|pattern args.style.fg_volatile +-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel +-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel +-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty +-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty +-- @tparam[opt=beautiful.taglist_squares_resize] string args.style.squares_resize +-- @tparam[opt=beautiful.taglist_disable_icon] string args.style.disable_icon +-- @tparam[opt=beautiful.taglist_font] string args.style.font +-- @tparam[opt=beautiful.taglist_spacing] number args.style.spacing The spacing between tags. +-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel A user provided image for selected squares. +-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel A user provided image for unselected squares. +-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty A user provided image for selected squares for empty tags. +-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags. +-- @tparam[opt=beautiful.taglist_squares_resize] boolean args.style.squares_resize True or false to resize squares. +-- @tparam[opt=beautiful.taglist_font] string args.style.font The font. +-- @tparam[opt=beautiful.taglist_shape] gears.shape|function args.style.shape +-- @tparam[opt=beautiful.taglist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.taglist_shape_border_color] string args.style.shape_border_color +-- @tparam[opt=beautiful.taglist_shape_empty] gears.shape|function args.style.shape_empty +-- @tparam[opt=beautiful.taglist_shape_border_width_empty] number args.style.shape_border_width_empty +-- @tparam[opt=beautiful.taglist_shape_border_color_empty] string args.style.border_color_empty +-- @tparam[opt=beautiful.taglist_shape_focus] gears.shape|function args.style.shape_focus +-- @tparam[opt=beautiful.taglist_shape_border_width_focus] number args.style.shape_border_width_focus +-- @tparam[opt=beautiful.taglist_shape_border_color_focus] string args.style.shape_border_color_focus +-- @tparam[opt=beautiful.taglist_shape_urgent] gears.shape|function args.style.shape_urgent +-- @tparam[opt=beautiful.taglist_shape_border_width_urgent] number args.style.shape_border_width_urgent +-- @tparam[opt=beautiful.taglist_shape_border_color_urgent] string args.style.shape_border_color_urgent +-- @tparam[opt=beautiful.taglist_shape_volatile] gears.shape|function args.style.shape_volatile +-- @tparam[opt=beautiful.taglist_shape_border_width_volatile] number args.style.shape_border_width_volatile +-- @tparam[opt=beautiful.taglist_shape_border_color_volatile] string args.style.shape_border_color_volatile -- @param filter **DEPRECATED** use args.filter -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 7fbff70c3..d352ff104 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -377,6 +377,10 @@ local instances -- @tparam[opt=nil] string|color shape_border_color_urgent -- @see gears.color +--- The icon size. +-- @beautiful beautiful.tasklist_icon_size +-- @tparam[opt=nil] integer tasklist_icon_size + -- Public structures tasklist.filter, tasklist.source = {}, {} @@ -605,7 +609,7 @@ end -- -- @property count -- @readonly --- @tparam number The number of client. +-- @tparam number count The number of client. -- @propemits true false --- Set the tasklist layout. @@ -799,53 +803,54 @@ end -- function used to generate the list of client. -- @tparam[opt] table args.widget_template A custom widget to be used for each client -- @tparam[opt={}] table args.style The style overrides default theme. --- @tparam[opt=nil] string|pattern args.style.fg_normal --- @tparam[opt=nil] string|pattern args.style.bg_normal --- @tparam[opt=nil] string|pattern args.style.fg_focus --- @tparam[opt=nil] string|pattern args.style.bg_focus --- @tparam[opt=nil] string|pattern args.style.fg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_urgent --- @tparam[opt=nil] string|pattern args.style.fg_minimize --- @tparam[opt=nil] string|pattern args.style.bg_minimize --- @tparam[opt=nil] string args.style.bg_image_normal --- @tparam[opt=nil] string args.style.bg_image_focus --- @tparam[opt=nil] string args.style.bg_image_urgent --- @tparam[opt=nil] string args.style.bg_image_minimize --- @tparam[opt=nil] boolean args.style.disable_icon --- @tparam[opt=nil] number args.style.icon_size The size of the icon --- @tparam[opt='▪'] string args.style.sticky Extra icon when client is sticky --- @tparam[opt='⌃'] string args.style.ontop Extra icon when client is ontop --- @tparam[opt='▴'] string args.style.above Extra icon when client is above --- @tparam[opt='▾'] string args.style.below Extra icon when client is below --- @tparam[opt='✈'] string args.style.floating Extra icon when client is floating --- @tparam[opt='+'] string args.style.maximized Extra icon when client is maximized --- @tparam[opt='⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal --- @tparam[opt='⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical --- @tparam[opt=false] boolean args.style.disable_task_name --- @tparam[opt=nil] string args.style.font --- @tparam[opt="left"] string args.style.align *left*, *right* or *center* --- @tparam[opt=nil] string args.style.font_focus --- @tparam[opt=nil] string args.style.font_minimized --- @tparam[opt=nil] string args.style.font_urgent --- @tparam[opt=nil] number args.style.spacing The spacing between tags. --- @tparam[opt=nil] gears.shape args.style.shape --- @tparam[opt=nil] number args.style.shape_border_width --- @tparam[opt=nil] string|color args.style.shape_border_color --- @tparam[opt=nil] gears.shape args.style.shape_focus --- @tparam[opt=nil] number args.style.shape_border_width_focus --- @tparam[opt=nil] string|color args.style.shape_border_color_focus --- @tparam[opt=nil] gears.shape args.style.shape_minimized --- @tparam[opt=nil] number args.style.shape_border_width_minimized --- @tparam[opt=nil] string|color args.style.shape_border_color_minimized --- @tparam[opt=nil] gears.shape args.style.shape_urgent --- @tparam[opt=nil] number args.style.shape_border_width_urgent --- @tparam[opt=nil] string|color args.style.shape_border_color_urgent +-- @tparam[opt=beautiful.tasklist_fg_normal] string|pattern args.style.fg_normal +-- @tparam[opt=beautiful.tasklist_bg_normal] string|pattern args.style.bg_normal +-- @tparam[opt=beautiful.tasklist_fg_focus or beautiful.fg_focus] string|pattern args.style.fg_focus +-- @tparam[opt=beautiful.tasklist_bg_focus or beautiful.bg_focus] string|pattern args.style.bg_focus +-- @tparam[opt=beautiful.tasklist_fg_urgent or beautiful.fg_urgent] string|pattern args.style.fg_urgent +-- @tparam[opt=beautiful.tasklist_bg_urgent or beautiful.bg_urgent] string|pattern args.style.bg_urgent +-- @tparam[opt=beautiful.tasklist_fg_minimize or beautiful.fg_minimize] string|pattern args.style.fg_minimize +-- @tparam[opt=beautiful.tasklist_bg_minimize or beautiful.bg_minimize] string|pattern args.style.bg_minimize +-- @tparam[opt=beautiful.tasklist_bg_image_normal] string args.style.bg_image_normal +-- @tparam[opt=beautiful.tasklist_bg_image_focus] string args.style.bg_image_focus +-- @tparam[opt=beautiful.tasklist_bg_image_urgent] string args.style.bg_image_urgent +-- @tparam[opt=beautiful.tasklist_bg_image_minimize] string args.style.bg_image_minimize +-- @tparam[opt=beautiful.tasklist_disable_icon] boolean args.style.disable_icon +-- @tparam[opt=beautiful.tasklist_icon_size] number args.style.icon_size The size of the icon +-- @tparam[opt=beautiful.tasklist_sticky or '▪'] string args.style.sticky Extra icon when client is sticky +-- @tparam[opt=beautiful.tasklist_ontop or '⌃'] string args.style.ontop Extra icon when client is ontop +-- @tparam[opt=beautiful.tasklist_above or '▴'] string args.style.above Extra icon when client is above +-- @tparam[opt=beautiful.tasklist_below or '▾'] string args.style.below Extra icon when client is below +-- @tparam[opt=beautiful.tasklist_floating or '✈'] string args.style.floating Extra icon when client is floating +-- @tparam[opt=beautiful.tasklist_maximized or '+'] string args.style.maximized Extra icon when client is maximized +-- @tparam[opt=beautiful.tasklist_maximized_horizontal or '⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal +-- @tparam[opt=beautiful.tasklist_maximized_vertical or '⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical +-- @tparam[opt=beautiful.tasklist_disable_task_name or false] boolean args.style.disable_task_name +-- @tparam[opt=beautiful.tasklist_font] string args.style.font +-- @tparam[opt=beautiful.tasklist_align or "left"] string args.style.align *left*, *right* or *center* +-- @tparam[opt=beautiful.tasklist_font_focus] string args.style.font_focus +-- @tparam[opt=beautiful.tasklist_font_minimized] string args.style.font_minimized +-- @tparam[opt=beautiful.tasklist_font_urgent] string args.style.font_urgent +-- @tparam[opt=beautiful.tasklist_spacing] number args.style.spacing The spacing between tags. +-- @tparam[opt=beautiful.tasklist_shape] gears.shape args.style.shape +-- @tparam[opt=beautiful.tasklist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.tasklist_shape_border_color] string|color args.style.shape_border_color +-- @tparam[opt=beautiful.tasklist_shape_focus] gears.shape args.style.shape_focus +-- @tparam[opt=beautiful.tasklist_shape_border_width_focus] number args.style.shape_border_width_focus +-- @tparam[opt=beautiful.tasklist_shape_border_color_focus] string|color args.style.shape_border_color_focus +-- @tparam[opt=beautiful.tasklist_shape_minimized] gears.shape args.style.shape_minimized +-- @tparam[opt=beautiful.tasklist_shape_border_width_minimized] number args.style.shape_border_width_minimized +-- @tparam[opt=beautiful.tasklist_shape_border_color_minimized] string|color args.style.shape_border_color_minimized +-- @tparam[opt=beautiful.tasklist_shape_urgent] gears.shape args.style.shape_urgent +-- @tparam[opt=beautiful.tasklist_shape_border_width_urgent] number args.style.shape_border_width_urgent +-- @tparam[opt=beautiful.tasklist_shape_border_color_urgent] string|color args.style.shape_border_color_urgent -- @param filter **DEPRECATED** use args.filter -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function -- @param base_widget **DEPRECATED** use args.base_layout -- @constructorfct awful.widget.tasklist +-- @usebeautiful beautiful.tasklist_plain_task_name 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 090fcb9e0..9dfca6f16 100644 --- a/lib/awful/widget/watch.lua +++ b/lib/awful/widget/watch.lua @@ -1,5 +1,6 @@ --------------------------------------------------------------------------- ---- Watch widget. +--- Execute a command at a set interval and display its output. +-- -- Here is an example of simple temperature widget which will update each 15 -- seconds implemented in two different ways. -- The first, simpler one, will just display the return command output @@ -7,20 +8,18 @@ -- In the other example `sensors` returns to the widget its full output -- and it's trimmed in the widget callback function: -- --- 211 mytextclock, --- 212 wibox.widget.textbox(' | '), --- 213 -- one way to do that: --- 214 awful.widget.watch('bash -c "sensors | grep temp1"', 15), --- 215 -- another way: --- 216 awful.widget.watch('sensors', 15, function(widget, stdout) --- 217 for line in stdout:gmatch("[^\r\n]+") do --- 218 if line:match("temp1") then --- 219 widget:set_text(line) --- 220 return --- 221 end --- 222 end --- 223 end), --- 224 s.mylayoutbox, +-- -- one way to do that: +-- local w = awful.widget.watch('bash -c "sensors | grep temp1"', 15) +-- +-- -- another way: +-- local w = awful.widget.watch('sensors', 15, function(widget, stdout) +-- for line in stdout:gmatch("[^\r\n]+") do +-- if line:match("temp1") then +-- widget:set_text(line) +-- return +-- end +-- end +-- end) -- -- ![Example screenshot](../images/awful_widget_watch.png) -- @@ -55,7 +54,7 @@ local watch = { mt = {} } -- function(widget, stdout, stderr, exitreason, exitcode) -- widget:set_text(stdout) -- end --- @param callback.widget Base widget instance. +-- @tparam wibox.widget callback.widget Base widget instance. -- @tparam string callback.stdout Output on stdout. -- @tparam string callback.stderr Output on stderr. -- @tparam string callback.exitreason Exit Reason. @@ -64,7 +63,7 @@ local watch = { mt = {} } -- For "exit" reason it's the exit code. -- For "signal" reason — the signal causing process termination. -- --- @param[opt=wibox.widget.textbox()] base_widget Base widget. +-- @tparam[opt=wibox.widget.textbox()] wibox.widget base_widget Base widget. -- -- @return The widget used by this watch. -- @return Its gears.timer. diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index 9db96f254..44601324c 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- Theme library. +--- Key+value based theme library and associated utility modules. -- -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> @@ -89,62 +89,52 @@ local active_font --- The default font. -- @beautiful beautiful.font --- @param string +-- @param[opt="sans 8"] string --- The default background color. +--- The default background color. +-- +-- The background color can be transparent. If there is a +-- compositing manager such as compton, then it will be +-- real transparency and may include blur (provided by the +-- compositor). When there is no compositor, it will take +-- a picture of the wallpaper and blend it. +-- -- @beautiful beautiful.bg_normal -- @param color --- The default focused element background color. +--- The default focused element background color. -- @beautiful beautiful.bg_focus -- @param color --- The default urgent element background color. +--- The default urgent element background color. -- @beautiful beautiful.bg_urgent -- @param color --- The default minimized element background color. +--- The default minimized element background color. -- @beautiful beautiful.bg_minimize -- @param color --- The system tray background color. --- Please note that only solid colors are currently supported. --- @beautiful beautiful.bg_systray --- @param color - --- The default focused element foreground (text) color. +--- The default focused element foreground (text) color. -- @beautiful beautiful.fg_normal -- @param color --- The default focused element foreground (text) color. +--- The default focused element foreground (text) color. -- @beautiful beautiful.fg_focus -- @param color --- The default urgent element foreground (text) color. +--- The default urgent element foreground (text) color. -- @beautiful beautiful.fg_urgent -- @param color --- The default minimized element foreground (text) color. +--- The default minimized element foreground (text) color. -- @beautiful beautiful.fg_minimize -- @param color ---- The gap between clients. --- @beautiful beautiful.useless_gap --- @param[opt=0] number - ---- The fallback border width. --- @beautiful beautiful.border_width --- @param number - ---- The fallback border color. --- @beautiful beautiful.border_color --- @param color - --- The wallpaper path. -- @beautiful beautiful.wallpaper -- @tparam string|gears.surface wallpaper --- The icon theme name. +--- The icon theme name. -- It has to be a directory in `/usr/share/icons` or an XDG icon folder. -- @beautiful beautiful.icon_theme -- @param string @@ -234,7 +224,7 @@ end --- Get the height of a font. -- --- @param name Name of the font. +-- @tparam string name Name of the font. -- @staticfct beautiful.get_font_height function beautiful.get_font_height(name) return load_font(name).height diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua index 49aac58e5..835e099fd 100644 --- a/lib/gears/debug.lua +++ b/lib/gears/debug.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Utility functions to make development easier. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @utillib gears.debug @@ -141,7 +143,7 @@ end -- @tparam table fallback The new class. -- @tparam string old_name The old class name. -- @tparam string new_name The new class name. --- @tparam[opt={}] args The name. +-- @tparam[opt={}] table args The name. -- @tparam[opt] number args.deprecated_in The version which deprecated this -- class. -- @treturn table A proxy class. diff --git a/lib/gears/filesystem.lua b/lib/gears/filesystem.lua index de58e1a70..64aa43ae0 100644 --- a/lib/gears/filesystem.lua +++ b/lib/gears/filesystem.lua @@ -1,5 +1,8 @@ --------------------------------------------------------------------------- ---- Filesystem module for gears. +--- Various filesystem utility functions. +-- +-- Note that these functions are blocking. If you need to do a large number of +-- I/O operations, it is better to use `lgi.Gio` async functions. -- -- @utillib gears.filesystem --------------------------------------------------------------------------- diff --git a/lib/gears/math.lua b/lib/gears/math.lua index db295f673..38eddaeb4 100644 --- a/lib/gears/math.lua +++ b/lib/gears/math.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Various math related functions. +-- --- Math module for gears. -- -- @utillib gears.math diff --git a/lib/gears/protected_call.lua b/lib/gears/protected_call.lua index fb967d147..7c688ee29 100644 --- a/lib/gears/protected_call.lua +++ b/lib/gears/protected_call.lua @@ -1,4 +1,9 @@ --------------------------------------------------------------------------- +-- Safely call a function and handle errors using `gears.debug`. +-- +-- This is a `pcall`/`xpcall` wrapper. All it does is to integrate into the +-- AwesomeWM-wide error handling and logging. +-- -- @author Uli Schlachter -- @copyright 2016 Uli Schlachter -- @utillib gears.protected_call diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index 4af3d326f..b78c733c1 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -215,7 +215,7 @@ end -- @param cr A cairo content -- @tparam number width The rectangle width -- @tparam number height The rectangle height --- @tparam number radius the corner radius +-- @tparam number radius The corner radius -- @staticfct gears.shape.rounded_rect function module.rounded_rect(cr, width, height, radius) @@ -627,8 +627,8 @@ end -- @tparam[opt=math.min(width height)/2] number thickness The arc thickness -- @tparam[opt=0] number start_angle The start angle (in radian) -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian) --- @tparam[opt=false] boolean start_rounded if the arc start rounded --- @tparam[opt=false] boolean end_rounded if the arc end rounded +-- @tparam[opt=false] boolean start_rounded If the arc start rounded +-- @tparam[opt=false] boolean end_rounded If the arc end rounded -- @staticfct gears.shape.arc function module.arc(cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded) start_angle = start_angle or 0 diff --git a/lib/gears/sort/init.lua b/lib/gears/sort/init.lua index 02c2123f8..2488bd7f0 100644 --- a/lib/gears/sort/init.lua +++ b/lib/gears/sort/init.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Extra sorting algorithms. +--- Utilities to sort and arrange data. -- -- @utillib gears.sort --------------------------------------------------------------------------- diff --git a/lib/gears/string.lua b/lib/gears/string.lua index a4e4db951..229ed810b 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- String module for gears. +--- Various string manipulation and introspection fuctions. -- -- @utillib gears.string --------------------------------------------------------------------------- @@ -10,7 +10,7 @@ local xml_entity_names = { ["'"] = "'", ["\""] = """, ["<"] = "<", --- Escape a string from XML char. -- Useful to set raw text in textbox. --- @param text Text to escape. +-- @tparam string text Text to escape. -- @treturn string Escaped text. -- @staticfct gears.string.xml_escape function gstring.xml_escape(text) @@ -21,7 +21,7 @@ local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = " amp = "&" }; --- Unescape a string from entities. --- @param text Text to unescape. +-- @tparam string text Text to unescape. -- @treturn string Unescaped text. -- @staticfct gears.string.xml_unescape function gstring.xml_unescape(text) diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index a0c2d2b8f..3bf983571 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Utilities to integrate and manipulate Cairo drawing surfaces. +-- -- @author Uli Schlachter -- @copyright 2012 Uli Schlachter -- @module gears.surface @@ -195,10 +197,9 @@ end -- -- If the wibox or client size change, this function need to be called -- again. --- @param draw A wibox or a client --- @param shape or gears.shape function or a custom function with a context, --- width and height as parameter. --- @param[opt] Any additional parameters will be passed to the shape function. +-- @tparam client|wibox draw A wibox or a client. +-- @tparam gears.shape|function shape The shape. +-- @param[opt] ... Any additional parameters will be passed to the shape function. -- @staticfct apply_shape_bounding function surface.apply_shape_bounding(draw, shape, ...) local geo = draw:geometry() diff --git a/lib/gears/table.lua b/lib/gears/table.lua index b98aa66d8..9702c7bc2 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -1,8 +1,8 @@ --------------------------------------------------------------------------- ---- Table module for gears. +--- Various functions to worj with tables. -- -- Examples --- ======= +-- ======== -- -- Using `cycle_value`, you can cycle through values in a table. -- When the end of the table is reached, `cycle_value` loops around to the beginning. diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index b1a9644a4..c27ef6480 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Timer objects and functions. +--- Class to execute code at specific intervals. -- -- @usage -- -- Create a widget and update its content using the output of a shell @@ -134,13 +134,18 @@ function timer:again() end --- The timer is started. --- @property started --- @param boolean +-- +-- For this to be `true` by default, pass `autostart` to the constructor. +-- +-- @property[opt=false] started +-- @tparam boolean started +-- @see start +-- @see stop --- The timer timeout value. --- **Signal:** property::timeout +-- -- @property timeout --- @param number +-- @tparam number timeout -- @propemits true false local timer_instance_mt = { @@ -273,7 +278,7 @@ end --- Call the given function at the end of the current GLib event loop iteration. -- @tparam function callback The function that should be called --- @param ... Arguments to the callback function +--@param ... Arguments to the callback function -- @staticfct gears.timer.delayed_call function timer.delayed_call(callback, ...) assert(type(callback) == "function", "callback must be a function, got: " .. type(callback)) diff --git a/lib/menubar/icon_theme.lua b/lib/menubar/icon_theme.lua index 358f00737..b1946081d 100644 --- a/lib/menubar/icon_theme.lua +++ b/lib/menubar/icon_theme.lua @@ -82,6 +82,7 @@ local index_theme_cache = {} -- @tparam string icon_theme_name Internal name of icon theme -- @tparam table base_directories Paths used for lookup -- @treturn table An instance of the class `icon_theme` +-- @usebeautiful beautiful.icon_theme icon_theme.new = function(icon_theme_name, base_directories) icon_theme_name = icon_theme_name or beautiful.icon_theme or get_default_icon_theme_name() base_directories = base_directories or get_pragmatic_base_directories() diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index 88c8fa5ad..e594fafd1 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -454,6 +454,13 @@ end --- Show the menubar on the given screen. -- @param[opt] scr Screen. -- @staticfct menubar.show +-- @usebeautiful beautiful.menubar_fg_normal +-- @usebeautiful beautiful.menubar_bg_normal +-- @usebeautiful beautiful.menubar_border_width +-- @usebeautiful beautiful.menubar_border_color +-- @usebeautiful beautiful.menubar_fg_focus +-- @usebeautiful beautiful.menubar_bg_focus +-- @usebeautiful beautiful.menubar_font function menubar.show(scr) scr = get_screen(scr or awful.screen.focused() or 1) local fg_color = theme.menubar_fg_normal or theme.menu_fg_normal or theme.fg_normal diff --git a/lib/menubar/utils.lua b/lib/menubar/utils.lua index 9c8f283fd..a3f1e1945 100644 --- a/lib/menubar/utils.lua +++ b/lib/menubar/utils.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Utility module for menubar +--- Utility functions for the `menubar` module. -- -- @author Antonio Terceiro -- @copyright 2009, 2011-2012 Antonio Terceiro, Alexander Yakushev @@ -199,7 +199,7 @@ local function get_icon_lookup_path() end --- Remove CR newline from the end of the string. --- @param s string to trim +-- @tparam string s The string to trim -- @staticfct menubar.utils.rtrim function utils.rtrim(s) if not s then return end diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index 92078d744..a9576c8b3 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -35,12 +35,12 @@ local action = {} -- implement keyboard navigation. -- -- @property selected --- @param boolean +-- @tparam boolean selected -- @propemits true false --- The action position (index). -- @property position --- @param number +-- @tparam number position -- @propemits true false --- The action icon. @@ -53,7 +53,7 @@ local action = {} -- @DOC_wibox_nwidget_actionlist_icon_only_EXAMPLE@ -- -- @property icon_only --- @param[opt=false] boolean +-- @tparam[opt=false] boolean icon_only -- @propemits true false --- When a notification is invoked. diff --git a/lib/naughty/container/background.lua b/lib/naughty/container/background.lua index 535fae5a1..852a6e340 100644 --- a/lib/naughty/container/background.lua +++ b/lib/naughty/container/background.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification background. +--- A notification background widget. -- -- This widget holds the boilerplate code associated with the notification -- background. This includes the color and potentially some other styling @@ -16,6 +16,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2019 Emmanuel Lepage Vallee -- @containermod naughty.widget.background +-- @supermodule wibox.container.background -- @see wibox.container.background ---------------------------------------------------------------------------- local wbg = require("wibox.container.background") diff --git a/lib/naughty/init.lua b/lib/naughty/init.lua index ba23d761d..6b8774073 100644 --- a/lib/naughty/init.lua +++ b/lib/naughty/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Desktop notification handling library. +-- -- @author Uli Schlachter <psychon@znc.in> -- @copyright 2014 Uli Schlachter -- @module naughty diff --git a/lib/naughty/layout/box.lua b/lib/naughty/layout/box.lua index 0c6482471..fae1aeac2 100644 --- a/lib/naughty/layout/box.lua +++ b/lib/naughty/layout/box.lua @@ -208,7 +208,7 @@ end) -- } -- -- @property widget_template --- @param widget +-- @tparam[opt=nil] widget|nil|table widget_template -- @usebeautiful beautiful.notification_max_width The maximum width for the -- resulting widget. diff --git a/lib/naughty/layout/legacy.lua b/lib/naughty/layout/legacy.lua index c5d6c887f..d132d4f65 100644 --- a/lib/naughty/layout/legacy.lua +++ b/lib/naughty/layout/legacy.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification popup widget. +--- A notification popup widget (deprecated implementation). -- -- This is the legacy notification widget. It was the default until Awesome -- v4.3 but is now being deprecated in favor of a more flexible widget. diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 40ff87aae..a2e9e02d1 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A notification object. +--- Notification manipulation class. -- -- This class creates individual notification objects that can be manipulated -- to extend the default behavior. @@ -110,7 +110,7 @@ local notification = {} -- * critical -- -- @property urgency --- @param string +-- @tparam string urgency -- @propemits true false --- The notification category. @@ -167,17 +167,17 @@ local notification = {} -- be updated with a date further in the future. -- -- @property resident --- @param[opt=false] boolean +-- @tparam[opt=false] boolean resident -- @propemits true false --- Delay in seconds after which hovered popup disappears. -- @property hover_timeout --- @param number +-- @tparam[opt=nil] number|nil hover_timeout -- @propemits true false --- Target screen for the notification. -- @property screen --- @param screen +-- @tparam screen screen -- @propemits true false --- Corner of the workarea displaying the popups. @@ -195,34 +195,35 @@ local notification = {} --@DOC_awful_notification_box_corner_EXAMPLE@ -- -- @property position --- @param string +-- @tparam[opt=beautiful.notification_position] string position -- @propemits true false -- @see awful.placement.next_to --- Boolean forcing popups to display on top. -- @property ontop --- @param boolean +-- @tparam[opt=false] boolean ontop --- Popup height. -- --@DOC_awful_notification_geometry_EXAMPLE@ -- -- @property height --- @param number +-- @tparam number height -- @propemits true false -- @see width --- Popup width. -- @property width --- @param number +-- @tparam number width -- @propemits true false -- @see height --- Notification font. --@DOC_naughty_colors_EXAMPLE@ -- @property font --- @param string +-- @tparam string font -- @propemits true false +-- @see wibox.widget.textbox.font --- "All in one" way to access the default image or icon. -- @@ -248,7 +249,7 @@ local notification = {} --- Desired icon size in px. -- @property icon_size --- @param number +-- @tparam[opt=beautiful.notification_icon_size] number icon_size -- @propemits true false --- The icon provided in the `app_icon` field of the DBus notification. @@ -257,7 +258,7 @@ local notification = {} -- icon name to be fetched from the theme. -- -- @property app_icon --- @param string +-- @tparam string app_icon -- @propemits true false --- The notification image. @@ -287,7 +288,7 @@ local notification = {} --@DOC_awful_notification_fg_EXAMPLE@ -- -- @property fg --- @tparam string|color|pattern fg +-- @tparam[beautiful.notification_fg] string|color|pattern fg -- @propemits true false -- @see title -- @see gears.color @@ -297,14 +298,14 @@ local notification = {} --@DOC_awful_notification_bg_EXAMPLE@ -- -- @property bg --- @tparam string|color|pattern bg +-- @tparam[opt=beautiful.notification_bg] string|color|pattern bg -- @propemits true false -- @see title -- @see gears.color --- Border width. -- @property border_width --- @param number +-- @tparam[opt=beautiful.notification_border_width or 0] number border_width -- @propemits true false --- Border color. @@ -312,7 +313,7 @@ local notification = {} --@DOC_awful_notification_border_color_EXAMPLE@ -- -- @property border_color --- @param string +-- @tparam[opt=beautiful.notification_border_color] string border_color -- @propemits true false -- @see gears.color @@ -368,14 +369,14 @@ local notification = {} -- args will override ones defined -- in the preset. -- @property preset --- @param table +-- @tparam table preset -- @propemits true false --- Function that will be called with all arguments. -- The notification will only be displayed if the function returns true. -- Note: this function is only relevant to notifications sent via dbus. -- @property callback --- @param function +-- @tparam function callback -- @propemits true false --- A table containing strings that represents actions to buttons. @@ -383,7 +384,7 @@ local notification = {} -- The table key (a number) is used by DBus to set map the action. -- -- @property actions --- @param table +-- @tparam table actions -- @propemits true false --- Ignore this notification, do not display. @@ -392,19 +393,20 @@ local notification = {} -- handler. -- -- @property ignore --- @param boolean +-- @tparam[opt=false] boolean ignore -- @propemits true false --- Tell if the notification is currently suspended (read only). -- -- This is always equal to `naughty.suspended` ---@property suspended ---@param boolean +-- @property suspended +-- @tparam[opt=false] boolean suspended -- @propemits true false +-- @see naughty.suspended --- If the notification is expired. -- @property is_expired --- @param boolean +-- @tparam boolean is_expired -- @propemits true false -- @see naughty.expiration_paused @@ -436,7 +438,7 @@ local notification = {} -- client. -- -- @property clients --- @param table +-- @tparam table clients --- The maximum popup width. -- @@ -444,8 +446,8 @@ local notification = {} -- this is ignored by `naughty.list.notifications` because it delegate this -- decision to the layout. -- --- @property[opt=500] max_width --- @param number +-- @property max_width +-- @tparam[opt=500] number max_width -- @propemits true false --- The application name specified by the notification. @@ -454,7 +456,7 @@ local notification = {} -- property, but can sometime be specified for remote or headless notifications. -- In these case, it helps to triage and detect the notification from the rules. -- @property app_name --- @param string +-- @tparam string app_name -- @propemits true false --- The widget template used to represent the notification. @@ -463,7 +465,7 @@ local notification = {} -- off with a specialized notification widget. -- -- @property widget_template --- @param table +-- @tparam table|nil widget_template -- @propemits true false --- Destroy notification by notification object. @@ -921,9 +923,9 @@ end -- @tparam[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] string args.bg Background color. -- @tparam[opt=`beautiful.notification_border_width` or 1] integer args.border_width Border width. -- @tparam[opt=`beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'`] gears.color args.border_color Border color. --- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape. --- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity. --- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin. +-- @tparam[opt=beautiful.notification_shape] gears.shape args.shape Widget shape. +-- @tparam[opt=beautiful.notification_opacity] gears.opacity args.opacity Widget opacity. +-- @tparam[opt=beautiful.notification_margin] gears.margin args.margin Widget margin. -- @tparam[opt] function args.run Function to run on left click. The notification -- object will be passed to it as an argument. -- You need to call e.g. diff --git a/lib/naughty/widget/icon.lua b/lib/naughty/widget/icon.lua index f17c5c9d4..00eb59eb6 100644 --- a/lib/naughty/widget/icon.lua +++ b/lib/naughty/widget/icon.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification square icon. +--- A notification square icon widget. -- -- This widget is a specialized `wibox.widget.imagebox` with the following extra -- features: @@ -14,6 +14,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.icon +-- @supermodule wibox.widget.imagebox -- @see wibox.widget.imagebox ---------------------------------------------------------------------------- local imagebox = require("wibox.widget.imagebox") @@ -24,7 +25,7 @@ local dpi = require("beautiful.xresources").apply_dpi local icon = {} --- The default way to resize the icon. +--- The default way to resize the icon. -- @beautiful beautiful.notification_icon_resize_strategy -- @param number @@ -130,6 +131,11 @@ local valid_strategies = { -- there is no specified strategy. -- @usebeautiful beautiful.notification_icon_size The size upper bound. + +--- The default notification icon size. +-- @beautiful beautiful.notification_icon_size +-- @tparam number notification_icon_size The size (in pixels). + function icon:set_resize_strategy(strategy) assert(valid_strategies[strategy], "Invalid strategy") diff --git a/lib/naughty/widget/message.lua b/lib/naughty/widget/message.lua index 9224f1726..6d9a68514 100644 --- a/lib/naughty/widget/message.lua +++ b/lib/naughty/widget/message.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification content message. +--- A notification content message widget. -- -- This widget is a specialized `wibox.widget.textbox` with the following extra -- features: @@ -12,6 +12,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.message +-- @supermodule wibox.widget.textbox -- @see wibox.widget.textbox ---------------------------------------------------------------------------- local textbox = require("wibox.widget.textbox") diff --git a/lib/naughty/widget/title.lua b/lib/naughty/widget/title.lua index dceba4f95..27f1311d6 100644 --- a/lib/naughty/widget/title.lua +++ b/lib/naughty/widget/title.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification title. +--- A notification title widget. -- -- This widget is a specialized `wibox.widget.textbox` with the following extra -- features: @@ -12,6 +12,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.title +-- @supermodule wibox.widget.textbox -- @see wibox.widget.textbox ---------------------------------------------------------------------------- local textbox = require("wibox.widget.textbox") diff --git a/lib/ruled/client.lua b/lib/ruled/client.lua index 54af13a3d..98e0fe0cb 100644 --- a/lib/ruled/client.lua +++ b/lib/ruled/client.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Rules for clients. +--- Apply properties to a new client based on pre-determined rules. -- -- This module applies @{rules} to clients during startup (via @{client.manage}, -- but its functions can be used for client matching in general. diff --git a/lib/ruled/notification.lua b/lib/ruled/notification.lua index de6b306e5..55e8905ea 100644 --- a/lib/ruled/notification.lua +++ b/lib/ruled/notification.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Rules for notifications. +--- Apply properties to a new `naughty.notification` based on pre-determined rules. -- --@DOC_wibox_nwidget_rules_urgency_EXAMPLE@ -- diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index dde2327ee..95b07df86 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -1,6 +1,5 @@ --------------------------------------------------------------------------- --- --- A circular chart (arc chart). +-- A circular chart (arc chart) container. -- -- It can contain a central widget (or not) and display multiple values. -- @@ -43,7 +42,19 @@ local arcchart = { mt = {} } --- The arc thickness. -- @beautiful beautiful.arcchart_thickness --- @param number +-- @tparam number arcchart_thickness + +--- If the chart has rounded edges. +-- @beautiful beautiful.arcchart_rounded_edge +-- @tparam boolean arcchart_rounded_edge + +--- The radial background. +-- @beautiful beautiful.arcchart_bg +-- @tparam gears.color arcchart_bg + +--- The (radiant) angle where the first value start. +-- @beautiful beautiful.arcchart_start_angle +-- @tparam number arcchart_start_angle local function outline_workarea(width, height) local x, y = 0, 0 @@ -102,7 +113,6 @@ function arcchart:after_draw_children(_, cr, width, height) local wa = outline_workarea(width, height) cr:translate(wa.x+border_width/2, wa.y+border_width/2) - -- Get the min and max value --local min_val = self:get_min_value() or 0 --TODO support min_values local max_val = self:get_max_value() @@ -245,9 +255,9 @@ end --- The arcchart values foreground colors. --@DOC_wibox_container_arcchart_color_EXAMPLE@ -- @property colors --- @tparam table values An ordered set of colors for each value in arcchart. +-- @tparam table colors An ordered set of colors for each value in arcchart. -- @propemits true false --- @propbeautiful +-- @usebeautiful beautiful.arcchart_color --- The border width. -- @@ -279,7 +289,7 @@ end --- The value. --@DOC_wibox_container_arcchart_value_EXAMPLE@ -- @property value --- @tparam number value Between min_value and max_value +-- @tparam number value Between `min_value` and `max_value` -- @see values -- @propemits true false @@ -297,18 +307,21 @@ end -- @property rounded_edge -- @tparam[opt=false] boolean rounded_edge -- @propemits true false +-- @propbeautiful --- The arc thickness. --@DOC_wibox_container_arcchart_thickness_EXAMPLE@ -- @property thickness -- @propemits true false -- @tparam number thickness +-- @propbeautiful --- The (radiant) angle where the first value start. ---@DOC_wibox_container_arcchart_start_angle_EXAMPLE@ +-- @DOC_wibox_container_arcchart_start_angle_EXAMPLE@ -- @property start_angle -- @tparam[opt=math.pi] number start_angle A number between 0 and 2*math.pi -- @propemits true false +-- @usebeautiful beautiful.arcchart_start_angle for _, prop in ipairs {"border_width", "border_color", "paddings", "colors", "rounded_edge", "bg", "thickness", "values", "min_value", "max_value", diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index 580c8fd66..384ae7efd 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -349,7 +349,7 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_width --- @tparam[opt=0] number width The border width. +-- @tparam[opt=0] number border_width The border width. -- @propemits true false -- @introducedin 4.4 -- @see border_color @@ -386,7 +386,7 @@ end -- -- @deprecatedproperty shape_border_color -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. --- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient +-- @tparam color fg The border color, pattern or gradient -- @renamedin 4.4 border_color -- @see gears.color -- @see border_color @@ -395,7 +395,7 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_color --- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient +-- @tparam[opt=fg] color border_color The border color, pattern or gradient -- @propemits true false -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. -- @introducedin 4.4 @@ -462,7 +462,7 @@ end -- as arguments. Any other arguments passed to this method will be appended. -- -- @property bgimage --- @tparam string|surface|function image A background image or a function +-- @tparam string|surface|function bgimage A background image or a function -- @see gears.surface function background:set_bgimage(image, ...) diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index 7df9cd9cf..1c8bd90a0 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -94,7 +94,7 @@ end --- Set all the margins to val. -- -- @property margins --- @tparam number|table val The margin value. It can be a number or a table with +-- @tparam number|table margins The margin value. It can be a number or a table with -- the *left*/*right*/*top*/*bottom* keys. -- @propemits false false @@ -126,7 +126,7 @@ end --- Set the margins color to create a border. -- -- @property color --- @param color A color used to fill the margin. +-- @tparam gears.color color A color used to fill the margin. -- @propemits true false function margin:set_color(color) @@ -206,13 +206,13 @@ end --- Returns a new margin container. -- --- @param[opt] widget A widget to use. --- @param[opt] left A margin to use on the left side of the widget. --- @param[opt] right A margin to use on the right side of the widget. --- @param[opt] top A margin to use on the top side of the widget. --- @param[opt] bottom A margin to use on the bottom side of the widget. --- @param[opt] color A color for the margins. --- @param[opt] draw_empty whether or not to draw the margin when the content is empty +-- @tparam[opt] widget widget A widget to use. +-- @tparam[opt] number left A margin to use on the left side of the widget. +-- @tparam[opt] number right A margin to use on the right side of the widget. +-- @tparam[opt] number top A margin to use on the top side of the widget. +-- @tparam[opt] number bottom A margin to use on the bottom side of the widget. +-- @tparam[opt] gears.color color A color for the margins. +-- @tparam[opt] boolean draw_empty Whether or not to draw the margin when the content is empty -- @treturn table A new margin container -- @constructorfct wibox.container.margin local function new(widget, left, right, top, bottom, color, draw_empty) diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index b8ec08055..ac458e9c0 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -178,7 +178,7 @@ end -- --@DOC_wibox_container_radialprogressbar_value_EXAMPLE@ -- @property value --- @tparam number value Between min_value and max_value. +-- @tparam number value Between `min_value` and `max_value`. -- @propemits true false function radialprogressbar:set_value(val) diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index 9da97003f..fedc8e4f9 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -101,7 +101,7 @@ end -- --@DOC_wibox_container_rotate_angle_EXAMPLE@ -- @property direction --- @tparam string dir The direction. +-- @tparam[opt="north"] string direction The direction. -- @propemits true false function rotate:set_direction(dir) diff --git a/lib/wibox/container/tile.lua b/lib/wibox/container/tile.lua index 46fdd391c..e00b8775f 100644 --- a/lib/wibox/container/tile.lua +++ b/lib/wibox/container/tile.lua @@ -110,7 +110,7 @@ end --@DOC_wibox_container_tile_horizontal_crop_EXAMPLE@ -- -- @property horizontal_crop --- @tparam[opt=false] boolean tiled +-- @tparam[opt=false] boolean horizontal_crop -- @see vertical_crop --- Avoid painting incomplete vertical tiles. @@ -118,7 +118,7 @@ end --@DOC_wibox_container_tile_vertical_crop_EXAMPLE@ -- -- @property vertical_crop --- @tparam[opt=false] boolean tiled +-- @tparam[opt=false] boolean vertical_crop -- @see horizontal_crop --- Enable or disable the tiling. @@ -199,9 +199,19 @@ end --- Create a new tile container. -- @tparam table args --- @tparam wibox.widget widget args.widget The widget to tile. +-- @tparam wibox.widget args.widget args.widget The widget to tile. -- @tparam string args.halign Either `left`, `right` or `center`. -- @tparam string args.valign Either `top`, `bottom` or `center`. +-- @tparam number args.horizontal_spacing The horizontal spacing between the tiled. +-- @tparam number args.vertical_spacing The vertical spacing between the tiled. +-- @tparam boolean args.horizontal_crop Avoid painting incomplete horizontal tiles. +-- @tparam boolean args.vertical_crop Avoid painting incomplete vertical tiles. +-- @tparam boolean args.tiled Enable or disable the tiling. +-- @tparam wibox.widget args.widget The widget to be placed. +-- @tparam boolean args.fill_vertical Fill the vertical space. +-- @tparam boolean args.fill_horizontal Fill the horizontal space. +-- @tparam boolean args.content_fill_vertical Stretch the contained widget so it takes all the vertical space. +-- @tparam boolean args.content_fill_horizontal Stretch the contained widget so it takes all the horizontal space. -- @constructorfct wibox.container.tile function module.mt:__call(...) return new(...) diff --git a/lib/wibox/drawable.lua b/lib/wibox/drawable.lua index b8748df77..b79bb3d67 100644 --- a/lib/wibox/drawable.lua +++ b/lib/wibox/drawable.lua @@ -199,7 +199,7 @@ local function find_widgets(self, result, hierarchy, x, y) end end ---- Find a widget by a point. +-- Find a widget by a point. -- The drawable must have drawn itself at least once for this to work. -- @param x X coordinate of the point -- @param y Y coordinate of the point diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index e606864b7..ff458fe78 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Box where widget can be displayed. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @popupmod wibox diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index 58f341794..64d0d948c 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -273,7 +273,7 @@ end -- `"inside"`. -- -- @property expand --- @tparam[opt="inside"] string mode How to use unused space. +-- @tparam[opt="inside"] string expand How to use unused space. function align:set_expand(mode) if mode == "none" or mode == "outside" then diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index bd76c3207..5d4affcbf 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Place many widgets in a column or row, until the available space is used up. +-- -- A `fixed` layout may be initialized with any number of child widgets, and -- during runtime widgets may be added and removed dynamically. -- diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index 9fceef375..153629bae 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -1,4 +1,7 @@ --------------------------------------------------------------------------- +-- Split the space equally between multiple widgets. +-- +-- -- A `flex` layout may be initialized with any number of child widgets, and -- during runtime widgets may be added and removed dynamically. -- @@ -49,7 +52,7 @@ local flex = {} --- Remove a widget from the layout. -- --- @tparam index The widget index to remove. +-- @tparam number index The widget index to remove. -- @treturn boolean index If the operation is successful. -- @method remove -- @interface layout diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index 6ecc04167..dc292ac22 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A grid layout. +--- Place multiple widgets in multiple rows and columns. -- -- Widgets spanning several columns or rows cannot be included using the -- declarative system. @@ -52,7 +52,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- row is filled, creating it if it does not exist. -- --@DOC_wibox_layout_grid_orientation_EXAMPLE@ --- @param[opt="vertical"] string Preferred orientation: "horizontal" or "vertical". +-- @tparam[opt="vertical"] string orientation Preferred orientation: "horizontal" or "vertical". -- @property orientation --- Allow to superpose widgets in the same cell. @@ -60,39 +60,39 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- widget and prevent from adding it. -- --@DOC_wibox_layout_grid_superpose_EXAMPLE@ --- @param[opt=false] boolean +-- @tparam[opt=false] boolean superpose -- @property superpose --- Force the number of rows of the layout. -- @property forced_num_rows --- @tparam[opt=nil] number|nil number Forced number of rows (`nil` for automatic). +-- @tparam[opt=nil] number|nil forced_num_rows Forced number of rows (`nil` for automatic). --- Force the number of columns of the layout. -- @property forced_num_cols --- @tparam[opt=nil] number|nil number Forced number of columns (`nil` for automatic). +-- @tparam[opt=nil] number|nil forced_num_cols Forced number of columns (`nil` for automatic). --- Set the minimum size for the columns. -- --@DOC_wibox_layout_grid_min_size_EXAMPLE@ --- @param[opt=0] number Minimum size of the columns. +-- @tparam[opt=0] number min_cols_size Minimum size of the columns. -- @property min_cols_size --- Set the minimum size for the rows. --- @param[opt=0] number Minimum size of the rows. +-- @tparam[opt=0] number min_rows_size Minimum size of the rows. -- @property min_rows_size --- The spacing between columns. -- -- see `spacing` -- --- @param[opt=0] number The spacing +-- @tparam[opt=0] number horizontal_spacing The spacing -- @property horizontal_spacing --- The spacing between rows. -- -- see `spacing` -- --- @param[opt=0] number The spacing +-- @tparam[opt=0] number vertical_spacing The spacing -- @property vertical_spacing --- The spacing between rows and columns. @@ -101,21 +101,21 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- preferred `orientation`. -- --@DOC_wibox_layout_grid_spacing_EXAMPLE@ --- @param[opt=0] number The spacing +-- @tparam[opt=0] number spacing The spacing -- @property spacing --- Controls if the columns are expanded to use all the available width. -- -- see `expand` -- --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean horizontal_expand Expand the grid into the available space -- @property horizontal_expand --- Controls if the rows are expanded to use all the available height. -- -- see `expand` -- --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean vertical_expand Expand the grid into the available space -- @property vertical_expand --- Controls if the columns/rows are expanded to use all the available space. @@ -124,7 +124,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- preferred `orientation`. -- --@DOC_wibox_layout_grid_expand_EXAMPLE@ --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean expand Expand the grid into the available space -- @property expand --- Controls if the columns all have the same width or if the width of each @@ -132,7 +132,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- -- see `homogeneous` -- --- @param[opt=true] boolean All the columns have the same width. +-- @tparam[opt=true] boolean horizontal_homogeneous All the columns have the same width. -- @property horizontal_homogeneous --- Controls if the rows all have the same height or if the height of each row @@ -140,7 +140,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- -- see `homogeneous` -- --- @param[opt=true] boolean All the rows have the same height. +-- @tparam[opt=true] boolean vertical_homogeneous All the rows have the same height. -- @property vertical_homogeneous --- Controls if the columns/rows all have the same size or if the size depends @@ -150,7 +150,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- by the preferred `orientation`. -- --@DOC_wibox_layout_grid_expand_EXAMPLE@ --- @param[opt=true] boolean All the columns/rows have the same size. +-- @tparam[opt=true] boolean homogeneous All the columns/rows have the same size. -- @property homogeneous --- Child widget position. Return of `get_widget_position`. @@ -305,7 +305,7 @@ end --@DOC_wibox_layout_grid_add_EXAMPLE@ -- -- @method add_widget_at --- @param child Widget that should be added +-- @tparam wibox.widget 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 -- @tparam[opt=1] number row_span The number of rows the widget spans. @@ -400,7 +400,7 @@ end --- Return the coordinates of the widget. -- @method get_widget_position --- @param widget The widget +-- @tparam widget widget The widget -- @treturn table The `position` table of the coordinates in the grid, with -- fields `row`, `col`, `row_span` and `col_span`. function grid:get_widget_position(widget) @@ -441,8 +441,8 @@ 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 +-- @tparam widget old The widget to remove +-- @tparam widget new The widget to add -- @treturn boolean If the operation is successful (widget found) function grid:replace_widget(old, new) -- check if the new object is a widget diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index b570f449d..f89b2c515 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A stacked layout. +-- Place multiple widgets on top of each other. -- -- This layout display widgets on top of each other. It can be used to overlay -- a `wibox.widget.textbox` on top of a `awful.widget.progressbar` or manage @@ -31,7 +31,7 @@ local stack = {mt={}} --- Remove a widget from the layout. -- --- @tparam index The widget index to remove +-- @tparam number index The widget index to remove -- @treturn boolean index If the operation is successful -- @method remove -- @interface layout @@ -115,7 +115,7 @@ end --- Raise a widget at `index` to the top of the stack. -- -- @method raise --- @tparam number index the widget index to raise +-- @tparam number index The widget index to raise function stack:raise(index) if (not index) or (not self._private.widgets[index]) then return end diff --git a/lib/wibox/widget/background.lua b/lib/wibox/widget/background.lua index 0919c2799..7712d5540 100644 --- a/lib/wibox/widget/background.lua +++ b/lib/wibox/widget/background.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- This class has been moved to `wibox.container.background` +-- This class has been moved to `wibox.container.background`. -- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index 26e035231..1cae73bc0 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Base class of every widgets, containers and layouts, +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @classmod wibox.widget.base @@ -31,17 +33,17 @@ local base = {} -- widgets hierarchy. A hierarchy loop is when a widget, or any of its -- children, contain (directly or indirectly) itself. -- @property all_children --- @tparam table children The children. +-- @tparam table all_children The children. -- @baseclass wibox.widget.base --- Force a widget height. -- @property forced_height --- @tparam number|nil height The height (`nil` for automatic) +-- @tparam number|nil forced_height The height (`nil` for automatic) -- @baseclass wibox.widget.base --- Force a widget width. -- @property forced_width --- @tparam number|nil width The width (`nil` for automatic) +-- @tparam number|nil forced_width The width (`nil` for automatic) -- @baseclass wibox.widget.base --- The widget opacity (transparency). @@ -51,14 +53,14 @@ local base = {} --- The widget visibility. -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @baseclass wibox.widget.base --- The widget buttons. -- -- The table contains a list of `awful.button` objects. -- @property buttons --- @param table +-- @tparam table buttons -- @see awful.button -- @baseclass wibox.widget.base @@ -92,7 +94,7 @@ local base = {} -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -123,7 +125,7 @@ local base = {} -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -148,7 +150,7 @@ local base = {} -- @signal mouse::enter -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -173,7 +175,7 @@ local base = {} -- @signal mouse::leave -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. diff --git a/lib/wibox/widget/calendar.lua b/lib/wibox/widget/calendar.lua index b7b21c86a..09bab2b79 100644 --- a/lib/wibox/widget/calendar.lua +++ b/lib/wibox/widget/calendar.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A calendar widget. +-- Display a monthly or yearly calendar. -- -- This module defines two widgets: a month calendar and a year calendar -- @@ -71,7 +71,7 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" -- A table representing the date {day=[number|nil], month=[number|nil], year=[number]}. -- -- E.g.. {day=21, month=2, year=2005}, {month=2, year=2005}, {year=2005} --- @tparam date table Date table. +-- @tparam table date Date table. -- @tparam number date.year Date year -- @tparam number|nil date.month Date month -- @tparam number|nil date.day Date day @@ -80,34 +80,44 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" --- The calendar font. -- -- Choose a monospace font for a better rendering. +-- --@DOC_wibox_widget_calendar_font_EXAMPLE@ --- @param[opt="Monospace 10"] string Font of the calendar +-- +-- @tparam[opt="Monospace 10"] string font Font of the calendar -- @property font +-- @usebeautiful beautiful.calendar_font --- The calendar spacing. -- -- The spacing between cells in the month. -- The spacing between months in a year calendar is twice this value. --- @param[opt=5] number Spacing of the grid +-- @tparam[opt=5] number spacing Spacing of the grid -- @property spacing +-- @usebeautiful beautiful.calendar_spacing --- Display the calendar week numbers. -- --@DOC_wibox_widget_calendar_week_numbers_EXAMPLE@ --- @param[opt=false] boolean Display week numbers +-- +-- @tparam[opt=false] boolean week_numbers Display week numbers -- @property week_numbers +-- @usebeautiful beautiful.calendar_week_numbers --- Start the week on Sunday. -- --@DOC_wibox_widget_calendar_start_sunday_EXAMPLE@ --- @param[opt=false] boolean Start the week on Sunday +-- +-- @tparam[opt=false] boolean start_sunday Start the week on Sunday -- @property start_sunday +-- @usebeautiful beautiful.calendar_start_sunday --- Format the weekdays with three characters instead of two -- --@DOC_wibox_widget_calendar_long_weekdays_EXAMPLE@ --- @param[opt=false] boolean Use three characters for the weekdays instead of two +-- +-- @tparam[opt=false] boolean long_weekdays Use three characters for the weekdays instead of two -- @property long_weekdays +-- @usebeautiful beautiful.calendar_long_weekdays --- The widget encapsulating function. -- @@ -119,15 +129,16 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" -- It is used to add a container to the grid layout and to the cells: -- --@DOC_wibox_widget_calendar_fn_embed_cell_EXAMPLE@ --- @param function Function to embed the widget depending on its flag +-- @tparam function fn_embed Function to embed the widget depending on its flag -- @property fn_embed --- Allow cells to have flexible height -- --@DOC_wibox_widget_calendar_flex_height_EXAMPLE@ -- --- @param[opt=false] boolean Allow flex height. +-- @tparam[opt=false] boolean flex_height Allow flex height. -- @property flex_height +-- @usebeautiful beautiful.flex_height --- Make a textbox -- @tparam string text Text of the textbox @@ -257,7 +268,7 @@ end --- Create a grid layout for the year calendar -- @tparam table props Table of year calendar properties --- @param date Year to display (number or string) +-- @tparam number|string date Year to display. -- @treturn widget Grid layout local function create_year(props, date) -- Create a grid widget with the 12 months diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index f04cf6640..099f32e36 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -137,7 +137,7 @@ local checkbox = {} -- If none is set, then the `shape` property will be used. --@DOC_wibox_widget_checkbox_check_shape_EXAMPLE@ -- @property check_shape --- @tparam gears.shape shape +-- @tparam gears.shape check_shape -- @propbeautiful -- @propemits true false -- @see gears.shape @@ -254,7 +254,7 @@ end --- If the checkbox is checked. -- @property checked --- @param boolean +-- @tparam[opt=false] boolean checked for _, prop in ipairs {"border_width", "bg", "border_color", "check_border_color", "check_border_width", "check_color", "shape", "check_shape", "paddings", diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index 51b5d7545..9d8e1cb7f 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A graph widget. +--- Display multiple values as a stream of bars. -- -- The graph goes from left to right. To change this to right to left, use -- a `wibox.container.mirror` widget. This can also be used to have data @@ -84,7 +84,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_stacked_group_disable_EXAMPLE@ -- -- @property group_colors --- @tparam table colors A table with colors for data groups. +-- @tparam table group_colors A table with colors for data groups. -- @see gears.color --- The maximum value the graph should handle. diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index ace4eed74..946bddc38 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -547,7 +547,7 @@ end -- @DOC_wibox_widget_imagebox_vertical_fit_policy_EXAMPLE@ -- -- @property vertical_fit_policy --- @tparam[opt="auto"] string horizontal_fit_policy +-- @tparam[opt="auto"] string vertical_fit_policy -- @propemits true false -- @see horizontal_fit_policy -- @see resize diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index ccc49c9af..26afbda31 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +--- Utility function for working with widgets. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @module wibox.widget diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 608fdcf6b..1268a6ba0 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -191,7 +191,7 @@ end -- --@DOC_wibox_widget_piechart_label_EXAMPLE@ -- @property display_labels --- @param[opt=true] boolean +-- @tparam[opt=true] boolean display_labels --- The pie elements border width. -- diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index 9e1979849..c541d4ecd 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -54,7 +54,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_border_color_EXAMPLE@ -- -- @property border_color --- @tparam gears.color color The border color to set. +-- @tparam gears.color border_color The border color to set. -- @propemits true false -- @propbeautiful -- @see gears.color @@ -75,7 +75,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_bar_border_color_EXAMPLE@ -- -- @property bar_border_color --- @tparam gears.color color The border color to set. +-- @tparam gears.color bar_border_color The border color to set. -- @propemits true false -- @propbeautiful -- @see gears.color @@ -104,7 +104,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_background_color_EXAMPLE@ -- -- @property background_color --- @tparam gears.color color The progressbar background color. +-- @tparam gears.color background_color The progressbar background color. -- @propemits true false -- @usebeautiful beautiful.progressbar_bg -- @see gears.color @@ -114,7 +114,7 @@ local progressbar = { mt = {} } --@DOC_wibox_widget_progressbar_bar_shape_EXAMPLE@ -- -- @property bar_shape --- @tparam[opt=gears.shape.rectangle] gears.shape shape +-- @tparam[opt=gears.shape.rectangle] gears.shape bar_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -243,7 +243,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_margins1_EXAMPLE@ -- -- @property margins --- @tparam[opt=0] (table|number|nil) margins A table for each side or a number +-- @tparam[opt=0] table|number|nil margins A table for each side or a number -- @tparam[opt=0] number margins.top -- @tparam[opt=0] number margins.bottom -- @tparam[opt=0] number margins.left @@ -268,7 +268,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_paddings1_EXAMPLE@ -- -- @property paddings --- @tparam[opt=0] (table|number|nil) padding A table for each side or a number +-- @tparam[opt=0] (table|number|nil) paddings A table for each side or a number -- @tparam[opt=0] number paddings.top -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left @@ -591,8 +591,24 @@ end -- -- @tparam table args Standard widget() arguments. You should add width and -- height constructor parameters to set progressbar geometry. --- @tparam number args.width The width. --- @tparam number args.height The height. +-- @tparam[opt] number args.width The width. +-- @tparam[opt] number args.height The height. +-- @tparam[opt] gears.color args.border_color The progressbar border color. +-- @tparam[opt] number args.border_width The progressbar border width. +-- @tparam[opt] gears.color args.bar_border_color The progressbar inner border color. +-- @tparam[opt] number args.bar_border_width The progressbar inner border width. +-- @tparam[opt] gears.color args.color The progressbar foreground color. +-- @tparam[opt] gears.color args.background_color The progressbar background color. +-- @tparam[opt] gears.shape args.bar_shape The progressbar inner shape. +-- @tparam[opt] gears.shape args.shape The progressbar shape. +-- @tparam[opt] boolean args.clip Force the inner part (the bar) to fit in the background shape. +-- @tparam[opt] boolean args.ticks The progressbar to draw ticks. +-- @tparam[opt] number args.ticks_gap The progressbar ticks gap. +-- @tparam[opt] number args.ticks_size The progressbar ticks size. +-- @tparam[opt] number args.max_value The maximum value the progressbar should handle. +-- @tparam[opt] table|number args.margins The progressbar margins. +-- @tparam[opt] table|number args.paddings The progressbar padding. +-- @tparam[opt] number args.value Set the progressbar value. -- @treturn wibox.widget.progressbar A progressbar widget. -- @constructorfct wibox.widget.progressbar function progressbar.new(args) diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index 2ae0daa42..d600bcd5c 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -68,7 +68,7 @@ local separator = {} --- The relative percentage covered by the bar. -- -- @property span_ratio --- @tparam[opt=1] number A number between 0 and 1. +-- @tparam[opt=1] number span_ratio A number between 0 and 1. -- @propbeautiful -- @propemits true false @@ -112,7 +112,7 @@ local separator = {} --- The relative percentage covered by the bar. -- @beautiful beautiful.separator_span_ratio --- @tparam[opt=1] number A number between 0 and 1. +-- @tparam[opt=1] number separator_span_ratio A number between 0 and 1. --- The separator's color. -- @beautiful beautiful.separator_color @@ -203,6 +203,13 @@ end --- Create a new separator. -- @constructorfct wibox.widget.separator -- @tparam table args The arguments (all properties are available). +-- @tparam[opt] string args.orientation The separator's orientation. +-- @tparam[opt] number args.thickness The separator's thickness. +-- @tparam[opt] function args.shape The separator's shape. +-- @tparam[opt] number args.span_ratio The relative percentage covered by the bar. +-- @tparam[opt] color args.color The separator's color. +-- @tparam[opt] color args.border_color The separator's border color. +-- @tparam[opt] number args.border_width The separator's border width. local function new(args) local ret = base.make_widget(nil, nil, { diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua index b72577519..4244bdf1b 100644 --- a/lib/wibox/widget/slider.lua +++ b/lib/wibox/widget/slider.lua @@ -30,7 +30,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_shape_EXAMPLE@ -- -- @property handle_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam[opt=gears shape rectangle] gears.shape handle_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -49,7 +49,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_margins_EXAMPLE@ -- -- @property handle_margins --- @tparam[opt={}] table margins +-- @tparam[opt={}] table handle_margins -- @tparam[opt=0] number margins.left -- @tparam[opt=0] number margins.right -- @tparam[opt=0] number margins.top @@ -86,7 +86,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_shape_EXAMPLE@ -- -- @property bar_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam[opt=gears shape rectangle] gears.shape bar_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -124,7 +124,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_margins_EXAMPLE@ -- -- @property bar_margins --- @tparam[opt={}] table margins +-- @tparam[opt={}] table bar_margins -- @tparam[opt=0] number margins.left -- @tparam[opt=0] number margins.right -- @tparam[opt=0] number margins.top @@ -136,6 +136,7 @@ local slider = {mt={}} -- @property bar_border_width -- @tparam[opt=0] number bar_border_width -- @propemits true false +-- @propbeautiful --- The bar (background) border_color. -- @@ -148,8 +149,6 @@ local slider = {mt={}} --- The slider value. -- --- **Signal:** *property::value* notify the value is changed. --- --@DOC_wibox_widget_slider_value_EXAMPLE@ -- -- @property value @@ -521,8 +520,25 @@ local function mouse_press(self, x, y, button_id, _, geo) end --- Create a slider widget. --- @tparam[opt={}] table args +-- -- @constructorfct wibox.widget.slider +-- @tparam[opt={}] table args +-- @tparam[opt] gears.shape args.handle_shape The slider handle shape. +-- @tparam[opt] color args.handle_color The slider handle color. +-- @tparam[opt] table args.handle_margins The slider handle margins. +-- @tparam[opt] number args.handle_width The slider handle width. +-- @tparam[opt] color args.handle_border_color The handle border_color. +-- @tparam[opt] number args.handle_border_width The handle border width. +-- @tparam[opt] gears.shape args.bar_shape The bar (background) shape. +-- @tparam[opt] number args.bar_height The bar (background) height. +-- @tparam[opt] color args.bar_color The bar (background) color. +-- @tparam[opt] color args.bar_active_color The bar (active) color. +-- @tparam[opt] table args.bar_margins The bar (background) margins. +-- @tparam[opt] number args.bar_border_width The bar (background) border width. +-- @tparam[opt] color args.bar_border_color The bar (background) border_color. +-- @tparam[opt] number args.value The slider value. +-- @tparam[opt] number args.minimum The slider minimum value. +-- @tparam[opt] number args.maximum The slider maximum value. 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 f7a20361b..911c768d4 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Container for the various system tray icons. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @widgetmod wibox.widget.systray @@ -27,20 +29,23 @@ local display_on_screen = "primary" --- The systray background color. -- +-- Please note that only solid+opaque colors are supported. It does **not** +-- support gradients, patterns or transparent colors. +-- -- @beautiful beautiful.bg_systray --- @param string The color (string like "#ff0000" only) +-- @tparam string bg_systray The color (string like "#ff0000" only) --- The maximum number of rows for systray icons. Icons will fill the -- current column (orthogonally to the systray direction) before -- filling the next column. -- -- @beautiful beautiful.systray_max_rows --- @tparam[opt=1] integer The positive number of rows +-- @tparam[opt=1] integer systray_max_rows The positive number of rows. --- The systray icon spacing. -- -- @beautiful beautiful.systray_icon_spacing --- @tparam[opt=0] integer The icon spacing +-- @tparam[opt=0] integer systray_icon_spacing The icon spacing local function should_display_on(s) if display_on_screen == "primary" then @@ -143,7 +148,7 @@ end -- available space. Otherwise, any single icon has a size of `size`x`size`. -- -- @property base_size --- @tparam integer|nil size The base size +-- @tparam integer|nil base_size The base size -- @propemits true false function systray:set_base_size(size) @@ -157,7 +162,7 @@ end --- Decide between horizontal or vertical display. -- -- @property horizontal --- @tparam boolean horiz Use horizontal mode? +-- @tparam boolean horizontal Use horizontal mode? -- @propemits true false function systray:set_horizontal(horiz) @@ -171,7 +176,7 @@ end --- Should the systray icons be displayed in reverse order? -- -- @property reverse --- @tparam boolean rev Display in reverse order. +-- @tparam boolean reverse Display in reverse order. -- @propemits true false function systray:set_reverse(rev) @@ -189,7 +194,7 @@ end -- visible on the primary screen. The default value is "primary". -- -- @property screen --- @tparam screen|"primary" s The screen to display on. +-- @tparam screen|"primary" screen The screen to display on. -- @propemits true false function systray:set_screen(s) @@ -204,9 +209,12 @@ end -- -- Note that this widget can only exist once. -- --- @tparam boolean revers Show in the opposite direction +-- @tparam boolean reverse Show in the opposite direction -- @treturn table The new `systray` widget -- @constructorfct wibox.widget.systray +-- @usebeautiful beautiful.bg_systray +-- @usebeautiful beautiful.systray_icon_spacing +-- @usebeautiful beautiful.systray_max_rows 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 3a295a8fe..be8f2d36b 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -21,11 +21,6 @@ local setmetatable = setmetatable local textbox = { mt = {} } ---- The textbox font. --- --- @beautiful beautiful.font --- @param string - --- Set the DPI of a Pango layout local function setup_dpi(box, dpi) assert(dpi, "No DPI provided") @@ -258,7 +253,7 @@ end --@DOC_wibox_widget_textbox_ellipsize_EXAMPLE@ -- -- @property ellipsize --- @tparam[opt="end"] string mode The ellipsize mode. +-- @tparam[opt="end"] string ellipsize The ellipsize mode. -- @propemits true false function textbox:set_ellipsize(mode) @@ -285,7 +280,7 @@ end -- @DOC_wibox_widget_textbox_wrap1_EXAMPLE@ -- -- @property wrap --- @tparam[opt="word_char"] string mode Where to wrap? After "word", "char" or "word_char". +-- @tparam[opt="word_char"] string wrap Where to wrap? After "word", "char" or "word_char". -- @propemits true false function textbox:set_wrap(mode) @@ -315,7 +310,7 @@ end --@DOC_wibox_widget_textbox_valign1_EXAMPLE@ -- -- @property valign --- @tparam[opt="center"] string mode The vertical alignment +-- @tparam[opt="center"] string valign The vertical alignment -- @propemits true false function textbox:set_valign(mode) @@ -345,7 +340,7 @@ end --@DOC_wibox_widget_textbox_align1_EXAMPLE@ -- -- @property align --- @tparam[opt="left"] string mode The horizontal alignment +-- @tparam[opt="left"] string align The horizontal alignment -- @propemits true false function textbox:set_align(mode) diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 2a4c2596e..61a04295d 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Text clock widget. +--- Display the time (and date) in a text box. -- -- The `wibox.widget.textclock` widget is part of the Awesome WM's widget -- system (see @{03-declarative-layout.md}). diff --git a/luaa.c b/luaa.c index 4ebf17d5f..2dbd3ac5f 100644 --- a/luaa.c +++ b/luaa.c @@ -19,7 +19,7 @@ * */ -/** AwesomeWM lifecycle API. +/** AwesomeWM lifecycle and low-level APIs. * * This module contains the functions and signal to manage the lifecycle of the * AwesomeWM process. It allows to execute code at specific point from the early diff --git a/mouse.c b/mouse.c index c7214a595..8bd81aa41 100644 --- a/mouse.c +++ b/mouse.c @@ -19,7 +19,7 @@ * */ -/** awesome mouse API. +/** Manipulate and inspect the mouse cursor. * * The mouse buttons are represented as index. The common ones are: * diff --git a/mousegrabber.c b/mousegrabber.c index 31e0c3457..f048d5d22 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -19,7 +19,7 @@ * */ -/** awesome mousegrabber API. +/** Set a callback to process all mouse events. * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @coreclassmod mousegrabber diff --git a/objects/client.c b/objects/client.c index fbabe7897..74bb0d6fc 100644 --- a/objects/client.c +++ b/objects/client.c @@ -19,7 +19,7 @@ * */ -/** A process window. +/** A process window managed by AwesomeWM. * * Clients are the name used by Awesome (and X11) to refer to a window. * @@ -39,9 +39,6 @@ * client's content. * Finally, each clients can have titlebars (see `awful.titlebar`). * - * Additionally to the classes described here, one can also use signals as - * described in @{signals} and X properties as described in @{xproperties}. - * * Some signal names are starting with a dot. These dots are artefacts from * the documentation generation, you get the real signal name by * removing the starting dot. @@ -273,9 +270,10 @@ lua_class_t client_class; * To implement focus stealing filters see `awful.ewmh.add_activate_filter`. * * @signal request::activate + * @tparam client c The client. * @tparam string context The context where this signal was used. * @tparam[opt] table hints A table with additional hints: - * @tparam[opt=false] boolean hints.raise should the client be raised? + * @tparam[opt=false] boolean hints.raise Should the client be raised? * @request client activate ewmh granted When the client asks to be activated. * @classsignal */ @@ -294,9 +292,10 @@ lua_class_t client_class; * moving the mouse. * * @signal request::autoactivate + * @tparam client c The client. * @tparam string context The context where this signal was used. * @tparam[opt] table hints A table with additional hints: - * @tparam[opt=false] boolean hints.raise should the client be raised? + * @tparam[opt=false] boolean hints.raise Should the client be raised? * @classsignal * */ @@ -307,7 +306,7 @@ lua_class_t client_class; * @tparam client c The client * @tparam string context Why and what to resize. This is used for the * handlers to know if they are capable of applying the new geometry. - * @tparam[opt={}] table Additional arguments. Each context handler may + * @tparam[opt={}] table hints Additional arguments. Each context handler may * interpret this differently. * @request client geometry client_maximize_horizontal granted When a client * (programmatically) asks for the maximization to be changed. @@ -320,6 +319,10 @@ lua_class_t client_class; * * @signal request::tag * @tparam client c The client requesting a new tag. + * @tparam[opt] tag tag A preferred tag. + * @tparam[opt] table hints + * @tparam[opt] string hints.reason + * @tparam[opt] screen hints.screen * @classsignal */ @@ -373,6 +376,8 @@ lua_class_t client_class; /** Emitted when a client gets tagged. * @signal tagged * @tparam tag t The tag object. + * @see tags + * @see untagged */ /** Emitted when a client gets unfocused. @@ -382,6 +387,8 @@ lua_class_t client_class; /** Emitted when a client gets untagged. * @signal untagged * @tparam tag t The tag object. + * @see tags + * @see tagged */ /** @@ -680,7 +687,7 @@ lua_class_t client_class; * } * * @property icon_sizes - * @tparam table sizes + * @tparam table icon_sizes * @propemits false false * @readonly * @see awful.widget.clienticon @@ -1108,7 +1115,7 @@ lua_class_t client_class; * advised to set `size_hints_honor` to `false` in the `ruled.client` rules. * * @property size_hints - * @tparam[opt] table|nil hints The hints. + * @tparam[opt] table|nil size_hints The hints. * @tparam[opt] table|nil hints.user_position A table with `x` and `y` keys. It * contains the preferred position of the client. This is set when the * position has been modified by the user. See `program_position`. @@ -1159,7 +1166,7 @@ lua_class_t client_class; * should be enabled. * * @property motif_wm_hints - * @tparam table hints The hints. + * @tparam table motif_wm_hints The hints. * @tparam[opt] boolean hints.functions.all * @tparam[opt] boolean hints.functions.resize * @tparam[opt] boolean hints.functions.move diff --git a/objects/drawable.c b/objects/drawable.c index 0bf6a21ec..d404b7a46 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -20,10 +20,7 @@ * */ -/** awesome drawable API. - * - * Furthermore to the classes described here, one can also use signals as - * described in @{signals}. +/** Low-level API to allow Cairo to draw on clients and wiboxes. * * @author Uli Schlachter <psychon@znc.in> * @copyright 2012 Uli Schlachter @@ -241,4 +238,6 @@ drawable_class_setup(lua_State *L) NULL); } +/* @DOC_cobject_COMMON@ */ + // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/objects/screen.c b/objects/screen.c index 9eccdc206..9582671e1 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -19,7 +19,7 @@ * */ -/** awesome screen API. +/** A physical or virtual screen object. * * Screen objects can be added and removed over time. To get a callback for all * current and future screens, use `awful.screen.connect_for_each_screen`: @@ -37,9 +37,6 @@ * Most basic Awesome objects also have a screen property, see `mouse.screen` * `client.screen`, `wibox.screen` and `tag.screen`. * - * Furthermore to the classes described here, one can also use signals as - * described in @{signals}. - * * @DOC_uml_nav_tables_screen_EXAMPLE@ * * @author Julien Danjou <julien@danjou.info> @@ -1677,8 +1674,8 @@ luaA_screen_count(lua_State *L) * * @tparam integer x X-coordinate for screen. * @tparam integer y Y-coordinate for screen. - * @tparam integer width width for screen. - * @tparam integer height height for screen. + * @tparam integer width Width for screen. + * @tparam integer height Height for screen. * @treturn screen The new screen. * @constructorfct fake_add */ @@ -1766,6 +1763,8 @@ luaA_screen_fake_remove(lua_State *L) * @tparam integer width The new width for screen. * @tparam integer height The new height for screen. * @method fake_resize + * @see split + * @see geometry */ static int luaA_screen_fake_resize(lua_State *L) diff --git a/objects/tag.c b/objects/tag.c index b76e9ea89..f9ec5cce2 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -19,7 +19,7 @@ * */ - /** awesome tag API. + /** Labelled container where `client` objects can be stored. * * What is a tag? * ============== diff --git a/root.c b/root.c index 4dcca6ad1..a159cc15c 100644 --- a/root.c +++ b/root.c @@ -19,7 +19,16 @@ * */ -/** awesome root window API. +/** APIs to interact with the root window. + * + * X11 windows (clients) are stored in a tree. Each window + * can have children. A common example of this are modal + * dialog windows. + * + * This tree goes beyond a process. The root window is where + * the wallpaper is drawn. It span the combined geometry of + * every screen. It also persist when AwesomeWM is restarted. + * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @coreclassmod root @@ -339,7 +348,7 @@ luaA_root_fake_input(lua_State *L) * (the wallpaper). * * @property keys - * @param table + * @tparam table keys * @see awful.key */ static int @@ -505,7 +514,7 @@ luaA_root_wallpaper(lua_State *L) /** Get the content of the root window as a cairo surface. * * @property content - * @tparam surface A cairo surface with the root window content (aka the whole surface from every screens). + * @tparam surface content A cairo surface with the root window content (aka the whole surface from every screens). * @see gears.surface */ static int diff --git a/xkb.c b/xkb.c index 40b98f8e2..44d1bb8b7 100644 --- a/xkb.c +++ b/xkb.c @@ -37,7 +37,7 @@ * Switch keyboard layout. * * @staticfct xkb_set_layout_group - * @tparam integer num keyboard layout number, integer from 0 to 3 + * @tparam integer num Keyboard layout number, integer from 0 to 3 */ int luaA_xkb_set_layout_group(lua_State *L)