From 52dec54e25b3e77fde0b76dacd00f0f70583d23a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 8 Jun 2019 17:47:39 -0400 Subject: [PATCH 01/23] build: Fix CI issues present in large PRs. Some files, like the tests output and property lists are updated when compiling. --- .travis.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.travis.yml b/.travis.yml index 5664b2fa..75a8cd0f 100644 --- a/.travis.yml +++ b/.travis.yml @@ -303,6 +303,7 @@ script: i=$((i+1)) travis_fold_start "test_commit_${commit}_.$i.$n" echo "Testing commit $commit" + git reset --hard # Some files are updated when compiling... git checkout "$commit" git --no-pager show --stat From 43c851798bd86827dfc56bb8d8eed265029a12d4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 04:20:47 -0400 Subject: [PATCH 02/23] doc: Update the parser for the next commits. Otherwise the CI will fail. --- docs/_parser.lua | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/_parser.lua b/docs/_parser.lua index 323f8677..a1ad5b8a 100644 --- a/docs/_parser.lua +++ b/docs/_parser.lua @@ -68,17 +68,37 @@ local function path_to_module(path) error("Cannot figure out module for " .. tostring(path)) end +local modtypes = { + classmod = true, + widgetmod = true, + containermod = true, + layoutmod = true, + coreclassmod = true, + popupmod = true, +} + +local libtypes = { + module = true, + submodule = true, + utillib = true, + themelib = true, +} + function module.path_to_html(path) local mod = path_to_module(path):gsub(".init", "") local f = assert(io.open(path)) while true do local line = f:read() if not line then break end - if line:match("@classmod") then + + local tag = line:gmatch("@([^ ]+) ")() or "" + + if modtypes[tag] then f:close() return "../classes/".. mod ..".html#" end - if line:match("@module") or line:match("@submodule") then + + if libtypes[tag] then f:close() return "../libraries/".. mod ..".html#" end From d92fda78c46891b1cd44d299361e37f253187e4f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Wed, 5 Jun 2019 17:25:29 -0400 Subject: [PATCH 03/23] doc: Cleanup how methods are rendered in the doc. Previously, there was some `module:foo()` or `gears.object:foo()` because the doc used the "raw" name and/or, in some undefined and race condition prone (due to `pairs()` order), the formatted "classmod" name. Now, just display `:foo()` and be done with it. --- docs/config.ld | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/config.ld b/docs/config.ld index 1207cadf..790237af 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -163,7 +163,13 @@ custom_display_name_handler = function(item, default_handler) return default_handler(item) .. " [deprecated]" end - return default_handler(item) + local ret = default_handler(item) + + -- Get rid of the "module:" in front of method names. It is either wrong or + -- just redundant. + ret = ret:gsub("([^:]*)(:[^:])","%2") + + return ret end -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 From 89a02ac6cd6577fd67fc65d058dd6da32dc4d5fb Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 01:02:31 -0400 Subject: [PATCH 04/23] doc: Standardize the function name. There was some issues like `gears.shape.circle` being called `module.circle`. There is also a disparity between how the constructor and "normal" functions are called. This commit attempts to force everything to have the full module name. --- docs/config.ld | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/config.ld b/docs/config.ld index 790237af..dc4173f7 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -169,6 +169,20 @@ custom_display_name_handler = function(item, default_handler) -- just redundant. ret = ret:gsub("([^:]*)(:[^:])","%2") + -- Undocumented API to get rid of `module.rounded_rect` rather than + -- `gears.shape.rounded_rect` + if ret:sub(1, 7) == "module." and module then + return ret:gsub("^module", item.module.name) + end + + -- Undocumented API to make the libraries and classmod "function" section + -- more consistent. Right now some have their full awful.foo.bar while other + -- have "just" `bar`. Given we use constructors from metatables, we have no + -- choice but to use the full function name. It also makes copy/paste easier. + if item.type == "function" and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then + return item.module.name .. "." .. ret + end + return ret end From c0e8660ca0f63d1cd2e180406e15e77bacc0b44d Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 01:19:02 -0400 Subject: [PATCH 05/23] doc: Display the `Parameters:`

in the doc. It was displayed for most sections, but not the functions. This is problem when the doc already contains a bullet list just before the parameter section. The two looked as if they were a single list. --- docs/config.ld | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index dc4173f7..edb96a0a 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -50,7 +50,7 @@ tparam_alias('screen', 'screen') tparam_alias('screen_or_idx', 'screen|int') -- Hack to get the functions and method on top of the signals and properties -new_type("function", "Functions") +new_type("function", "Functions", false, "Parameters") -- Documentation for objects properties new_type("property", "Object properties", false, "Type") -- Documentation for objects deprecated properties @@ -62,17 +62,17 @@ new_type("signalhandler", "Request handlers", false, "Arguments") -- Allow objects to define a set of beautiful properties affecting them new_type("beautiful", "Theme variables", false, "Type") -- Put deprecated methods in their own section -new_type("deprecated", "Deprecated functions", false, "param") +new_type("deprecated", "Deprecated functions", false, "Parameters") -- For the legacy stateless layout related functions -new_type("legacylayout", "Layout related functions", false, "param") +new_type("legacylayout", "Layout related functions", false, "Parameters") -- Have a category for the client layouts -new_type("clientlayout", "Client layouts", false, "param") +new_type("clientlayout", "Client layouts", false, "Parameters") -- Source functions for the taglist/tasklist/layoutlist new_type("sourcefunction", "List source functions", false) -- Document some callback prototypes new_type("callback", "Callback functions prototype", false, "Parameters") -- gears.matcher / awful.rules sources -new_type("rulesources", "Rule sources", false, "param") +new_type("rulesources", "Rule sources", false, "Parameters") -- gears.matcher / awful.rules rule components new_type("rulecomponent", "Rule components", false, "Type") -- Filter functions for the taglist/tasklist/layoutlist From 6a2b8abe11d18f74dd014f1831ef835e0d038e01 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 01:21:35 -0400 Subject: [PATCH 06/23] doc: Do not mess with the in the deprecated definiton. It worked fine for the table in the header, but the name is also used in the "main" documentation below. This caused the while text to be within the "" section. --- docs/config.ld | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config.ld b/docs/config.ld index edb96a0a..5b698d5c 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -160,7 +160,7 @@ custom_display_name_handler = function(item, default_handler) end if item.type == "deprecated" or item.type == "deprecatedproperty" then - return default_handler(item) .. " [deprecated]" + return default_handler(item) .. " [deprecated]" end local ret = default_handler(item) From d00ac0be937b41fa1b09f0c9b3a50a99334719c2 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 02:06:28 -0400 Subject: [PATCH 07/23] doc: Add a widget, container and layout section to the index. --- docs/config.ld | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/config.ld b/docs/config.ld index 5b698d5c..8088b740 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -1,3 +1,6 @@ +local args = ... + + -- Configuration file for ldoc project='awesome' @@ -86,6 +89,11 @@ kind_names={topic='Documentation', module='Libraries', script='Sample files'} -- Sort modules alphabetically sort_modules=true +-- Add more project level (left side index) types. +new_type("widgetmod" , "Widgets" , true) +new_type("containermod", "Widget containers", true) +new_type("layoutmod" , "Widget layouts" , true) + file = { -- C parts of libraries '../dbus.c', @@ -152,7 +160,6 @@ local no_prefix = { } custom_display_name_handler = function(item, default_handler) - -- Remove the "namespace" from the signals and properties if no_prefix[item.type] then local name = item.name:match("%.([^.]+)$") From e9d41648515c6c632989fdae2327d5b14730f3b6 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 02:10:36 -0400 Subject: [PATCH 08/23] doc: Move all containers to a new section. --- lib/awful/widget/only_on_screen.lua | 2 +- lib/wibox/container/arcchart.lua | 2 +- lib/wibox/container/background.lua | 2 +- lib/wibox/container/constraint.lua | 2 +- lib/wibox/container/margin.lua | 2 +- lib/wibox/container/mirror.lua | 2 +- lib/wibox/container/place.lua | 3 +-- lib/wibox/container/radialprogressbar.lua | 2 +- lib/wibox/container/rotate.lua | 2 +- lib/wibox/container/scroll.lua | 2 +- 10 files changed, 10 insertions(+), 11 deletions(-) diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua index 6d8aae1d..c7494a6a 100644 --- a/lib/awful/widget/only_on_screen.lua +++ b/lib/awful/widget/only_on_screen.lua @@ -4,7 +4,7 @@ -- -- @author Uli Schlachter -- @copyright 2017 Uli Schlachter --- @classmod awful.widget.only_on_screen +-- @containermod awful.widget.only_on_screen --------------------------------------------------------------------------- local type = type diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index f2754146..4b778391 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -7,7 +7,7 @@ --@DOC_wibox_container_defaults_arcchart_EXAMPLE@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2013 Emmanuel Lepage Vallee --- @classmod wibox.container.arcchart +-- @containermod wibox.container.arcchart --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index a88d9dd7..a1d01495 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -5,7 +5,7 @@ --@DOC_wibox_container_defaults_background_EXAMPLE@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.container.background +-- @containermod wibox.container.background --------------------------------------------------------------------------- local base = require("wibox.widget.base") diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index 1d317acc..e54fe266 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -3,7 +3,7 @@ --@DOC_wibox_container_defaults_constraint_EXAMPLE@ -- @author Lukáš Hrázký -- @copyright 2012 Lukáš Hrázký --- @classmod wibox.container.constraint +-- @containermod wibox.container.constraint --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index 632a007e..bcd4b072 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -3,7 +3,7 @@ --@DOC_wibox_container_defaults_margin_EXAMPLE@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.container.margin +-- @containermod wibox.container.margin --------------------------------------------------------------------------- local pairs = pairs diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua index bad0a106..52d6fe79 100644 --- a/lib/wibox/container/mirror.lua +++ b/lib/wibox/container/mirror.lua @@ -3,7 +3,7 @@ --@DOC_wibox_container_defaults_mirror_EXAMPLE@ -- @author dodo -- @copyright 2012 dodo --- @classmod wibox.container.mirror +-- @containermod wibox.container.mirror --------------------------------------------------------------------------- local type = type diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua index a6fb1811..34c79cb8 100644 --- a/lib/wibox/container/place.lua +++ b/lib/wibox/container/place.lua @@ -4,8 +4,7 @@ --@DOC_wibox_container_defaults_place_EXAMPLE@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2016 Emmanuel Lepage Vallee --- @release @AWESOME_VERSION@ --- @classmod wibox.container.place +-- @containermod wibox.container.place --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index a2850862..1507c755 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -8,7 +8,7 @@ --@DOC_wibox_container_defaults_radialprogressbar_EXAMPLE@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2013 Emmanuel Lepage Vallee --- @classmod wibox.container.radialprogressbar +-- @containermod wibox.container.radialprogressbar --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index b981c3b8..d3b08f51 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -4,7 +4,7 @@ --@DOC_wibox_container_defaults_rotate_EXAMPLE@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.container.rotate +-- @containermod wibox.container.rotate --------------------------------------------------------------------------- local error = error diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua index fa2ac477..fbd41b78 100644 --- a/lib/wibox/container/scroll.lua +++ b/lib/wibox/container/scroll.lua @@ -20,7 +20,7 @@ -- } -- @author Uli Schlachter (based on ideas from Saleur Geoffrey) -- @copyright 2015 Uli Schlachter --- @classmod wibox.container.scroll +-- @containermod wibox.container.scroll --------------------------------------------------------------------------- local cache = require("gears.cache") From bb51add0899c662791ce011c60bd8d60db71a0e1 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 02:15:53 -0400 Subject: [PATCH 09/23] doc: Move all widgets to a new section. --- lib/awful/widget/button.lua | 2 +- lib/awful/widget/clienticon.lua | 2 +- lib/awful/widget/keyboardlayout.lua | 2 +- lib/awful/widget/launcher.lua | 2 +- lib/awful/widget/layoutbox.lua | 2 +- lib/awful/widget/layoutlist.lua | 2 +- lib/awful/widget/prompt.lua | 2 +- lib/awful/widget/taglist.lua | 2 +- lib/awful/widget/tasklist.lua | 2 +- lib/awful/widget/watch.lua | 2 +- lib/wibox/widget/calendar.lua | 2 +- lib/wibox/widget/checkbox.lua | 2 +- lib/wibox/widget/graph.lua | 2 +- lib/wibox/widget/imagebox.lua | 2 +- lib/wibox/widget/piechart.lua | 2 +- lib/wibox/widget/progressbar.lua | 2 +- lib/wibox/widget/separator.lua | 2 +- lib/wibox/widget/slider.lua | 2 +- lib/wibox/widget/systray.lua | 2 +- lib/wibox/widget/textbox.lua | 2 +- lib/wibox/widget/textclock.lua | 2 +- 21 files changed, 21 insertions(+), 21 deletions(-) diff --git a/lib/awful/widget/button.lua b/lib/awful/widget/button.lua index e4af1716..db6629a2 100644 --- a/lib/awful/widget/button.lua +++ b/lib/awful/widget/button.lua @@ -9,7 +9,7 @@ -- )) -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou --- @classmod awful.widget.button +-- @widgetmod awful.widget.button --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/awful/widget/clienticon.lua b/lib/awful/widget/clienticon.lua index 98e87dc4..bafda1d2 100644 --- a/lib/awful/widget/clienticon.lua +++ b/lib/awful/widget/clienticon.lua @@ -1,7 +1,7 @@ --- Container showing the icon of a client. -- @author Uli Schlachter -- @copyright 2017 Uli Schlachter --- @classmod awful.widget.clienticon +-- @widgetmod awful.widget.clienticon local base = require("wibox.widget.base") local surface = require("gears.surface") diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index e5809000..35f8a81a 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Aleksey Fedotov <lexa@cfotr.com> -- @copyright 2015 Aleksey Fedotov --- @classmod awful.widget.keyboardlayout +-- @widgetmod awful.widget.keyboardlayout --------------------------------------------------------------------------- local capi = {awesome = awesome} diff --git a/lib/awful/widget/launcher.lua b/lib/awful/widget/launcher.lua index b1024787..e8c6959e 100644 --- a/lib/awful/widget/launcher.lua +++ b/lib/awful/widget/launcher.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou --- @classmod awful.widget.launcher +-- @widgetmod awful.widget.launcher --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/awful/widget/layoutbox.lua b/lib/awful/widget/layoutbox.lua index e049e7a1..56e671a3 100644 --- a/lib/awful/widget/layoutbox.lua +++ b/lib/awful/widget/layoutbox.lua @@ -3,7 +3,7 @@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou --- @classmod awful.widget.layoutbox +-- @widgetmod awful.widget.layoutbox --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index bb43c779..1d2d5be4 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -20,7 +20,7 @@ -- -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2010, 2018 Emmanuel Lepage Vallee --- @classmod awful.widget.layoutlist +-- @widgetmod awful.widget.layoutlist ---------------------------------------------------------------------------- local capi = {screen = screen, tag = tag} diff --git a/lib/awful/widget/prompt.lua b/lib/awful/widget/prompt.lua index 8d75611b..13853f29 100644 --- a/lib/awful/widget/prompt.lua +++ b/lib/awful/widget/prompt.lua @@ -6,7 +6,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou -- @copyright 2018 Aire-One --- @classmod awful.widget.prompt +-- @widgetmod awful.widget.prompt --------------------------------------------------------------------------- --- The prompt foreground color. diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index 4845a1de..8e6d4050 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -34,7 +34,7 @@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou --- @classmod awful.widget.taglist +-- @widgetmod awful.widget.taglist --------------------------------------------------------------------------- -- Grab environment we need diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index bfe6a070..240a5983 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -70,7 +70,7 @@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou --- @classmod awful.widget.tasklist +-- @widgetmod awful.widget.tasklist --------------------------------------------------------------------------- -- Grab environment we need diff --git a/lib/awful/widget/watch.lua b/lib/awful/widget/watch.lua index fe2af7fb..42e0c364 100644 --- a/lib/awful/widget/watch.lua +++ b/lib/awful/widget/watch.lua @@ -27,7 +27,7 @@ -- @author Benjamin Petrenko -- @author Yauheni Kirylau -- @copyright 2015, 2016 Benjamin Petrenko, Yauheni Kirylau --- @classmod awful.widget.watch +-- @widgetmod awful.widget.watch --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/widget/calendar.lua b/lib/wibox/widget/calendar.lua index fe7c6ff2..932c21dd 100644 --- a/lib/wibox/widget/calendar.lua +++ b/lib/wibox/widget/calendar.lua @@ -21,7 +21,7 @@ -- -- @author getzze -- @copyright 2017 getzze --- @classmod wibox.widget.calendar +-- @widgetmod wibox.widget.calendar --------------------------------------------------------------------------- diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index f69eed60..e5eb9f87 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -8,7 +8,7 @@ --@DOC_wibox_widget_defaults_checkbox_EXAMPLE@ -- @author Emmanuel Lepage Valle -- @copyright 2010 Emmanuel Lepage Vallee --- @classmod wibox.widget.checkbox +-- @widgetmod wibox.widget.checkbox --------------------------------------------------------------------------- local color = require( "gears.color" ) diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index 0d5f4cd6..a5ceb086 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -13,7 +13,7 @@ --@DOC_wibox_widget_defaults_graph_EXAMPLE@ -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou --- @classmod wibox.widget.graph +-- @widgetmod wibox.widget.graph --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index e973fc02..f8e28b48 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -3,7 +3,7 @@ --@DOC_wibox_widget_defaults_imagebox_EXAMPLE@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.widget.imagebox +-- @widgetmod wibox.widget.imagebox --------------------------------------------------------------------------- local base = require("wibox.widget.base") diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 9688d826..0cd7adfe 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -7,7 +7,7 @@ --@DOC_wibox_widget_defaults_piechart_EXAMPLE@ -- @author Emmanuel Lepage Valle -- @copyright 2012 Emmanuel Lepage Vallee --- @classmod wibox.widget.piechart +-- @widgetmod wibox.widget.piechart --------------------------------------------------------------------------- local color = require( "gears.color" ) diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index cad18a74..56eb5ac5 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -17,7 +17,7 @@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou --- @classmod wibox.widget.progressbar +-- @widgetmod wibox.widget.progressbar --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index 7e2f56ce..67b1fff4 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -19,7 +19,7 @@ -- -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2014, 2017 Emmanuel Lepage Vallee --- @classmod wibox.widget.separator +-- @widgetmod wibox.widget.separator --------------------------------------------------------------------------- local beautiful = require( "beautiful" ) local base = require( "wibox.widget.base" ) diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua index 2be2033d..15d41813 100644 --- a/lib/wibox/widget/slider.lua +++ b/lib/wibox/widget/slider.lua @@ -6,7 +6,7 @@ -- @author Grigory Mishchenko <grishkokot@gmail.com> -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2015 Grigory Mishchenko, 2016 Emmanuel Lepage Vallee --- @classmod wibox.widget.slider +-- @widgetmod wibox.widget.slider --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua index 4609d20b..b06294b0 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.widget.systray +-- @widgetmod wibox.widget.systray --------------------------------------------------------------------------- local wbase = require("wibox.widget.base") diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index 5630eb23..4264be48 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -4,7 +4,7 @@ -- @author Uli Schlachter -- @author dodo -- @copyright 2010, 2011 Uli Schlachter, dodo --- @classmod wibox.widget.textbox +-- @widgetmod wibox.widget.textbox --------------------------------------------------------------------------- local base = require("wibox.widget.base") diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 4a7baa8f..dce46865 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -3,7 +3,7 @@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou --- @classmod wibox.widget.textclock +-- @widgetmod wibox.widget.textclock --------------------------------------------------------------------------- local setmetatable = setmetatable From 7b00d7667302b2eb9b9ebb010b3b15beb95f3af0 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 02:19:03 -0400 Subject: [PATCH 10/23] doc: Move all layouts to a new section. --- lib/wibox/layout/align.lua | 2 +- lib/wibox/layout/fixed.lua | 2 +- lib/wibox/layout/flex.lua | 2 +- lib/wibox/layout/grid.lua | 2 +- lib/wibox/layout/manual.lua | 2 +- lib/wibox/layout/ratio.lua | 2 +- lib/wibox/layout/stack.lua | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index afb12dba..1271b7e4 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -3,7 +3,7 @@ --@DOC_wibox_layout_defaults_align_EXAMPLE@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.layout.align +-- @layoutmod wibox.layout.align --------------------------------------------------------------------------- local table = table diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index ee7a56ae..5eec5861 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -3,7 +3,7 @@ --@DOC_wibox_layout_defaults_fixed_EXAMPLE@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.layout.fixed +-- @layoutmod wibox.layout.fixed --------------------------------------------------------------------------- local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1) diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index c09daa50..490ff421 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -3,7 +3,7 @@ --@DOC_wibox_layout_defaults_flex_EXAMPLE@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.layout.flex +-- @layoutmod wibox.layout.flex --------------------------------------------------------------------------- local base = require("wibox.widget.base") diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index a0734614..37bccc53 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -13,7 +13,7 @@ --@DOC_wibox_layout_defaults_grid_EXAMPLE@ -- @author getzze -- @copyright 2017 getzze --- @classmod wibox.layout.grid +-- @layoutmod wibox.layout.grid --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/wibox/layout/manual.lua b/lib/wibox/layout/manual.lua index 4fe4aa3d..d16a0bb5 100644 --- a/lib/wibox/layout/manual.lua +++ b/lib/wibox/layout/manual.lua @@ -7,7 +7,7 @@ --@DOC_wibox_layout_defaults_manual_EXAMPLE@ -- @author Emmanuel Lepage Vallee -- @copyright 2016 Emmanuel Lepage Vallee --- @classmod wibox.layout.manual +-- @layoutmod wibox.layout.manual --------------------------------------------------------------------------- local gtable = require("gears.table") local base = require("wibox.widget.base") diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua index 04828a6a..de79be27 100644 --- a/lib/wibox/layout/ratio.lua +++ b/lib/wibox/layout/ratio.lua @@ -6,7 +6,7 @@ --@DOC_wibox_layout_defaults_ratio_EXAMPLE@ -- @author Emmanuel Lepage Vallee -- @copyright 2016 Emmanuel Lepage Vallee --- @classmod wibox.layout.ratio +-- @layoutmod wibox.layout.ratio --------------------------------------------------------------------------- local base = require("wibox.widget.base" ) diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index 7592c44d..4cc8d6c2 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -11,7 +11,7 @@ --@DOC_wibox_layout_defaults_stack_EXAMPLE@ -- @author Emmanuel Lepage Vallee -- @copyright 2016 Emmanuel Lepage Vallee --- @classmod wibox.layout.stack +-- @layoutmod wibox.layout.stack --------------------------------------------------------------------------- local base = require("wibox.widget.base" ) From 9d0c2200b275357fe24dd79248e71c65870b0a1c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 02:40:00 -0400 Subject: [PATCH 11/23] doc: Add a section for the important classes. The choice is very subjective, but at least they stand out. --- docs/config.ld | 1 + lib/awful/keygrabber.lua | 3 +-- lib/gears/timer.lua | 2 +- lib/naughty/notification.lua | 2 +- lib/wibox/init.lua | 2 +- mouse.c | 2 +- mousegrabber.c | 2 +- objects/button.c | 2 +- objects/client.c | 2 +- objects/drawable.c | 2 +- objects/key.c | 2 +- objects/screen.c | 2 +- objects/tag.c | 2 +- root.c | 2 +- 14 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 8088b740..17214014 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -93,6 +93,7 @@ sort_modules=true new_type("widgetmod" , "Widgets" , true) new_type("containermod", "Widget containers", true) new_type("layoutmod" , "Widget layouts" , true) +new_type("coreclassmod", "Core components" , true) file = { -- C parts of libraries diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index 928a6ecb..82e1038e 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -60,7 +60,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2012 dodo -- @copyright 2017 Emmanuel Lepage Vallee --- @classmod awful.keygrabber +-- @coreclassmod awful.keygrabber --------------------------------------------------------------------------- local ipairs = ipairs @@ -731,7 +731,6 @@ end -- @return the given callback `g`. -- -- @deprecated awful.keygrabber.run --- @see keygrabber.run --- A lower level API to interact with the keygrabber directly. -- diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index bcc692cf..a955472b 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -46,7 +46,7 @@ -- -- @author Uli Schlachter -- @copyright 2014 Uli Schlachter --- @classmod gears.timer +-- @coreclassmod gears.timer --------------------------------------------------------------------------- local capi = { awesome = awesome } diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 792a4ae9..4be3b164 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -13,7 +13,7 @@ -- @author Emmanuel Lepage Vallee -- @copyright 2008 koniu -- @copyright 2017 Emmanuel Lepage Vallee --- @classmod naughty.notification +-- @coreclassmod naughty.notification --------------------------------------------------------------------------- local gobject = require("gears.object") local gtable = require("gears.table") diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index 383cf50f..0e59e9eb 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox +-- @coreclassmod wibox --------------------------------------------------------------------------- local capi = { diff --git a/mouse.c b/mouse.c index d4c11bba..3f2ccf89 100644 --- a/mouse.c +++ b/mouse.c @@ -57,7 +57,7 @@ * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @module mouse + * @coreclassmod mouse */ #include "mouse.h" diff --git a/mousegrabber.c b/mousegrabber.c index 282c9d22..5efe7205 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -22,7 +22,7 @@ /** awesome mousegrabber API * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @module mousegrabber + * @coreclassmod mousegrabber */ #include "mousegrabber.h" diff --git a/objects/button.c b/objects/button.c index 846ed7d4..9670b470 100644 --- a/objects/button.c +++ b/objects/button.c @@ -30,7 +30,7 @@ * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @classmod button + * @coreclassmod button */ #include "button.h" diff --git a/objects/client.c b/objects/client.c index f38e1626..40ba1525 100644 --- a/objects/client.c +++ b/objects/client.c @@ -84,7 +84,7 @@ * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @classmod client + * @coreclassmod client */ #include "objects/client.h" diff --git a/objects/drawable.c b/objects/drawable.c index f041ecc0..89e750d6 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -27,7 +27,7 @@ * * @author Uli Schlachter <psychon@znc.in> * @copyright 2012 Uli Schlachter - * @classmod drawable + * @coreclassmod drawable */ #include "drawable.h" diff --git a/objects/key.c b/objects/key.c index 932921ca..eca16c7f 100644 --- a/objects/key.c +++ b/objects/key.c @@ -31,7 +31,7 @@ * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @classmod key + * @coreclassmod key */ #include "objects/key.h" diff --git a/objects/screen.c b/objects/screen.c index 0800450f..cbc57c53 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -42,7 +42,7 @@ * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @classmod screen + * @coreclassmod screen */ #include "objects/screen.h" diff --git a/objects/tag.c b/objects/tag.c index 9b289dee..7c95aecc 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -180,7 +180,7 @@ * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @classmod tag + * @coreclassmod tag */ #include "tag.h" diff --git a/root.c b/root.c index bc649c40..9edef1d5 100644 --- a/root.c +++ b/root.c @@ -22,7 +22,7 @@ /** awesome root window API * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou - * @module root + * @coreclassmod root */ #include "globalconf.h" From f1dceb02f60d9f51a5c01a3eb55813d0d6819521 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 02:44:00 -0400 Subject: [PATCH 12/23] doc: Move all popups to a section. --- docs/config.ld | 1 + lib/awful/hotkeys_popup/widget.lua | 2 +- lib/awful/popup.lua | 2 +- lib/awful/titlebar.lua | 2 +- lib/awful/tooltip.lua | 2 +- lib/awful/wibar.lua | 2 +- lib/awful/widget/calendar_popup.lua | 2 +- lib/naughty/layout/legacy.lua | 2 +- lib/wibox/init.lua | 2 +- 9 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 17214014..7b4eb69b 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -94,6 +94,7 @@ new_type("widgetmod" , "Widgets" , true) new_type("containermod", "Widget containers", true) new_type("layoutmod" , "Widget layouts" , true) new_type("coreclassmod", "Core components" , true) +new_type("popupmod" , "Popups and bars" , true) file = { -- C parts of libraries diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index f8efb46a..044deae5 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -3,7 +3,7 @@ -- -- @author Yauheni Kirylau <yawghen@gmail.com> -- @copyright 2014-2015 Yauheni Kirylau --- @module awful.hotkeys_popup.widget +-- @popupmod awful.hotkeys_popup.widget --------------------------------------------------------------------------- local capi = { diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index 7dc4e59f..66efbf13 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -18,7 +18,7 @@ -- -- @author Emmanuel Lepage Vallee -- @copyright 2016 Emmanuel Lepage Vallee --- @classmod awful.popup +-- @popupmod awful.popup --------------------------------------------------------------------------- local wibox = require( "wibox" ) local util = require( "awful.util" ) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index ed7b3054..793abf20 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -9,7 +9,7 @@ -- -- @author Uli Schlachter -- @copyright 2012 Uli Schlachter --- @classmod awful.titlebar +-- @popupmod awful.titlebar --------------------------------------------------------------------------- local error = error diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index 5fb6db1f..5cfbad24 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -39,7 +39,7 @@ -- -- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org> -- @copyright 2009 Sébastien Gross --- @classmod awful.tooltip +-- @popupmod awful.tooltip ------------------------------------------------------------------------- local timer = require("gears.timer") diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index bdb3da88..bb7da67e 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -5,7 +5,7 @@ -- -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2016 Emmanuel Lepage Vallee --- @classmod awful.wibar +-- @popupmod awful.wibar --------------------------------------------------------------------------- -- Grab environment we need diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index df49c89c..fe3fdc78 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -22,7 +22,7 @@ -- -- @author getzze -- @copyright 2017 getzze --- @classmod awful.widget.calendar_popup +-- @popupmod awful.widget.calendar_popup --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/naughty/layout/legacy.lua b/lib/naughty/layout/legacy.lua index 530351c3..c0973290 100644 --- a/lib/naughty/layout/legacy.lua +++ b/lib/naughty/layout/legacy.lua @@ -17,7 +17,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2008 koniu -- @copyright 2017 Emmanuel Lepage Vallee --- @classmod naughty.layout.legacy +-- @popupmod naughty.layout.legacy ---------------------------------------------------------------------------- local capi = { screen = screen, awesome = awesome } diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index 0e59e9eb..8335badf 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @coreclassmod wibox +-- @popupmod wibox --------------------------------------------------------------------------- local capi = { From ded35502d5820af51891ae2151c0c65e866bf188 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 03:40:17 -0400 Subject: [PATCH 13/23] doc: Add a section for utility libraries Dedicated for the modules extensions developers will need, but that the general "I only edit rc.lua" user wont. --- docs/config.ld | 1 + lib/gears/debug.lua | 2 +- lib/gears/filesystem.lua | 2 +- lib/gears/geometry.lua | 2 +- lib/gears/math.lua | 2 +- lib/gears/object.lua | 2 +- lib/gears/protected_call.lua | 2 +- lib/gears/sort/init.lua | 2 +- lib/gears/string.lua | 2 +- lib/gears/table.lua | 2 +- lib/gears/wallpaper.lua | 2 +- 11 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 7b4eb69b..73a3370d 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -95,6 +95,7 @@ new_type("containermod", "Widget containers", true) new_type("layoutmod" , "Widget layouts" , true) new_type("coreclassmod", "Core components" , true) new_type("popupmod" , "Popups and bars" , true) +new_type("utillib" , "Utility libraries", true) file = { -- C parts of libraries diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua index fe5e934d..f8aeccff 100644 --- a/lib/gears/debug.lua +++ b/lib/gears/debug.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @module gears.debug +-- @utillib gears.debug --------------------------------------------------------------------------- local tostring = tostring diff --git a/lib/gears/filesystem.lua b/lib/gears/filesystem.lua index 5a12b1ad..3179292a 100644 --- a/lib/gears/filesystem.lua +++ b/lib/gears/filesystem.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- --- Filesystem module for gears -- --- @module gears.filesystem +-- @utillib gears.filesystem --------------------------------------------------------------------------- -- Grab environment we need diff --git a/lib/gears/geometry.lua b/lib/gears/geometry.lua index 876fb1e6..98c5c2ab 100644 --- a/lib/gears/geometry.lua +++ b/lib/gears/geometry.lua @@ -7,7 +7,7 @@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou --- @module gears.geometry +-- @utillib gears.geometry --------------------------------------------------------------------------- local math = math diff --git a/lib/gears/math.lua b/lib/gears/math.lua index accbe449..58c69ad8 100644 --- a/lib/gears/math.lua +++ b/lib/gears/math.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- --- Math module for gears -- --- @module gears.math +-- @utillib gears.math --------------------------------------------------------------------------- local rtable = table diff --git a/lib/gears/object.lua b/lib/gears/object.lua index 4fe1d22b..d6f539fd 100644 --- a/lib/gears/object.lua +++ b/lib/gears/object.lua @@ -6,7 +6,7 @@ -- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod gears.object +-- @utillib gears.object --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/gears/protected_call.lua b/lib/gears/protected_call.lua index ef22f609..d8f62642 100644 --- a/lib/gears/protected_call.lua +++ b/lib/gears/protected_call.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Uli Schlachter -- @copyright 2016 Uli Schlachter --- @module gears.protected_call +-- @utillib gears.protected_call --------------------------------------------------------------------------- local gdebug = require("gears.debug") diff --git a/lib/gears/sort/init.lua b/lib/gears/sort/init.lua index 2f5e3b9a..02c2123f 100644 --- a/lib/gears/sort/init.lua +++ b/lib/gears/sort/init.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- --- Extra sorting algorithms. -- --- @module gears.sort +-- @utillib gears.sort --------------------------------------------------------------------------- return { diff --git a/lib/gears/string.lua b/lib/gears/string.lua index 6b6eb6b0..84c57788 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- --- String module for gears -- --- @module gears.string +-- @utillib gears.string --------------------------------------------------------------------------- local gstring = {} diff --git a/lib/gears/table.lua b/lib/gears/table.lua index d5f52574..70f99003 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- --- Table module for gears -- --- @module gears.table +-- @utillib gears.table --------------------------------------------------------------------------- diff --git a/lib/gears/wallpaper.lua b/lib/gears/wallpaper.lua index f238b475..13da9b7b 100644 --- a/lib/gears/wallpaper.lua +++ b/lib/gears/wallpaper.lua @@ -20,7 +20,7 @@ -- -- @author Uli Schlachter -- @copyright 2012 Uli Schlachter --- @module gears.wallpaper +-- @utillib gears.wallpaper --------------------------------------------------------------------------- local cairo = require("lgi").cairo From cdeafeff94b96259e4b28f804ef32d1a1754b3bc Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 03:49:21 -0400 Subject: [PATCH 14/23] doc: Add a section for theme related libraries --- docs/config.ld | 1 + lib/beautiful/gtk.lua | 2 +- lib/beautiful/init.lua | 2 +- lib/gears/color.lua | 2 +- lib/gears/shape.lua | 2 +- 5 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 73a3370d..dc244ae2 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -96,6 +96,7 @@ new_type("layoutmod" , "Widget layouts" , true) new_type("coreclassmod", "Core components" , true) new_type("popupmod" , "Popups and bars" , true) new_type("utillib" , "Utility libraries", true) +new_type("themelib" , "Theme related libraries", true) file = { -- C parts of libraries diff --git a/lib/beautiful/gtk.lua b/lib/beautiful/gtk.lua index df71b1a3..13a8023b 100644 --- a/lib/beautiful/gtk.lua +++ b/lib/beautiful/gtk.lua @@ -3,7 +3,7 @@ -- -- @author Yauheni Kirylau <yawghen@gmail.com> -- @copyright 2016-2017 Yauheni Kirylau --- @module beautiful.gtk +-- @themelib beautiful.gtk --------------------------------------------------------------------------- local get_dpi = require("beautiful.xresources").get_dpi local gears_debug = require("gears.debug") diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index a10fbf7e..f87aafd9 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -4,7 +4,7 @@ -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Damien Leone, Julien Danjou --- @module beautiful +-- @themelib beautiful ---------------------------------------------------------------------------- -- Grab environment diff --git a/lib/gears/color.lua b/lib/gears/color.lua index b14e52b5..10f6a2bc 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -39,7 +39,7 @@ -- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @module gears.color +-- @themelib gears.color --------------------------------------------------------------------------- local setmetatable = setmetatable diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index 6c6bf223..707e06cc 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -38,7 +38,7 @@ -- -- @author Emmanuel Lepage Vallee -- @copyright 2011-2016 Emmanuel Lepage Vallee --- @module gears.shape +-- @themelib gears.shape --------------------------------------------------------------------------- local g_matrix = require( "gears.matrix" ) local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1) From 6ce4fa6802a4a22f4bac7a76885afafc69e23e12 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 04:21:08 -0400 Subject: [PATCH 15/23] doc: Remove the old module alias hack. The module names for also have their alias. The commit also remove 2 deprecated module that were forgotton in the previous "get rid of the deprecated modules in the doc" PR. --- CMakeLists.txt | 3 --- docs/aliases/awful_client.lua | 5 ----- docs/aliases/awful_mouse.lua | 5 ----- docs/aliases/awful_screen.lua | 5 ----- docs/aliases/awful_tag.lua | 5 ----- docs/common/rules_index.ldoc | 4 ++-- docs/config.ld | 20 +++++++++++++++----- docs/ldoc.css | 6 ++++++ 8 files changed, 23 insertions(+), 30 deletions(-) delete mode 100644 docs/aliases/awful_client.lua delete mode 100644 docs/aliases/awful_mouse.lua delete mode 100644 docs/aliases/awful_screen.lua delete mode 100644 docs/aliases/awful_tag.lua diff --git a/CMakeLists.txt b/CMakeLists.txt index 26d5ebad..ed9a35b1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -286,9 +286,6 @@ if(GENERATE_DOC) # Copy the images to the build directory file(COPY ${SOURCE_DIR}/docs/images DESTINATION ${BUILD_DIR}/doc) - # Copy the aliases to the build directory - file(COPY ${SOURCE_DIR}/docs/aliases DESTINATION ${BUILD_DIR}/docs) - # Copy ldoc files. configure_file(${SOURCE_DIR}/docs/ldoc.css ${BUILD_DIR}/docs COPYONLY) configure_file(${SOURCE_DIR}/docs/ldoc.ltp ${BUILD_DIR}/docs COPYONLY) diff --git a/docs/aliases/awful_client.lua b/docs/aliases/awful_client.lua deleted file mode 100644 index 24ff923d..00000000 --- a/docs/aliases/awful_client.lua +++ /dev/null @@ -1,5 +0,0 @@ ---------------------------------------------------------------------------- ---- This module documentation has been merged with the `client` class. --- --- @module awful.client ---------------------------------------------------------------------------- diff --git a/docs/aliases/awful_mouse.lua b/docs/aliases/awful_mouse.lua deleted file mode 100644 index efdb1a07..00000000 --- a/docs/aliases/awful_mouse.lua +++ /dev/null @@ -1,5 +0,0 @@ ---------------------------------------------------------------------------- ---- This module documentation has been merged with the `mouse` class. --- --- @module awful.mouse ---------------------------------------------------------------------------- diff --git a/docs/aliases/awful_screen.lua b/docs/aliases/awful_screen.lua deleted file mode 100644 index 755b6a01..00000000 --- a/docs/aliases/awful_screen.lua +++ /dev/null @@ -1,5 +0,0 @@ ---------------------------------------------------------------------------- ---- This module documentation has been merged with the `screen` class. --- --- @module awful.screen ---------------------------------------------------------------------------- diff --git a/docs/aliases/awful_tag.lua b/docs/aliases/awful_tag.lua deleted file mode 100644 index ee7887e3..00000000 --- a/docs/aliases/awful_tag.lua +++ /dev/null @@ -1,5 +0,0 @@ ---------------------------------------------------------------------------- ---- This module documentation has been merged with the `tag` class. --- --- @module awful.tag ---------------------------------------------------------------------------- diff --git a/docs/common/rules_index.ldoc b/docs/common/rules_index.ldoc index ac75c08c..181a7028 100644 --- a/docs/common/rules_index.ldoc +++ b/docs/common/rules_index.ldoc @@ -15,8 +15,8 @@ -- callbackA function to call when this client is ready -- markedIf a client is marked or not -- is\_fixedReturn if a client has a fixed size or not --- immobilizedIs the client immobilized horizontally? --- immobilizedIs the client immobilized vertically? +-- immobilized\_horizontalIs the client immobilized horizontally? +-- immobilized\_verticalIs the client immobilized vertically? -- floatingThe client floating state -- xThe x coordinates -- yThe y coordinates diff --git a/docs/config.ld b/docs/config.ld index dc244ae2..75892c65 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -121,11 +121,6 @@ file = { '../lib/', -- Auto generated scripts '../script_files/', - -- Old APIs the user should not longer use directly - '../docs/aliases/awful_client.lua', - '../docs/aliases/awful_screen.lua', - '../docs/aliases/awful_tag.lua', - '../docs/aliases/awful_mouse.lua', exclude = { -- exclude these modules, as they do not contain any written -- documentation @@ -149,6 +144,8 @@ file = { -- in the index '../lib/awful/widget/graph.lua', '../lib/awful/widget/progressbar.lua', + '../lib/awful/widget/textclock.lua', + '../lib/awful/wibox.lua', '../lib/wibox/layout/constraint.lua', '../lib/wibox/layout/margin.lua', '../lib/wibox/layout/mirror.lua', @@ -163,6 +160,14 @@ local no_prefix = { deprecatedproperty = true, } +-- These modules merge the doc of their `awful` siblings. +local coreclassmap = { + tag = "tag and awful.tag", + screen = "screen and awful.screen", + client = "client and awful.client", + mouse = "mouse and awful.mouse", +} + custom_display_name_handler = function(item, default_handler) -- Remove the "namespace" from the signals and properties if no_prefix[item.type] then @@ -170,6 +175,11 @@ custom_display_name_handler = function(item, default_handler) return name ~= "" and name or item.name end + -- Handle the left sidebar modules. + if item.type == "coreclassmod" and coreclassmap[item.name] then + return coreclassmap[item.name] + end + if item.type == "deprecated" or item.type == "deprecatedproperty" then return default_handler(item) .. " [deprecated]" end diff --git a/docs/ldoc.css b/docs/ldoc.css index a761088f..db42a48e 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -355,6 +355,12 @@ a:target + * { background-color: #FF9; } +/* tag + awful.tag */ +.listplusign { + color: #b7c1ff; + text-decoration: underline; + text-decoration-color: white; +} /* styles for prettification of source */ pre .comment { color: #bbccaa; } From 63ca0f0d8f78174a660e9131cdf472562c899683 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 6 Jun 2019 16:32:53 -0400 Subject: [PATCH 16/23] doc: Use an explicit @method stereotype for all methods. ldoc has a magical `@classmod` module type which tries to detect what is a method and what is a static function. It fails about as often as it works. This commit makes everything explicit to remove such issues. Fixes #2640 Ref #1373 --- docs/common/fixed.ldoc | 15 +++------ docs/common/object.ldoc | 8 ++--- docs/common/wibox.ldoc | 12 +++---- docs/common/widget.ldoc | 16 +++++---- docs/config.ld | 25 +++++++++++++- lib/awful/client.lua | 20 +++++++----- lib/awful/keygrabber.lua | 4 ++- lib/awful/screen.lua | 10 +++--- lib/awful/tag.lua | 8 +++-- lib/awful/widget/only_on_screen.lua | 5 --- lib/gears/timer.lua | 3 ++ lib/naughty/notification.lua | 4 +++ lib/wibox/container/arcchart.lua | 6 +--- lib/wibox/container/background.lua | 6 +--- lib/wibox/container/constraint.lua | 6 +--- lib/wibox/container/margin.lua | 8 ++--- lib/wibox/container/mirror.lua | 6 +--- lib/wibox/container/place.lua | 14 +++----- lib/wibox/container/radialprogressbar.lua | 6 +--- lib/wibox/container/rotate.lua | 8 ++--- lib/wibox/container/scroll.lua | 23 ++++++++++--- lib/wibox/init.lua | 4 ++- lib/wibox/layout/fixed.lua | 11 +++++-- lib/wibox/layout/flex.lua | 17 +++------- lib/wibox/layout/grid.lua | 31 ++++++++++++++++-- lib/wibox/layout/manual.lua | 32 +++++++++++------- lib/wibox/layout/ratio.lua | 40 +++++++++++++++++------ lib/wibox/layout/stack.lua | 26 +++++++-------- lib/wibox/widget/checkbox.lua | 6 ++++ lib/wibox/widget/graph.lua | 10 ++++-- lib/wibox/widget/imagebox.lua | 5 +-- lib/wibox/widget/piechart.lua | 4 +++ lib/wibox/widget/progressbar.lua | 4 ++- lib/wibox/widget/separator.lua | 4 +++ lib/wibox/widget/systray.lua | 10 +++++- lib/wibox/widget/textbox.lua | 5 +++ lib/wibox/widget/textclock.lua | 1 + objects/client.c | 26 +++++++-------- objects/drawable.c | 4 +-- objects/screen.c | 6 ++-- 40 files changed, 278 insertions(+), 181 deletions(-) diff --git a/docs/common/fixed.ldoc b/docs/common/fixed.ldoc index 6596b7d2..79098bcc 100644 --- a/docs/common/fixed.ldoc +++ b/docs/common/fixed.ldoc @@ -4,8 +4,7 @@ -- @tparam number index A widget or a widget index -- @param widget2 The widget to take the place of the first one -- @treturn boolean If the operation is successful --- @name set --- @class function +-- @method set --- Replace the first instance of `widget` in the layout with `widget2`. -- **Signal:** widget::replaced The argument is the new widget and the old one @@ -14,16 +13,14 @@ -- @param widget2 The widget to replace `widget` with -- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget. -- @treturn boolean If the operation is successful --- @name replace_widget --- @class function +-- @method replace_widget --- Swap 2 widgets in a layout. -- **Signal:** widget::swapped The arguments are both widgets and both (new) indexes. -- @tparam number index1 The first widget index -- @tparam number index2 The second widget index -- @treturn boolean If the operation is successful --- @name swap --- @class function +-- @method swap --- Swap 2 widgets in a layout. -- If widget1 is present multiple time, only the first instance is swapped @@ -33,8 +30,7 @@ -- @param widget2 The second widget -- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget. -- @treturn boolean If the operation is successful --- @name swap_widgets --- @class function +-- @method swap_widgets --- Get all direct children of this layout. -- @param layout The layout you are modifying. @@ -43,5 +39,4 @@ --- Reset a ratio layout. This removes all widgets from the layout. -- **Signal:** widget::reset -- @param layout The layout you are modifying. --- @name reset --- @class function +-- @method reset diff --git a/docs/common/object.ldoc b/docs/common/object.ldoc index b75fe61c..df722763 100644 --- a/docs/common/object.ldoc +++ b/docs/common/object.ldoc @@ -2,7 +2,7 @@ --- Disconnect from a signal. -- @tparam string name The name of the signal. -- @tparam function func The callback that should be disconnected. --- @function disconnect_signal +-- @method disconnect_signal --- Emit a signal. -- @@ -10,12 +10,12 @@ -- @param ... Extra arguments for the callback functions. Each connected -- function receives the object as first argument and then any extra -- arguments that are given to emit_signal(). --- @function emit_signal +-- @method emit_signal --- Connect to a signal. -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. --- @function connect_signal +-- @method connect_signal --- Connect to a signal weakly. -- @@ -27,4 +27,4 @@ -- are doing. -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. --- @function weak_connect_signal +-- @method weak_connect_signal diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc index 050bb2b8..b60cb511 100644 --- a/docs/common/wibox.ldoc +++ b/docs/common/wibox.ldoc @@ -199,20 +199,20 @@ --- Get or set mouse buttons bindings to a wibox. -- -- @param buttons_table A table of buttons objects, or nothing. --- @function buttons +-- @method buttons --- Get or set wibox geometry. That's the same as accessing or setting the x, -- y, width or height properties of a wibox. -- -- @param A table with coordinates to modify. -- @return A table with wibox coordinates and geometry. --- @function geometry +-- @method geometry --- Get or set wibox struts. -- -- @param strut A table with new strut, or nothing -- @return The wibox strut in a table. --- @function struts +-- @method struts -- @see client.struts --- The default background color. @@ -226,8 +226,7 @@ --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @param args An array containing the widgets disposition --- @name setup --- @class function +-- @method setup --- The background of the wibox. -- @param c The background to use. This must either be a cairo pattern object, @@ -255,5 +254,4 @@ -- @treturn table A sorted table of widgets positions. The first element is the biggest -- container while the last is the topmost widget. The table contains *x*, *y*, -- *width*, *height* and *widget*. --- @name find_widgets --- @class function +-- @method find_widgets diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index 81c88a76..bab76351 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -6,19 +6,23 @@ -- @return The index -- @return The parent layout -- @return The path between self and widget --- @function index +-- @method index + +--- Get or set the children elements. +-- @property children +-- @tparam table The children --- Get all direct and indirect children widgets. -- This will scan all containers recursively to find widgets -- Warning: This method it prone to stack overflow id the widget, or any of its -- children, contain (directly or indirectly) itself. --- @treturn table The children --- @function get_all_children +-- @property all_children +-- @tparam table The children --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @param args An array containing the widgets disposition --- @function setup +-- @method setup --- Force a widget height. -- @property forced_height @@ -38,14 +42,14 @@ --- Set/get a widget's buttons. -- @param _buttons The table of buttons that should bind to the widget. --- @function buttons +-- @method buttons --- Emit a signal and ensure all parent widgets in the hierarchies also -- forward the signal. This is useful to track signals when there is a dynamic -- set of containers and layouts wrapping the widget. -- @tparam string signal_name -- @param ... Other arguments --- @function emit_signal_recursive +-- @method emit_signal_recursive --- When the layout (size) change. -- This signal is emitted when the previous results of `:layout()` and `:fit()` diff --git a/docs/config.ld b/docs/config.ld index 75892c65..7883fa5e 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -52,12 +52,16 @@ tparam_alias('tab', 'table') tparam_alias('screen', 'screen') tparam_alias('screen_or_idx', 'screen|int') --- Hack to get the functions and method on top of the signals and properties +-- Hack to get the functions on top of the signals and properties new_type("function", "Functions", false, "Parameters") -- Documentation for objects properties new_type("property", "Object properties", false, "Type") -- Documentation for objects deprecated properties new_type("deprecatedproperty", "Deprecated object properties", false, "Type") +-- Use a custom type for the methods to bypass the faulty ldoc built-in detection. +-- (yes, the space after Methods *is* on purpose to avoid clashing with ldoc +-- internal "methods" concept) +new_type("method", "Object methods ", false, "Parameters") -- New type for signals new_type("signal", "Signals", false, "Arguments") -- New type for signals connections @@ -155,6 +159,21 @@ file = { } } +-- Mimics the ldoc built-in method style, but better. +-- +-- This custom renderer exists because using ldoc built-in method detection +-- turned out to be too unreliable and upstream is dead. +local function render_methods(item) + local ret = item.name + + -- Some methods will have it depending on the weather. Most wont. + if not ret:find(":") then + ret = ":"..ret + end + + return ret .. (item.args and " "..item.args or "") +end + local no_prefix = { property = true, signal = true, clientruleproperty = true, deprecatedproperty = true, @@ -184,6 +203,10 @@ custom_display_name_handler = function(item, default_handler) return default_handler(item) .. " [deprecated]" end + if item.type == "method" then + return render_methods(item) + end + local ret = default_handler(item) -- Get rid of the "module:" in front of method names. It is either wrong or diff --git a/lib/awful/client.lua b/lib/awful/client.lua index b3d4c885..e45381de 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -164,7 +164,7 @@ end --- Jump to the given client. -- Takes care of focussing the screen, the right tag, etc. -- --- @function client.jump_to +-- @method jump_to -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client and its first @@ -409,7 +409,7 @@ function client.moveresize(x, y, w, h, c) end --- Move/resize a client relative to current coordinates. --- @function client.relative_move +-- @method relative_move -- @see geometry -- @tparam[opt=c.x] number x The relative x coordinate. -- @tparam[opt=c.y] number y The relative y coordinate. @@ -435,7 +435,7 @@ function client.movetotag(target, c) end --- Move a client to a tag. --- @function client.move_to_tag +-- @method move_to_tag -- @tparam tag target The tag to move the client to. function client.object.move_to_tag(self, target) local s = target.screen @@ -460,7 +460,7 @@ function client.toggletag(target, c) end --- Toggle a tag on a client. --- @function client.toggle_tag +-- @method toggle_tag -- @tparam tag target The tag to move the client to. function client.object.toggle_tag(self, target) -- Check that tag and client screen are identical @@ -496,7 +496,7 @@ function client.movetoscreen(c, s) end --- Move a client to a screen. Default is next screen, cycling. --- @function client.move_to_screen +-- @method move_to_screen -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1. -- @see screen -- @see request::activate @@ -524,7 +524,7 @@ function client.object.move_to_screen(self, s) end --- Tag a client with the set of current tags. --- @function client.to_selected_tags +-- @method to_selected_tags -- @see screen.selected_tags function client.object.to_selected_tags(self) local tags = {} @@ -625,7 +625,7 @@ function client.togglemarked(c) end --- Return the marked clients and empty the marked table. --- @function awful.client.getmarked +-- @deprecated awful.client.getmarked -- @return A table with all marked clients. function client.getmarked() local copy = gtable.clone(client.data.marked, false) @@ -1300,7 +1300,7 @@ function client.get_transient_for_matching(c, matcher) end --- Get a matching transient_for client (if any). --- @function client.get_transient_for_matching +-- @method get_transient_for_matching -- @tparam function matcher A function that should return true, if -- a matching parent client is found. -- @treturn client.client|nil The matching parent client or nil. @@ -1328,7 +1328,7 @@ function client.is_transient_for(c, c2) end --- Is a client transient for another one? --- @function client.is_transient_for +-- @method is_transient_for -- @client c2 The parent client to check. -- @treturn client.client|nil The parent client or nil. function client.object.is_transient_for(self, c2) @@ -1432,6 +1432,8 @@ object.properties(capi.client, { setter_fallback = client.property.set, }) +--@DOC_object_COMMON@ + return client -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index 82e1038e..5036b068 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -463,6 +463,7 @@ end -- Note that only a single keygrabber can be started at any one time. If another -- keygrabber (or this one) is currently running. This method returns false. -- +-- @method start -- @treturn boolean If the keygrabber was successfully started. function keygrabber:start() if self.grabber or keygrab.current_instance then @@ -514,7 +515,7 @@ function keygrabber:start() end --- Stop the keygrabber. --- @function keygrabber:stop +-- @method stop function keygrabber:stop(_stop_key, _stop_mods) -- (at)function disables ldoc params keygrab.stop(self.grabber) @@ -534,6 +535,7 @@ end -- -- Those keybindings will automatically start the keygrabbing when hit. -- +-- @method add_keybinding -- @tparam table mods A table with modifier keys, such as `shift`, `mod4`, `mod1` (alt) or -- `control`. -- @tparam string key The key name, such as `left` or `f` diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index a998a467..ae0a5f84 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -57,7 +57,7 @@ function screen.getdistance_sq(s, x, y) end --- Get the square distance between a `screen` and a point. --- @function screen.get_square_distance +-- @method get_square_distance -- @tparam number x X coordinate of point -- @tparam number y Y coordinate of point -- @treturn number The squared distance of the screen to the provided point. @@ -128,7 +128,7 @@ end -- This gets the next screen relative to this one in -- the specified direction. -- --- @function screen:get_next_in_direction +-- @method get_next_in_direction -- @param self Screen. -- @param dir The direction, can be either "up", "down", "left" or "right". function screen.object.get_next_in_direction(self, dir) @@ -388,7 +388,7 @@ end -- -- This is used by `all_clients` internally (with `stacked=true`). -- --- @function screen:get_all_clients +-- @method get_all_clients -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom) -- @treturn table The clients list. function screen.object.get_all_clients(s, stacked) @@ -410,7 +410,7 @@ end -- -- This is used by `tiles_clients` internally (with `stacked=true`). -- --- @function screen:get_tiled_clients +-- @method get_tiled_clients -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom) -- @treturn table The clients list. function screen.object.get_tiled_clients(s, stacked) @@ -661,6 +661,8 @@ object.properties(capi.screen, { auto_emit = true, }) +--@DOC_object_COMMON@ + return screen -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 631914d5..6b743939 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -218,8 +218,8 @@ function tag.move(new_index, target_tag) tag.object.set_index(target_tag, new_index) end ---- Swap 2 tags --- @function tag.swap +--- Swap 2 tags. +-- @method swap -- @param tag2 The second tag -- @see client.swap function tag.object.swap(self, tag2) @@ -1371,7 +1371,7 @@ function tag.viewprev(screen) end --- View only a tag. --- @function tag.view_only +-- @method view_only -- @see selected function tag.object.view_only(self) local tags = self.screen.tags @@ -1685,6 +1685,8 @@ object.properties(capi.tag, { setter_fallback = tag.setproperty, }) +--@DOC_object_COMMON@ + return setmetatable(tag, tag.mt) -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua index c7494a6a..95bec166 100644 --- a/lib/awful/widget/only_on_screen.lua +++ b/lib/awful/widget/only_on_screen.lua @@ -63,15 +63,10 @@ function only_on_screen:get_widget() return self._private.widget end ---- Get the number of children element --- @treturn table The children function only_on_screen:get_children() return {self._private.widget} end ---- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function only_on_screen:set_children(children) self:set_widget(children[1]) end diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index a955472b..f7c39db1 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -84,6 +84,7 @@ local gdebug = require("gears.debug") local timer = { mt = {} } --- Start the timer. +-- @method start function timer:start() if self.data.source_id ~= nil then gdebug.print_error(traceback("timer already started")) @@ -97,6 +98,7 @@ function timer:start() end --- Stop the timer. +-- @method stop function timer:stop() if self.data.source_id == nil then gdebug.print_error(traceback("timer not started")) @@ -110,6 +112,7 @@ end --- Restart the timer. -- This is equivalent to stopping the timer if it is running and then starting -- it. +-- @method again function timer:again() if self.data.source_id ~= nil then self:stop() diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 4be3b164..2a355cb3 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -240,6 +240,7 @@ local notification = {} --- Destroy notification by notification object. -- +-- @method destroy -- @tparam string reason One of the reasons from `notification_closed_reason` -- @tparam[opt=false] boolean keep_visible If true, keep the notification visible -- @return True if the popup was successfully destroyed, false otherwise @@ -261,6 +262,7 @@ function notification:destroy(reason, keep_visible) end --- Set new notification timeout. +-- @method reset_timeout -- @tparam number new_timeout Time in seconds after which notification disappears. function notification:reset_timeout(new_timeout) if self.timer then self.timer:stop() end @@ -543,4 +545,6 @@ function notification._gen_next_id() return counter end +--@DOC_object_COMMON@ + return setmetatable(notification, {__call = function(_, ...) return create(...) end}) diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index 4b778391..28175337 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -197,21 +197,17 @@ function arcchart:set_widget(widget) self:emit_signal("widget::layout_changed") end ---- Get the children elements. --- @treturn table The children function arcchart:get_children() return {self._private.widget} end ---- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function arcchart:set_children(children) self._private.widget = children and children[1] self:emit_signal("widget::layout_changed") end --- Reset this layout. The widget will be removed and the rotation reset. +-- @method reset function arcchart:reset() self:set_widget(nil) end diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index a1d01495..73d89dd5 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -175,15 +175,10 @@ function background:get_widget() return self._private.widget end --- Get children element --- @treturn table The children function background:get_children() return {self._private.widget} end --- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function background:set_children(children) self:set_widget(children[1]) end @@ -239,6 +234,7 @@ end --- Set the background shape. -- -- Any other arguments will be passed to the shape function +-- @method set_shape -- @param shape A function taking a context, width and height as arguments -- @see gears.shape -- @see shape diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index e54fe266..8fd84dc2 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -51,15 +51,10 @@ function constraint:get_widget() return self._private.widget end ---- Get the number of children element --- @treturn table The children function constraint:get_children() return {self._private.widget} end ---- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function constraint:set_children(children) self:set_widget(children[1]) end @@ -121,6 +116,7 @@ end --- Reset this layout. The widget will be unreferenced, strategy set to "max" -- and the constraints set to nil. +-- @method reset function constraint:reset() self._private.width = nil self._private.height = nil diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index bcd4b072..9a5fcd4f 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -80,15 +80,10 @@ function margin:get_widget() return self._private.widget end --- Get the number of children element --- @treturn table The children function margin:get_children() return {self._private.widget} end --- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function margin:set_children(children) self:set_widget(children[1]) end @@ -136,7 +131,7 @@ function margin:get_color() end --- Draw the margin even if the content size is 0x0 (default: true) --- @function draw_empty +-- @method draw_empty -- @tparam boolean draw_empty Draw nothing is content is 0x0 or draw the margin anyway function margin:set_draw_empty(draw_empty) @@ -150,6 +145,7 @@ end --- Reset this layout. The widget will be unreferenced, the margins set to 0 -- and the color erased +-- @method reset function margin:reset() self:set_widget(nil) self:set_margins(0) diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua index 52d6fe79..ac41d41d 100644 --- a/lib/wibox/container/mirror.lua +++ b/lib/wibox/container/mirror.lua @@ -61,20 +61,16 @@ function mirror:get_widget() return self._private.widget end ---- Get the number of children element --- @treturn table The children function mirror:get_children() return {self._private.widget} end ---- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function mirror:set_children(children) self:set_widget(children[1]) end --- Reset this layout. The widget will be removed and the axes reset. +-- @method reset function mirror:reset() self._private.horizontal = false self._private.vertical = false diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua index 34c79cb8..86c7b5fe 100644 --- a/lib/wibox/container/place.lua +++ b/lib/wibox/container/place.lua @@ -61,10 +61,6 @@ function place:fit(context, width, height) and height or h end ---- The widget to be placed. --- @property widget --- @tparam widget widget The widget - function place:set_widget(widget) if widget then base.check_widget(widget) @@ -77,20 +73,20 @@ function place:get_widget() return self._private.widget end ---- Get the number of children element --- @treturn table The children +--- Get or set the children elements. +-- @property children +-- @tparam table The children + function place:get_children() return {self._private.widget} end ---- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function place:set_children(children) self:set_widget(children[1]) end --- Reset this layout. The widget will be removed and the rotation reset. +-- @method reset function place:reset() self:set_widget(nil) end diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index 1507c755..766ec818 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -134,21 +134,17 @@ function radialprogressbar:set_widget(widget) self:emit_signal("widget::layout_changed") end ---- Get the children elements --- @treturn table The children function radialprogressbar:get_children() return {self._private.widget} end ---- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function radialprogressbar:set_children(children) self._private.widget = children and children[1] self:emit_signal("widget::layout_changed") end --- Reset this container. +-- @method reset function radialprogressbar:reset() self:set_widget(nil) end diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index d3b08f51..a0f2775a 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -74,20 +74,16 @@ function rotate:get_widget() return self._private.widget end ---- Get the number of children element --- @treturn table The children function rotate:get_children() return {self._private.widget} end ---- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function rotate:set_children(children) self:set_widget(children[1]) end --- Reset this layout. The widget will be removed and the rotation reset. +-- @method reset function rotate:reset() self._private.direction = nil self:set_widget(nil) @@ -125,7 +121,7 @@ function rotate:set_direction(dir) self:emit_signal("widget::layout_changed") end ---- Get the direction of this rotating layout +-- Get the direction of this rotating layout function rotate:get_direction() return self._private.direction or "north" end diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua index fbd41b78..4f63377d 100644 --- a/lib/wibox/container/scroll.lua +++ b/lib/wibox/container/scroll.lua @@ -220,6 +220,7 @@ _need_scroll_redraw = function(self) end --- Pause the scrolling animation. +-- @method pause -- @see continue function scroll:pause() if self._private.paused then @@ -230,6 +231,7 @@ function scroll:pause() end --- Continue the scrolling animation. +-- @method continue -- @see pause function scroll:continue() if not self._private.paused then @@ -244,6 +246,7 @@ end -- For must scroll step functions, the effect of this function should be to -- display the widget without any scrolling applied. -- This function does not undo the effect of @{pause}. +-- @method reset_scrolling function scroll:reset_scrolling() self._private.timer:start() if self._private.paused then @@ -252,6 +255,7 @@ function scroll:reset_scrolling() end --- Set the direction in which this widget scroll. +-- @method set_direction -- @param dir Either "h" for horizontal scrolling or "v" for vertical scrolling function scroll:set_direction(dir) if dir == self._private.dir then @@ -285,20 +289,16 @@ function scroll:get_widget() return self._private.widget end ---- Get the number of children element --- @treturn table The children function scroll:get_children() return {self._private.widget} end ---- Replace the layout children --- This layout only accept one children, all others will be ignored --- @tparam table children A table composed of valid widgets function scroll:set_children(children) self:set_widget(children[1]) end --- Specify the expand mode that is used for extra space. +-- @method set_expand -- @tparam boolean expand If true, the widget is expanded to include the extra -- space. If false, the extra space is simply left empty. -- @see set_extra_space @@ -311,6 +311,7 @@ function scroll:set_expand(expand) end --- Set the number of frames per second that this widget should draw. +-- @method set_fps -- @tparam number fps The number of frames per second function scroll:set_fps(fps) if fps == self._private.fps then @@ -323,6 +324,7 @@ end --- Set the amount of extra space that should be included in the scrolling. This -- extra space will likely be left empty between repetitions of the widgets. +-- @method set_extra_space -- @tparam number extra_space The amount of extra space -- @see set_expand function scroll:set_extra_space(extra_space) @@ -336,6 +338,7 @@ end --- Set the speed of the scrolling animation. The exact meaning depends on the -- step function that is used, but for the simplest step functions, this will be -- in pixels per second. +-- @method set_speed -- @tparam number speed The speed for the animation function scroll:set_speed(speed) if speed == self._private.speed then @@ -349,6 +352,7 @@ end -- @{set_direction}. If the child widget is smaller than this size, no scrolling -- is done. If the child widget is larger, then only this size will be visible -- and the rest is made visible via scrolling. +-- @method set_max_size -- @tparam number max_size The maximum size of this widget or nil for unlimited. function scroll:set_max_size(max_size) if max_size == self._private.max_size then @@ -373,6 +377,7 @@ end -- -- The step function should return a single number. This number is the offset at -- which the widget is drawn and should be between 0 and `size+extra_space`. +-- @method set_step_function -- @tparam function step_function A step function. -- @see step_functions function scroll:set_step_function(step_function) @@ -387,6 +392,7 @@ end --- Set an upper limit for the space for scrolling. -- This restricts the child widget's maximal size. +-- @method set_space_for_scrolling -- @tparam number space_for_scrolling The space for scrolling function scroll:set_space_for_scrolling(space_for_scrolling) if space_for_scrolling == self._private.space_for_scrolling then @@ -419,6 +425,7 @@ local function get_layout(dir, widget, fps, speed, extra_space, expand, max_size end --- Get a new horizontal scrolling container. +-- @function wibox.container.scroll.horizontal -- @param[opt] widget The widget that should be scrolled -- @param[opt=20] fps The number of frames per second -- @param[opt=10] speed The speed of the animation @@ -433,6 +440,7 @@ function scroll.horizontal(widget, fps, speed, extra_space, expand, max_size, st end --- Get a new vertical scrolling container. +-- @function wibox.container.scroll.vertical -- @param[opt] widget The widget that should be scrolled -- @param[opt=20] fps The number of frames per second -- @param[opt=10] speed The speed of the animation @@ -452,18 +460,21 @@ scroll.step_functions = {} --- A step function that scrolls the widget in an increasing direction with -- constant speed. +-- @callback scroll.step_functions.linear_increase function scroll.step_functions.linear_increase(elapsed, size, _, speed, extra_space) return (elapsed * speed) % (size + extra_space) end --- A step function that scrolls the widget in an decreasing direction with -- constant speed. +-- @callback scroll.step_functions.linear_decrease function scroll.step_functions.linear_decrease(elapsed, size, _, speed, extra_space) return (-elapsed * speed) % (size + extra_space) end --- A step function that scrolls the widget to its end and back to its -- beginning, then back to its end, etc. The speed is constant. +-- @callback scroll.step_functions.linear_back_and_forth function scroll.step_functions.linear_back_and_forth(elapsed, size, visible_size, speed) local state = ((elapsed * speed) % (2 * size)) / size state = state <= 1 and state or 2 - state @@ -473,6 +484,7 @@ end --- A step function that scrolls the widget to its end and back to its -- beginning, then back to its end, etc. The speed is null at the ends and -- maximal in the middle. +-- @callback scroll.step_functions.nonlinear_back_and_forth function scroll.step_functions.nonlinear_back_and_forth(elapsed, size, visible_size, speed) local state = ((elapsed * speed) % (2 * size)) / size local negate = false @@ -501,6 +513,7 @@ end --- A step function that scrolls the widget to its end and back to its -- beginning, then back to its end, etc. The speed is null at the ends and -- maximal in the middle. At both ends the widget stands still for a moment. +-- @callback scroll.step_functions.waiting_nonlinear_back_and_forth function scroll.step_functions.waiting_nonlinear_back_and_forth(elapsed, size, visible_size, speed) local state = ((elapsed * speed) % (2 * size)) / size local negate = false diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index 8335badf..3f72b82b 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -65,6 +65,7 @@ end --- Create a widget that reflects the current state of this wibox. -- @treturn widget A new widget. +-- @method to_widget function wibox:to_widget() local bw = self.border_width or beautiful.border_width or 0 return wibox.widget { @@ -88,6 +89,7 @@ end --- Save a screenshot of the wibox to `path`. -- @tparam string path The path. -- @tparam[opt=nil] table context A widget context. +-- @method save_to_svg function wibox:save_to_svg(path, context) wibox.widget.draw_to_svg_file( self:to_widget(), path, self:geometry().width, self:geometry().height, context @@ -350,7 +352,7 @@ end --- Redraw a wibox. You should never have to call this explicitely because it is -- automatically called when needed. -- @param wibox --- @function draw +-- @method draw function wibox.mt:__call(...) return new(...) diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index 5eec5861..a6f5ca2a 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -62,7 +62,8 @@ function fixed:layout(context, width, height) return result end ---- Add some widgets to the given fixed layout +--- Add some widgets to the given layout +-- @method add -- @param ... Widgets that should be added (must at least be one) function fixed:add(...) -- No table.pack in Lua 5.1 :-( @@ -77,6 +78,7 @@ end --- Remove a widget from the layout +-- @method remove -- @tparam number index The widget index to remove -- @treturn boolean index If the operation is successful function fixed:remove(index) @@ -92,6 +94,7 @@ end --- Remove one or more widgets from the layout -- The last parameter can be a boolean, forcing a recursive seach of the -- widget(s) to remove. +-- @method remove_widgets -- @param widget ... Widgets that should be removed (must at least be one) -- @treturn boolean If the operation is successful function fixed:remove_widgets(...) @@ -128,6 +131,7 @@ function fixed:set_children(children) end --- Replace the first instance of `widget` in the layout with `widget2` +-- @method replace_widget -- @param widget The widget to replace -- @param widget2 The widget to replace `widget` with -- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget. @@ -219,8 +223,9 @@ function fixed:set_spacing_widget(wdg) self:emit_signal("widget::layout_changed") end ---- Insert a new widget in the layout at position `index` +--- Insert a new widget in the layout at position `index`. -- **Signal:** widget::inserted The arguments are the widget and the index +-- @method insert -- @tparam number index The position -- @param widget The widget -- @treturn boolean If the operation is successful @@ -235,7 +240,7 @@ function fixed:insert(index, widget) return true end --- Fit the fixed layout into the given space +-- Fit the fixed layout into the given space. -- @param context The context in which we are fit. -- @param orig_width The available width. -- @param orig_height The available height. diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index 490ff421..59815c43 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -17,37 +17,28 @@ local flex = {} --@DOC_fixed_COMMON@ ---- Replace the layout children --- @tparam table children A table composed of valid widgets --- @name set_children --- @class function - --- Add some widgets to the given fixed layout -- @param layout The layout you are modifying. -- @tparam widget ... Widgets that should be added (must at least be one) --- @name add --- @class function +-- @method add --- Remove a widget from the layout -- @tparam index The widget index to remove -- @treturn boolean index If the operation is successful --- @name remove --- @class function +-- @method remove --- Remove one or more widgets from the layout -- The last parameter can be a boolean, forcing a recursive seach of the -- widget(s) to remove. -- @param widget ... Widgets that should be removed (must at least be one) -- @treturn boolean If the operation is successful --- @name remove_widgets --- @class function +-- @method remove_widgets --- Insert a new widget in the layout at position `index` -- @tparam number index The position -- @param widget The widget -- @treturn boolean If the operation is successful --- @name insert --- @class function +-- @method insert --- The widget used to fill the spacing between the layout elements. -- diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index 37bccc53..48385204 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -222,6 +222,7 @@ local function find_widget(widgets_table, widget) end --- Get the number of rows and columns occupied by the widgets in the grid. +-- @method get_dimension -- @treturn number,number The number of rows and columns function grid:get_dimension() return self._private.num_rows, self._private.num_cols @@ -248,6 +249,7 @@ end --- Find the next available cell to insert a widget. -- The grid is browsed according to the `orientation`. +-- @method get_next_empty -- @tparam[opt=1] number hint_row The row coordinate of the last occupied cell. -- @tparam[opt=1] number hint_column The column coordinate of the last occupied cell. -- @return number,number The row,column coordinate of the next empty cell @@ -281,7 +283,10 @@ end --- Add some widgets to the given grid layout. --- The widgets are assumed to span one cell +-- +-- The widgets are assumed to span one cell. +-- +-- @method add -- @param ... Widgets that should be added (must at least be one) function grid:add(...) local args = { n=select('#', ...), ... } @@ -298,6 +303,8 @@ end --- Add a widget to the grid layout at specific coordinate. -- --@DOC_wibox_layout_grid_add_EXAMPLE@ +-- +-- @method add_widget_at -- @param child Widget that should be added -- @tparam number row Row number for the top left corner of the widget -- @tparam number col Column number for the top left corner of the widget @@ -341,6 +348,7 @@ function grid:add_widget_at(child, row, col, row_span, col_span) end --- Remove one or more widgets from the layout. +-- @method remove -- @param ... Widgets that should be removed (must at least be one) -- @treturn boolean If the operation is successful function grid:remove(...) @@ -366,6 +374,8 @@ end --- Remove widgets at the coordinates. -- --@DOC_wibox_layout_grid_remove_EXAMPLE@ +-- +-- @method remove_widgets_at -- @tparam number row The row coordinate of the widget to remove -- @tparam number col The column coordinate of the widget to remove -- @tparam[opt=1] number row_span The number of rows the area to remove spans. @@ -388,6 +398,7 @@ function grid:remove_widgets_at(row, col, row_span, col_span) end --- Return the coordinates of the widget. +-- @method get_widget_position -- @param widget The widget -- @treturn table The `position` table of the coordinates in the grid, with -- fields `row`, `col`, `row_span` and `col_span`. @@ -405,6 +416,7 @@ end --- Return the widgets at the coordinates. +-- @method get_widgets_at -- @tparam number row The row coordinate of the widget -- @tparam number col The column coordinate of the widget -- @tparam[opt=1] number row_span The number of rows to span. @@ -427,6 +439,7 @@ function grid:get_widgets_at(row, col, row_span, col_span) end --- Replace old widget by new widget, spanning the same columns and rows. +-- @method replace_widget -- @param old The widget to remove -- @param new The widget to add -- @treturn boolean If the operation is successful (widget found) @@ -494,6 +507,8 @@ end --- Insert column at index. -- --@DOC_wibox_layout_grid_insert_column_EXAMPLE@ +-- +-- @method insert_column -- @tparam number|nil index Insert the new column at index. If `nil`, the column is added at the end. -- @treturn number The index of the inserted column function grid:insert_column(index) @@ -508,8 +523,9 @@ function grid:insert_column(index) end --- Extend column at index. --- --@DOC_wibox_layout_grid_extend_column_EXAMPLE@ +-- +-- @method extend_column -- @tparam number|nil index Extend the column at index. If `nil`, the last column is extended. -- @treturn number The index of the extended column function grid:extend_column(index) @@ -526,6 +542,8 @@ end --- Remove column at index. -- --@DOC_wibox_layout_grid_remove_column_EXAMPLE@ +-- +-- @method remove_column -- @tparam number|nil index Remove column at index. If `nil`, the last column is removed. -- @treturn number The index of the removed column function grid:remove_column(index) @@ -542,6 +560,8 @@ end --- Insert row at index. -- -- see `insert_column` +-- +-- @method insert_row -- @tparam number|nil index Insert the new row at index. If `nil`, the row is added at the end. -- @treturn number The index of the inserted row function grid:insert_row(index) @@ -558,6 +578,8 @@ end --- Extend row at index. -- -- see `extend_column` +-- +-- @method extend_row -- @tparam number|nil index Extend the row at index. If `nil`, the last row is extended. -- @treturn number The index of the extended row function grid:extend_row(index) @@ -574,6 +596,8 @@ end --- Remove row at index. -- -- see `remove_column` +-- +-- @method remove_row -- @tparam number|nil index Remove row at index. If `nil`, the last row is removed. -- @treturn number The index of the removed row function grid:remove_row(index) @@ -597,7 +621,7 @@ function grid:get_children() return ret end --- Add list of children to the layout +-- Add list of children to the layout. function grid:set_children(children) self:reset() if #children > 0 then @@ -837,6 +861,7 @@ end -- Remove all widgets and reset row and column counts -- -- **Signal:** widget::reset +-- @method reset function grid:reset() self._private.widgets = {} -- reset the number of columns and rows to the forced value or to 0 diff --git a/lib/wibox/layout/manual.lua b/lib/wibox/layout/manual.lua index d16a0bb5..6fa617ee 100644 --- a/lib/wibox/layout/manual.lua +++ b/lib/wibox/layout/manual.lua @@ -15,24 +15,24 @@ local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility local manual_layout = {} ---- Add some widgets to the given stack layout +--- Add some widgets to the given stack layout. +-- +-- @method add -- @param layout The layout you are modifying. -- @tparam widget ... Widgets that should be added --- @name add --- @class function ---- Remove a widget from the layout +--- Remove a widget from the layout. +-- +-- @method remove -- @tparam index The widget index to remove -- @treturn boolean index If the operation is successful --- @name remove --- @class function ---- Insert a new widget in the layout at position `index` +--- Insert a new widget in the layout at position `index`. +-- +-- @method insert -- @tparam number index The position -- @param widget The widget -- @treturn boolean If the operation is successful --- @name insert --- @class function function manual_layout:insert(index, widget) table.insert(self._private.widgets, index, widget) @@ -44,13 +44,14 @@ function manual_layout:insert(index, widget) self:emit_signal("widget::layout_changed") end ---- Remove one or more widgets from the layout +--- Remove one or more widgets from the layout. +-- -- The last parameter can be a boolean, forcing a recursive seach of the -- widget(s) to remove. +-- +-- @method remove_widgets -- @param widget ... Widgets that should be removed (must at least be one) -- @treturn boolean If the operation is successful --- @name remove_widgets --- @class function function manual_layout:fit(_, width, height) @@ -145,6 +146,8 @@ end -- The function is compatible with the `awful.placement` prototype. -- --@DOC_wibox_layout_manual_add_at_EXAMPLE@ +-- +-- @method add_at -- @tparam widget widget The widget. -- @tparam table|function point Either an `{x=x,y=y}` table or a function -- returning the new geometry. @@ -167,6 +170,7 @@ function manual_layout:add_at(widget, point) end --- Move a widget (by index). +-- @method move -- @tparam number index The widget index. -- @tparam table|function point A new point value. -- @see add_at @@ -179,6 +183,8 @@ end --- Move a widget. -- --@DOC_wibox_layout_manual_move_widget_EXAMPLE@ +-- +-- @method move_widget -- @tparam widget widget The widget. -- @tparam table|function point A new point value. -- @see add_at @@ -206,7 +212,9 @@ function manual_layout:reset() end --- Create a manual layout. +-- @function wibox.layout.manual -- @tparam table ... Widgets to add to the layout. + local function new_manual(...) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua index de79be27..9055392a 100644 --- a/lib/wibox/layout/ratio.lua +++ b/lib/wibox/layout/ratio.lua @@ -38,7 +38,7 @@ local ratio = {} -- @property spacing -- @tparam number spacing Spacing between widgets. --- Compute the sum of all ratio (ideally, it should be 1) +-- Compute the sum of all ratio (ideally, it should be 1). local function gen_sum(self, i_s, i_e) local sum, new_w = 0,0 @@ -201,12 +201,13 @@ function ratio:layout(context, width, height) return result end ---- Increase the ratio of "widget" +--- Increase the ratio of "widget". -- If the increment produce an invalid ratio (not between 0 and 1), the method -- do nothing. -- --@DOC_wibox_layout_ratio_inc_ratio_EXAMPLE@ -- +-- @method inc_ratio -- @tparam number index The widget index to change -- @tparam number increment An floating point value between -1 and 1 where the -- end result is within 0 and 1 @@ -221,9 +222,11 @@ function ratio:inc_ratio(index, increment) self:set_ratio(index, self._private.ratios[index] + increment) end ---- Increment the ratio of the first instance of `widget` +--- Increment the ratio of the first instance of `widget`. -- If the increment produce an invalid ratio (not between 0 and 1), the method -- do nothing. +-- +-- @method inc_widget_ratio -- @param widget The widget to ajust -- @tparam number increment An floating point value between -1 and 1 where the -- end result is within 0 and 1 @@ -235,7 +238,9 @@ function ratio:inc_widget_ratio(widget, increment) self:inc_ratio(index, increment) end ---- Set the ratio of the widget at position `index` +--- Set the ratio of the widget at position `index`. +-- +-- @method set_ratio -- @tparam number index The index of the widget to change -- @tparam number percent An floating point value between 0 and 1 function ratio:set_ratio(index, percent) @@ -263,6 +268,8 @@ function ratio:set_ratio(index, percent) end --- Get the ratio at `index`. +-- +-- @method get_ratio -- @tparam number index The widget index to query -- @treturn number The index (between 0 and 1) function ratio:get_ratio(index) @@ -271,6 +278,8 @@ function ratio:get_ratio(index) end --- Set the ratio of `widget` to `percent`. +-- +-- @method set_widget_ratio -- @tparam widget widget The widget to ajust. -- @tparam number percent A floating point value between 0 and 1. function ratio:set_widget_ratio(widget, percent) @@ -284,6 +293,7 @@ end -- --@DOC_wibox_layout_ratio_ajust_ratio_EXAMPLE@ -- +-- @method ajust_ratio -- @tparam number index The index of the widget to change -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" @@ -323,7 +333,9 @@ function ratio:ajust_ratio(index, before, itself, after) self:emit_signal("widget::layout_changed") end ---- Update all widgets to match a set of a ratio +--- Update all widgets to match a set of a ratio. +-- +-- @method ajust_widget_ratio -- @param widget The widget to ajust -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" @@ -333,8 +345,10 @@ function ratio:ajust_widget_ratio(widget, before, itself, after) self:ajust_ratio(index, before, itself, after) end ---- Add some widgets to the given fixed layout +--- Add some widgets to the given fixed layout. +-- -- **Signal:** widget::added The argument are the widgets +-- @method add -- @tparam widget ... Widgets that should be added (must at least be one) function ratio:add(...) -- No table.pack in Lua 5.1 :-( @@ -350,8 +364,10 @@ function ratio:add(...) self:emit_signal("widget::added", ...) end ---- Remove a widget from the layout +--- Remove a widget from the layout. +-- -- **Signal:** widget::removed The arguments are the widget and the index +-- @method remove -- @tparam number index The widget index to remove -- @treturn boolean index If the operation is successful function ratio:remove(index) @@ -370,8 +386,10 @@ function ratio:remove(index) return true end ---- Insert a new widget in the layout at position `index` +--- Insert a new widget in the layout at position `index`. -- **Signal:** widget::inserted The arguments are the widget and the index +-- +-- @method insert -- @tparam number index The position -- @param widget The widget function ratio:insert(index, widget) @@ -437,15 +455,17 @@ local function get_layout(dir, widget1, ...) return ret end ---- Returns a new horizontal ratio layout. A ratio layout shares the available space +--- Returns a new horizontal ratio layout. A ratio layout shares the available space. -- equally among all widgets. Widgets can be added via :add(widget). +-- @function wibox.layout.ratio.horizontal -- @tparam widget ... Widgets that should be added to the layout. function ratio.horizontal(...) return get_layout("horizontal", ...) end ---- Returns a new vertical ratio layout. A ratio layout shares the available space +--- Returns a new vertical ratio layout. A ratio layout shares the available space. -- equally among all widgets. Widgets can be added via :add(widget). +-- @function wibox.layout.ratio.vertical -- @tparam widget ... Widgets that should be added to the layout. function ratio.vertical(...) return get_layout("vertical", ...) diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index 4cc8d6c2..510a7950 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -24,32 +24,28 @@ local stack = {mt={}} --@DOC_fixed_COMMON@ ---- Add some widgets to the given stack layout +--- Add some widgets to the given stack layout. -- @param layout The layout you are modifying. -- @tparam widget ... Widgets that should be added (must at least be one) --- @name add --- @class function +-- @method add --- Remove a widget from the layout -- @tparam index The widget index to remove -- @treturn boolean index If the operation is successful --- @name remove --- @class function +-- @method remove ---- Insert a new widget in the layout at position `index` +--- Insert a new widget in the layout at position `index`. -- @tparam number index The position -- @param widget The widget -- @treturn boolean If the operation is successful --- @name insert --- @class function +-- @method insert ---- Remove one or more widgets from the layout +--- Remove one or more widgets from the layout. -- The last parameter can be a boolean, forcing a recursive seach of the -- widget(s) to remove. -- @param widget ... Widgets that should be removed (must at least be one) -- @treturn boolean If the operation is successful --- @name remove_widgets --- @class function +-- @method remove_widgets --- Add spacing around the widget, similar to the margin container. --@DOC_wibox_layout_stack_spacing_EXAMPLE@ @@ -86,7 +82,7 @@ function stack:fit(context, orig_width, orig_height) return math.min(max_w, orig_width), math.min(max_h, orig_height) end ---- If only the first stack widget is drawn +--- If only the first stack widget is drawn. -- @property top_only function stack:get_top_only() @@ -97,7 +93,8 @@ function stack:set_top_only(top_only) self._private.top_only = top_only end ---- Raise a widget at `index` to the top of the stack +--- Raise a widget at `index` to the top of the stack. +-- @method raise -- @tparam number index the widget index to raise function stack:raise(index) if (not index) or self._private.widgets[index] then return end @@ -109,7 +106,8 @@ function stack:raise(index) self:emit_signal("widget::layout_changed") end ---- Raise the first instance of `widget` +--- Raise the first instance of `widget`. +-- @method raise_widget -- @param widget The widget to raise -- @tparam[opt=false] boolean recursive Also look deeper in the hierarchy to -- find the widget diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index e5eb9f87..10df7e2d 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -224,6 +224,12 @@ function checkbox:set_paddings(val) self:emit_signal("widget::redraw_needed") end +--- Create a new checkbox. +-- @function wibox.widget.checkbox +-- @tparam[opt=false] boolean checked +-- @tparam[opt] table args +-- @tparam gears.color args.color The color. + local function new(checked, args) checked, args = checked or false, args or {} diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index a5ceb086..a8cb5480 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -231,6 +231,7 @@ end --- Add a value to the graph -- +-- @method add_value -- @param value The value to be added to the graph -- @param group The stack color group index. function graph:add_value(value, group) @@ -265,6 +266,7 @@ function graph:add_value(value, group) end --- Clear the graph. +-- @method clear function graph:clear() self._private.values = {} self:emit_signal("widget::redraw_needed") @@ -272,7 +274,9 @@ function graph:clear() end --- Set the graph height. --- @param height The height to set. +-- @property height +-- @param number The height to set. + function graph:set_height(height) if height >= 5 then self._private.height = height @@ -282,7 +286,9 @@ function graph:set_height(height) end --- Set the graph width. --- @param width The width to set. +-- @property width +-- @param number The width to set. + function graph:set_width(width) if width >= 5 then self._private.width = width diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index f8e28b48..cb121fc2 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -119,7 +119,7 @@ end -- is trimmed. -- -- @property clip_shape --- @param clip_shape A `gears_shape` compatible shape function +-- @tparam function clip_shape A `gears_shape` compatible shape function -- @see gears.shape -- @see set_clip_shape @@ -129,7 +129,8 @@ end -- -- Any other parameters will be passed to the clip shape function -- --- @param clip_shape A `gears_shape` compatible shape function +-- @tparam function clip_shape A `gears_shape` compatible shape function. +-- @method set_clip_shape -- @see gears.shape -- @see clip_shape function imagebox:set_clip_shape(clip_shape, ...) diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 0cd7adfe..7f22a7c2 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -218,6 +218,10 @@ function piechart:get_data() return list end +--- Create a new piechart. +-- @function wibox.widget.piechart +-- @tparam table data_list The data. + local function new(data_list) local ret = base.make_widget(nil, nil, { diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index 56eb5ac5..d2eacacc 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -368,7 +368,9 @@ function progressbar:fit(_, width, height) end --- Set the progressbar value. --- @param value The progress bar value between 0 and 1. +-- @property value +-- @param number The progress bar value between 0 and 1. + function progressbar:set_value(value) value = value or 0 diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index 67b1fff4..c02c9c8a 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -185,6 +185,10 @@ for _, prop in ipairs {"orientation", "color", "thickness", "span_ratio", end end +--- Create a new separator. +-- @function wibox.widget.separator +-- @tparam table args The arguments (all properties are available). + local function new(args) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua index b06294b0..d9ca261e 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -116,7 +116,9 @@ end --- Set the size of a single icon. -- If this is set to nil, then the size is picked dynamically based on the -- available space. Otherwise, any single icon has a size of `size`x`size`. +-- @property base_size -- @tparam integer|nil size The base size + function systray:set_base_size(size) base_size = get_args(self, size) if instance then @@ -125,7 +127,9 @@ function systray:set_base_size(size) end --- Decide between horizontal or vertical display. +-- @property horizontal -- @tparam boolean horiz Use horizontal mode? + function systray:set_horizontal(horiz) horizontal = get_args(self, horiz) if instance then @@ -134,7 +138,9 @@ function systray:set_horizontal(horiz) end --- Should the systray icons be displayed in reverse order? --- @tparam boolean rev Display in reverse order +-- @property reverse +-- @tparam boolean rev Display in reverse order. + function systray:set_reverse(rev) reverse = get_args(self, rev) if instance then @@ -146,7 +152,9 @@ end -- This can either be a screen, in which case the systray will be displayed on -- exactly that screen, or the string `"primary"`, in which case it will be -- visible on the primary screen. The default value is "primary". +-- @property screen -- @tparam screen|"primary" s The screen to display on. + function systray:set_screen(s) display_on_screen = get_args(self, s) if instance then diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index 4264be48..fd86832d 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -70,6 +70,7 @@ end --- Get the preferred size of a textbox. -- This returns the size that the textbox would use if infinite space were -- available. +-- @method get_preferred_size -- @tparam integer|screen s The screen on which the textbox will be displayed. -- @treturn number The preferred width. -- @treturn number The preferred height. @@ -88,6 +89,7 @@ end --- Get the preferred height of a textbox at a given width. -- This returns the height that the textbox would use when it is limited to the -- given width. +-- @method get_height_for_width -- @tparam number width The available width. -- @tparam integer|screen s The screen on which the textbox will be displayed. -- @treturn number The needed height. @@ -105,6 +107,7 @@ end --- Get the preferred size of a textbox. -- This returns the size that the textbox would use if infinite space were -- available. +-- @method get_preferred_size_at_dpi -- @tparam number dpi The DPI value to render at. -- @treturn number The preferred width. -- @treturn number The preferred height. @@ -119,6 +122,7 @@ end --- Get the preferred height of a textbox at a given width. -- This returns the height that the textbox would use when it is limited to the -- given width. +-- @method get_height_for_width_at_dpi -- @tparam number width The available width. -- @tparam number dpi The DPI value to render at. -- @treturn number The needed height. @@ -136,6 +140,7 @@ end -- @tparam string text The text to set. This can contain pango markup (e.g. -- `bold`). You can use `gears.string.escape` to escape -- parts of it. +-- @method set_markup_silently -- @treturn[1] boolean true -- @treturn[2] boolean false -- @treturn[2] string Error message explaining why the markup was invalid. diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index dce46865..fa1035ca 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -69,6 +69,7 @@ function textclock:get_refresh() end --- Force a textclock to update now. +-- @method force_update function textclock:force_update() self._timer:emit_signal("timeout") end diff --git a/objects/client.c b/objects/client.c index 40ba1525..65d9061d 100644 --- a/objects/client.c +++ b/objects/client.c @@ -919,14 +919,14 @@ * * @param struts A table with new strut values, or none. * @return A table with strut values. - * @function struts + * @method struts */ /** Get or set mouse buttons bindings for a client. * * @param buttons_table An array of mouse button bindings objects, or nothing. * @return A table with all buttons. - * @function buttons + * @method buttons */ /** Get the number of instances. @@ -2467,7 +2467,7 @@ luaA_client_get(lua_State *L) /** Check if a client is visible on its screen. * * @return A boolean value, true if the client is visible, false otherwise. - * @function isvisible + * @method isvisible */ static int luaA_client_isvisible(lua_State *L) @@ -2577,7 +2577,7 @@ out: /** Kill a client. * - * @function kill + * @method kill */ static int luaA_client_kill(lua_State *L) @@ -2589,7 +2589,7 @@ luaA_client_kill(lua_State *L) /** Swap a client with another one in global client list. * @client c A client to swap with. - * @function swap + * @method swap */ static int luaA_client_swap(lua_State *L) @@ -2639,7 +2639,7 @@ luaA_client_swap(lua_State *L) * @tparam table tags_table A table with tags to set, or `nil` to get the * current tags. * @treturn table A table with all tags. - * @function tags + * @method tags */ static int luaA_client_tags(lua_State *L) @@ -2708,7 +2708,7 @@ luaA_client_get_first_tag(lua_State *L, client_t *c) /** Raise a client on top of others which are on the same layer. * - * @function raise + * @method raise */ static int luaA_client_raise(lua_State *L) @@ -2729,7 +2729,7 @@ luaA_client_raise(lua_State *L) /** Lower a client on bottom of others which are on the same layer. * - * @function lower + * @method lower */ static int luaA_client_lower(lua_State *L) @@ -2756,7 +2756,7 @@ luaA_client_lower(lua_State *L) /** Stop managing a client. * - * @function unmanage + * @method unmanage */ static int luaA_client_unmanage(lua_State *L) @@ -2986,7 +2986,7 @@ HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT) * * @tparam table|nil geo A table with new coordinates, or nil. * @treturn table A table with client geometry and coordinates. - * @function geometry + * @method geometry */ static int luaA_client_geometry(lua_State *L) @@ -3023,7 +3023,7 @@ luaA_client_geometry(lua_State *L) * @param height Desired height of client * @return Actual width of client * @return Actual height of client - * @function apply_size_hints + * @method apply_size_hints */ static int luaA_client_apply_size_hints(lua_State *L) @@ -3640,7 +3640,7 @@ luaA_client_set_shape_input(lua_State *L, client_t *c) * * @param keys_table An array of key bindings objects, or nothing. * @return A table with all keys. - * @function keys + * @method keys */ static int luaA_client_keys(lua_State *L) @@ -3690,7 +3690,7 @@ luaA_client_get_icon_sizes(lua_State *L, client_t *c) * @tparam interger index The index in the list of icons to get. * @treturn surface A lightuserdata for a cairo surface. This reference must be * destroyed! - * @function get_icon + * @method get_icon */ static int luaA_client_get_some_icon(lua_State *L) diff --git a/objects/drawable.c b/objects/drawable.c index 89e750d6..07d15aea 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -188,7 +188,7 @@ luaA_drawable_get_surface(lua_State *L, drawable_t *drawable) /** Refresh a drawable's content. This has to be called whenever some drawing to * the drawable's surface has been done and should become visible. * - * @function refresh + * @method refresh */ static int luaA_drawable_refresh(lua_State *L) @@ -203,7 +203,7 @@ luaA_drawable_refresh(lua_State *L) /** Get drawable geometry. The geometry consists of x, y, width and height. * * @treturn table A table with drawable coordinates and geometry. - * @function geometry + * @method geometry */ static int luaA_drawable_geometry(lua_State *L) diff --git a/objects/screen.c b/objects/screen.c index cbc57c53..2f509315 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -1199,7 +1199,7 @@ luaA_screen_fake_add(lua_State *L) } /** Remove a screen. - * @function fake_remove + * @method fake_remove */ static int luaA_screen_fake_remove(lua_State *L) @@ -1231,7 +1231,7 @@ luaA_screen_fake_remove(lua_State *L) * @tparam integer y The new Y-coordinate for screen. * @tparam integer width The new width for screen. * @tparam integer height The new height for screen. - * @function fake_resize + * @method fake_resize */ static int luaA_screen_fake_resize(lua_State *L) @@ -1258,7 +1258,7 @@ luaA_screen_fake_resize(lua_State *L) /** Swap a screen with another one in global screen list. * @client s A screen to swap with. - * @function swap + * @method swap */ static int luaA_screen_swap(lua_State *L) From 11d7a614d9f0e78a1f72120280377038a0c7e80a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 7 Jun 2019 14:59:34 -0400 Subject: [PATCH 17/23] doc: Add a constructor stereotype for everything. This forces the constructor functions to be at the top of the API documentation rather than in a random position. --- docs/config.ld | 12 ++++++++++-- lib/awful/hotkeys_popup/widget.lua | 1 + lib/awful/keygrabber.lua | 2 +- lib/awful/popup.lua | 2 +- lib/awful/tag.lua | 2 +- lib/awful/titlebar.lua | 2 +- lib/awful/tooltip.lua | 2 +- lib/awful/wibar.lua | 2 +- lib/awful/widget/button.lua | 1 + lib/awful/widget/calendar_popup.lua | 4 ++-- lib/awful/widget/clienticon.lua | 2 +- lib/awful/widget/keyboardlayout.lua | 6 +++++- lib/awful/widget/launcher.lua | 1 + lib/awful/widget/layoutbox.lua | 1 + lib/awful/widget/layoutlist.lua | 2 +- lib/awful/widget/only_on_screen.lua | 2 +- lib/awful/widget/prompt.lua | 2 +- lib/awful/widget/taglist.lua | 2 +- lib/awful/widget/tasklist.lua | 2 +- lib/awful/widget/watch.lua | 1 + lib/gears/cache.lua | 1 + lib/gears/matrix.lua | 5 +++++ lib/gears/timer.lua | 4 +++- lib/naughty/action.lua | 4 +++- lib/naughty/notification.lua | 2 +- lib/wibox/container/arcchart.lua | 2 +- lib/wibox/container/background.lua | 2 +- lib/wibox/container/constraint.lua | 2 +- lib/wibox/container/margin.lua | 2 +- lib/wibox/container/mirror.lua | 2 +- lib/wibox/container/place.lua | 2 +- lib/wibox/container/radialprogressbar.lua | 2 +- lib/wibox/container/rotate.lua | 2 +- lib/wibox/container/scroll.lua | 4 ++-- lib/wibox/init.lua | 2 +- lib/wibox/layout/align.lua | 2 ++ lib/wibox/layout/fixed.lua | 4 ++-- lib/wibox/layout/flex.lua | 4 ++-- lib/wibox/layout/grid.lua | 6 +++--- lib/wibox/layout/manual.lua | 2 +- lib/wibox/layout/ratio.lua | 4 ++-- lib/wibox/layout/stack.lua | 2 +- lib/wibox/widget/calendar.lua | 4 ++-- lib/wibox/widget/checkbox.lua | 2 +- lib/wibox/widget/graph.lua | 2 +- lib/wibox/widget/imagebox.lua | 2 +- lib/wibox/widget/init.lua | 2 +- lib/wibox/widget/piechart.lua | 2 +- lib/wibox/widget/progressbar.lua | 2 +- lib/wibox/widget/separator.lua | 2 +- lib/wibox/widget/slider.lua | 2 +- lib/wibox/widget/systray.lua | 2 +- lib/wibox/widget/textbox.lua | 2 +- lib/wibox/widget/textclock.lua | 2 +- objects/screen.c | 2 +- 55 files changed, 85 insertions(+), 56 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 7883fa5e..8a049456 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -52,6 +52,8 @@ tparam_alias('tab', 'table') tparam_alias('screen', 'screen') tparam_alias('screen_or_idx', 'screen|int') +-- The first stereotype are the constructors. +new_type("constructorfct", "Constructors", false, "Parameters") -- Hack to get the functions on top of the signals and properties new_type("function", "Functions", false, "Parameters") -- Documentation for objects properties @@ -223,8 +225,14 @@ custom_display_name_handler = function(item, default_handler) -- more consistent. Right now some have their full awful.foo.bar while other -- have "just" `bar`. Given we use constructors from metatables, we have no -- choice but to use the full function name. It also makes copy/paste easier. - if item.type == "function" and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then - return item.module.name .. "." .. ret + if (item.type == "function" or item.type == "constructorfct") + and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then + ret = item.module.name .. "." .. ret + end + + -- It isn't there by default. + if item.type == "constructorfct" then + ret = ret .. " " .. item.args end return ret diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index 044deae5..a9278745 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -125,6 +125,7 @@ widget.merge_duplicates = true -- @tparam[opt] table args.labels Labels used for displaying human-readable keynames. -- @tparam[opt] table args.group_rules Rules for showing 3rd-party hotkeys. @see `awful.hotkeys_popup.keys.vim`. -- @return Widget instance. +-- @constructorfct awful.widget.hotkeys_popup.widget.new function widget.new(args) args = args or {} local widget_instance = { diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index 5036b068..65b7629c 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -663,7 +663,7 @@ end -- @tparam[opt=false] boolean args.autostart Start the grabbing immediately -- @tparam[opt=false] boolean args.mask_modkeys Do not call the callbacks on -- modifier keys (like `Control` or `Mod4`) events. --- @function awful.keygrabber +-- @constructorfct awful.keygrabber function keygrab.run_with_keybindings(args) args = args or {} diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index 66efbf13..c9e97e8f 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -394,7 +394,7 @@ end -- @tparam table|number args.offset The X and Y offset compared to the parent object -- @tparam boolean args.hide_on_right_click Whether or not to hide the popup on -- right clicks. --- @function awful.popup +-- @constructorfct awful.popup local function create_popup(_, args) assert(args) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 6b743939..9066f5d3 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -259,7 +259,7 @@ end -- layout = awful.layout.suit.max, -- }) -- --- @function awful.tag.add +-- @constructorfct awful.tag.add -- @param name The tag name, a string -- @param props The tags inital properties, a table -- @return The created tag diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 793abf20..85d31814 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -502,7 +502,7 @@ end -- @tparam[opt=top] string args.fg_normal -- @tparam[opt=top] string args.fg_focus -- @tparam[opt=top] string args.font --- @function awful.titlebar +-- @constructorfct awful.titlebar local function new(c, args) args = args or {} local position = args.position or "top" diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index 5cfbad24..0420eb72 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -577,7 +577,7 @@ end -- @see text -- @see markup -- @see align --- @function awful.tooltip +-- @constructorfct awful.tooltip function tooltip.new(args) -- gears.object, properties are linked to set_/get_ functions local self = object { diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index bb7da67e..84846be7 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -344,7 +344,7 @@ end -- @tparam string args.stretch If the wibar need to be stretched to fill the screen. --@DOC_wibox_constructor_COMMON@ -- @return The new wibar --- @function awful.wibar +-- @constructorfct awful.wibar function awfulwibar.new(args) args = args or {} local position = args.position or "top" diff --git a/lib/awful/widget/button.lua b/lib/awful/widget/button.lua index db6629a2..4a4b398b 100644 --- a/lib/awful/widget/button.lua +++ b/lib/awful/widget/button.lua @@ -24,6 +24,7 @@ local button = { mt = {} } --- Create a button widget. When clicked, the image is deplaced to make it like -- a real button. -- +-- @constructorfct awful.widget.button -- @param args Widget arguments. "image" is the image to display. -- @return A textbox widget configured as a button. function button.new(args) diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index fe3fdc78..56621876 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -371,7 +371,7 @@ end -- @tparam table args.style_normal Cell style for the normal day cells (see `cell_properties`) -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`) -- @treturn wibox A wibox containing the calendar --- @function awful.widget.calendar_popup.month +-- @constructorfct awful.widget.calendar_popup.month function calendar_popup.month(args) return get_cal_wibox("month", args) end @@ -407,7 +407,7 @@ end -- @tparam table args.style_normal Cell style for the normal day cells (see `cell_properties`) -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`) -- @treturn wibox A wibox containing the calendar --- @function awful.widget.calendar_popup.year +-- @constructorfct awful.widget.calendar_popup.year function calendar_popup.year(args) return get_cal_wibox("year", args) end diff --git a/lib/awful/widget/clienticon.lua b/lib/awful/widget/clienticon.lua index bafda1d2..69e53aca 100644 --- a/lib/awful/widget/clienticon.lua +++ b/lib/awful/widget/clienticon.lua @@ -99,7 +99,7 @@ end --- Returns a new clienticon. -- @tparam client c The client whose icon should be displayed. -- @treturn widget A new `widget` --- @function awful.widget.clienticon +-- @constructorfct awful.widget.clienticon local function new(c) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index 35f8a81a..3c15799c 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -252,7 +252,11 @@ local function update_layout(self) update_status(self) end ---- Create a keyboard layout widget. It shows current keyboard layout name in a textbox. +--- Create a keyboard layout widget. +-- +-- It shows current keyboard layout name in a textbox. +-- +-- @constructorfct awful.widget.keyboardlayout -- @return A keyboard layout widget. function keyboardlayout.new() local widget = textbox() diff --git a/lib/awful/widget/launcher.lua b/lib/awful/widget/launcher.lua index e8c6959e..4c2ff0c4 100644 --- a/lib/awful/widget/launcher.lua +++ b/lib/awful/widget/launcher.lua @@ -16,6 +16,7 @@ local launcher = { mt = {} } -- @param args Standard widget table arguments, plus image for the image path -- and command for the command to run on click, or either menu to create menu. -- @return A launcher widget. +-- @constructorfct awful.widget.launcher function launcher.new(args) if not args.command and not args.menu then return end local w = wbutton(args) diff --git a/lib/awful/widget/layoutbox.lua b/lib/awful/widget/layoutbox.lua index 56e671a3..5583e683 100644 --- a/lib/awful/widget/layoutbox.lua +++ b/lib/awful/widget/layoutbox.lua @@ -44,6 +44,7 @@ end -- symbol of the current tag. -- @param screen The screen number that the layout will be represented for. -- @return An imagebox widget configured as a layoutbox. +-- @constructorfct awful.widget.layoutbox function layoutbox.new(screen) screen = get_screen(screen or 1) diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index 1d2d5be4..6cb3ff18 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -382,7 +382,7 @@ end -- @tparam string|pattern args.style.shape_border_width_selected -- @tparam string|pattern args.style.shape_border_color_selected -- @treturn widget The action widget. --- @function awful.widget.layoutlist +-- @constructorfct awful.widget.layoutlist local is_connected, instances = false, setmetatable({}, {__mode = "v"}) diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua index 95bec166..37ce050d 100644 --- a/lib/awful/widget/only_on_screen.lua +++ b/lib/awful/widget/only_on_screen.lua @@ -91,7 +91,7 @@ end -- @param[opt] widget The widget to display. -- @param[opt] s The screen to display on. -- @treturn table A new only_on_screen container --- @function wibox.container.only_on_screen +-- @constructorfct awful.widget.only_on_screen local function new(widget, s) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/awful/widget/prompt.lua b/lib/awful/widget/prompt.lua index 13853f29..e58d8eea 100644 --- a/lib/awful/widget/prompt.lua +++ b/lib/awful/widget/prompt.lua @@ -113,7 +113,7 @@ end -- for the matching modifiers + key. See @{awful.prompt.run} for details. -- @return An instance of prompt widget, inherits from -- `wibox.container.background`. --- @function awful.widget.prompt +-- @constructorfct awful.widget.prompt function widgetprompt.new(args) args = args or {} local promptbox = background() diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index 8e6d4050..8be36dc5 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -462,7 +462,7 @@ end -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function -- @param base_widget **DEPRECATED** use args.base_widget --- @function awful.widget.taglist +-- @constructorfct awful.widget.taglist function taglist.new(args, filter, buttons, style, update_function, base_widget) local screen = nil diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 240a5983..89942037 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -518,7 +518,7 @@ end -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function -- @param base_widget **DEPRECATED** use args.base_widget --- @function awful.tasklist +-- @constructorfct awful.widget.tasklist function tasklist.new(args, filter, buttons, style, update_function, base_widget) local screen = nil diff --git a/lib/awful/widget/watch.lua b/lib/awful/widget/watch.lua index 42e0c364..03926c14 100644 --- a/lib/awful/widget/watch.lua +++ b/lib/awful/widget/watch.lua @@ -64,6 +64,7 @@ local watch = { mt = {} } -- -- @return The widget used by this watch. -- @return Its gears.timer. +-- @constructorfct awful.widget.watch function watch.new(command, timeout, callback, base_widget) timeout = timeout or 5 base_widget = base_widget or textbox() diff --git a/lib/gears/cache.lua b/lib/gears/cache.lua index dc5add5f..9fb1d908 100644 --- a/lib/gears/cache.lua +++ b/lib/gears/cache.lua @@ -37,6 +37,7 @@ end -- garbage-collected at any time, but might be useful to keep. -- @param creation_cb Callback that is used for creating missing cache entries. -- @return A new cache object. +-- @constructorfct gears.cache function cache.new(creation_cb) return setmetatable({ _cache = setmetatable({}, { __mode = "v" }), diff --git a/lib/gears/matrix.lua b/lib/gears/matrix.lua index a6bc9755..f66a4004 100644 --- a/lib/gears/matrix.lua +++ b/lib/gears/matrix.lua @@ -20,6 +20,7 @@ local matrix_mt = {} -- @tparam number x0 The x0 transformation part. -- @tparam number y0 The y0 transformation part. -- @return A new matrix describing the given transformation. +-- @constructorfct create function matrix.create(xx, yx, xy, yy, x0, y0) return setmetatable({ xx = xx, xy = xy, x0 = x0, @@ -31,6 +32,7 @@ end -- @tparam number x The translation in x direction. -- @tparam number y The translation in y direction. -- @return A new matrix describing the given transformation. +-- @constructorfct create_translate function matrix.create_translate(x, y) return matrix.create(1, 0, 0, 1, x, y) end @@ -39,6 +41,7 @@ end -- @tparam number sx The scaling in x direction. -- @tparam number sy The scaling in y direction. -- @return A new matrix describing the given transformation. +-- @constructorfct create_scale function matrix.create_scale(sx, sy) return matrix.create(sx, 0, 0, sy, 0, 0) end @@ -46,6 +49,7 @@ end --- Create a new rotation matrix -- @tparam number angle The angle of the rotation in radians. -- @return A new matrix describing the given transformation. +-- @constructorfct create_rotate function matrix.create_rotate(angle) local c, s = math.cos(angle), math.sin(angle) return matrix.create(c, s, -s, c, 0, 0) @@ -56,6 +60,7 @@ end -- @tparam number y The vertical rotation point -- @tparam number angle The angle of the rotation in radians. -- @return A new matrix describing the given transformation. +-- @constructorfct create_rotate_at function matrix.create_rotate_at(x, y, angle) return matrix.create_translate( -x, -y ) * matrix.create_rotate ( angle ) diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index f7c39db1..ab51e006 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -157,7 +157,7 @@ local timer_instance_mt = { -- "timeout" signal. -- @tparam[opt=false] boolean args.single_shot Run only once then stop. -- @treturn timer --- @function gears.timer +-- @constructorfct gears.timer function timer.new(args) args = args or {} local ret = object() @@ -257,6 +257,8 @@ function timer.mt.__call(_, ...) return timer.new(...) end +--@DOC_object_COMMON@ + return setmetatable(timer, timer.mt) -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index a16a9570..bf98e712 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -14,7 +14,7 @@ local gobject = require("gears.object") local action = {} --- Create a new action. --- @function naughty.action +-- @constructorfct naughty.action -- @tparam table args The arguments. -- @tparam string args.name The name. -- @tparam string args.position The position. @@ -124,4 +124,6 @@ local function new(_, args) return ret end +--@DOC_object_COMMON@ + return setmetatable(action, {__call = new}) diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 2a355cb3..4e00d58f 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -451,7 +451,7 @@ end -- @usage naughty.notify({ title = "Achtung!", message = "You're idling", timeout = 0 }) -- @treturn ?table The notification object, or nil in case a notification was -- not displayed. --- @function naughty.notification +-- @constructorfct naughty.notification local function create(args) if cst.config.notify_callback then args = cst.config.notify_callback(args) diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index 28175337..5b5f495a 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -316,7 +316,7 @@ end --- Returns a new arcchart layout. -- @param[opt] widget The widget to display. --- @function wibox.container.arcchart +-- @constructorfct wibox.container.arcchart local function new(widget) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index 73d89dd5..455fe047 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -385,7 +385,7 @@ end -- @param[opt] widget The widget to display. -- @param[opt] bg The background to use for that widget. -- @param[opt] shape A `gears.shape` compatible shape function --- @function wibox.container.background +-- @constructorfct wibox.container.background local function new(widget, bg, shape) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index 8fd84dc2..0d937707 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -136,7 +136,7 @@ end -- @param[opt] width The maximum width of the widget. nil for no limit. -- @param[opt] height The maximum height of the widget. nil for no limit. -- @treturn table A new constraint container --- @function wibox.container.constraint +-- @constructorfct wibox.container.constraint local function new(widget, strategy, width, height) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index 9a5fcd4f..78d74cc1 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -190,7 +190,7 @@ end -- @param[opt] color A color for the margins. -- @param[opt] draw_empty whether or not to draw the margin when the content is empty -- @treturn table A new margin container --- @function wibox.container.margin +-- @constructorfct wibox.container.margin local function new(widget, left, right, top, bottom, color, draw_empty) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua index ac41d41d..fa86ec86 100644 --- a/lib/wibox/container/mirror.lua +++ b/lib/wibox/container/mirror.lua @@ -108,7 +108,7 @@ end -- @param[opt] widget The widget to display. -- @param[opt] reflection A table describing the reflection to apply. -- @treturn table A new mirror container --- @function wibox.container.mirror +-- @constructorfct wibox.container.mirror local function new(widget, reflection) local ret = base.make_widget(nil, nil, {enable_properties = true}) ret._private.horizontal = false diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua index 86c7b5fe..fca97419 100644 --- a/lib/wibox/container/place.lua +++ b/lib/wibox/container/place.lua @@ -172,7 +172,7 @@ end -- @tparam[opt="center"] string halign The horizontal alignment -- @tparam[opt="center"] string valign The vertical alignment -- @treturn table A new place container. --- @function wibox.container.place +-- @constructorfct wibox.container.place local function new(widget, halign, valign) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index 766ec818..3d698792 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -233,7 +233,7 @@ end --- Returns a new radialprogressbar layout. A radialprogressbar layout -- radialprogressbars a given widget. Use `.widget` to set the widget. -- @param[opt] widget The widget to display. --- @function wibox.container.radialprogressbar +-- @constructorfct wibox.container.radialprogressbar local function new(widget) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index a0f2775a..5a3f784c 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -133,7 +133,7 @@ end -- @param[opt] widget The widget to display. -- @param[opt] dir The direction to rotate to. -- @treturn table A new rotate container. --- @function wibox.container.rotate +-- @constructorfct wibox.container.rotate local function new(widget, dir) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua index 4f63377d..06413078 100644 --- a/lib/wibox/container/scroll.lua +++ b/lib/wibox/container/scroll.lua @@ -425,7 +425,7 @@ local function get_layout(dir, widget, fps, speed, extra_space, expand, max_size end --- Get a new horizontal scrolling container. --- @function wibox.container.scroll.horizontal +-- @constructorfct wibox.container.scroll.horizontal -- @param[opt] widget The widget that should be scrolled -- @param[opt=20] fps The number of frames per second -- @param[opt=10] speed The speed of the animation @@ -440,7 +440,7 @@ function scroll.horizontal(widget, fps, speed, extra_space, expand, max_size, st end --- Get a new vertical scrolling container. --- @function wibox.container.scroll.vertical +-- @constructorfct wibox.container.scroll.vertical -- @param[opt] widget The widget that should be scrolled -- @param[opt=20] fps The number of frames per second -- @param[opt=10] speed The speed of the animation diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index 3f72b82b..f55a899e 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -253,7 +253,7 @@ end -- @tparam[opt=nil] table args --@DOC_wibox_constructor_COMMON@ -- @treturn wibox The new wibox --- @function .wibox +-- @constructorfct wibox local function new(args) args = args or {} diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index 1271b7e4..283a395e 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -279,6 +279,7 @@ end -- three widgets. The widget set via :set_left() is left-aligned. :set_right() -- sets a widget which will be right-aligned. The remaining space between those -- two will be given to the widget set via :set_middle(). +-- @constructorfct wibox.layout.align.horizontal -- @tparam[opt] widget left Widget to be put to the left. -- @tparam[opt] widget middle Widget to be put to the middle. -- @tparam[opt] widget right Widget to be put to the right. @@ -296,6 +297,7 @@ end -- three widgets. The widget set via :set_top() is top-aligned. :set_bottom() -- sets a widget which will be bottom-aligned. The remaining space between those -- two will be given to the widget set via :set_middle(). +-- @constructorfct wibox.layout.align.vertical -- @tparam[opt] widget top Widget to be put to the top. -- @tparam[opt] widget middle Widget to be put to the middle. -- @tparam[opt] widget bottom Widget to be put to the right. diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index a6f5ca2a..aedfbeac 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -322,7 +322,7 @@ end -- Note that widgets ignore `forced_height`. They will use the preferred/minimum width -- on the horizontal axis, and a stretched height on the vertical axis. -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.fixed.horizontal +-- @constructorfct wibox.layout.fixed.horizontal function fixed.horizontal(...) return get_layout("x", ...) end @@ -333,7 +333,7 @@ end -- Note that widgets ignore `forced_width`. They will use the preferred/minimum height -- on the vertical axis, and a stretched width on the horizontal axis. -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.fixed.vertical +-- @constructorfct wibox.layout.fixed.vertical function fixed.vertical(...) return get_layout("y", ...) end diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index 59815c43..c37d8176 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -170,7 +170,7 @@ end --- Returns a new horizontal flex layout. A flex layout shares the available space -- equally among all widgets. Widgets can be added via :add(widget). -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.flex.horizontal +-- @constructorfct wibox.layout.flex.horizontal function flex.horizontal(...) return get_layout("horizontal", ...) end @@ -178,7 +178,7 @@ end --- Returns a new vertical flex layout. A flex layout shares the available space -- equally among all widgets. Widgets can be added via :add(widget). -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.flex.vertical +-- @constructorfct wibox.layout.flex.vertical function flex.vertical(...) return get_layout("vertical", ...) end diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index 48385204..1322a6e9 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -885,7 +885,7 @@ end -- -- A grid layout sets widgets in a grids of custom number of rows and columns. -- @tparam[opt="y"] string orientation The preferred grid extension direction. --- @function wibox.layout.grid +-- @constructorfct wibox.layout.grid local function new(orientation) -- Preference for vertical direction: fill rows first, extend grid with new row local dir = (orientation == "horizontal"or orientation == "vertical") @@ -924,7 +924,7 @@ end -- up to `forced_num_rows`. Then the next column is filled, creating it if it doesn't exist. -- @tparam number|nil forced_num_rows Forced number of rows (`nil` for automatic). -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.grid.horizontal +-- @constructorfct wibox.layout.grid.horizontal function grid.horizontal(forced_num_rows, widget, ...) local ret = new("horizontal") ret:set_forced_num_rows(forced_num_rows) @@ -942,7 +942,7 @@ end -- up to `forced_num_cols`. Then the next row is filled, creating it if it doesn't exist. -- @tparam number|nil forced_num_cols Forced number of columns (`nil` for automatic). -- @tparam widget ... Widgets that should be added to the layout. --- @function wibox.layout.grid.vertical +-- @constructorfct wibox.layout.grid.vertical function grid.vertical(forced_num_cols, widget, ...) local ret = new("vertical") ret:set_forced_num_cols(forced_num_cols) diff --git a/lib/wibox/layout/manual.lua b/lib/wibox/layout/manual.lua index 6fa617ee..d263141b 100644 --- a/lib/wibox/layout/manual.lua +++ b/lib/wibox/layout/manual.lua @@ -212,7 +212,7 @@ function manual_layout:reset() end --- Create a manual layout. --- @function wibox.layout.manual +-- @constructorfct wibox.layout.manual -- @tparam table ... Widgets to add to the layout. local function new_manual(...) diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua index 9055392a..0e8f18ac 100644 --- a/lib/wibox/layout/ratio.lua +++ b/lib/wibox/layout/ratio.lua @@ -457,7 +457,7 @@ end --- Returns a new horizontal ratio layout. A ratio layout shares the available space. -- equally among all widgets. Widgets can be added via :add(widget). --- @function wibox.layout.ratio.horizontal +-- @constructorfct wibox.layout.ratio.horizontal -- @tparam widget ... Widgets that should be added to the layout. function ratio.horizontal(...) return get_layout("horizontal", ...) @@ -465,7 +465,7 @@ end --- Returns a new vertical ratio layout. A ratio layout shares the available space. -- equally among all widgets. Widgets can be added via :add(widget). --- @function wibox.layout.ratio.vertical +-- @constructorfct wibox.layout.ratio.vertical -- @tparam widget ... Widgets that should be added to the layout. function ratio.vertical(...) return get_layout("vertical", ...) diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index 510a7950..e55930db 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -156,7 +156,7 @@ function stack:set_vertical_offset(value) end --- Create a new stack layout. --- @function wibox.layout.stack +-- @constructorfct wibox.layout.stack -- @treturn widget A new stack layout local function new(...) diff --git a/lib/wibox/widget/calendar.lua b/lib/wibox/widget/calendar.lua index 932c21dd..3aef7c33 100644 --- a/lib/wibox/widget/calendar.lua +++ b/lib/wibox/widget/calendar.lua @@ -352,7 +352,7 @@ end -- @tparam number|nil date.day Date day -- @tparam[opt="Monospace 10"] string font Font of the calendar -- @treturn widget The month calendar widget --- @function wibox.widget.calendar.month +-- @constructorfct wibox.widget.calendar.month function calendar.month(date, font) return get_calendar("month", date, font) end @@ -368,7 +368,7 @@ end -- @tparam number|nil date.day Date day -- @tparam[opt="Monospace 10"] string font Font of the calendar -- @treturn widget The year calendar widget --- @function wibox.widget.calendar.year +-- @constructorfct wibox.widget.calendar.year function calendar.year(date, font) return get_calendar("year", date, font) end diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index 10df7e2d..efe10ec4 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -225,7 +225,7 @@ function checkbox:set_paddings(val) end --- Create a new checkbox. --- @function wibox.widget.checkbox +-- @constructorfct wibox.widget.checkbox -- @tparam[opt=false] boolean checked -- @tparam[opt] table args -- @tparam gears.color args.color The color. diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index a8cb5480..0482969f 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -319,7 +319,7 @@ end -- @param args Standard widget() arguments. You should add width and height -- key to set graph geometry. -- @return A new graph widget. --- @function wibox.widget.graph +-- @constructorfct wibox.widget.graph function graph.new(args) args = args or {} diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index cb121fc2..61e35f8c 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -157,7 +157,7 @@ end -- to fit into the available space. -- @param clip_shape A `gears.shape` compatible function -- @treturn table A new `imagebox` --- @function wibox.widget.imagebox +-- @constructorfct wibox.widget.imagebox local function new(image, resize_allowed, clip_shape) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index 4793206f..d151e8de 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter --- @classmod wibox.widget +-- @module wibox.widget --------------------------------------------------------------------------- local cairo = require("lgi").cairo diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 7f22a7c2..2e57e952 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -219,7 +219,7 @@ function piechart:get_data() end --- Create a new piechart. --- @function wibox.widget.piechart +-- @constructorfct wibox.widget.piechart -- @tparam table data_list The data. local function new(data_list) diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index d2eacacc..d6497476 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -427,7 +427,7 @@ end -- @param args Standard widget() arguments. You should add width and height -- key to set progressbar geometry. -- @return A progressbar widget. --- @function wibox.widget.progressbar +-- @constructorfct wibox.widget.progressbar function progressbar.new(args) args = args or {} diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index c02c9c8a..a02e8433 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -186,7 +186,7 @@ for _, prop in ipairs {"orientation", "color", "thickness", "span_ratio", end --- Create a new separator. --- @function wibox.widget.separator +-- @constructorfct wibox.widget.separator -- @tparam table args The arguments (all properties are available). local function new(args) diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua index 15d41813..63a10f74 100644 --- a/lib/wibox/widget/slider.lua +++ b/lib/wibox/widget/slider.lua @@ -475,7 +475,7 @@ end --- Create a slider widget. -- @tparam[opt={}] table args --- @function wibox.widget.slider +-- @constructorfct wibox.widget.slider local function new(args) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua index d9ca261e..59b715d3 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -166,7 +166,7 @@ end -- Note that this widget can only exist once. -- @tparam boolean revers Show in the opposite direction -- @treturn table The new `systray` widget --- @function wibox.widget.systray +-- @constructorfct wibox.widget.systray local function new(revers) local ret = wbase.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index fd86832d..6c70d6eb 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -280,7 +280,7 @@ end -- @tparam[opt=""] string text The textbox content -- @tparam[opt=false] boolean ignore_markup Ignore the pango/HTML markup -- @treturn table A new textbox widget --- @function wibox.widget.textbox +-- @constructorfct wibox.widget.textbox local function new(text, ignore_markup) local ret = base.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index fa1035ca..99f255ef 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -88,7 +88,7 @@ end -- e.g. "Z" for UTC, "±hh:mm" or "Europe/Amsterdam". See -- https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new. -- @treturn table A textbox widget. --- @function wibox.widget.textclock +-- @constructorfct wibox.widget.textclock local function new(format, refresh, tzid) local w = textbox() gtable.crush(w, textclock, true) diff --git a/objects/screen.c b/objects/screen.c index 2f509315..b3e4f81f 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -1173,7 +1173,7 @@ luaA_screen_count(lua_State *L) * @tparam integer width width for screen. * @tparam integer height height for screen. * @return The new screen. - * @function fake_add + * @constructorfct fake_add */ static int luaA_screen_fake_add(lua_State *L) From b4ece0f053a20a96496b3b152fccafb1730b5438 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 7 Jun 2019 19:08:05 -0400 Subject: [PATCH 18/23] doc: Use an explicit tag for all static functions. This way their name doesn't get mangle by the broken magic. It will also eventually allow to `error()` in the template when the implicit `@function` is used. This commit also fixes a large number of issues found while proof-reading everything. --- docs/common/cobject.ldoc | 6 +- docs/config.ld | 42 ++++++++++---- lib/awful/client.lua | 34 +++++------ lib/awful/completion.lua | 3 + lib/awful/ewmh.lua | 3 + lib/awful/hotkeys_popup/init.lua | 2 +- lib/awful/hotkeys_popup/widget.lua | 6 ++ lib/awful/key.lua | 5 +- lib/awful/keygrabber.lua | 20 ++----- lib/awful/layout/init.lua | 10 +++- lib/awful/layout/suit/fair.lua | 13 ++++- lib/awful/layout/suit/floating.lua | 3 +- lib/awful/layout/suit/tile.lua | 1 + lib/awful/menu.lua | 21 +++++-- lib/awful/mouse/init.lua | 8 +-- lib/awful/placement.lua | 14 ++++- lib/awful/popup.lua | 3 + lib/awful/prompt.lua | 1 + lib/awful/rules.lua | 13 ++++- lib/awful/screen.lua | 20 ++++--- lib/awful/spawn.lua | 9 +++ lib/awful/tag.lua | 35 ++++++------ lib/awful/titlebar.lua | 15 ++++- lib/awful/tooltip.lua | 11 +--- lib/awful/util.lua | 4 ++ lib/awful/wibar.lua | 8 +-- lib/awful/widget/calendar_popup.lua | 5 +- lib/awful/widget/keyboardlayout.lua | 1 + lib/beautiful/gtk.lua | 48 ---------------- lib/beautiful/init.lua | 57 ++++++++++++++++++- lib/beautiful/theme_assets.lua | 10 +++- lib/beautiful/xresources.lua | 9 ++- lib/gears/color.lua | 14 +++-- lib/gears/debug.lua | 11 +++- lib/gears/filesystem.lua | 18 +++++- lib/gears/geometry.lua | 9 ++- lib/gears/math.lua | 9 +-- lib/gears/object.lua | 8 ++- lib/gears/protected_call.lua | 1 + lib/gears/shape.lua | 21 ++++++- lib/gears/sort/topological.lua | 7 ++- lib/gears/string.lua | 45 +++++++-------- lib/gears/surface.lua | 30 +++++++--- lib/gears/table.lua | 51 +++++++++-------- lib/gears/timer.lua | 8 +-- lib/gears/wallpaper.lua | 8 ++- lib/menubar/init.lua | 29 ++++++---- lib/menubar/menu_gen.lua | 2 + lib/menubar/utils.lua | 7 +++ lib/naughty/core.lua | 5 ++ lib/wibox/hierarchy.lua | 15 ++++- lib/wibox/widget/base.lua | 53 ++++++++--------- lib/wibox/widget/init.lua | 3 + luaa.c | 24 ++++---- mouse.c | 2 +- mousegrabber.c | 6 +- objects/button.c | 6 +- objects/client.c | 8 +-- objects/drawable.c | 8 +-- objects/key.c | 6 +- objects/screen.c | 10 ++-- objects/tag.c | 10 ++-- root.c | 20 +++---- selection.c | 2 +- spawn.c | 2 +- tests/examples/awful/placement/bottom.lua | 3 +- .../examples/awful/placement/bottom_left.lua | 3 +- .../examples/awful/placement/bottom_right.lua | 3 +- .../awful/placement/center_horizontal.lua | 4 +- .../awful/placement/center_vertical.lua | 3 +- tests/examples/awful/placement/centered.lua | 3 +- tests/examples/awful/placement/left.lua | 3 +- .../awful/placement/maximize_horizontally.lua | 3 +- .../awful/placement/maximize_vertically.lua | 3 +- tests/examples/awful/placement/right.lua | 3 +- .../examples/awful/placement/stretch_down.lua | 3 +- .../examples/awful/placement/stretch_left.lua | 3 +- .../awful/placement/stretch_right.lua | 3 +- tests/examples/awful/placement/stretch_up.lua | 3 +- tests/examples/awful/placement/top.lua | 3 +- tests/examples/awful/placement/top_left.lua | 3 +- tests/examples/awful/placement/top_right.lua | 3 +- xkb.c | 6 +- 83 files changed, 586 insertions(+), 370 deletions(-) diff --git a/docs/common/cobject.ldoc b/docs/common/cobject.ldoc index dcacb3a8..b8bf3d6f 100644 --- a/docs/common/cobject.ldoc +++ b/docs/common/cobject.ldoc @@ -3,7 +3,7 @@ /** Disconnect from a signal. * @tparam string name The name of the signal. * @tparam function func The callback that should be disconnected. - * @function disconnect_signal + * @staticfct disconnect_signal */ /** Emit a signal. @@ -12,13 +12,13 @@ * @param ... Extra arguments for the callback functions. Each connected * function receives the object as first argument and then any extra * arguments that are given to emit_signal(). - * @function emit_signal + * @staticfct emit_signal */ /** Connect to a signal. * @tparam string name The name of the signal. * @tparam function func The callback to call when the signal is emitted. - * @function connect_signal + * @staticfct connect_signal */ /* diff --git a/docs/config.ld b/docs/config.ld index 8a049456..764989fa 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -56,6 +56,9 @@ tparam_alias('screen_or_idx', 'screen|int') new_type("constructorfct", "Constructors", false, "Parameters") -- Hack to get the functions on top of the signals and properties new_type("function", "Functions", false, "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") -- Documentation for objects properties new_type("property", "Object properties", false, "Type") -- Documentation for objects deprecated properties @@ -141,6 +144,7 @@ file = { '../lib/wibox/container/init.lua', '../lib/naughty/constants.lua', '../lib/naughty/dbus.lua', + '../lib/beautiful/gtk.lua', -- Ignore some parts of the widget library '../lib/awful/widget/init.lua', @@ -189,7 +193,23 @@ local coreclassmap = { mouse = "mouse and awful.mouse", } +-- Add the full module name in front. +local add_mod = { + ["function"] = true, + constructorfct = true, + staticfct = true, + deprecated = true, +} + +-- Add the arguments. +local add_args = { + constructorfct = true, + staticfct = true, +} + custom_display_name_handler = function(item, default_handler) + local ret = default_handler(item) + -- Remove the "namespace" from the signals and properties if no_prefix[item.type] then local name = item.name:match("%.([^.]+)$") @@ -201,15 +221,22 @@ custom_display_name_handler = function(item, default_handler) return coreclassmap[item.name] end + -- Undocumented API to make the libraries and classmod "function" section + -- more consistent. Right now some have their full awful.foo.bar while other + -- have "just" `bar`. Given we use constructors from metatables, we have no + -- choice but to use the full function name. It also makes copy/paste easier. + if add_mod[item.type] and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then + ret = item.module.name .. "." .. ret + end + if item.type == "deprecated" or item.type == "deprecatedproperty" then - return default_handler(item) .. " [deprecated]" + return ret .. " [deprecated]" end if item.type == "method" then return render_methods(item) end - local ret = default_handler(item) -- Get rid of the "module:" in front of method names. It is either wrong or -- just redundant. @@ -221,17 +248,8 @@ custom_display_name_handler = function(item, default_handler) return ret:gsub("^module", item.module.name) end - -- Undocumented API to make the libraries and classmod "function" section - -- more consistent. Right now some have their full awful.foo.bar while other - -- have "just" `bar`. Given we use constructors from metatables, we have no - -- choice but to use the full function name. It also makes copy/paste easier. - if (item.type == "function" or item.type == "constructorfct") - and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then - ret = item.module.name .. "." .. ret - end - -- It isn't there by default. - if item.type == "constructorfct" then + if add_args[item.type] then ret = ret .. " " .. item.args end diff --git a/lib/awful/client.lua b/lib/awful/client.lua index e45381de..c4ff1f00 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -239,7 +239,7 @@ end --- Get a client by its relative index to another client. -- If no client is passed, the focused client will be used. -- --- @function awful.client.next +-- @staticfct awful.client.next -- @tparam int i The index. Use 1 to get the next, -1 to get the previous. -- @client[opt] sel The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) @@ -274,7 +274,7 @@ function client.next(i, sel, stacked) end --- Swap a client with another client in the given direction. --- @function awful.client.swap.bydirection +-- @staticfct awful.client.swap.bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @client[opt=focused] c The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) @@ -295,8 +295,9 @@ function client.swap.bydirection(dir, c, stacked) end end ---- Swap a client with another client in the given direction. Swaps across screens. --- @function awful.client.swap.global_bydirection +--- Swap a client with another client in the given direction. +-- Swaps across screens. +-- @staticfct awful.client.swap.global_bydirection -- @param dir The direction, can be either "up", "down", "left" or "right". -- @client[opt] sel The client. function client.swap.global_bydirection(dir, sel) @@ -329,7 +330,7 @@ function client.swap.global_bydirection(dir, sel) end --- Swap a client by its relative index. --- @function awful.client.swap.byidx +-- @staticfct awful.client.swap.byidx -- @param i The index. -- @client[opt] c The client, otherwise focused one is used. function client.swap.byidx(i, c) @@ -342,7 +343,7 @@ end --- Cycle clients. -- --- @function awful.client.cycle +-- @staticfct awful.client.cycle -- @param clockwise True to cycle clients clockwise. -- @param[opt] s The screen where to cycle clients. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) @@ -886,7 +887,7 @@ end --- Restore (=unminimize) a random client. --- @function awful.client.restore +-- @staticfct awful.client.restore -- @param s The screen to use. -- @return The restored client if some client was restored, otherwise nil. function client.restore(s) @@ -907,7 +908,7 @@ function client.restore(s) return nil end ---- Normalize a set of numbers to 1 +--- Normalize a set of numbers to 1. -- @param set the set of numbers to normalize -- @param num the number of numbers to normalize local function normalize(set, num) @@ -1204,7 +1205,7 @@ end --- Set a client property to be persistent across restarts (via X properties). -- --- @function awful.client.property.persist +-- @staticfct awful.client.property.persist -- @param prop The property name. -- @param kind The type (used for register_xproperty). -- One of "string", "number" or "boolean". @@ -1221,16 +1222,17 @@ function client.property.persist(prop, kind) end end ---- --- Returns an iterator to cycle through, starting from the client in focus or --- the given index, all clients that match a given criteria. +--- Returns an iterator to cycle through clients. +-- +-- Starting from the client in focus or the given index, all clients that match +-- a given criteria. -- -- @param filter a function that returns true to indicate a positive match -- @param start what index to start iterating from. Defaults to using the -- index of the currently focused client. -- @param s which screen to use. nil means all screens. -- --- @function awful.client.iterate +-- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances -- local urxvt = function (c) -- return awful.rules.match(c, {class = "URxvt"}) @@ -1387,7 +1389,7 @@ do -- See `awful.client.focus.history.enable_tracking` to enable it again. -- @treturn int The internal value of `disabled_count` (calls to this -- function without calling `awful.client.focus.history.enable_tracking`). - -- @function awful.client.focus.history.disable_tracking + -- @staticfct awful.client.focus.history.disable_tracking function client.focus.history.disable_tracking() disabled_count = disabled_count + 1 if disabled_count == 1 then @@ -1401,7 +1403,7 @@ do -- This is the default, but can be disabled -- through `awful.client.focus.history.disable_tracking`. -- @treturn boolean True if history tracking has been enabled. - -- @function awful.client.focus.history.enable_tracking + -- @staticfct awful.client.focus.history.enable_tracking function client.focus.history.enable_tracking() assert(disabled_count > 0) disabled_count = disabled_count - 1 @@ -1414,7 +1416,7 @@ do --- Is history tracking enabled? -- @treturn bool True if history tracking is enabled. -- @treturn int The number of times that tracking has been disabled. - -- @function awful.client.focus.history.is_enabled + -- @staticfct awful.client.focus.history.is_enabled function client.focus.history.is_enabled() return disabled_count == 0, disabled_count end diff --git a/lib/awful/completion.lua b/lib/awful/completion.lua index 4fd14840..f374c909 100644 --- a/lib/awful/completion.lua +++ b/lib/awful/completion.lua @@ -32,6 +32,7 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion" --- Enable programmable bash completion in awful.completion.bash at the price of -- a slight overhead. -- @param 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 local c, err = io.popen("/usr/bin/env bash -c 'source " .. bashcomp_src .. "; complete -p'") @@ -70,6 +71,7 @@ completion.default_shell = nil -- @treturn string The new command. -- @treturn number The new cursor position. -- @treturn table The table with all matches. +-- @staticfct awful.completion.shell function completion.shell(command, cur_pos, ncomp, shell) local wstart = 1 local wend = 1 @@ -192,6 +194,7 @@ end -- @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. +-- @staticfct awful.completion.generic function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args -- The keywords table may be empty if #keywords == 0 then diff --git a/lib/awful/ewmh.lua b/lib/awful/ewmh.lua index 139e8e1a..d98f62ac 100644 --- a/lib/awful/ewmh.lua +++ b/lib/awful/ewmh.lua @@ -54,6 +54,7 @@ local ewmh = { --- Update a client's settings when its geometry changes, skipping signals -- resulting from calls within. local repair_geometry_lock = false + local function repair_geometry(window) if repair_geometry_lock then return end repair_geometry_lock = true @@ -166,6 +167,7 @@ end -- @see generic_activate_filters -- @see contextual_activate_filters -- @see remove_activate_filter +-- @staticfct awful.ewmh.add_activate_filter function ewmh.add_activate_filter(f, context) if not context then table.insert(ewmh.generic_activate_filters, f) @@ -185,6 +187,7 @@ end -- @see generic_activate_filters -- @see contextual_activate_filters -- @see add_activate_filter +-- @staticfct awful.ewmh.remove_activate_filter function ewmh.remove_activate_filter(f, context) local tab = context and (ewmh.contextual_activate_filters[context] or {}) or ewmh.generic_activate_filters diff --git a/lib/awful/hotkeys_popup/init.lua b/lib/awful/hotkeys_popup/init.lua index 182fe5ab..8aaa7544 100644 --- a/lib/awful/hotkeys_popup/init.lua +++ b/lib/awful/hotkeys_popup/init.lua @@ -24,7 +24,7 @@ local hotkeys_popup = { -- @tparam[opt] screen s The screen. -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. --- @function awful.hotkeys_popup.show_help +-- @staticfct awful.hotkeys_popup.show_help -- @see awful.hotkeys_popup.widget.show_help hotkeys_popup.show_help = hotkeys_popup.widget.show_help diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index a9278745..1068c16e 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -490,6 +490,7 @@ function widget.new(args) -- @tparam[opt] table show_args Additional arguments. -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. + -- @method show_help function widget_instance:show_help(c, s, show_args) show_args = show_args or {} local show_awesome_keys = show_args.show_awesome_keys ~= false @@ -549,6 +550,7 @@ function widget.new(args) --- Add hotkey descriptions for third-party applications. -- @tparam table hotkeys Table with bindings, -- see `awful.hotkeys_popup.key.vim` as an example. + -- @method add_hotkeys function widget_instance:add_hotkeys(hotkeys) for group, bindings in pairs(hotkeys) do for _, binding in ipairs(bindings) do @@ -571,6 +573,7 @@ function widget.new(args) -- @tparam string group hotkeys group name, -- @tparam table data rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. + -- @method add_group_rules function widget_instance:add_group_rules(group, data) self.group_rules[group] = data end @@ -591,6 +594,7 @@ end -- @tparam[opt] table args Additional arguments. -- @tparam[opt=true] boolean args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. +-- @staticfct awful.hotkeys_popup.widget.show_help function widget.show_help(...) return get_default_widget():show_help(...) end @@ -599,6 +603,7 @@ end -- (default widget instance will be used). -- @tparam table hotkeys Table with bindings, -- see `awful.hotkeys_popup.key.vim` as an example. +-- @staticfct awful.hotkeys_popup.widget.add_hotkeys function widget.add_hotkeys(...) return get_default_widget():add_hotkeys(...) end @@ -608,6 +613,7 @@ end -- @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) return get_default_widget():add_group_rules(group, data) end diff --git a/lib/awful/key.lua b/lib/awful/key.lua index ee4b5148..6e0a5691 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -3,7 +3,7 @@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou --- @module awful.key +-- @classmod awful.key --------------------------------------------------------------------------- -- Grab environment we need @@ -59,6 +59,7 @@ capi.awesome.connect_signal("xkb::map_changed" , function() conversion = nil en -- @tparam table mod A modified table. Valid modifiers are: Any, Mod1, -- Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control. -- @tparam string k The key +-- @staticfct awful.key.execute function key.execute(mod, k) local modmap = generate_conversion_map() local active = capi.awesome._active_modifiers @@ -111,6 +112,7 @@ end -- @tparam table data User data for key, -- for example {description="select next tag", group="tag"}. -- @treturn table A table with one or several key objects. +-- @constructorfct awful.key function key.new(mod, _key, press, release, data) if type(release)=='table' then data=release @@ -145,6 +147,7 @@ end -- @param _key The key object. -- @param pressed_mod The modifiers to compare with. -- @param pressed_key The key to compare with. +-- @staticfct awful.key.match function key.match(_key, pressed_mod, pressed_key) -- First, compare key. if pressed_key ~= _key.key then return false end diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index 65b7629c..4c94e66d 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -724,16 +724,6 @@ function keygrab.run_with_keybindings(args) return ret end ---- Run a grabbing function. --- --- Calling this is equivalent to `keygrabber.run`. --- --- @param g The key grabber callback that will get the key events until it --- will be deleted or a new grabber is added. --- @return the given callback `g`. --- --- @deprecated awful.keygrabber.run - --- A lower level API to interact with the keygrabber directly. -- -- Grab keyboard input and read pressed keys, calling the least callback @@ -750,7 +740,7 @@ end -- -- Here is the content of the modifier table: -- --- +--
-- -- -- @@ -785,7 +775,7 @@ end -- end -- end) -- end --- @function awful.keygrabber.run +-- @deprecated awful.keygrabber.run function keygrab.run(g) -- Remove the grabber if it is in the stack. keygrab.stop(g) @@ -807,7 +797,7 @@ end local signals = {} --- Connect to a signal for all keygrabbers at once. --- @function awful.keygrabber.connect_signal +-- @staticfct awful.keygrabber.connect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. function keygrab.connect_signal(name, callback) @@ -820,7 +810,7 @@ function keygrab.connect_signal(name, callback) end --- Disconnect to a signal for all keygrabbers at once. --- @function awful.keygrabber.disconnect_signal +-- @staticfct awful.keygrabber.disconnect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. function keygrab.disconnect_signal(name, callback) @@ -840,7 +830,7 @@ end -- `my_keygrabber:emit_signal(name, ...)`. This function works on the whole -- keygrabber module, not one of its instance. -- --- @function awful.keygrabber.emit_signal +-- @staticfct awful.keygrabber.emit_signal -- @tparam string name The signal name. -- @param ... Other arguments for the callbacks. function keygrab.emit_signal(name, ...) diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua index 6dcfaa41..29c6b885 100644 --- a/lib/awful/layout/init.lua +++ b/lib/awful/layout/init.lua @@ -73,7 +73,7 @@ layout.layouts = { -- awful.layout.suit.corner.sw, -- awful.layout.suit.corner.se, -- --- @field layout.layouts +-- @field awful.layout.layouts --- Return the tag layout index (from `awful.layout.layouts`). -- @@ -82,6 +82,7 @@ layout.layouts = { -- -- @tparam tag t The tag. -- @treturn nil|number The layout index. +-- @staticfct awful.layout.get_tag_layout_index function layout.get_tag_layout_index(t) return gtable.hasitem(layout.layouts, t.layout) end @@ -95,6 +96,7 @@ local delayed_arrange = {} --- Get the current layout. -- @param screen The screen. -- @return The layout function. +-- @staticfct awful.layout.get function layout.get(screen) screen = screen or capi.mouse.screen local t = get_screen(screen).selected_tag @@ -105,6 +107,7 @@ end -- @param i Relative index. -- @param s The screen. -- @param[opt] layouts A table of layouts. +-- @staticfct awful.layout.inc function layout.inc(i, s, layouts) if type(i) == "table" then -- Older versions of this function had arguments (layouts, i, s), but @@ -150,6 +153,7 @@ end --- Set the layout function of the current tag. -- @param _layout Layout name. -- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify. +-- @staticfct awful.layout.set function layout.set(_layout, t) t = t or capi.mouse.screen.selected_tag t.layout = _layout @@ -168,6 +172,7 @@ end -- @treturn table A table with the workarea (x, y, width, height), the screen -- geometry (x, y, width, height), the clients, the screen and sometime, a -- "geometries" table with client as keys and geometry as value +-- @staticfct awful.layout.parameters function layout.parameters(t, screen) screen = get_screen(screen) t = t or screen.selected_tag @@ -210,6 +215,7 @@ end --- Arrange a screen using its current layout. -- @param screen The screen to arrange. +-- @staticfct awful.layout.arrange function layout.arrange(screen) screen = get_screen(screen) if not screen or delayed_arrange[screen] then return end @@ -250,6 +256,7 @@ end --- Get the current layout name. -- @param _layout The layout. -- @return The layout name. +-- @staticfct awful.layout.getname function layout.getname(_layout) _layout = _layout or layout.get() return _layout.name @@ -318,6 +325,7 @@ capi.client.connect_signal("list", function() -- @tparam client c The client -- @tparam string context The context -- @tparam table hints Additional hints +-- @signalhandler awful.layout.move_handler function layout.move_handler(c, context, hints) --luacheck: no unused args -- Quit if it isn't a mouse.move on a tiled layout, that's handled elsewhere if c.floating then return end diff --git a/lib/awful/layout/suit/fair.lua b/lib/awful/layout/suit/fair.lua index 161b6edf..6930a09e 100644 --- a/lib/awful/layout/suit/fair.lua +++ b/lib/awful/layout/suit/fair.lua @@ -88,21 +88,30 @@ local function do_fair(p, orientation) end end ---- Horizontal fair layout. +-- Horizontal fair layout. -- @param screen The screen to arrange. fair.horizontal = {} fair.horizontal.name = "fairh" + function fair.horizontal.arrange(p) return do_fair(p, "east") end ---- Vertical fair layout. +-- Vertical fair layout. -- @param screen The screen to arrange. fair.name = "fairv" function fair.arrange(p) return do_fair(p, "south") end +--- The fair layout. +-- Try to give all clients the same size. +-- @clientlayout awful.layout.suit.fair + +--- The horizontal fair layout. +-- Try to give all clients the same size. +-- @clientlayout awful.layout.suit.fair.horizontal + return fair -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/awful/layout/suit/floating.lua b/lib/awful/layout/suit/floating.lua index b7694357..9c2e6ea4 100644 --- a/lib/awful/layout/suit/floating.lua +++ b/lib/awful/layout/suit/floating.lua @@ -22,6 +22,7 @@ local capi = local floating = {} --- Jump mouse cursor to the client's corner when resizing it. +-- @field awful.layout.suit.floating.resize_jump_to_corner floating.resize_jump_to_corner = true function floating.mouse_resize_handler(c, corner, x, y) @@ -103,7 +104,7 @@ function floating.arrange() end --- The floating layout. --- @clientlayout awful.layout.suit. +-- @clientlayout awful.layout.suit.floating floating.name = "floating" diff --git a/lib/awful/layout/suit/tile.lua b/lib/awful/layout/suit/tile.lua index 09e95d1c..335398fb 100644 --- a/lib/awful/layout/suit/tile.lua +++ b/lib/awful/layout/suit/tile.lua @@ -43,6 +43,7 @@ local tile = {} -- @see gears.surface --- Jump mouse cursor to the client's corner when resizing it. +-- @field awful.layout.suit.tile.resize_jump_to_corner tile.resize_jump_to_corner = true local function mouse_resize_handler(c, _, _, _, orientation) diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index 78d1e55b..cc1d29ac 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -5,7 +5,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @author dodo -- @copyright 2008, 2011 Damien Leone, Julien Danjou, dodo --- @module awful.menu +-- @popupmod awful.menu -------------------------------------------------------------------------------- local wibox = require("wibox") @@ -358,6 +358,7 @@ end --- Show a menu. -- @param args The arguments -- @param args.coords Menu position defaulting to mouse.coords() +-- @method show function menu:show(args) args = args or {} local coords = args.coords or nil @@ -371,6 +372,7 @@ function menu:show(args) end --- Hide a menu popup. +-- @method hide function menu:hide() -- Remove items from screen for i = 1, #self.items do @@ -389,6 +391,7 @@ end --- Toggle menu visibility. -- @param args The arguments -- @param args.coords Menu position {x,y} +-- @method toggle function menu:toggle(args) if self.wibox.visible then self:hide() @@ -397,7 +400,8 @@ function menu:toggle(args) end end ---- Update menu content +--- Update menu content. +-- @method update function menu:update() if self.wibox.visible then self:show({ coords = { x = self.x, y = self.y } }) @@ -407,6 +411,7 @@ end --- Get the elder parent so for example when you kill -- it, it will destroy the whole family. +-- @method get_root function menu:get_root() return self.parent and menu.get_root(self.parent) or self end @@ -417,6 +422,7 @@ end -- @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. +-- @method add function menu:add(args, index) if not args then return end local theme = load_theme(args.theme or {}, self.theme) @@ -470,8 +476,9 @@ function menu:add(args, index) return item 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 +--- 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. +-- @method delete function menu:delete(num) if type(num) == "table" then num = gtable.hasitem(self.items, num) @@ -511,6 +518,7 @@ end -- returning `true` or `false` to indicate whether the client should be -- included in the menu. -- @return The menu. +-- @constructorfct awful.menu.clients function menu.clients(args, item_args, filter) local cls_t = {} for c in client_iterate(filter or function() return true end) do @@ -553,6 +561,7 @@ local clients_menu = nil -- returning `true` or `false` to indicate whether the client should be -- included in the menu. -- @return The menu. +-- @constructorfct awful.menu.client_list function menu.client_list(args, item_args, filter) if clients_menu and clients_menu.wibox.visible then clients_menu:hide() @@ -565,10 +574,11 @@ end -------------------------------------------------------------------------------- ---- Default awful.menu.entry constructor +--- 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 +-- @constructorfct awful.menu.entry function menu.entry(parent, args) -- luacheck: no unused args args = args or {} args.text = args[1] or args.text or "" @@ -668,6 +678,7 @@ end -- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false. -- -- @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 -- -- a particular rule. -- -- Bound to a key, it can be used to select from dozens of terminals open on diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index 662daa06..b94d63eb 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -72,7 +72,7 @@ function mouse.client_under_pointer() end --- Move a client. --- @function awful.mouse.client.move +-- @staticfct awful.mouse.client.move -- @param c The client to move, or the focused one if nil. -- @param snap The pixel to snap clients. -- @param finished_cb Deprecated, do not use @@ -125,7 +125,7 @@ function mouse.client.dragtotag.border(c) end --- Move the wibox under the cursor. --- @function awful.mouse.wibox.move +-- @staticfct awful.mouse.wibox.move --@tparam wibox w The wibox to move, or none to use that under the pointer function mouse.wibox.move(w) w = w or mouse.current_wibox @@ -183,7 +183,7 @@ function mouse.client.corner(c, corner) end --- Resize a client. --- @function awful.mouse.client.resize +-- @staticfct awful.mouse.client.resize -- @param c The client to resize, or the focused one by default. -- @tparam string corner The corner to grab on resize. Auto detected by default. -- @tparam[opt={}] table args A set of `awful.placement` arguments @@ -417,7 +417,7 @@ end) -- @treturn integer table.y The vertical position -- @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true -- when button 1 is pressed. --- @function mouse.coords +-- @staticfct mouse.coords return mouse diff --git a/lib/awful/placement.lua b/lib/awful/placement.lua index 73f49360..e79c9ed2 100644 --- a/lib/awful/placement.lua +++ b/lib/awful/placement.lua @@ -811,7 +811,8 @@ end -- or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn table The new geometry --- @treturn string The corner name +-- @treturn string The corner name. +-- @staticfct awful.placement.closest_corner function placement.closest_corner(d, args) args = add_context(args, "closest_corner") d = d or capi.client.focus @@ -855,6 +856,7 @@ end -- @tparam[opt={}] table args The arguments -- @tparam[opt=client's screen] integer args.screen The screen. -- @treturn table The new client geometry. +-- @staticfct awful.placement.no_offscreen function placement.no_offscreen(c, args) --compatibility with the old API @@ -897,6 +899,7 @@ end -- @param c The client. -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.no_overlap function placement.no_overlap(c, args) c = c or capi.client.focus args = add_context(args, "no_overlap") @@ -969,6 +972,7 @@ end -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.under_mouse function placement.under_mouse(d, args) args = add_context(args, "under_mouse") d = d or capi.client.focus @@ -993,6 +997,7 @@ end -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.next_to_mouse function placement.next_to_mouse(d, args) if type(args) == "number" then gdebug.deprecate( @@ -1042,6 +1047,7 @@ end -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.resize_to_mouse function placement.resize_to_mouse(d, args) d = d or capi.client.focus args = add_context(args, "resize_to_mouse") @@ -1119,6 +1125,7 @@ end -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) -- @tparam[opt={}] table args Other arguments -- @treturn table The new geometry +-- @staticfct awful.placement.align function placement.align(d, args) args = add_context(args, "align") d = d or capi.client.focus @@ -1193,6 +1200,7 @@ end -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn table The new geometry +-- @staticfct awful.placement.stretch function placement.stretch(d, args) args = add_context(args, "stretch") @@ -1265,6 +1273,7 @@ end -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn table The new geometry +-- @staticfct awful.placement.maximize function placement.maximize(d, args) args = add_context(args, "maximize") d = d or capi.client.focus @@ -1318,6 +1327,7 @@ end -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn table The new geometry +-- @staticfct awful.placement.scale function placement.scale(d, args) args = add_context(args, "scale_to_percent") d = d or capi.client.focus @@ -1400,6 +1410,7 @@ end -- @treturn table The new geometry -- @treturn string The choosen position ("left", "right", "top" or "bottom") -- @treturn string The choosen anchor ("front", "middle" or "back") +-- @staticfct awful.placement.next_to function placement.next_to(d, args) args = add_context(args, "next_to") d = d or capi.client.focus @@ -1527,6 +1538,7 @@ end -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`) -- @tparam[opt={}] table args The arguments -- @treturn boolean If the geometry was restored +-- @staticfct awful.placement.restore function placement.restore(d, args) if not args or not args.context then return false end d = d or capi.client.focus diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index c9e97e8f..fd87a304 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -234,6 +234,7 @@ end -- @see awful.popup.preferred_positions -- @see awful.popup.preferred_anchors -- @treturn table The new geometry +-- @method move_next_to function popup:move_next_to(obj) if self._private.is_relative == false then return end @@ -256,6 +257,7 @@ end -- -- @tparam widget widget The widget -- @tparam[opt=1] number button The button index +-- @method bind_to_widget function popup:bind_to_widget(widget, button) if not self._private.button_for_widget then self._private.button_for_widget = {} @@ -267,6 +269,7 @@ end --- Unbind the popup from a widget button. -- @tparam widget widget The widget +-- @method unbind_to_widget function popup:unbind_to_widget(widget) widget:disconnect_signal("button::press", self._private.show_fct) end diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index fb49d69a..de25e8e2 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -454,6 +454,7 @@ end -- with mod table, key and command as arguments when a key was pressed. -- [**DEPRECATED**] -- @see gears.color +-- @staticfct awful.prompt.run function prompt.run(args, textbox, exe_callback, completion_callback, history_path, history_max, done_callback, changed_callback, keypressed_callback) diff --git a/lib/awful/rules.lua b/lib/awful/rules.lua index 9aa9db7d..4b1e86bb 100644 --- a/lib/awful/rules.lua +++ b/lib/awful/rules.lua @@ -134,6 +134,7 @@ local crules = gmatcher() -- @client c The client. -- @tab rule The rule to check. -- @treturn bool True if it matches, false otherwise. +-- @staticfct awful.rules.match function rules.match(c, rule) return crules:_match(c, rule) end @@ -142,6 +143,7 @@ end -- @client c The client. -- @tab rule The rule to check. -- @treturn bool True if at least one rule is matched, false otherwise. +-- @staticfct awful.rules.match_any function rules.match_any(c, rule) return crules:_match_any(c, rule) end @@ -151,6 +153,7 @@ end -- @tab entry Rule entry (with keys `rule`, `rule_any`, `except` and/or -- `except_any`). -- @treturn bool +-- @staticfct awful.rules.matches function rules.matches(c, entry) return crules:matches_rule(c, entry) end @@ -160,6 +163,7 @@ end -- @tab _rules The rules to check. List with "rule", "rule_any", "except" and -- "except_any" keys. -- @treturn table The list of matched rules. +-- @staticfct awful.rules.matching_rules function rules.matching_rules(c, _rules) return crules:matching_rules(c, _rules) end @@ -169,13 +173,15 @@ end -- @tab _rules The rules to check. List of tables with `rule`, `rule_any`, -- `except` and `except_any` keys. -- @treturn bool True if at least one rule is matched, false otherwise. +-- @staticfct awful.rules.matches_list function rules.matches_list(c, _rules) return crules:matches_rules(c, _rules) end --- Remove a source. -- @tparam string name The source name. --- @treturn boolean If the source was removed, +-- @treturn boolean If the source was removed. +-- @staticfct awful.rules.remove_rule_source function rules.remove_rule_source(name) return crules:remove_matching_source(name) end @@ -183,6 +189,7 @@ end --- Apply awful.rules.rules to a client. -- @client c The client. +-- @staticfct awful.rules.apply function rules.apply(c) return crules:apply(c) end @@ -226,7 +233,7 @@ end -- @tparam[opt={}] table precede A list of names of sources this source have a -- priority over. -- @treturn boolean Returns false if a dependency conflict was found. --- @function awful.rules.add_rule_source +-- @staticfct awful.rules.add_rule_source function rules.add_rule_source(name, cb, ...) local function callback(_, ...) @@ -519,7 +526,7 @@ end -- @client c The client. -- @tab props Properties to apply. -- @tab[opt] callbacks Callbacks to apply. --- @function awful.rules.execute +-- @staticfct awful.rules.execute crules._execute = function(_, c, props, callbacks) -- This has to be done first, as it will impact geometry related props. diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index ae0a5f84..b9043f97 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -69,7 +69,7 @@ end -- -- The number returned can be used as an index into the global -- `screen` table/object. --- @function awful.screen.getbycoord +-- @staticfct awful.screen.getbycoord -- @tparam number x The x coordinate -- @tparam number y The y coordinate -- @treturn ?number The screen index @@ -86,7 +86,7 @@ end -- -- This moves the mouse pointer to the last known position on the new screen, -- or keeps its position relative to the current focused screen. --- @function awful.screen.focus +-- @staticfct awful.screen.focus -- @screen _screen Screen number (defaults / falls back to mouse.screen). function screen.focus(_screen) client = client or require("awful.client") @@ -149,7 +149,7 @@ end -- -- This moves the mouse pointer to the last known position on the new screen, -- or keeps its position relative to the current focused screen. --- @function awful.screen.focus_bydirection +-- @staticfct awful.screen.focus_bydirection -- @param dir The direction, can be either "up", "down", "left" or "right". -- @param _screen Screen. function screen.focus_bydirection(dir, _screen) @@ -166,7 +166,7 @@ end -- This moves the mouse pointer to the last known position on the new screen, -- or keeps its position relative to the current focused screen. -- --- @function awful.screen.focus_relative +-- @staticfct awful.screen.focus_relative -- @tparam int offset Value to add to the current focused screen index. 1 to -- focus the next one, -1 to focus the previous one. function screen.focus_relative(offset) @@ -242,6 +242,7 @@ end -- focused screen by default. -- @tparam client c A client. -- @treturn screen The preferred screen. +-- @staticfct awful.screen.preferred function screen.preferred(c) return capi.awesome.startup and c.screen or screen.focused() end @@ -254,7 +255,7 @@ end -- It is possible to set `awful.screen.default_focused_args` to override the -- default settings. -- --- @function awful.screen.focused +-- @staticfct awful.screen.focused -- @tparam[opt] table args -- @tparam[opt=false] boolean args.client Use the client screen instead of the -- mouse screen. @@ -272,7 +273,7 @@ end -- -- This method computes the different variants of the "usable" screen geometry. -- --- @function screen.get_bounding_geometry +-- @staticfct 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. @@ -341,7 +342,7 @@ end -- -- This is used by `screen.clients` internally (with `stacked=true`). -- --- @function screen:get_clients +-- @method get_clients -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom) -- @treturn table The clients list. function screen.object.get_clients(s, stacked) @@ -430,7 +431,7 @@ end --- Call a function for each existing and created-in-the-future screen. -- --- @function awful.screen.connect_for_each_screen +-- @staticfct awful.screen.connect_for_each_screen -- @tparam function func The function to call. -- @screen func.screen The screen. function screen.connect_for_each_screen(func) @@ -441,7 +442,7 @@ function screen.connect_for_each_screen(func) end --- Undo the effect of connect_for_each_screen. --- @function awful.screen.disconnect_for_each_screen +-- @staticfct awful.screen.disconnect_for_each_screen -- @tparam function func The function that should no longer be called. function screen.disconnect_for_each_screen(func) capi.screen.disconnect_signal("added", func) @@ -525,6 +526,7 @@ end -- defaulting to 96. -- -- @tparam boolean enabled Enable or disable automatic DPI support. +-- @staticfct awful.screen.set_auto_dpi_enabled function screen.set_auto_dpi_enabled(enabled) for s in capi.screen do s.data.dpi_cache = nil diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua index 3ff8449b..8b54b4d8 100644 --- a/lib/awful/spawn.lua +++ b/lib/awful/spawn.lua @@ -344,6 +344,7 @@ end -- @treturn[1] ?string The startup notification ID, if `sn` is not false, or -- a `callback` is provided. -- @treturn[2] string Error message. +-- @staticfct awful.spawn function spawn.spawn(cmd, sn_rules, callback) if cmd and cmd ~= "" then local enable_sn = (sn_rules ~= false or callback) @@ -363,6 +364,7 @@ end --- Spawn a program using the shell. -- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`). -- @tparam string cmd The command. +-- @staticfct awful.spawn.with_shell function spawn.with_shell(cmd) if cmd and cmd ~= "" then cmd = { util.shell, "-c", cmd } @@ -389,6 +391,7 @@ end -- termination. -- @treturn[1] Integer the PID of the forked process. -- @treturn[2] string Error message. +-- @staticfct awful.spawn.with_line_callback function spawn.with_line_callback(cmd, callbacks) local stdout_callback, stderr_callback, done_callback, exit_callback = callbacks.stdout, callbacks.stderr, callbacks.output_done, callbacks.exit @@ -434,6 +437,7 @@ end -- @treturn[1] Integer the PID of the forked process. -- @treturn[2] string Error message. -- @see spawn.with_line_callback +-- @staticfct awful.spawn.easy_async function spawn.easy_async(cmd, callback) local stdout = '' local stderr = '' @@ -484,6 +488,7 @@ end -- @treturn[1] Integer the PID of the forked process. -- @treturn[2] string Error message. -- @see spawn.with_line_callback +-- @staticfct awful.spawn.easy_async_with_shell function spawn.easy_async_with_shell(cmd, callback) return spawn.easy_async({ util.shell, "-c", cmd or "" }, callback) end @@ -495,6 +500,7 @@ end -- @tparam[opt] function done_callback Function that is called when the -- operation finishes (e.g. due to end of file). -- @tparam[opt=false] boolean close Should the stream be closed after end-of-file? +-- @staticfct awful.spawn.read_lines function spawn.read_lines(input_stream, line_callback, done_callback, close) local stream = Gio.DataInputStream.new(input_stream) local function done() @@ -644,6 +650,7 @@ end -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. -- @see awful.rules +-- @staticfct awful.spawn.once function spawn.once(cmd, rules, matcher, unique_id, callback) local hash = unique_id or hash_command(cmd, rules) local status = register_common(hash, rules, matcher, callback) @@ -676,6 +683,7 @@ end -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. -- @see awful.rules +-- @staticfct awful.spawn.single_instance function spawn.single_instance(cmd, rules, matcher, unique_id, callback) local hash = unique_id or hash_command(cmd, rules) register_common(hash, rules, matcher, callback) @@ -703,6 +711,7 @@ local raise_rules = {focus = true, switch_to_tags = true, raise = true} -- @tparam[opt] function callback A callback function when the client is created. -- @see awful.rules -- @treturn client The client if it already exists. +-- @staticfct awful.spawn.raise_or_spawn function spawn.raise_or_spawn(cmd, rules, matcher, unique_id, callback) local hash = unique_id or hash_command(cmd, rules) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 9066f5d3..de66251b 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -296,7 +296,7 @@ function tag.add(name, props) end --- Create a set of tags and attach it to a screen. --- @function awful.tag.new +-- @staticfct awful.tag.new -- @param names The tag name, in a table -- @param screen The tag screen, or 1 if not set. -- @param layout The layout or layout table to set for this tags by default. @@ -322,7 +322,7 @@ function tag.new(names, screen, layout) end --- Find a suitable fallback tag. --- @function awful.tag.find_fallback +-- @staticfct awful.tag.find_fallback -- @param screen The screen to look for a tag on. [awful.screen.focused()] -- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)] function tag.find_fallback(screen, invalids) @@ -340,7 +340,7 @@ end -- -- mouse.screen.selected_tag:delete() -- --- @function tag.delete +-- @method delete -- @see awful.tag.add -- @see awful.tag.find_fallback -- @tparam[opt=awful.tag.find_fallback()] tag fallback_tag Tag to assign @@ -429,7 +429,7 @@ function tag.delete(target_tag, fallback_tag) end --- Update the tag history. --- @function awful.tag.history.update +-- @staticfct awful.tag.history.update -- @param obj Screen object. function tag.history.update(obj) local s = get_screen(obj) @@ -470,7 +470,7 @@ function tag.history.update(obj) end --- Revert tag history. --- @function awful.tag.history.restore +-- @staticfct awful.tag.history.restore -- @param screen The screen. -- @param idx Index in history. Defaults to "previous" which is a special index -- toggling between last two selected sets of tags. Number (eg 1) will go back @@ -522,6 +522,7 @@ end -- @tparam screen s The screen of the tag -- @tparam string name The name of the tag -- @return The tag found, or `nil` +-- @staticfct awful.tag.find_by_name -- @usage -- For the current screen -- local t = awful.tag.find_by_name(awful.screen.focused(), "name") -- @@ -696,7 +697,7 @@ function tag.setmwfact(mwfact, t) end --- Increase master width factor. --- @function awful.tag.incmwfact +-- @staticfct awful.tag.incmwfact -- @see master_width_factor -- @param add Value to add to master width factor. -- @param t The tag to modify, if null tag.selected() is used. @@ -972,7 +973,7 @@ function tag.setgap(useless_gap, t) end --- Increase the spacing between clients --- @function awful.tag.incgap +-- @staticfct awful.tag.incgap -- @see gap -- @param add Value to add to the spacing between clients -- @param t The tag to modify, if null tag.selected() is used. @@ -1079,7 +1080,7 @@ end --- Toggle size fill policy for the master client(s) -- between "expand" and "master_width_factor". --- @function awful.tag.togglemfpol +-- @staticfct awful.tag.togglemfpol -- @see master_fill_policy -- @tparam tag t The tag to modify, if null tag.selected() is used. function tag.togglemfpol(t) @@ -1160,7 +1161,7 @@ function tag.getnmaster(t) end --- Increase the number of master windows. --- @function awful.tag.incnmaster +-- @staticfct awful.tag.incnmaster -- @see master_count -- @param add Value to add to number of master windows. -- @param[opt] t The tag to modify, if null tag.selected() is used. @@ -1278,7 +1279,7 @@ function tag.getncol(t) end --- Increase number of column windows. --- @function awful.tag.incncol +-- @staticfct awful.tag.incncol -- @param add Value to add to number of column windows. -- @param[opt] t The tag to modify, if null tag.selected() is used. -- @tparam[opt=false] boolean sensible Limit column_count based on the number @@ -1309,7 +1310,7 @@ function tag.incncol(add, t, sensible) end --- View no tag. --- @function awful.tag.viewnone +-- @staticfct awful.tag.viewnone -- @tparam[opt] int|screen screen The screen. function tag.viewnone(screen) screen = screen or ascreen.focused() @@ -1322,7 +1323,7 @@ end --- View a tag by its taglist index. -- -- This is equivalent to `screen.tags[i]:view_only()` --- @function awful.tag.viewidx +-- @staticfct awful.tag.viewidx -- @see screen.tags -- @param i The **relative** index to see. -- @param[opt] screen The screen. @@ -1357,14 +1358,14 @@ function tag.getidx(query_tag) end --- View next tag. This is the same as tag.viewidx(1). --- @function awful.tag.viewnext +-- @staticfct awful.tag.viewnext -- @param screen The screen. function tag.viewnext(screen) return tag.viewidx(1, screen) end --- View previous tag. This is the same a tag.viewidx(-1). --- @function awful.tag.viewprev +-- @staticfct awful.tag.viewprev -- @param screen The screen. function tag.viewprev(screen) return tag.viewidx(-1, screen) @@ -1404,7 +1405,7 @@ end -- selected. The tags already selected do not count. To do nothing if one or -- more of the tags are already selected, set `maximum` to zero. -- --- @function awful.tag.viewmore +-- @staticfct awful.tag.viewmore -- @param tags A table with tags to view only. -- @param[opt] screen The screen of the tags. -- @tparam[opt=#tags] number maximum The maximum number of tags to select. @@ -1437,7 +1438,7 @@ function tag.viewmore(tags, screen, maximum) end --- Toggle selection of a tag --- @function awful.tag.viewtoggle +-- @staticfct awful.tag.viewtoggle -- @see selected -- @tparam tag t Tag to be toggled function tag.viewtoggle(t) @@ -1530,7 +1531,7 @@ end --- Add a signal to all attached tags and all tags that will be attached in the -- future. When a tag is detached from the screen, its signal is removed. -- --- @function awful.tag.attached_connect_signal +-- @staticfct awful.tag.attached_connect_signal -- @screen screen The screen concerned, or all if nil. -- @tparam[opt] string signal The signal name. -- @tparam[opt] function Callback diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 85d31814..60e602c0 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -431,8 +431,7 @@ local titlebar = { --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @param args An array containing the widgets disposition --- @name setup --- @class function +-- @method setup local all_titlebars = setmetatable({}, { __mode = 'k' }) @@ -564,6 +563,7 @@ end -- @param c The client whose titlebar is modified -- @param[opt] position The position of the titlebar. Must be one of "left", -- "right", "top", "bottom". Default is "top". +-- @staticfct awful.titlebar.show function titlebar.show(c, position) position = position or "top" if load_titlebars(c, true, position) then return end @@ -577,6 +577,7 @@ end -- @param c The client whose titlebar is modified -- @param[opt] position The position of the titlebar. Must be one of "left", -- "right", "top", "bottom". Default is "top". +-- @staticfct awful.titlebar.hide function titlebar.hide(c, position) position = position or "top" get_titlebar_function(c, position)(c, 0) @@ -586,6 +587,7 @@ end -- @param c The client whose titlebar is modified -- @param[opt] position The position of the titlebar. Must be one of "left", -- "right", "top", "bottom". Default is "top". +-- @staticfct awful.titlebar.toggle function titlebar.toggle(c, position) position = position or "top" if load_titlebars(c, true, position) then return end @@ -602,6 +604,7 @@ end -- This way, you can e.g. modify the font that is used. -- @param c The client for which a titlewidget should be created. -- @return The title widget. +-- @staticfct awful.titlebar.widget.titlewidget function titlebar.widget.titlewidget(c) local ret = textbox() local function update() @@ -618,6 +621,7 @@ end -- available. This way, you can e.g. disallow resizes. -- @param c The client for which an icon widget should be created. -- @return The icon widget. +-- @staticfct awful.titlebar.widget.iconwidget function titlebar.widget.iconwidget(c) return clienticon(c) end @@ -635,6 +639,7 @@ end -- @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 +-- @staticfct awful.titlebar.widget.button function titlebar.widget.button(c, name, selector, action) local ret = imagebox() @@ -718,6 +723,7 @@ end --- Create a new float button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.floatingbutton function titlebar.widget.floatingbutton(c) local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle) c:connect_signal("property::floating", widget.update) @@ -726,6 +732,7 @@ end --- Create a new maximize button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.maximizedbutton function titlebar.widget.maximizedbutton(c) local widget = titlebar.widget.button(c, "maximized", function(cl) return cl.maximized @@ -738,6 +745,7 @@ end --- Create a new minimize button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.minimizebutton function titlebar.widget.minimizebutton(c) local widget = titlebar.widget.button(c, "minimize", function() return "" end, @@ -748,12 +756,14 @@ end --- Create a new closing button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.closebutton 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. +-- @staticfct awful.titlebar.widget.ontopbutton function titlebar.widget.ontopbutton(c) local widget = titlebar.widget.button(c, "ontop", function(cl) return cl.ontop end, @@ -764,6 +774,7 @@ end --- Create a new sticky button for a client. -- @param c The client for which the button is wanted. +-- @staticfct awful.titlebar.widget.stickybutton 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 0420eb72..930010ad 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -276,20 +276,13 @@ function tooltip:set_align(value) end --- The shape of the tooltip window. --- If the shape require some parameters, use `set_shape`. -- -- @DOC_awful_tooltip_shape_EXAMPLE@ -- -- @property shape -- @see gears.shape --- @see set_shape -- @see beautiful.tooltip_shape ---- Set the tooltip shape. --- All other arguments will be passed to the shape function. --- @tparam gears.shape s The shape --- @see shape --- @see gears.shape function tooltip:set_shape(s) self.backgroundbox:set_shape(s) end @@ -520,7 +513,7 @@ end -- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. --- @function add_to_object +-- @method add_to_object function tooltip:add_to_object(obj) if not obj then return end @@ -533,7 +526,7 @@ end -- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. --- @function remove_from_object +-- @method remove_from_object function tooltip:remove_from_object(obj) obj:disconnect_signal("mouse::enter", self.show) obj:disconnect_signal("mouse::leave", self.hide) diff --git a/lib/awful/util.lua b/lib/awful/util.lua index 66be0871..d0a14d1f 100644 --- a/lib/awful/util.lua +++ b/lib/awful/util.lua @@ -99,6 +99,7 @@ end --- Eval Lua code. -- @return The return value of Lua code. +-- @staticfct awful.util.eval function util.eval(s) return assert(load(s))() end @@ -129,6 +130,7 @@ end -- @param path The file path. -- @return A function if everything is alright, a string with the error -- otherwise. +-- @staticfct awful.util.checkfile function util.checkfile(path) local f, e = loadfile(path) -- Return function if function, otherwise return error. @@ -140,6 +142,7 @@ end -- It checks if the configuration file is valid, and then restart if it's ok. -- If it's not ok, the error will be returned. -- @return Never return if awesome restart, or return a string error. +-- @staticfct awful.util.restart function util.restart() local c = util.checkfile(capi.awesome.conffile) @@ -225,6 +228,7 @@ end -- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' } -- @tparam[opt] string size The size. If this is specified, subdirectories `x` -- of the dirs are searched first. +-- @staticfct awful.util.geticonpath function util.geticonpath(iconname, exts, dirs, size) exts = exts or { 'png', 'gif' } dirs = dirs or { '/usr/share/pixmaps/', '/usr/share/icons/hicolor/' } diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index 84846be7..b29d6d84 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -217,11 +217,6 @@ local function set_position(wb, position, skip_reattach) end end ---- Stretch the wibar. --- --- @property stretch --- @param[opt=true] boolean - local function get_stretch(w) return w._stretch end @@ -233,7 +228,8 @@ local function set_stretch(w, value) end --- Remove a wibar. --- @function remove +-- @method remove + local function remove(self) self.visible = false diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 56621876..f7e480f0 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -203,6 +203,7 @@ end -- @tparam string position Two-character position of the calendar in the screen -- @tparam screen screen Screen where to display the calendar -- @treturn wibox The wibox calendar +-- @method call_calendar function calendar_popup:call_calendar(offset, position, screen) local inc_offset = offset or 0 local pos = position or self.position @@ -230,7 +231,8 @@ function calendar_popup:call_calendar(offset, position, screen) return self end ---- Toggle calendar visibility +--- Toggle calendar visibility. +-- @method toggle function calendar_popup:toggle() self:call_calendar(0) self.visible = not self.visible @@ -247,6 +249,7 @@ end -- @tparam[opt={}] table args Additional options -- @tparam[opt=true] bool args.on_hover Show popup during mouse hover -- @treturn wibox The wibox calendar +-- @method attach function calendar_popup:attach(widget, position, args) position = position or "tr" args = args or {} diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index 3c15799c..a87b556a 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -135,6 +135,7 @@ end -- xkb_symbols pattern "vendor/file(section):group_idx". -- @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) if group_names == nil then return nil diff --git a/lib/beautiful/gtk.lua b/lib/beautiful/gtk.lua index 13a8023b..1ff79383 100644 --- a/lib/beautiful/gtk.lua +++ b/lib/beautiful/gtk.lua @@ -63,54 +63,6 @@ local function read_gtk_color_properties_from_widget(gtk_widget, properties) return result end - --- luacheck: max comment line length 300 - ---- Get GTK+3 theme variables from GtkStyleContext --- @treturn table Key-value table with the following structure: ---
Modifier name Key name
--- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
Result key StyleContext key StyleContext fallback #1 StyleContext fallback #2 GTK Widget fallback
`font_size` Label font-size
`font_family` Label font-family
`bg_color` `theme_bg_color` Window bg
`fg_color` `theme_fg_color` Window fg
`base_color` `theme_base_color` Entry bg
`text_color` `theme_text_color` Entry fg
`button_bg_color` `theme_button_bg_color` `theme_bg_color` Button bg
`button_fg_color` `theme_button_fg_color` `theme_fg_color` Button fg
`button_border_color` Button border-color
`button_border_radius` Button border-radius
`button_border_width` Button border-top-width
`selected_bg_color` `theme_selected_bg_color` ToggleButton bg
`selected_fg_color` `theme_selected_fg_color` ToggleButton fg
`menubar_bg_color` `menubar_bg_color` `theme_bg_color` HeaderBar bg
`menubar_fg_color` `menubar_fg_color` `theme_fg_color` HeaderBar fg
`header_button_bg_color` `header_button_bg_color` `menubar_bg_color` `theme_bg_color` HeaderBar > Button bg
`header_button_fg_color` `header_button_fg_color` `menubar_fg_color` `theme_fg_color` HeaderBar > Button fg
`header_button_border_color` HeaderBar > Button border-color
`error_color` `error_color` `error_bg_color` destructive Button bg
`error_bg_color` `error_bg_color` `error_color` destructive Button bg
`error_fg_color` `error_fg_color` `theme_selected_fg_color` destructive Button fg
`warning_color` `warning_color` `warning_bg_color`
`warning_bg_color` `warning_bg_color` `warning_color`
`warning_fg_color` `warning_fg_color` `theme_selected_fg_color`
`success_color` `success_color` `success_bg_color`
`success_bg_color` `success_bg_color` `success_color`
`success_fg_color` `success_fg_color` `theme_selected_fg_color`
`tooltip_bg_color` `theme_tooltip_bg_color` `theme_bg_color`
`tooltip_fg_color` `theme_tooltip_fg_color` `theme_fg_color`
`osd_bg_color` `osd_bg` `theme_tooltip_bg_color` `theme_bg_color`
`osd_fg_color` `osd_fg` `theme_tooltip_fg_color` `theme_fg_color`
`osd_border_color` `osd_borders_color` `osd_fg_color`
`wm_bg_color` `wm_bg` `menubar_bg_color` `theme_bg_color` HeaderBar bg
`wm_border_focused_color` `wm_border_focused` `theme_selected_bg_color` ToggleButton bg
`wm_border_unfocused_color` `wm_border_unfocused` `wm_border` `menubar_bg_color` HeaderBar bg
`wm_title_focused_color` `wm_title_focused` `wm_title` `theme_selected_fg_color` ToggleButton fg
`wm_title_unfocused_color` `wm_title_unfocused` `wm_unfocused_title` `menubar_fg_color` HeaderBar fg
`wm_icons_focused_color` `wm_icons_focused` `wm_title_focused` `theme_selected_fg_color` ToggleButton fg
`wm_icons_unfocused_color` `wm_icons_unfocused` `wm_title_unfocused` `menubar_fg_color` HeaderBar fg
--- function gtk.get_theme_variables() if gtk.cached_theme_variables then return gtk.cached_theme_variables diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index f87aafd9..5ab2d582 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -37,6 +37,56 @@ local descs = setmetatable({}, { __mode = 'k' }) local fonts = setmetatable({}, { __mode = 'v' }) local active_font + +-- luacheck: max comment line length 300 + +--- Get GTK+3 theme variables from GtkStyleContext +-- @treturn table Key-value table with the following structure: +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +--
Result key StyleContext key StyleContext fallback #1 StyleContext fallback #2 GTK Widget fallback
`font_size` Label font-size
`font_family` Label font-family
`bg_color` `theme_bg_color` Window bg
`fg_color` `theme_fg_color` Window fg
`base_color` `theme_base_color` Entry bg
`text_color` `theme_text_color` Entry fg
`button_bg_color` `theme_button_bg_color` `theme_bg_color` Button bg
`button_fg_color` `theme_button_fg_color` `theme_fg_color` Button fg
`button_border_color` Button border-color
`button_border_radius` Button border-radius
`button_border_width` Button border-top-width
`selected_bg_color` `theme_selected_bg_color` ToggleButton bg
`selected_fg_color` `theme_selected_fg_color` ToggleButton fg
`menubar_bg_color` `menubar_bg_color` `theme_bg_color` HeaderBar bg
`menubar_fg_color` `menubar_fg_color` `theme_fg_color` HeaderBar fg
`header_button_bg_color` `header_button_bg_color` `menubar_bg_color` `theme_bg_color` HeaderBar > Button bg
`header_button_fg_color` `header_button_fg_color` `menubar_fg_color` `theme_fg_color` HeaderBar > Button fg
`header_button_border_color` HeaderBar > Button border-color
`error_color` `error_color` `error_bg_color` destructive Button bg
`error_bg_color` `error_bg_color` `error_color` destructive Button bg
`error_fg_color` `error_fg_color` `theme_selected_fg_color` destructive Button fg
`warning_color` `warning_color` `warning_bg_color`
`warning_bg_color` `warning_bg_color` `warning_color`
`warning_fg_color` `warning_fg_color` `theme_selected_fg_color`
`success_color` `success_color` `success_bg_color`
`success_bg_color` `success_bg_color` `success_color`
`success_fg_color` `success_fg_color` `theme_selected_fg_color`
`tooltip_bg_color` `theme_tooltip_bg_color` `theme_bg_color`
`tooltip_fg_color` `theme_tooltip_fg_color` `theme_fg_color`
`osd_bg_color` `osd_bg` `theme_tooltip_bg_color` `theme_bg_color`
`osd_fg_color` `osd_fg` `theme_tooltip_fg_color` `theme_fg_color`
`osd_border_color` `osd_borders_color` `osd_fg_color`
`wm_bg_color` `wm_bg` `menubar_bg_color` `theme_bg_color` HeaderBar bg
`wm_border_focused_color` `wm_border_focused` `theme_selected_bg_color` ToggleButton bg
`wm_border_unfocused_color` `wm_border_unfocused` `wm_border` `menubar_bg_color` HeaderBar bg
`wm_title_focused_color` `wm_title_focused` `wm_title` `theme_selected_fg_color` ToggleButton fg
`wm_title_unfocused_color` `wm_title_unfocused` `wm_unfocused_title` `menubar_fg_color` HeaderBar fg
`wm_icons_focused_color` `wm_icons_focused` `wm_title_focused` `theme_selected_fg_color` ToggleButton fg
`wm_icons_unfocused_color` `wm_icons_unfocused` `wm_title_unfocused` `menubar_fg_color` HeaderBar fg
+-- +-- @staticfct beautiful.gtk.get_theme_variables + --- The default font. -- @beautiful beautiful.font @@ -155,6 +205,7 @@ end -- See https://developer.gnome.org/pango/stable/pango-Fonts.html#PangoFontDescription. -- @tparam string|lgi.Pango.FontDescription name The name of the font. -- @treturn lgi.Pango.FontDescription +-- @staticfct beautiful.get_font function beautiful.get_font(name) return load_font(name).description end @@ -165,6 +216,7 @@ end -- @tparam string|Pango.FontDescription name The base font. -- @tparam string merge Attributes that should be merged, e.g. "bold". -- @treturn lgi.Pango.FontDescription +-- @staticfct beautiful.get_merged_font function beautiful.get_merged_font(name, merge) local font = beautiful.get_font(name) merge = Pango.FontDescription.from_string(merge) @@ -175,7 +227,8 @@ end --- Get the height of a font. -- --- @param name Name of the font +-- @param name Name of the font. +-- @staticfct beautiful.get_font_height function beautiful.get_font_height(name) return load_font(name).height end @@ -208,6 +261,7 @@ end -- the theme file (which should return a table) or directly a table -- containing all the theme values. -- @treturn true|nil True if successful, nil in case of error. +-- @staticfct beautiful.init function beautiful.init(config) if config then local state, t_theme = nil, nil @@ -258,6 +312,7 @@ end --- Get the current theme. -- -- @treturn table The current theme table. +-- @staticfct beautiful.get function beautiful.get() return theme end diff --git a/lib/beautiful/theme_assets.lua b/lib/beautiful/theme_assets.lua index b7f6e780..555a963f 100644 --- a/lib/beautiful/theme_assets.lua +++ b/lib/beautiful/theme_assets.lua @@ -3,7 +3,7 @@ -- -- @author Yauhen Kirylau <yawghen@gmail.com> -- @copyright 2015 Yauhen Kirylau --- @submodule beautiful +-- @module beautiful ---------------------------------------------------------------------------- local cairo = require("lgi").cairo @@ -19,6 +19,7 @@ local theme_assets = {} -- @tparam number size Size. -- @tparam color fg Background color. -- @return Image with the square. +-- @staticfct beautiful.theme_assets.taglist_squares_sel function theme_assets.taglist_squares_sel(size, fg) local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size) local cr = cairo.Context(img) @@ -31,6 +32,7 @@ end -- @tparam number size Size. -- @tparam color fg Background color. -- @return Image with the square. +-- @staticfct beautiful.theme_assets.taglist_squares_unsel function theme_assets.taglist_squares_unsel(size, fg) local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size) local cr = cairo.Context(img) @@ -84,6 +86,7 @@ end -- @tparam color bg Background color. -- @tparam color fg Main foreground color. -- @tparam color alt_fg Accent foreground color. +-- @staticfct beautiful.theme_assets.gen_awesome_name function theme_assets.gen_awesome_name(cr, height, bg, fg, alt_fg) local ls = height/10 -- letter_size local letter_line = ls/18 @@ -152,6 +155,7 @@ end -- @tparam number height Height. -- @tparam color bg Background color. -- @tparam color fg Foreground color. +-- @staticfct beautiful.theme_assets.gen_logo function theme_assets.gen_logo(cr, width, height, bg, fg) local ls = math.min(width, height) @@ -174,6 +178,7 @@ end -- @tparam color bg Background color. -- @tparam color fg Background color. -- @return Image with the logo. +-- @staticfct beautiful.theme_assets.awesome_icon function theme_assets.awesome_icon(size, bg, fg) local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size) local cr = cairo.Context(img) @@ -187,6 +192,7 @@ end -- @tparam color alt_fg Accent foreground color. -- @tparam screen s Screen (to get wallpaper size). -- @return Wallpaper image. +-- @staticfct beautiful.theme_assets.wallpaper function theme_assets.wallpaper(bg, fg, alt_fg, s) s = s or screen.primary local height = s.geometry.height @@ -215,6 +221,7 @@ end -- @tparam string postfix `nil`, `"hover"` or `"press"`. -- @tparam string toggle_state `nil`, `"active"` or `"inactive"`. -- @treturn table Beautiful theme table with the images recolored. +-- @staticfct beautiful.theme_assets.recolor_titlebar function theme_assets.recolor_titlebar(theme, color, state, postfix, toggle_state) if postfix then postfix='_'..postfix end if toggle_state then toggle_state='_'..toggle_state end @@ -266,6 +273,7 @@ end -- @tparam table theme Beautiful theme table -- @tparam color color Icons' color. -- @treturn table Beautiful theme table with the images recolored. +-- @staticfct beautiful.theme_assets.recolor_layout function theme_assets.recolor_layout(theme, color) for _, layout_name in ipairs({ 'layout_fairh', diff --git a/lib/beautiful/xresources.lua b/lib/beautiful/xresources.lua index 5e45b4fc..71299cb4 100644 --- a/lib/beautiful/xresources.lua +++ b/lib/beautiful/xresources.lua @@ -3,7 +3,7 @@ -- -- @author Yauhen Kirylau <yawghen@gmail.com> -- @copyright 2015 Yauhen Kirylau --- @submodule beautiful +-- @module beautiful ---------------------------------------------------------------------------- -- Grab environment @@ -45,7 +45,8 @@ local fallback = { } --- Get current base colorscheme from xrdb. --- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15' +-- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15'. +-- @staticfct beautiful.xresources.get_current_theme function xresources.get_current_theme() local keys = { 'background', 'foreground' } for i=0,15 do table.insert(keys, "color"..i) end @@ -77,7 +78,7 @@ end -- This function is deprecated. Use `s.dpi` and avoid getting the DPI without -- a screen. -- --- @deprecated xresources.get_dpi +-- @deprecated beautiful.xresources.get_dpi -- @tparam[opt] integer|screen s The screen. -- @treturn number DPI value. @@ -118,6 +119,7 @@ end --- Set DPI for a given screen (defaults to global). -- @tparam number dpi DPI value. -- @tparam[opt] integer s Screen. +-- @staticfct beautiful.xresources.set_dpi function xresources.set_dpi(dpi, s) s = get_screen(s) if not s then @@ -132,6 +134,7 @@ end -- @tparam number size Size -- @tparam[opt] integer|screen s The screen. -- @treturn integer Resulting size (rounded to integer). +-- @staticfct beautiful.xresources.apply_dpi function xresources.apply_dpi(size, s) return round(size / 96 * xresources.get_dpi(s)) end diff --git a/lib/gears/color.lua b/lib/gears/color.lua index 10f6a2bc..0e1d9be4 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -32,10 +32,6 @@ -- calling :set_matrix() on it, because this function uses a cache and your -- changes could thus have unintended side effects. Use @{create_pattern_uncached} -- if you need to modify the returned pattern. --- @see create_pattern_uncached, create_solid_pattern, create_png_pattern, --- create_linear_pattern, create_radial_pattern --- @tparam string col The string describing the pattern. --- @return a cairo pattern object -- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter @@ -65,6 +61,7 @@ local pattern_cache -- @param col The color to parse -- @treturn table 4 values representing color in RGBA format (each of them in -- [0, 1] range) or nil if input is incorrect. +-- @staticfct gears.color.parse_color -- @usage -- This will return 0, 1, 0, 1 -- gears.color.parse_color("#00ff00ff") function color.parse_color(col) @@ -123,6 +120,7 @@ end -- -- @param col The color for the pattern -- @return A cairo pattern object +-- @staticfct gears.color.create_solid_pattern function color.create_solid_pattern(col) if col == nil then col = "#000000" @@ -136,6 +134,7 @@ end -- -- @param file The filename of the file -- @return a cairo pattern object +-- @staticfct gears.color.create_png_pattern function color.create_png_pattern(file) if type(file) == "table" then file = file.file @@ -192,6 +191,7 @@ end -- For the explanation of ``, see `color.create_pattern`. -- @tparam string|table arg The argument describing the pattern. -- @return a cairo pattern object +-- @staticfct gears.color.create_linear_pattern function color.create_linear_pattern(arg) local pat @@ -217,6 +217,7 @@ end -- For the explanation of ``, see `color.create_pattern`. -- @tparam string|table arg The argument describing the pattern -- @return a cairo pattern object +-- @staticfct gears.color.create_radial_pattern function color.create_radial_pattern(arg) local pat @@ -249,6 +250,7 @@ color.types = { -- @see create_pattern -- @param col The string describing the pattern. -- @return a cairo pattern object +-- @staticfct gears.color.create_pattern_uncached function color.create_pattern_uncached(col) -- If it already is a cairo pattern, just leave it as that if cairo.Pattern:is_type_of(col) then @@ -273,6 +275,7 @@ end --- Create a pattern from a given string, same as @{gears.color}. -- @see gears.color +-- @staticfct gears.color.create_pattern function color.create_pattern(col) if cairo.Pattern:is_type_of(col) then return col @@ -285,6 +288,7 @@ end -- operator OVER) doesn't influence the visual result. -- @param col An argument that `create_pattern` accepts. -- @return The pattern if it is surely opaque, else nil +-- @staticfct gears.color.create_opaque_pattern function color.create_opaque_pattern(col) local pattern = color.create_pattern(col) local kind = pattern:get_type() @@ -335,6 +339,7 @@ end -- @param image Image or path to it. -- @param new_color New color. -- @return Recolored image. +-- @staticfct gears.color.recolor_image function color.recolor_image(image, new_color) if type(image) == 'string' then image = surface.duplicate_surface(image) @@ -349,6 +354,7 @@ end -- @param check_color The color to check. -- @tparam string fallback The color to return if the first is invalid. (default: black) -- @treturn string color if it is valid, else fallback. +-- @staticfct gears.color.ensure_pango_color function color.ensure_pango_color(check_color, fallback) check_color = tostring(check_color) -- Pango markup supports alpha, PangoColor does not. Thus, check for this. diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua index f8aeccff..98271f18 100644 --- a/lib/gears/debug.lua +++ b/lib/gears/debug.lua @@ -49,6 +49,7 @@ end -- @param tag The name of the value. -- @tparam[opt] int depth Depth of recursion. -- @return string A string that contains the expanded value of data. +-- @staticfct gears.debug.dump_return function debug.dump_return(data, tag, depth) return dump_raw(data, nil, tag, depth) end @@ -57,23 +58,27 @@ end -- @param data Table to print. -- @param tag The name of the table. -- @tparam[opt] int depth Depth of recursion. +-- @staticfct gears.debug.dump function debug.dump(data, tag, depth) print(debug.dump_return(data, tag, depth)) end --- Print an warning message --- @tparam string message The warning message to print +-- @tparam string message The warning message to print. +-- @staticfct gears.debug.print_warning function debug.print_warning(message) io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n") end --- Print an error message --- @tparam string message The error message to print +-- @tparam string message The error message to print. +-- @staticfct gears.debug.print_error function debug.print_error(message) io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n") end local displayed_deprecations = {} + --- Display a deprecation notice, but only once per traceback. -- -- This function also emits the `debug::deprecate` signal on the `awesome` @@ -84,6 +89,7 @@ local displayed_deprecations = {} -- @tparam boolean args.raw Print the message as-is without the automatic context -- @tparam integer args.deprecated_in Print the message only when Awesome's -- version is equal to or greater than deprecated_in. +-- @staticfct gears.debug.deprecate function debug.deprecate(see, args) args = args or {} if args.deprecated_in then @@ -124,6 +130,7 @@ end -- @tparam string old_name The old class name -- @tparam string new_name The new class name -- @treturn table A proxy class. +-- @staticfct gears.debug.deprecate_class function debug.deprecate_class(fallback, old_name, new_name) local message = old_name.." has been renamed to "..new_name diff --git a/lib/gears/filesystem.lua b/lib/gears/filesystem.lua index 3179292a..a555130d 100644 --- a/lib/gears/filesystem.lua +++ b/lib/gears/filesystem.lua @@ -26,6 +26,7 @@ end --- Create a directory, including all missing parent directories. -- @tparam string dir The directory. -- @return (true, nil) on success, (false, err) on failure +-- @staticfct gears.filesystem.make_directories function filesystem.make_directories(dir) return make_directory(Gio.File.new_for_path(dir)) end @@ -37,7 +38,8 @@ end --- Create all parent directories for a given path. -- @tparam string path The path whose parents should be created. --- @return (true, nil) on success, (false, err) on failure +-- @return (true, nil) on success, (false, err) on failure. +-- @staticfct gears.filesystem.make_parent_directories function filesystem.make_parent_directories(path) return make_directory(Gio.File.new_for_path(path):get_parent()) end @@ -45,6 +47,7 @@ end --- Check if a file exists, is readable and not a directory. -- @tparam string filename The file path. -- @treturn boolean True if file exists and is readable. +-- @staticfct gears.filesystem.file_readable function filesystem.file_readable(filename) local gfile = Gio.File.new_for_path(filename) local gfileinfo = gfile:query_info("standard::type,access::can-read", @@ -56,6 +59,7 @@ end --- Check if a file exists, is executable and not a directory. -- @tparam string filename The file path. -- @treturn boolean True if file exists and is executable. +-- @staticfct gears.filesystem.file_executable function filesystem.file_executable(filename) local gfile = Gio.File.new_for_path(filename) local gfileinfo = gfile:query_info("standard::type,access::can-execute", @@ -67,6 +71,7 @@ end --- Check if a path exists, is readable and a directory. -- @tparam string path The directory path. -- @treturn boolean True if path exists and is readable. +-- @staticfct gears.filesystem.dir_readable function filesystem.dir_readable(path) local gfile = Gio.File.new_for_path(path) local gfileinfo = gfile:query_info("standard::type,access::can-read", @@ -78,30 +83,35 @@ end --- Check if a path is a directory. -- @tparam string path The directory path -- @treturn boolean True if path exists and is a directory. +-- @staticfct gears.filesystem.is_dir function filesystem.is_dir(path) return Gio.File.new_for_path(path):query_file_type({}) == "DIRECTORY" end --- Get the config home according to the XDG basedir specification. -- @return the config home (XDG_CONFIG_HOME) with a slash at the end. +-- @staticfct gears.filesystem.get_xdg_config_home function filesystem.get_xdg_config_home() return (os.getenv("XDG_CONFIG_HOME") or os.getenv("HOME") .. "/.config") .. "/" end --- Get the cache home according to the XDG basedir specification. -- @return the cache home (XDG_CACHE_HOME) with a slash at the end. +-- @staticfct gears.filesystem.get_xdg_cache_home function filesystem.get_xdg_cache_home() return (os.getenv("XDG_CACHE_HOME") or os.getenv("HOME") .. "/.cache") .. "/" end --- Get the data home according to the XDG basedir specification. -- @treturn string the data home (XDG_DATA_HOME) with a slash at the end. +-- @staticfct gears.filesystem.get_xdg_data_home function filesystem.get_xdg_data_home() return (os.getenv("XDG_DATA_HOME") or os.getenv("HOME") .. "/.local/share") .. "/" end --- Get the data dirs according to the XDG basedir specification. -- @treturn table the data dirs (XDG_DATA_DIRS) with a slash at the end of each entry. +-- @staticfct gears.filesystem.get_xdg_data_dirs function filesystem.get_xdg_data_dirs() local xdg_data_dirs = os.getenv("XDG_DATA_DIRS") or "/usr/share:/usr/local/share" return gtable.map( @@ -112,12 +122,14 @@ end --- Get the path to the user's config dir. -- This is the directory containing the configuration file ("rc.lua"). -- @return A string with the requested path with a slash at the end. +-- @staticfct gears.filesystem.get_configuration_dir function filesystem.get_configuration_dir() return awesome.conffile:match(".*/") or "./" end --- Get the path to a directory that should be used for caching data. -- @return A string with the requested path with a slash at the end. +-- @staticfct gears.filesystem.get_cache_dir function filesystem.get_cache_dir() local result = filesystem.get_xdg_cache_home() .. "awesome/" filesystem.make_directories(result) @@ -126,12 +138,14 @@ end --- Get the path to the directory where themes are installed. -- @return A string with the requested path with a slash at the end. +-- @staticfct gears.filesystem.get_themes_dir function filesystem.get_themes_dir() return (os.getenv('AWESOME_THEMES_PATH') or awesome.themes_path) .. "/" end --- Get the path to the directory where our icons are installed. -- @return A string with the requested path with a slash at the end. +-- @staticfct gears.filesystem.get_awesome_icon_dir function filesystem.get_awesome_icon_dir() return (os.getenv('AWESOME_ICON_PATH') or awesome.icon_path) .. "/" end @@ -141,6 +155,7 @@ end -- default paths. -- @param d The directory to get (either "config" or "cache"). -- @return A string containing the requested path. +-- @staticfct gears.filesystem.get_dir function filesystem.get_dir(d) if d == "config" then -- No idea why this is what is returned, I recommend everyone to use @@ -159,6 +174,7 @@ end -- If ommited, all files are considered. -- @treturn string|nil A randomly selected filename from the specified path (with -- a specified extension if required) or nil if no suitable file is found. +-- @staticfct gears.filesystem.get_random_file_from_dir function filesystem.get_random_file_from_dir(path, exts) local files, valid_exts = {}, {} diff --git a/lib/gears/geometry.lua b/lib/gears/geometry.lua index 98c5c2ab..364aedf9 100644 --- a/lib/gears/geometry.lua +++ b/lib/gears/geometry.lua @@ -21,7 +21,8 @@ local gears = {geometry = {rectangle = {} } } -- @tparam number geom.height The rectangle height -- @tparam number x X coordinate of point -- @tparam number y Y coordinate of point --- @treturn number The squared distance of the rectangle to the provided point +-- @treturn number The squared distance of the rectangle to the provided point. +-- @staticfct gears.geometry.rectangle.get_square_distance function gears.geometry.rectangle.get_square_distance(geom, x, y) local dist_x, dist_y = 0, 0 if x < geom.x then @@ -42,6 +43,7 @@ end -- @tparam number x The x coordinate -- @tparam number y The y coordinate -- @return The key from the closest geometry. +-- @staticfct gears.geometry.rectangle.get_closest_by_coord function gears.geometry.rectangle.get_closest_by_coord(list, x, y) local dist = math.huge local ret = nil @@ -66,6 +68,7 @@ end -- @tparam number y The y coordinate -- @return The key from the closest geometry. In case no result is found, *nil* -- is returned. +-- @staticfct gears.geometry.rectangle.get_by_coord function gears.geometry.rectangle.get_by_coord(list, x, y) for k, geometry in pairs(list) do if x >= geometry.x and x < geometry.x + geometry.width @@ -126,6 +129,7 @@ end -- @tparam table recttbl A table of rectangle specifications. -- @tparam table cur The current rectangle. -- @return The index for the rectangle in recttbl closer to cur in the given direction. nil if none found. +-- @staticfct gears.geometry.rectangle.get_in_direction function gears.geometry.rectangle.get_in_direction(dir, recttbl, cur) local dist, dist_min local target = nil @@ -151,6 +155,7 @@ end -- @param a The area. -- @param b The other area. -- @return True if they intersect, false otherwise. +-- @staticfct gears.geometry.rectangle.area_intersect_area function gears.geometry.rectangle.area_intersect_area(a, b) return (b.x < a.x + a.width and b.x + b.width > a.x @@ -170,6 +175,7 @@ end -- @tparam number b.width The rectangle width -- @tparam number b.height The rectangle height -- @treturn table The intersect area. +-- @staticfct gears.geometry.rectangle.get_intersection function gears.geometry.rectangle.get_intersection(a, b) local g = {} g.x = math.max(a.x, b.x) @@ -191,6 +197,7 @@ end -- @tparam number elem.width The rectangle width -- @tparam number elem.height The rectangle height -- @return The new area list. +-- @staticfct gears.geometry.rectangle.area_remove function gears.geometry.rectangle.area_remove(areas, elem) for i = #areas, 1, -1 do -- Check if the 'elem' intersect diff --git a/lib/gears/math.lua b/lib/gears/math.lua index 58c69ad8..2bacf6bb 100644 --- a/lib/gears/math.lua +++ b/lib/gears/math.lua @@ -37,10 +37,9 @@ end -- For example, if we consider a set with value { 10, 15, 34 }, -- it will return a table containing 2^n set: -- { }, { 10 }, { 15 }, { 34 }, { 10, 15 }, { 10, 34 }, etc. --- @class function --- @name subsets -- @param set A set. -- @return A table with all subset. +-- @staticfct gears.math.subsets function gmath.subsets(set) local mask = {} local ret = {} @@ -56,11 +55,10 @@ function gmath.subsets(set) end --- Make i cycle. --- @class function --- @name cycle -- @param t A length. Must be greater than zero. -- @param i An absolute index to fit into #t. -- @return An integer in (1, t) or nil if t is less than or equal to zero. +-- @staticfct gears.math.cycle function gmath.cycle(t, i) if t < 1 then return end i = i % t @@ -71,10 +69,9 @@ function gmath.cycle(t, i) end --- Round a number to an integer. --- @class function --- @name round -- @tparam number x -- @treturn integer +-- @staticfct gears.math.round function gmath.round(x) return math.floor(x + 0.5) end diff --git a/lib/gears/object.lua b/lib/gears/object.lua index d6f539fd..a7be7f35 100644 --- a/lib/gears/object.lua +++ b/lib/gears/object.lua @@ -49,6 +49,7 @@ end --@DOC_text_gears_object_signal_EXAMPLE@ -- @tparam string name The name of the signal -- @tparam function func The callback to call when the signal is emitted +-- @method connect_signal function object:connect_signal(name, func) assert(type(func) == "function", "callback must be a function, got: " .. type(func)) local sig = find_signal(self, name) @@ -95,6 +96,7 @@ end -- collected and automatically disconnects the signal when that happens. -- @tparam string name The name of the signal -- @tparam function func The callback to call when the signal is emitted +-- @method weak_connect_signal function object:weak_connect_signal(name, func) assert(type(func) == "function", "callback must be a function, got: " .. type(func)) local sig = find_signal(self, name) @@ -105,6 +107,7 @@ end --- Disonnect to a signal. -- @tparam string name The name of the signal -- @tparam function func The callback that should be disconnected +-- @method disconnect_signal function object:disconnect_signal(name, func) local sig = find_signal(self, name) sig.weak[func] = nil @@ -117,6 +120,7 @@ end -- @param ... Extra arguments for the callback functions. Each connected -- function receives the object as first argument and then any extra arguments -- that are given to emit_signal() +-- @method emit_signal function object:emit_signal(name, ...) local sig = find_signal(self, name) for func in pairs(sig.strong) do @@ -179,7 +183,8 @@ end -- when an unknown property is set. -- @tparam[opt=nil] table args.class -- @treturn table A new object --- @function gears.object +-- @constructorfct gears.object + local function new(args) args = args or {} local ret = {} @@ -236,6 +241,7 @@ end -- @tparam[opt=2] integer level Level for `debug.getinfo(level, "S")`. -- Typically 2 or 3. -- @treturn string The module name, e.g. "wibox.container.background". +-- @staticfct gears.object.modulename function object.modulename(level) return debug.getinfo(level, "S").source:gsub(".*/lib/", ""):gsub("/", "."):gsub("%.lua", "") end diff --git a/lib/gears/protected_call.lua b/lib/gears/protected_call.lua index d8f62642..e42bc707 100644 --- a/lib/gears/protected_call.lua +++ b/lib/gears/protected_call.lua @@ -43,6 +43,7 @@ end -- @tparam function func The function to call -- @param ... Arguments to the function -- @return The result of the given function, or nothing if an error occurred. +-- @staticfct gears.protected_call function protected_call.call(func, ...) return do_pcall(func, ...) end diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index 707e06cc..c051a011 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -55,6 +55,7 @@ local module = {} -- @tparam number width The rectangle width -- @tparam number height The rectangle height -- @tparam number radius the corner radius +-- @staticfct gears.shape.rounded_rect function module.rounded_rect(cr, width, height, radius) radius = radius or 10 @@ -83,7 +84,8 @@ end -- -- @param cr A cairo content -- @param width The rectangle width --- @param height The rectangle height +-- @param height The rectangle height. +-- @staticfct gears.shape.rounded_bar function module.rounded_bar(cr, width, height) module.rounded_rect(cr, width, height, height / 2) end @@ -100,6 +102,7 @@ end -- @tparam boolean br If the bottom right corner is rounded -- @tparam boolean bl If the bottom left corner is rounded -- @tparam number rad The corner radius +-- @staticfct gears.shape.partially_rounded_rect function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad) rad = rad or 10 if width / 2 < rad then @@ -151,6 +154,7 @@ end -- @tparam[opt=5] number corner_radius The corner radius -- @tparam[opt=10] number arrow_size The width and height of the arrow -- @tparam[opt=width/2 - arrow_size/2] number arrow_position The position of the arrow +-- @staticfct gears.shape.infobubble function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position) arrow_size = arrow_size or 10 corner_radius = math.min((height-arrow_size)/2, corner_radius or 5) @@ -184,6 +188,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=height/2] number arrow_length The length of the arrow part +-- @staticfct gears.shape.rectangular_tag function module.rectangular_tag(cr, width, height, arrow_length) arrow_length = arrow_length or height/2 if arrow_length > 0 then @@ -213,6 +218,7 @@ end -- @tparam[opt=head_width] number head_width The width of the head (/\) of the arrow -- @tparam[opt=width /2] number shaft_width The width of the shaft of the arrow -- @tparam[opt=height/2] number shaft_length The head_length of the shaft (the rest is the head) +-- @staticfct gears.shape.arrow function module.arrow(cr, width, height, head_width, shaft_width, shaft_length) shaft_length = shaft_length or height / 2 shaft_width = shaft_width or width / 2 @@ -237,6 +243,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @staticfct gears.shape.hexagon function module.hexagon(cr, width, height) cr:move_to(height/2,0) cr:line_to(width-height/2,0) @@ -256,6 +263,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=height/2] number arrow_depth The width of the arrow part of the shape +-- @staticfct gears.shape.powerline function module.powerline(cr, width, height, arrow_depth) arrow_depth = arrow_depth or height/2 local offset = 0 @@ -283,6 +291,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @staticfct gears.shape.isosceles_triangle function module.isosceles_triangle(cr, width, height) cr:move_to( width/2, 0 ) cr:line_to( width , height ) @@ -298,6 +307,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=width/3] number thickness The cross section thickness +-- @staticfct gears.shape.cross function module.cross(cr, width, height, thickness) thickness = thickness or width/3 local xpadding = (width - thickness) / 2 @@ -325,6 +335,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam number corner_radius +-- @staticfct gears.shape.octogon function module.octogon(cr, width, height, corner_radius) corner_radius = corner_radius or math.min(10, math.min(width, height)/4) local offset = math.sqrt( (corner_radius*corner_radius) / 2 ) @@ -348,6 +359,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=math.min(width height) / 2)] number radius The radius +-- @staticfct gears.shape.circle function module.circle(cr, width, height, radius) radius = radius or math.min(width, height) / 2 cr:move_to(width/2+radius, height/2) @@ -362,6 +374,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @staticfct gears.shape.rectangle function module.rectangle(cr, width, height) cr:rectangle(0, 0, width, height) end @@ -375,6 +388,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=width/3] number base_width The parallelogram base width +-- @staticfct gears.shape.parallelogram function module.parallelogram(cr, width, height, base_width) base_width = base_width or width/3 cr:move_to(width-base_width, 0 ) @@ -391,6 +405,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @staticfct gears.shape.losange function module.losange(cr, width, height) cr:move_to(width/2 , 0 ) cr:line_to(width , height/2 ) @@ -411,6 +426,7 @@ end -- @tparam[opt=0] number start_angle The start angle (in radian) -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian) -- @tparam[opt=math.min(width height)/2] number radius The shape height +-- @staticfct gears.shape.pie function module.pie(cr, width, height, start_angle, end_angle, radius) radius = radius or math.floor(math.min(width, height)/2) start_angle, end_angle = start_angle or 0, end_angle or math.pi/2 @@ -444,6 +460,7 @@ end -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian) -- @tparam[opt=false] boolean start_rounded if the arc start rounded -- @tparam[opt=false] boolean end_rounded if the arc end rounded +-- @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 end_angle = end_angle or math.pi/2 @@ -562,6 +579,7 @@ end -- @tparam number h The shape height -- @tparam number percent The progressbar percent -- @tparam boolean hide_left Do not draw the left side of the shape +-- @staticfct gears.shape.radial_progress function module.radial_progress(cr, w, h, percent, hide_left) percent = percent or 1 local total_length = (2*(w-h))+2*((h/2)*math.pi) @@ -628,6 +646,7 @@ end -- -- @param shape A shape function -- @return A transformation handle, also act as a shape function +-- @staticfct gears.shape.transform function module.transform(shape) -- Apply the transformation matrix and apply the shape, then restore diff --git a/lib/gears/sort/topological.lua b/lib/gears/sort/topological.lua index 58ff32c7..8064e40c 100644 --- a/lib/gears/sort/topological.lua +++ b/lib/gears/sort/topological.lua @@ -18,6 +18,7 @@ end --- Ensure that `node` appears after all `dependencies`. -- @param node The node that edges are added to. -- @tparam table dependencies List of nodes that have to appear before `node`. +-- @method append function tsort:append(node, dependencies) add_node(self, node) for _, dep in ipairs(dependencies) do @@ -29,6 +30,7 @@ end --- Ensure that `node` appears before all `subordinates`. -- @param node The node that edges are added to. -- @tparam table subordinates List of nodes that have to appear after `node`. +-- @method prepend function tsort:prepend(node, subordinates) for _, dep in ipairs(subordinates) do self:append(dep, { node }) @@ -63,6 +65,7 @@ end --- Create a copy of this topological sort. -- This is useful to backup it before adding elements that can potentially -- have circular dependencies and thus render the original useless. +-- @method clone function tsort:clone() local new = tsort.topological() @@ -75,6 +78,7 @@ end --- Remove a node from the topological map. -- -- @param node The node +-- @method remove function tsort:remove(node) self._edges[node] = nil for _, deps in pairs(self._edges) do @@ -86,6 +90,7 @@ end -- @treturn[1] table A sorted list of nodes -- @treturn[2] nil -- @return[2] A node around which a loop exists +-- @method sort function tsort:sort() local result, state = {}, {} for node in pairs(self._edges) do @@ -104,7 +109,7 @@ end -- --@DOC_text_gears_sort_topological_EXAMPLE@ -- --- @function gears.sort.topological +-- @constructorfct gears.sort.topological function tsort.topological() return setmetatable({ diff --git a/lib/gears/string.lua b/lib/gears/string.lua index 84c57788..ff551883 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -7,43 +7,41 @@ local gstring = {} local xml_entity_names = { ["'"] = "'", ["\""] = """, ["<"] = "<", [">"] = ">", ["&"] = "&" }; + --- Escape a string from XML char. -- Useful to set raw text in textbox. --- @class function --- @name xml_escape -- @param text Text to escape. -- @return Escape text. +-- @staticfct gears.string.xml_escape function gstring.xml_escape(text) return text and text:gsub("['&<>\"]", xml_entity_names) or nil end local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "'", ndash = "-", mdash = "-", - amp = "&" }; + amp = "&" }; + --- Unescape a string from entities. --- @class function --- @name xml_unescape -- @param text Text to unescape. -- @return Unescaped text. +-- @staticfct gears.string.xml_unescape function gstring.xml_unescape(text) return text and text:gsub("&(%a+);", xml_entity_chars) or nil end --- Count number of lines in a string --- @class function --- @name linecount -- @tparam string text Input string. -- @treturn int Number of lines. +-- @staticfct gears.string.linecount function gstring.linecount(text) return select(2, text:gsub('\n', '\n')) + 1 end ---- Split a string into multiple lines --- @class function --- @name linewrap +--- Split a string into multiple lines. -- @param text String to wrap. -- @param width Maximum length of each line. Default: 72. -- @param indent Number of spaces added before each wrapped line. Default: 0. -- @return The string with lines wrapped to width. +-- @staticfct gears.string.linewrap function gstring.linewrap(text, width, indent) text = text or "" width = width or 72 @@ -62,8 +60,7 @@ end --- Escape all special pattern-matching characters so that lua interprets them -- literally instead of as a character class. -- Source: http://stackoverflow.com/a/20778724/15690 --- @class function --- @name quote_pattern +-- @staticfct gears.string.quote_pattern function gstring.quote_pattern(s) -- All special characters escaped in a string: %%, %^, %$, ... local patternchars = '['..("%^$().[]*+-?"):gsub("(.)", "%%%1")..']' @@ -72,8 +69,7 @@ end --- Generate a pattern matching expression that ignores case. -- @param s Original pattern matching expression. --- @class function --- @name query_to_pattern +-- @staticfct gears.string.query_to_pattern function gstring.query_to_pattern(q) local s = gstring.quote_pattern(q) -- Poor man's case-insensitive character matching. @@ -87,11 +83,10 @@ end --- Split separates a string containing a delimiter into the list of -- substrings between that delimiter. --- @class function --- @name split -- @tparam string str String to be splitted -- @tparam string delimiter Character where the string will be splitted -- @treturn table list of the substrings +-- @staticfct gears.string.split function gstring.split(str, delimiter) local pattern = "(.-)" .. delimiter .. "()" local result = {} @@ -106,22 +101,20 @@ function gstring.split(str, delimiter) return result end ---- Check if a string starts with another string --- @class function --- @name startswith +--- Check if a string starts with another string. -- @tparam string str String to search --- @tparam string sub String to check for +-- @tparam string sub String to check for. +-- @staticfct gears.string.startswith function gstring.startswith(str, sub) - return string.sub(str, 1, string.len(sub)) == sub + return string.sub(str, 1, string.len(sub)) == sub end ---- Check if a string ends with another string --- @class function --- @name endswith +--- Check if a string ends with another string. -- @tparam string str String to search --- @tparam string sub String to check for +-- @tparam string sub String to check for. +-- @staticfct gears.string.endswith function gstring.endswith(str, sub) - return sub == "" or string.sub(str,-string.len(sub)) == sub + return sub == "" or string.sub(str,-string.len(sub)) == sub end return gstring diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index dc61efd8..b85c7de1 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -35,7 +35,8 @@ end -- @param default The default value to return on error; when nil, then a surface -- in an error state is returned. -- @return The loaded surface, or the replacement default --- @return An error message, or nil on success +-- @return An error message, or nil on success. +-- @staticfct load_uncached_silently function surface.load_uncached_silently(_surface, default) -- On nil, return some sane default if not _surface then @@ -71,7 +72,8 @@ end -- in an error state is returned. -- @return The loaded surface, or the replacement default, or nil if called with -- nil. --- @return An error message, or nil on success +-- @return An error message, or nil on success. +-- @staticfct load_silently function surface.load_silently(_surface, default) if type(_surface) == "string" then local cache = surface_cache[_surface] @@ -106,6 +108,7 @@ end -- via `gears.debug.print_error`. -- @param _surface The surface to load or nil -- @return The loaded surface, or nil +-- @staticfct load_uncached function surface.load_uncached(_surface) return do_load_and_handle_errors(_surface, surface.load_uncached_silently) end @@ -114,7 +117,8 @@ end -- This is usually needed for loading images by file name. Errors are handled -- via `gears.debug.print_error`. -- @param _surface The surface to load or nil --- @return The loaded surface, or nil +-- @return The loaded surface, or nil. +-- @staticfct gears.surface function surface.load(_surface) return do_load_and_handle_errors(_surface, surface.load_silently) end @@ -125,7 +129,8 @@ end --- Get the size of a cairo surface -- @param surf The surface you are interested in --- @return The surface's width and height +-- @return The surface's width and height. +-- @staticfct get_size function surface.get_size(surf) local cr = cairo.Context(surf) local x, y, w, h = cr:clip_extents() @@ -142,6 +147,7 @@ end -- surface. -- @param s Source surface. -- @return The surface's duplicate. +-- @staticfct duplicate_surface function surface.duplicate_surface(s) s = surface.load(s) @@ -166,6 +172,7 @@ end -- @param[opt=white] shape_color The shape color or pattern -- @param[opt=transparent] bg_color The surface background color -- @treturn cairo.surface the new surface +-- @staticfct load_from_shape function surface.load_from_shape(width, height, shape, shape_color, bg_color, ...) color = color or require("gears.color") @@ -191,7 +198,8 @@ end -- @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 +-- @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() @@ -224,13 +232,15 @@ end --- Create an SVG file with this widget content. -- This is dynamic, so the SVG will be updated along with the widget content. -- because of this, the painting may happen hover multiple event loop cycles. --- @deprecated wibox.widget.draw_to_svg_file +-- @deprecated draw_to_svg_file -- @tparam widget widget A widget -- @tparam string path The output file path -- @tparam number width The surface width -- @tparam number height The surface height -- @return The cairo surface --- @return The hierarchy +-- @return The hierarchy. +-- @see wibox.widget.draw_to_svg_file +-- @see wibox.widget.draw_to_image_surface function surface.widget_to_svg(widget, path, width, height) gdebug.deprecate("Use wibox.widget.draw_to_svg_file instead of ".. "gears.surface.render_to_svg", {deprecated_in=5}) @@ -243,13 +253,15 @@ end --- Create a cairo surface with this widget content. -- This is dynamic, so the SVG will be updated along with the widget content. -- because of this, the painting may happen hover multiple event loop cycles. --- @deprecated wibox.widget.draw_to_image_surface +-- @deprecated draw_to_image_surface -- @tparam widget widget A widget -- @tparam number width The surface width -- @tparam number height The surface height -- @param[opt=cairo.Format.ARGB32] format The surface format -- @return The cairo surface --- @return The hierarchy +-- @return The hierarchy. +-- @see wibox.widget.draw_to_svg_file +-- @see wibox.widget.draw_to_image_surface function surface.widget_to_surface(widget, width, height, format) gdebug.deprecate("Use wibox.widget.draw_to_image_surface instead of ".. "gears.surface.render_to_surface", {deprecated_in=5}) diff --git a/lib/gears/table.lua b/lib/gears/table.lua index 70f99003..dd848a73 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -12,10 +12,9 @@ local gtable = {} --- Join all tables given as arguments. -- This will iterate over all tables and insert their entries into a new table. --- @class function --- @name join -- @tparam table ... Tables to join. -- @treturn table A new table containing all entries from the arguments. +-- @staticfct gears.table.join function gtable.join(...) local ret = {} for i = 1, select("#", ...) do @@ -36,12 +35,12 @@ end --- Override elements in the first table by the one in the second. -- -- Note that this method doesn't copy entries found in `__index`. --- @class function --- @name crush +-- -- @tparam table t the table to be overriden -- @tparam table set the table used to override members of `t` -- @tparam[opt=false] bool raw Use rawset (avoid the metatable) -- @treturn table t (for convenience) +-- @staticfct gears.table.crush function gtable.crush(t, set, raw) if raw then for k, v in pairs(set) do @@ -63,10 +62,9 @@ end -- -- This function removes any entries with non-numeric keys. -- --- @class function --- @name from_sparse -- @tparam table t A potentially sparse table. -- @treturn table A packed table with only numeric keys. +-- @staticfct gears.table.from_sparse function gtable.from_sparse(t) local keys= {} for k in pairs(t) do @@ -86,12 +84,12 @@ function gtable.from_sparse(t) end --- Check if a table has an item and return its key. --- @class function --- @name hasitem +-- -- @tparam table t The table. -- @param item The item to look for in values of the table. -- @treturn[1] string|number The key of the item. -- @treturn[2] nil +-- @staticfct gears.table.hasitem function gtable.hasitem(t, item) for k, v in pairs(t) do if v == item then @@ -110,6 +108,7 @@ end -- @tparam[opt=nil] number max The maximum number of entries to find. -- @treturn table|nil An ordered table with all the keys or `nil` if none were -- found. +-- @staticfct gears.table.find_keys function gtable.find_keys(t, matcher, ordered, max) if max == 0 then return nil end @@ -134,7 +133,8 @@ end -- returning a boolean. -- @tparam[opt=false] boolean ordered If true, only look for continuous -- numeric keys. --- @return The table key or nil +-- @return The table key or nil. +-- @staticfct gears.table.find_first_key function gtable.find_first_key(t, matcher, ordered) local ret = gtable.find_keys(t, matcher, ordered, 1) @@ -143,10 +143,10 @@ end --- Get a sorted table with all integer keys from a table. --- @class function --- @name keys +-- -- @tparam table t The table for which the keys to get. --- @treturn table A table with keys +-- @treturn table A table with keys. +-- @staticfct gears.table.keys function gtable.keys(t) local keys = { } for k, _ in pairs(t) do @@ -159,11 +159,11 @@ function gtable.keys(t) end --- Filter a table's keys for certain content type. --- @class function --- @name keys_filter +-- -- @tparam table t The table to retrieve the keys for. -- @tparam string ... The types to look for. -- @treturn table A filtered table. +-- @staticfct gears.table.keys_filter function gtable.keys_filter(t, ...) local keys = gtable.keys(t) local keys_filtered = { } @@ -179,10 +179,10 @@ function gtable.keys_filter(t, ...) end --- Reverse a table. --- @class function --- @name reverse +-- -- @tparam table t The table to reverse. -- @treturn table A reversed table. +-- @staticfct gears.table.reverse function gtable.reverse(t) local tr = { } -- Reverse all elements with integer keys. @@ -199,11 +199,11 @@ function gtable.reverse(t) end --- Clone a table. --- @class function --- @name clone +-- -- @tparam table t The table to clone. -- @tparam[opt=true] bool deep Create a deep clone? -- @treturn table A clone of `t`. +-- @staticfct gears.table.clone function gtable.clone(t, deep) deep = deep == nil and true or deep local c = { } @@ -218,11 +218,10 @@ function gtable.clone(t, deep) end --- Iterate over a table. +-- -- Returns an iterator to cycle through all elements of a table that match a -- given criteria, starting from the first element or the given index. -- --- @class function --- @name iterate -- @tparam table t The table to iterate. -- @tparam func filter A function that returns true to indicate a positive -- match. @@ -230,6 +229,7 @@ end -- @tparam[opt=1] int start Index to start iterating from. -- Default is 1 (=> start of the table). -- @treturn func +-- @staticfct gears.table.iterate function gtable.iterate(t, filter, start) local count = 0 local index = start or 1 @@ -246,11 +246,11 @@ function gtable.iterate(t, filter, start) end --- Merge items from one table to another one. --- @class function --- @name merge +-- -- @tparam table t The container table -- @tparam table set The mixin table. --- @treturn table (for convenience) +-- @treturn table (for convenience). +-- @staticfct gears.table.merge function gtable.merge(t, set) for _, v in ipairs(set) do table.insert(t, v) @@ -259,13 +259,14 @@ function gtable.merge(t, set) end --- Map a function to a table. +-- -- The function is applied to each value on the table, returning a modified -- table. --- @class function --- @name map +-- -- @tparam function f The function to be applied to each value in the table. -- @tparam table tbl The container table whose values will be operated on. -- @treturn table +-- @staticfct gears.table.map function gtable.map(f, tbl) local t = {} for k,v in pairs(tbl) do diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index ab51e006..5eb5ec4a 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -194,7 +194,7 @@ end -- @tparam number timeout Timeout in seconds (e.g. 1.5). -- @tparam function callback Function to run. -- @treturn timer The timer object that was set up. --- @function gears.timer.start_new +-- @staticfct gears.timer.start_new -- @see gears.timer.weak_start_new function timer.start_new(timeout, callback) local t = timer.new({ timeout = timeout }) @@ -216,7 +216,7 @@ end -- @tparam number timeout Timeout in seconds (e.g. 1.5). -- @tparam function callback Function to start. -- @treturn timer The timer object that was set up. --- @function gears.timer.weak_start_new +-- @staticfct gears.timer.weak_start_new -- @see gears.timer.start_new function timer.weak_start_new(timeout, callback) local indirection = setmetatable({}, { __mode = "v" }) @@ -234,7 +234,7 @@ local delayed_calls = {} --- Run all pending delayed calls now. This function should best not be used at -- all, because it means that less batching happens and the delayed calls run -- prematurely. --- @function gears.timer.run_delayed_calls_now +-- @staticfct gears.timer.run_delayed_calls_now function timer.run_delayed_calls_now() for _, callback in ipairs(delayed_calls) do protected_call(unpack(callback)) @@ -245,7 +245,7 @@ end --- Call the given function at the end of the current main loop iteration -- @tparam function callback The function that should be called -- @param ... Arguments to the callback function --- @function gears.timer.delayed_call +-- @staticfct gears.timer.delayed_call function timer.delayed_call(callback, ...) assert(type(callback) == "function", "callback must be a function, got: " .. type(callback)) table.insert(delayed_calls, { callback, ... }) diff --git a/lib/gears/wallpaper.lua b/lib/gears/wallpaper.lua index 13da9b7b..8b3f796a 100644 --- a/lib/gears/wallpaper.lua +++ b/lib/gears/wallpaper.lua @@ -50,7 +50,8 @@ end -- global variable. -- @param s The screen to set the wallpaper on or nil for all screens -- @return[1] The available geometry (table with entries width and height) --- @return[1] A cairo context that the wallpaper should be drawn to +-- @return[1] A cairo context that the wallpaper should be drawn to. +-- @staticfct gears.wallpaper.prepare_context function wallpaper.prepare_context(s) s = get_screen(s) @@ -109,6 +110,7 @@ end -- @param pattern The wallpaper that should be set. This can be a cairo surface, -- a description for gears.color or a cairo pattern. -- @see gears.color +-- @staticfct gears.wallpaper.set function wallpaper.set(pattern) if cairo.Surface:is_type_of(pattern) then pattern = cairo.Pattern.create_for_surface(pattern) @@ -130,6 +132,7 @@ end -- gears.color. The default is black. -- @param scale The scale factor for the wallpaper. Default is 1 (original size). -- @see gears.color +-- @staticfct gears.wallpaper.centered function wallpaper.centered(surf, s, background, scale) local geom, cr = wallpaper.prepare_context(s) local original_surf = surf @@ -169,6 +172,7 @@ end -- @param s The screen whose wallpaper should be set. Can be nil, in which case -- all screens are set. -- @param offset This can be set to a table with entries x and y. +-- @staticfct gears.wallpaper.tiled function wallpaper.tiled(surf, s, offset) local _, cr = wallpaper.prepare_context(s) @@ -198,6 +202,7 @@ end -- @param ignore_aspect If this is true, the image's aspect ratio is ignored. -- The default is to honor the aspect ratio. -- @param offset This can be set to a table with entries x and y. +-- @staticfct gears.wallpaper.maximized function wallpaper.maximized(surf, s, ignore_aspect, offset) local geom, cr = wallpaper.prepare_context(s) local original_surf = surf @@ -238,6 +243,7 @@ end -- @param background The background color that should be used. Gets handled via -- gears.color. The default is black. -- @see gears.color +-- @staticfct gears.wallpaper.fit function wallpaper.fit(surf, s, background) local geom, cr = wallpaper.prepare_context(s) local original_surf = surf diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index 55ad383e..16cf5d5b 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -4,19 +4,25 @@ -- List of menubar keybindings: -- --- -- --- * "Left" | "C-j" select an item on the left --- * "Right" | "C-k" select an item on the right --- * "Backspace" exit the current category if we are in any --- * "Escape" exit the current directory or exit menubar --- * "Home" select the first item --- * "End" select the last --- * "Return" execute the entry --- * "C-Return" execute the command with awful.spawn --- * "C-M-Return" execute the command in a terminal +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +--
KeybindingDescription
LeftC-j select an item on the left
RightC-k select an item on the right
Backspace exit the current category if we are in any
Escape exit the current directory or exit menubar
Home select the first item
End select the last
Return execute the entry
C-Return execute the command with awful.spawn
C-M-Return execute the command in a terminal
-- -- @author Alexander Yakushev <yakushev.alex@gmail.com> -- @copyright 2011-2012 Alexander Yakushev --- @module menubar +-- @popupmod menubar --------------------------------------------------------------------------- -- Grab environment we need @@ -362,6 +368,7 @@ end --- Refresh menubar's cache by reloading .desktop files. -- @tparam[opt] screen scr Screen. +-- @staticfct menubar.refresh function menubar.refresh(scr) scr = get_screen(scr or awful.screen.focused() or 1) menubar.menu_gen.generate(function(entries) @@ -418,6 +425,7 @@ end --- Show the menubar on the given screen. -- @param[opt] scr Screen. +-- @staticfct menubar.show 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 @@ -492,6 +500,7 @@ function menubar.show(scr) end --- Hide the menubar. +-- @staticfct menubar.hide function menubar.hide() if instance then instance.wibox.visible = false diff --git a/lib/menubar/menu_gen.lua b/lib/menubar/menu_gen.lua index a2434aa2..19fb6e73 100644 --- a/lib/menubar/menu_gen.lua +++ b/lib/menubar/menu_gen.lua @@ -58,6 +58,7 @@ menu_gen.all_categories = { } --- Find icons for category entries. +-- @staticfct menubar.menu_gen.lookup_category_icons function menu_gen.lookup_category_icons() for _, v in pairs(menu_gen.all_categories) do v.icon = utils.lookup_icon(v.icon_name) @@ -79,6 +80,7 @@ end -- @tparam function callback Will be fired when all menu entries were parsed -- with the resulting list of menu entries as argument. -- @tparam table callback.entries All menu entries. +-- @staticfct menubar.menu_gen.generate function menu_gen.generate(callback) -- Update icons for category entries menu_gen.lookup_category_icons() diff --git a/lib/menubar/utils.lua b/lib/menubar/utils.lua index 9b20c96b..ae081747 100644 --- a/lib/menubar/utils.lua +++ b/lib/menubar/utils.lua @@ -131,6 +131,7 @@ local all_icon_sizes = { local supported_icon_file_exts = { png = 1, xpm = 2, svg = 3 } local icon_lookup_path = nil + --- Get a list of icon lookup paths. -- @treturn table A list of directories, without trailing slash. local function get_icon_lookup_path() @@ -198,6 +199,7 @@ end --- Remove CR newline from the end of the string. -- @param s string to trim +-- @staticfct menubar.utils.rtrim function utils.rtrim(s) if not s then return end if string.byte(s, #s) == 13 then @@ -209,6 +211,7 @@ end --- Lookup an icon in different folders of the filesystem. -- @tparam string icon_file Short or full name of the icon. -- @treturn string|boolean Full name of the icon, or false on failure. +-- @staticfct menubar.utils.lookup_icon_uncached function utils.lookup_icon_uncached(icon_file) if not icon_file or icon_file == "" then return false @@ -244,6 +247,7 @@ local lookup_icon_cache = {} --- Lookup an icon in different folders of the filesystem (cached). -- @param icon Short or full name of the icon. -- @return full name of the icon. +-- @staticfct menubar.utils.lookup_icon function utils.lookup_icon(icon) if not lookup_icon_cache[icon] and lookup_icon_cache[icon] ~= false then lookup_icon_cache[icon] = utils.lookup_icon_uncached(icon) @@ -254,6 +258,7 @@ end --- Parse a .desktop file. -- @param file The .desktop file. -- @return A table with file entries. +-- @staticfct menubar.utils.parse_desktop_file function utils.parse_desktop_file(file) local program = { show = true, file = file } @@ -350,6 +355,7 @@ end -- @tparam function callback Will be fired when all the files were parsed -- with the resulting list of menu entries as argument. -- @tparam table callback.programs Paths of found .desktop files. +-- @staticfct menubar.utils.parse_dir function utils.parse_dir(dir_path, callback) local function get_readable_path(file) @@ -413,6 +419,7 @@ end -- @tparam str text Text. -- @tparam number|screen s Screen -- @treturn int Text width. +-- @staticfct menubar.utils.compute_text_width function utils.compute_text_width(text, s) local w, _ = w_textbox(gstring.xml_escape(text)):get_preferred_size(s) return w diff --git a/lib/naughty/core.lua b/lib/naughty/core.lua index f21a20a5..3b93f774 100644 --- a/lib/naughty/core.lua +++ b/lib/naughty/core.lua @@ -196,6 +196,7 @@ local conns = {} -- @usage naughty.connect_signal("added", function(notif) -- -- do something -- end) +-- @staticfct naughty.connect_signal function naughty.connect_signal(name, func) assert(name) conns[name] = conns[name] or {} @@ -205,6 +206,7 @@ end --- Emit a notification signal. -- @tparam string name The signal name. -- @param ... The signal callback arguments +-- @staticfct naughty.emit_signal function naughty.emit_signal(name, ...) assert(name) for _, func in pairs(conns[name] or {}) do @@ -216,6 +218,7 @@ end -- @tparam string name The name of the signal -- @tparam function func The attached function -- @treturn boolean If the disconnection was successful +-- @staticfct naughty.disconnect_signal function naughty.disconnect_signal(name, func) for k, v in ipairs(conns[name] or {}) do if v == func then @@ -291,6 +294,7 @@ end -- @treturn true|nil True if all notifications were successfully destroyed, nil -- otherwise. -- @see notification_closed_reason +-- @staticfct naughty.destroy_all_notifications function naughty.destroy_all_notifications(screens, reason) if not screens then screens = {} @@ -323,6 +327,7 @@ end -- -- @param id ID of the notification -- @return notification object if it was found, nil otherwise +-- @staticfct naughty.get_by_id function naughty.get_by_id(id) -- iterate the notifications to get the notfications with the correct ID for s in pairs(naughty.notifications) do diff --git a/lib/wibox/hierarchy.lua b/lib/wibox/hierarchy.lua index e0da295c..a5edddfa 100644 --- a/lib/wibox/hierarchy.lua +++ b/lib/wibox/hierarchy.lua @@ -5,7 +5,7 @@ -- -- @author Uli Schlachter -- @copyright 2015 Uli Schlachter --- @module wibox.hierarchy +-- @classmod wibox.hierarchy --------------------------------------------------------------------------- local matrix = require("gears.matrix") @@ -22,6 +22,7 @@ local widgets_to_count = setmetatable({}, { __mode = "k" }) -- occurrences. Note that for correct operations, the widget must not yet be -- visible in any hierarchy. -- @param widget The widget that should be counted. +-- @staticfct wibox.hierarchy.count_widget function hierarchy.count_widget(widget) widgets_to_count[widget] = true end @@ -203,6 +204,7 @@ end -- hierarchy on widget::layout_changed on some widget. -- @param callback_arg A second argument that is given to the above callbacks. -- @return A new widget hierarchy +-- @constructorfct wibox.hierarchy.new function hierarchy.new(context, widget, width, height, redraw_callback, layout_callback, callback_arg) local result = hierarchy_new(redraw_callback, layout_callback, callback_arg) result:update(context, widget, width, height) @@ -217,6 +219,7 @@ end -- @param[opt] region A region to use for accumulating changed parts -- @return A cairo region describing the changed parts (either the `region` -- argument or a new, internally created region). +-- @method update function hierarchy:update(context, widget, width, height, region) region = region or cairo.Region.create() hierarchy_update(self, context, widget, width, height, region, self._matrix, self._matrix_to_device) @@ -224,6 +227,7 @@ function hierarchy:update(context, widget, width, height, region) end --- Get the widget that this hierarchy manages. +-- @method get_widget function hierarchy:get_widget() return self._widget end @@ -231,6 +235,7 @@ end --- Get a matrix that transforms to the parent's coordinate space from this -- hierarchy's coordinate system. -- @return A matrix describing the transformation. +-- @method get_matrix_to_parent function hierarchy:get_matrix_to_parent() return self._matrix end @@ -239,6 +244,7 @@ end -- system (aka the coordinate system of the device that this -- hierarchy is applied upon) from this hierarchy's coordinate system. -- @return A matrix describing the transformation. +-- @method get_matrix_to_device function hierarchy:get_matrix_to_device() return self._matrix_to_device end @@ -246,6 +252,7 @@ end --- Get a matrix that transforms from the parent's coordinate space into this -- hierarchy's coordinate system. -- @return A matrix describing the transformation. +-- @method get_matrix_from_parent function hierarchy:get_matrix_from_parent() local m = self:get_matrix_to_parent() return m:invert() @@ -255,6 +262,7 @@ end -- system (aka the coordinate system of the device that this -- hierarchy is applied upon) into this hierarchy's coordinate system. -- @return A matrix describing the transformation. +-- @method get_matrix_from_device function hierarchy:get_matrix_from_device() local m = self:get_matrix_to_device() return m:invert() @@ -264,6 +272,7 @@ end -- This includes the size of this element plus the size of all children -- (after applying the corresponding transformation). -- @return x, y, width, height +-- @method get_draw_extents function hierarchy:get_draw_extents() local ext = self._draw_extents return ext.x, ext.y, ext.width, ext.height @@ -271,6 +280,7 @@ end --- Get the size that this hierarchy logically covers (in the current coordinate space). -- @return width, height +-- @method get_size function hierarchy:get_size() local ext = self._size return ext.width, ext.height @@ -278,6 +288,7 @@ end --- Get a list of all children. -- @return List of all children hierarchies. +-- @method get_children function hierarchy:get_children() return self._children end @@ -286,6 +297,7 @@ end -- only works with widgets registered via `count_widget`. -- @param widget The widget that should be counted -- @return The number of times that this widget is contained in this hierarchy. +-- @method get_count function hierarchy:get_count(widget) return self._widget_counts[widget] or 0 end @@ -301,6 +313,7 @@ end -- context. The context's clip is used to skip parts that aren't visible. -- @param context The context in which widgets are drawn. -- @param cr The cairo context that is used for drawing. +-- @method draw function hierarchy:draw(context, cr) local widget = self:get_widget() if not widget._private.visible then diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index a0ddf551..dc8bf5ff 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -18,12 +18,12 @@ local base = {} -- {{{ Functions on widgets ---- Functions available on all widgets. +-- Functions available on all widgets. base.widget = {} --- Set/get a widget's buttons. -- @tab _buttons The table of buttons that is bound to the widget. --- @function buttons +-- @method buttons function base.widget:buttons(_buttons) if _buttons then self._private.widget_buttons = _buttons @@ -33,7 +33,7 @@ end --- Set a widget's visibility. -- @tparam boolean b Whether the widget is visible. --- @function set_visible +-- @method set_visible function base.widget:set_visible(b) if b ~= self._private.visible then self._private.visible = b @@ -45,7 +45,7 @@ end --- Is the widget visible? -- @treturn boolean --- @function get_visible +-- @method get_visible function base.widget:get_visible() return self._private.visible or false end @@ -53,7 +53,7 @@ end --- Set a widget's opacity. -- @tparam number o The opacity to use (a number from 0 (transparent) to 1 -- (opaque)). --- @function set_opacity +-- @method set_opacity function base.widget:set_opacity(o) if o ~= self._private.opacity then self._private.opacity = o @@ -63,7 +63,7 @@ end --- Get the widget's opacity. -- @treturn number The opacity (between 0 (transparent) and 1 (opaque)). --- @function get_opacity +-- @method get_opacity function base.widget:get_opacity() return self._private.opacity end @@ -72,7 +72,7 @@ end -- @tparam[opt] number width With `nil` the default mechanism of calling the -- `:fit` method is used. -- @see fit_widget --- @function set_forced_width +-- @method set_forced_width function base.widget:set_forced_width(width) if width ~= self._private.forced_width then self._private.forced_width = width @@ -88,7 +88,7 @@ end -- actual size is during a `mouse::enter`, `mouse::leave` or button event. -- @treturn[opt] number The forced width (nil if automatic). -- @see fit_widget --- @function get_forced_width +-- @method get_forced_width function base.widget:get_forced_width() return self._private.forced_width end @@ -97,7 +97,7 @@ end -- @tparam[opt] number height With `nil` the default mechanism of calling the -- `:fit` method is used. -- @see fit_widget --- @function set_height +-- @method set_height function base.widget:set_forced_height(height) if height ~= self._private.forced_height then self._private.forced_height = height @@ -112,7 +112,7 @@ end -- If there is no forced width/height, then the only way to get the widget's -- actual size is during a `mouse::enter`, `mouse::leave` or button event. -- @treturn[opt] number The forced height (nil if automatic). --- @function get_forced_height +-- @method get_forced_height function base.widget:get_forced_height() return self._private.forced_height end @@ -121,7 +121,7 @@ end -- -- This method should be re-implemented by the relevant widgets. -- @treturn table The children --- @function get_children +-- @method get_children function base.widget:get_children() return {} end @@ -131,7 +131,7 @@ end -- The default implementation does nothing, this must be re-implemented by -- all layout and container widgets. -- @tab children A table composed of valid widgets. --- @function set_children +-- @method set_children function base.widget:set_children(children) -- luacheck: no unused -- Nothing on purpose end @@ -151,7 +151,7 @@ end -- *Warning*: This method it prone to stack overflow if the widget, or any of -- its children, contains (directly or indirectly) itself. -- @treturn table The children --- @function get_all_children +-- @method get_all_children function base.widget:get_all_children() local ret = {} digg_children(ret, self) @@ -175,7 +175,7 @@ end -- -- @tparam string signal_name -- @param ... Other arguments --- @function emit_signal_recursive +-- @method emit_signal_recursive function base.widget:emit_signal_recursive(signal_name, ...) -- This is a convenience wrapper, the real implementation is in the -- hierarchy. @@ -190,7 +190,7 @@ end -- @treturn number The index. -- @treturn widget The parent widget. -- @treturn table The path between "self" and "widget". --- @function index +-- @method index function base.widget:index(widget, recursive, ...) local widgets = self:get_children() for idx, w in ipairs(widgets) do @@ -261,7 +261,7 @@ end -- -- This gives only tight bounds if no rotations by non-multiples of 90° are -- used. --- @function wibox.widget.base.rect_to_device_geometry +-- @staticfct wibox.widget.base.rect_to_device_geometry function base.rect_to_device_geometry(cr, x, y, width, height) return matrix.transform_rectangle(cr.matrix, x, y, width, height) end @@ -278,7 +278,7 @@ end -- @tparam number height The available height for the widget. -- @treturn number The width that the widget wants to use. -- @treturn number The height that the widget wants to use. --- @function wibox.widget.base.fit_widget +-- @staticfct wibox.widget.base.fit_widget function base.fit_widget(parent, context, widget, width, height) record_dependency(parent, widget) @@ -326,7 +326,7 @@ end -- @tparam number width The available width for the widget. -- @tparam number height The available height for the widget. -- @treturn[opt] table The result from the widget's `:layout` callback. --- @function wibox.widget.base.layout_widget +-- @staticfct wibox.widget.base.layout_widget function base.layout_widget(parent, context, widget, width, height) record_dependency(parent, widget) @@ -346,7 +346,7 @@ end --- Handle a button event on a widget. -- -- This is used internally and should not be called directly. --- @function wibox.widget.base.handle_button +-- @staticfct wibox.widget.base.handle_button function base.handle_button(event, widget, x, y, button, modifiers, geometry) x = x or y -- luacheck: no unused local function is_any(mod) @@ -395,7 +395,7 @@ end -- @tparam number height The height of the widget in its own coordinate system. -- That is, after applying the transformation matrix. -- @treturn table An opaque object that can be returned from `:layout()`. --- @function wibox.widget.base.place_widget_via_matrix +-- @staticfct wibox.widget.base.place_widget_via_matrix function base.place_widget_via_matrix(widget, mat, width, height) return { _widget = widget, @@ -415,7 +415,7 @@ end -- @tparam number height The height of the widget in its own coordinate system. -- That is, after applying the transformation matrix. -- @treturn table An opaque object that can be returned from `:layout()`. --- @function wibox.widget.base.place_widget_at +-- @staticfct wibox.widget.base.place_widget_at function base.place_widget_at(widget, x, y, width, height) return base.place_widget_via_matrix(widget, matrix.create_translate(x, y), width, height) end @@ -535,7 +535,7 @@ end -- -- See [The declarative layout system](../documentation/03-declarative-layout.md.html). -- @tab args A table containing the widget's disposition. --- @function setup +-- @method setup function base.widget:setup(args) local f,ids = self.set_widget or self.add or self.set_first,{} local w, id = drill(ids, args) @@ -562,7 +562,7 @@ end -- -- See [The declarative layout system](../documentation/03-declarative-layout.md.html). -- @tab args A table containing the widgets disposition. --- @function wibox.widget.base.make_widget_declarative +-- @constructorfct wibox.widget.base.make_widget_declarative function base.make_widget_declarative(args) local ids = {} @@ -608,6 +608,7 @@ end -- @param wdg The value. -- @param[opt=nil] ... Arguments passed to the contructor (if any). -- @treturn The new widget. +-- @constructorfct wibox.widget.base.make_widget_from_value function base.make_widget_from_value(wdg, ...) local is_function, t = is_callable(wdg) @@ -635,7 +636,7 @@ end -- and setter methods. -- @tparam[opt=nil] table args.class The widget class -- @see fit_widget --- @function wibox.widget.base.make_widget +-- @constructorfct wibox.widget.base.make_widget function base.make_widget(proxy, widget_name, args) args = args or {} local ret = object { @@ -714,7 +715,7 @@ function base.make_widget(proxy, widget_name, args) end --- Generate an empty widget which takes no space and displays nothing. --- @function wibox.widget.base.empty_widget +-- @constructorfct wibox.widget.base.empty_widget function base.empty_widget() return base.make_widget() end @@ -722,7 +723,7 @@ end --- Do some sanity checking on a widget. -- -- This function raises an error if the widget is not valid. --- @function wibox.widget.base.check_widget +-- @staticfct wibox.widget.base.check_widget function base.check_widget(widget) assert(type(widget) == "table", "Type should be table, but is " .. tostring(type(widget))) assert(widget.is_widget, "Argument is not a widget!") diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index d151e8de..683e8bc7 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -37,6 +37,7 @@ setmetatable(widget, { -- @tparam number width The width of the widget -- @tparam number height The height of the widget -- @tparam[opt={dpi=96}] table context The context information to give to the widget. +-- @staticfct wibox.widget.draw_to_cairo_context function widget.draw_to_cairo_context(wdg, cr, width, height, context) local function no_op() end context = context or {dpi=96} @@ -50,6 +51,7 @@ end -- @tparam number width The surface width -- @tparam number height The surface height -- @tparam[opt={dpi=96}] table context The context information to give to the widget. +-- @staticfct wibox.widget.draw_to_svg_file function widget.draw_to_svg_file(wdg, path, width, height, context) local img = cairo.SvgSurface.create(path, width, height) local cr = cairo.Context(img) @@ -64,6 +66,7 @@ end -- @param[opt=cairo.Format.ARGB32] format The surface format -- @tparam[opt={dpi=96}] table context The context information to give to the widget. -- @return The cairo surface +-- @staticfct wibox.widget.draw_to_image_surface function widget.draw_to_image_surface(wdg, width, height, format, context) local img = cairo.ImageSurface(format or cairo.Format.ARGB32, width, height) local cr = cairo.Context(img) diff --git a/luaa.c b/luaa.c index 803d44d0..e6b07386 100644 --- a/luaa.c +++ b/luaa.c @@ -33,7 +33,7 @@ * * @tparam string name The name of the X11 property. * @tparam string type One of "string", "number" or "boolean". - * @function register_xproperty + * @staticfct register_xproperty */ #define _GNU_SOURCE @@ -216,7 +216,7 @@ composite_manager_running(void) /** Quit awesome. * @tparam[opt=0] integer code The exit code to use when exiting. - * @function quit + * @staticfct quit */ static int luaA_quit(lua_State *L) @@ -233,7 +233,7 @@ luaA_quit(lua_State *L) * awesome. * * @param cmd The command line to execute. - * @function exec + * @staticfct exec */ static int luaA_exec(lua_State *L) @@ -247,7 +247,7 @@ luaA_exec(lua_State *L) } /** Restart awesome. - * @function restart + * @staticfct restart */ static int luaA_restart(lua_State *L) @@ -262,7 +262,7 @@ luaA_restart(lua_State *L) * @tparam integer sig Signal number. * See `awesome.unix_signal` for a list of signals. * @treturn boolean true if the signal was successfully sent, else false - * @function kill + * @staticfct kill */ static int luaA_kill(lua_State *L) @@ -277,7 +277,7 @@ luaA_kill(lua_State *L) /** Synchronize with the X11 server. This is needed in the test suite to avoid * some race conditions. You should never need to use this function. - * @function sync + * @staticfct sync */ static int luaA_sync(lua_State *L) @@ -291,7 +291,7 @@ luaA_sync(lua_State *L) * @param pixbuf The pixbuf as a light user datum. * @param path The pixbuf origin path * @return A cairo surface as light user datum. - * @function pixbuf_to_surface + * @staticfct pixbuf_to_surface */ static int luaA_pixbuf_to_surface(lua_State *L) @@ -310,7 +310,7 @@ luaA_pixbuf_to_surface(lua_State *L) * @return[1] A cairo surface as light user datum. * @return[2] nil * @treturn[2] string Error message - * @function load_image + * @staticfct load_image */ static int luaA_load_image(lua_State *L) @@ -340,7 +340,7 @@ luaA_load_image(lua_State *L) * smaller size is picked. The default is 0 pixels, ie. the smallest icon. * * @param size The size of the icons in pixels. - * @function set_preferred_icon_size + * @staticfct set_preferred_icon_size */ static int luaA_set_preferred_icon_size(lua_State *L) @@ -674,7 +674,7 @@ luaA_awesome_index(lua_State *L) * * @param name A string with the event name. * @param func The function to call. - * @function connect_signal + * @staticfct connect_signal */ static int luaA_awesome_connect_signal(lua_State *L) @@ -689,7 +689,7 @@ luaA_awesome_connect_signal(lua_State *L) * * @param name A string with the event name. * @param func The function to call. - * @function disconnect_signal + * @staticfct disconnect_signal */ static int luaA_awesome_disconnect_signal(lua_State *L) @@ -706,7 +706,7 @@ luaA_awesome_disconnect_signal(lua_State *L) * * @param name A string with the event name. * @param ... The signal arguments. - * @function emit_signal + * @staticfct emit_signal */ static int luaA_awesome_emit_signal(lua_State *L) diff --git a/mouse.c b/mouse.c index 3f2ccf89..c446243a 100644 --- a/mouse.c +++ b/mouse.c @@ -274,7 +274,7 @@ luaA_mouse_coords(lua_State *L) /** Get the client or any object which is under the pointer. * * @treturn client.object|nil A client or nil. - * @function object_under_pointer + * @staticfct object_under_pointer */ static int luaA_mouse_object_under_pointer(lua_State *L) diff --git a/mousegrabber.c b/mousegrabber.c index 5efe7205..abb6b6c8 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -89,7 +89,7 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask) * * @param func A callback function as described above. * @param cursor The name of a X cursor to use while grabbing. - * @function run + * @staticfct run */ static int luaA_mousegrabber_run(lua_State *L) @@ -119,7 +119,7 @@ luaA_mousegrabber_run(lua_State *L) /** Stop grabbing the mouse pointer. * - * @function stop + * @staticfct stop */ int luaA_mousegrabber_stop(lua_State *L) @@ -132,7 +132,7 @@ luaA_mousegrabber_stop(lua_State *L) /** Check if mousegrabber is running. * * @treturn boolean True if running, false otherwise. - * @function isrunning + * @staticfct isrunning */ static int luaA_mousegrabber_isrunning(lua_State *L) diff --git a/objects/button.c b/objects/button.c index 9670b470..892347a9 100644 --- a/objects/button.c +++ b/objects/button.c @@ -45,17 +45,17 @@ /** Get the number of instances. * @treturn int The number of button objects alive. - * @function instances + * @staticfct instances */ /** Set a __index metamethod for all button instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /** Set a __newindex metamethod for all button instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ /** When bound mouse button + modifiers are pressed. diff --git a/objects/client.c b/objects/client.c index 65d9061d..38a45cd6 100644 --- a/objects/client.c +++ b/objects/client.c @@ -932,17 +932,17 @@ /** Get the number of instances. * * @return The number of client objects alive. - * @function instances + * @staticfct instances */ /* Set a __index metamethod for all client instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /* Set a __newindex metamethod for all client instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ typedef enum { @@ -2426,7 +2426,7 @@ client_kill(client_t *c) * @tparam[opt] boolean stacked Return clients in stacking order? (ordered from * top to bottom). * @treturn table A table with clients. - * @function get + * @staticfct get */ static int luaA_client_get(lua_State *L) diff --git a/objects/drawable.c b/objects/drawable.c index 07d15aea..bd6c7892 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -39,7 +39,7 @@ /** Drawable object. * * @field surface The drawable's cairo surface. - * @function drawable + * @staticfct drawable */ /** @@ -89,17 +89,17 @@ /** Get the number of instances. * * @return The number of drawable objects alive. - * @function instances + * @staticfct instances */ /** Set a __index metamethod for all drawable instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /** Set a __newindex metamethod for all drawable instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ static lua_class_t drawable_class; diff --git a/objects/key.c b/objects/key.c index eca16c7f..c42f7446 100644 --- a/objects/key.c +++ b/objects/key.c @@ -74,17 +74,17 @@ /** Get the number of instances. * * @return The number of key objects alive. - * @function instances + * @staticfct instances */ /** Set a __index metamethod for all key instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /** Set a __newindex metamethod for all key instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ static void diff --git a/objects/screen.c b/objects/screen.c index b3e4f81f..05e82375 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -191,17 +191,17 @@ /** Get the number of instances. * * @return The number of screen objects alive. - * @function instances + * @staticfct instances */ /* Set a __index metamethod for all screen instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /* Set a __newindex metamethod for all screen instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ DO_ARRAY(xcb_randr_output_t, randr_output, DO_NOTHING); @@ -1090,7 +1090,7 @@ luaA_screen_module_index(lua_State *L) * for s in screen do * print("Oh, wow, we have screen " .. tostring(s)) * end - * @function screen + * @staticfct screen */ static int luaA_screen_module_call(lua_State *L) @@ -1147,7 +1147,7 @@ luaA_screen_get_workarea(lua_State *L, screen_t *s) /** Get the number of screens. * * @return The screen count, at least 1. - * @function count + * @staticfct count */ static int luaA_screen_count(lua_State *L) diff --git a/objects/tag.c b/objects/tag.c index 7c95aecc..401a66a5 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -240,17 +240,17 @@ /** Get the number of instances. * * @return The number of tag objects alive. - * @function instances + * @staticfct instances */ /* Set a __index metamethod for all tag instances. * @tparam function cb The meta-method - * @function set_index_miss_handler + * @staticfct set_index_miss_handler */ /* Set a __newindex metamethod for all tag instances. * @tparam function cb The meta-method - * @function set_newindex_miss_handler + * @staticfct set_newindex_miss_handler */ @@ -408,10 +408,10 @@ luaA_tag_new(lua_State *L) /** Get or set the clients attached to this tag. * - * @param clients_table None or a table of clients to set as being tagged with + * @tparam[opt=nil] table clients_table None or a table of clients to set as being tagged with * this tag. * @return A table with the clients attached to this tags. - * @function clients + * @method clients */ static int luaA_tag_clients(lua_State *L) diff --git a/root.c b/root.c index 9edef1d5..4da0f660 100644 --- a/root.c +++ b/root.c @@ -223,7 +223,7 @@ _string_to_key_code(const char *s) * "Shift". Here is a list of the "real" key names matching the modifiers in * `fake_input`: * - * + *
* * * @@ -266,7 +266,7 @@ _string_to_key_code(const char *s) * coordinates relatives. * @param x In case of a motion event, this is the X coordinate. * @param y In case of a motion event, this is the Y coordinate. - * @function fake_input + * @staticfct fake_input */ static int luaA_root_fake_input(lua_State *L) @@ -334,7 +334,7 @@ luaA_root_fake_input(lua_State *L) * * @tparam table|nil keys_array An array of key binding objects, or nothing. * @return The array of key bindings objects of this client. - * @function keys + * @staticfct keys */ static int luaA_root_keys(lua_State *L) @@ -374,7 +374,7 @@ luaA_root_keys(lua_State *L) * * @param button_table An array of mouse button bindings objects, or nothing. * @return The array of mouse button bindings objects. - * @function buttons + * @staticfct buttons */ static int luaA_root_buttons(lua_State *L) @@ -413,7 +413,7 @@ luaA_root_buttons(lua_State *L) *@DOC_cursor_c_COMMON@ * * @param cursor_name A X cursor name. - * @function cursor + * @staticfct cursor */ static int luaA_root_cursor(lua_State *L) @@ -439,7 +439,7 @@ luaA_root_cursor(lua_State *L) /** Get the drawins attached to a screen. * * @return A table with all drawins. - * @function drawins + * @staticfct drawins */ static int luaA_root_drawins(lua_State *L) @@ -459,7 +459,7 @@ luaA_root_drawins(lua_State *L) * * @param pattern A cairo pattern as light userdata * @return A cairo surface or nothing. - * @function wallpaper + * @staticfct wallpaper */ static int luaA_root_wallpaper(lua_State *L) @@ -484,7 +484,7 @@ luaA_root_wallpaper(lua_State *L) * * @return Width of the root window. * @return height of the root window. - * @function size + * @staticfct size */ static int luaA_root_size(lua_State *L) @@ -498,7 +498,7 @@ luaA_root_size(lua_State *L) * * @return Width of the root window, in millimeters. * @return height of the root window, in millimeters. - * @function size_mm + * @staticfct size_mm */ static int luaA_root_size_mm(lua_State *L) @@ -510,7 +510,7 @@ luaA_root_size_mm(lua_State *L) /** Get the attached tags. * @return A table with all tags. - * @function tags + * @staticfct tags */ static int luaA_root_tags(lua_State *L) diff --git a/selection.c b/selection.c index ba164c13..ea9582cd 100644 --- a/selection.c +++ b/selection.c @@ -38,7 +38,7 @@ /** Get the selection (clipboard) content. * * @return A string with the selection (clipboard) content. - * @function selection + * @staticfct selection */ static xcb_window_t selection_window = XCB_NONE; diff --git a/spawn.c b/spawn.c index 29eede74..d736d583 100644 --- a/spawn.c +++ b/spawn.c @@ -426,7 +426,7 @@ spawn_child_exited(pid_t pid, int status) * @treturn[1] integer stdout, if `stdout` is true. * @treturn[1] integer stderr, if `stderr` is true. * @treturn[2] string An error string if an error occurred. - * @function spawn + * @staticfct spawn */ int luaA_spawn(lua_State *L) diff --git a/tests/examples/awful/placement/bottom.lua b/tests/examples/awful/placement/bottom.lua index 75ae8ff9..c70ee710 100644 --- a/tests/examples/awful/placement/bottom.lua +++ b/tests/examples/awful/placement/bottom.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name bottom --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.bottom --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/bottom_left.lua b/tests/examples/awful/placement/bottom_left.lua index f4704947..125a0e64 100644 --- a/tests/examples/awful/placement/bottom_left.lua +++ b/tests/examples/awful/placement/bottom_left.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name bottom_left --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.bottom_left --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/bottom_right.lua b/tests/examples/awful/placement/bottom_right.lua index 2c00137e..b0d45082 100644 --- a/tests/examples/awful/placement/bottom_right.lua +++ b/tests/examples/awful/placement/bottom_right.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name bottom_right --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.bottom_right --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/center_horizontal.lua b/tests/examples/awful/placement/center_horizontal.lua index 44f81b7a..1ab1eee2 100644 --- a/tests/examples/awful/placement/center_horizontal.lua +++ b/tests/examples/awful/placement/center_horizontal.lua @@ -3,8 +3,8 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name center_horizontal --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.center_horizontal --DOC_HEADER + screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/center_vertical.lua b/tests/examples/awful/placement/center_vertical.lua index 8e71e770..a867eab2 100644 --- a/tests/examples/awful/placement/center_vertical.lua +++ b/tests/examples/awful/placement/center_vertical.lua @@ -2,8 +2,7 @@ -- Align a client to the vertical center of the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER --- @name center_vertical --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.center_vertical --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/centered.lua b/tests/examples/awful/placement/centered.lua index be9fa5be..c7af1052 100644 --- a/tests/examples/awful/placement/centered.lua +++ b/tests/examples/awful/placement/centered.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name centered --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.centered --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/left.lua b/tests/examples/awful/placement/left.lua index a916b63b..3621383d 100644 --- a/tests/examples/awful/placement/left.lua +++ b/tests/examples/awful/placement/left.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name left --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.left --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_horizontally.lua b/tests/examples/awful/placement/maximize_horizontally.lua index b862e816..7fdf965f 100644 --- a/tests/examples/awful/placement/maximize_horizontally.lua +++ b/tests/examples/awful/placement/maximize_horizontally.lua @@ -2,8 +2,7 @@ -- Horizontally maximize the drawable in the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER --- @name maximize_horizontally --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.maximize_horizontally --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_vertically.lua b/tests/examples/awful/placement/maximize_vertically.lua index a8b177bc..b3758115 100644 --- a/tests/examples/awful/placement/maximize_vertically.lua +++ b/tests/examples/awful/placement/maximize_vertically.lua @@ -2,8 +2,7 @@ -- Vetically maximize the drawable in the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER --- @name maximize_vertically --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.maximize_vertically --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/right.lua b/tests/examples/awful/placement/right.lua index 40c33484..b1f63b66 100644 --- a/tests/examples/awful/placement/right.lua +++ b/tests/examples/awful/placement/right.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name right --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.right --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_down.lua b/tests/examples/awful/placement/stretch_down.lua index 76101bae..e22caf5d 100644 --- a/tests/examples/awful/placement/stretch_down.lua +++ b/tests/examples/awful/placement/stretch_down.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name stretch_down --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.stretch_down --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_left.lua b/tests/examples/awful/placement/stretch_left.lua index d00d511e..db81f765 100644 --- a/tests/examples/awful/placement/stretch_left.lua +++ b/tests/examples/awful/placement/stretch_left.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name stretch_left --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.stretch_left --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_right.lua b/tests/examples/awful/placement/stretch_right.lua index 963f67f0..d217a781 100644 --- a/tests/examples/awful/placement/stretch_right.lua +++ b/tests/examples/awful/placement/stretch_right.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name stretch_right --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.stretch_right --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_up.lua b/tests/examples/awful/placement/stretch_up.lua index 6cf4f1cb..67a2bea7 100644 --- a/tests/examples/awful/placement/stretch_up.lua +++ b/tests/examples/awful/placement/stretch_up.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name stretch_up --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.stretch_up --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/top.lua b/tests/examples/awful/placement/top.lua index 4d8f9d38..60fc1700 100644 --- a/tests/examples/awful/placement/top.lua +++ b/tests/examples/awful/placement/top.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name top --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.top --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/top_left.lua b/tests/examples/awful/placement/top_left.lua index 87ae8472..339bd9e1 100644 --- a/tests/examples/awful/placement/top_left.lua +++ b/tests/examples/awful/placement/top_left.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name top_left --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.top_left --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/tests/examples/awful/placement/top_right.lua b/tests/examples/awful/placement/top_right.lua index 952bdfd2..2df7c70a 100644 --- a/tests/examples/awful/placement/top_right.lua +++ b/tests/examples/awful/placement/top_right.lua @@ -3,8 +3,7 @@ -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @treturn table The new geometry --DOC_HEADER --- @name top_right --DOC_HEADER --- @class function --DOC_HEADER +-- @staticfct awful.placement.top_right --DOC_HEADER screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE diff --git a/xkb.c b/xkb.c index 04dd3b59..40b98f8e 100644 --- a/xkb.c +++ b/xkb.c @@ -36,7 +36,7 @@ /** * Switch keyboard layout. * - * @function xkb_set_layout_group + * @staticfct xkb_set_layout_group * @tparam integer num keyboard layout number, integer from 0 to 3 */ int @@ -56,7 +56,7 @@ luaA_xkb_set_layout_group(lua_State *L) /** * Get current layout number. * - * @function xkb_get_layout_group + * @staticfct xkb_get_layout_group * @treturn integer num Current layout number, integer from 0 to 3. */ int @@ -87,7 +87,7 @@ luaA_xkb_get_layout_group(lua_State *L) /** * Get layout short names. * - * @function xkb_get_group_names + * @staticfct xkb_get_group_names * @treturn string A string describing the current layout settings, * e.g.: 'pc+us+de:2+inet(evdev)+group(alt_shift_toggle)+ctrl(nocaps)' */ From 4ce6179d786062f1869b271bf27dedf3f0561576 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 7 Jun 2019 19:17:02 -0400 Subject: [PATCH 19/23] doc: Standardize how the @field are dsiplayed. Always add the module name. Until now some had it and some didn't. --- docs/config.ld | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 764989fa..8d301e76 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -199,6 +199,7 @@ local add_mod = { constructorfct = true, staticfct = true, deprecated = true, + field = true, } -- Add the arguments. @@ -225,8 +226,12 @@ custom_display_name_handler = function(item, default_handler) -- more consistent. Right now some have their full awful.foo.bar while other -- have "just" `bar`. Given we use constructors from metatables, we have no -- choice but to use the full function name. It also makes copy/paste easier. - if add_mod[item.type] and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then - ret = item.module.name .. "." .. ret + if add_mod[item.type] then + if (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then + ret = item.module.name .. "." .. ret + elseif item.type == "field" and ret:sub(1, #item.module.name) ~= item.module.name then + ret = item.module.name .. "." .. ret + end end if item.type == "deprecated" or item.type == "deprecatedproperty" then From 43799aec02315b82596a92ec7cd7672aa79dd0b7 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 7 Jun 2019 19:20:48 -0400 Subject: [PATCH 20/23] doc: Hardcode the header instead of using "machine readable". "classmod" is not useful for a humain. --- docs/ldoc.ltp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index f7a7501e..67dcdedf 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -87,7 +87,7 @@ # if ldoc.body then -- verbatim HTML as contents; 'non-code' entries $(ldoc.body) # elseif module then -- module documentation -

$(ldoc.module_typename(module)) $(module.name)

+

Module: $(module.name)

$(M(module.summary,module))

$(M(module.description,module))

# if module.tags.include then From 12a7236e2b3ec4fa65ae56029957301f0c46ea90 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 7 Jun 2019 22:53:36 -0400 Subject: [PATCH 21/23] doc: Add support for property types to ldoc. Rather that abusing of how the arguments are displayed to convey the type, add native support. It still uses the @param for the doc, so this doesn't cause a million little noisy changes, but the rendered HTML now have a real section for the type. This is added to both the summary and the expanded description. Additionally, if the type has a description string, a second is added. --- docs/config.ld | 51 +++++++++++++++++++++++++++++++++++++++++++++++--- docs/ldoc.css | 19 +++++++++++++++++++ docs/ldoc.ltp | 14 ++++++++++++-- 3 files changed, 79 insertions(+), 5 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 8d301e76..7ad68762 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -60,9 +60,9 @@ new_type("function", "Functions", false, "Parameters") -- @function and its implicit cousin to be banned in the CI. new_type("staticfct", "Static module functions", false, "Parameters") -- Documentation for objects properties -new_type("property", "Object properties", false, "Type") +new_type("property", "Object properties", false, "Type constraints") -- Documentation for objects deprecated properties -new_type("deprecatedproperty", "Deprecated object properties", false, "Type") +new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints") -- 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) @@ -72,7 +72,7 @@ new_type("signal", "Signals", false, "Arguments") -- New type for signals connections new_type("signalhandler", "Request handlers", false, "Arguments") -- Allow objects to define a set of beautiful properties affecting them -new_type("beautiful", "Theme variables", false, "Type") +new_type("beautiful", "Theme variables", false, "Type constraints") -- Put deprecated methods in their own section new_type("deprecated", "Deprecated functions", false, "Parameters") -- For the legacy stateless layout related functions @@ -180,6 +180,37 @@ local function render_methods(item) return ret .. (item.args and " "..item.args or "") end +-- Parse the magic parameters to type concention in something the template eats. +local function sanitize_type(item, ldoc) + + for parm in ldoc.modules.iter(item.params) do + local t = item:type_of_param(parm) + + -- Remove the value. + t = t:gsub("(\\[[^\\]]])","") + t = t:gsub("?","") + + -- Add " or " between alternatives + t = t:gsub("|"," or ") + + -- Fallback. + t = t == "" and parm or t + t = t == "" and "N/A" or t + + item.display_type = ""..t.."" + + -- There is no value in repeating the type a second time. + if item.params.map[parm] == "" then + item.hide_params = true + end + + if t ~= "N/A" then return end + end + + -- It has to be set, otherwise the table will have different col count. + item.display_type = "N/A" +end + local no_prefix = { property = true, signal = true, clientruleproperty = true, deprecatedproperty = true, @@ -208,9 +239,23 @@ local add_args = { staticfct = true, } +-- Add a type column to the summary and type field in the description. +local display_type = { + property = true, + beautiful = true, + field = true, + deprecatedproperty = true, +} + custom_display_name_handler = function(item, default_handler) local ret = default_handler(item) + -- Edit the input so the template is notified. + if display_type[item.type] then + -- Punch a hole in the sandbox and inject the `ldoc` object. + item.sanitize_type = sanitize_type + end + -- Remove the "namespace" from the signals and properties if no_prefix[item.type] then local name = item.name:match("%.([^.]+)$") diff --git a/docs/ldoc.css b/docs/ldoc.css index db42a48e..4a4412e4 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -290,6 +290,25 @@ table.module_list td.summary, table.function_list td.summary { border-left-width: 0px; } +table.function_list td.shortname { + background-color: white; + border-right-width: 0px; +} + +.proptype { + padding-right: 20px; + float: right; +} + +td.summarytype { + background-color: white; + color: #a4c7ff; + font-size: 85%; + border-left: none; + border-right: none; + text-align: right; +} + dl.function { margin-right: 15px; margin-left: 15px; diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 67dcdedf..fa9bd49d 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -127,8 +127,15 @@

$(kind)

Modifier name Key name
# for item in items() do +# local dn = display_name(item) +# if item.sanitize_type then item.sanitize_type(item, ldoc) end - +# if item.display_type then + + +# else + +# end # end -- for items @@ -165,6 +172,9 @@
$(display_name(item)) +# if item.display_type then + ($(item.display_type)) +# end # if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then line $(item.lineno) # end @@ -187,7 +197,7 @@ # end -- iter tags # end -# if show_parms and item.params and #item.params > 0 then +# if show_parms and item.params and #item.params > 0 and not item.hide_params then # local subnames = module.kinds:type_of(item).subnames # if subnames then

$(subnames):

From 90a29f92eb419e964d3e35157beb989e0446af00 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 8 Jun 2019 00:15:59 -0400 Subject: [PATCH 22/23] doc: Fix all the property, theme and field types. --- docs/common/wibox.ldoc | 4 + lib/awful/hotkeys_popup/widget.lua | 5 +- lib/awful/keygrabber.lua | 2 + lib/awful/menu.lua | 1 + lib/awful/screen.lua | 4 +- lib/awful/tag.lua | 2 +- lib/awful/titlebar.lua | 144 +++++++++++----------- lib/awful/tooltip.lua | 16 ++- lib/awful/util.lua | 1 + lib/awful/widget/taglist.lua | 10 +- lib/beautiful/init.lua | 18 +++ lib/gears/matrix.lua | 1 + lib/menubar/init.lua | 5 + lib/menubar/utils.lua | 2 + lib/naughty/action.lua | 2 +- lib/naughty/notification.lua | 1 + lib/wibox/container/arcchart.lua | 6 + lib/wibox/container/constraint.lua | 1 + lib/wibox/container/radialprogressbar.lua | 7 ++ lib/wibox/layout/align.lua | 4 + lib/wibox/layout/fixed.lua | 1 + lib/wibox/widget/checkbox.lua | 21 +++- lib/wibox/widget/graph.lua | 3 + lib/wibox/widget/imagebox.lua | 2 +- lib/wibox/widget/progressbar.lua | 10 ++ lib/wibox/widget/separator.lua | 2 +- lib/wibox/widget/textbox.lua | 1 + 27 files changed, 187 insertions(+), 89 deletions(-) diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc index b60cb511..a48b7530 100644 --- a/docs/common/wibox.ldoc +++ b/docs/common/wibox.ldoc @@ -217,10 +217,12 @@ --- The default background color. -- @beautiful beautiful.bg_normal +-- @param color -- @see bg --- The default foreground (text) color. -- @beautiful beautiful.fg_normal +-- @param color -- @see fg --- Set a declarative widget hierarchy description. @@ -232,6 +234,7 @@ -- @param c The background to use. This must either be a cairo pattern object, -- nil or a string that gears.color() understands. -- @property bg +-- @param color -- @see gears.color --- The background image of the drawable. @@ -245,6 +248,7 @@ -- @param c The foreground to use. This must either be a cairo pattern object, -- nil or a string that gears.color() understands. -- @property fg +-- @param color -- @see gears.color --- Find a widget by a point. diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index 1068c16e..a3aeab25 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -49,13 +49,16 @@ local widget = { } --- Don't show hotkeys without descriptions. +-- @tfield boolean widget.hide_without_description +-- @param boolean widget.hide_without_description = true --- Merge hotkey records into one if they have the same modifiers and -- description. +-- @tfield boolean widget.merge_duplicates +-- @param boolean widget.merge_duplicates = true - --- Hotkeys widget background color. -- @beautiful beautiful.hotkeys_bg -- @tparam color hotkeys_bg diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index 4c94e66d..2d076c67 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -314,6 +314,7 @@ end -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@ -- -- @property timeout +-- @param number -- @see gears.timer -- @see timeout_callback @@ -393,6 +394,7 @@ end -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@ -- -- @property root_keybindings +-- @param table -- @see export_keybindings -- @see keybindings diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index cc1d29ac..ee7acc9b 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -50,6 +50,7 @@ end --- The icon used for sub-menus. -- @beautiful beautiful.menu_submenu_icon +-- @tparam string|gears.surface menu_submenu_icon --- The menu text font. -- @beautiful beautiful.menu_font diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index b9043f97..443b6417 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -248,7 +248,7 @@ function screen.preferred(c) end --- The defaults arguments for `awful.screen.focused`. --- @tfield[opt=nil] table awful.screen.default_focused_args +-- @tfield[opt={}] table awful.screen.default_focused_args --- Get the focused screen. -- @@ -537,7 +537,7 @@ end --- The number of pixels per inch of the screen. -- @property dpi --- @treturn number the DPI value. +-- @param number the DPI value. local xft_dpi, fallback_dpi diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index de66251b..d54f0c29 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -742,7 +742,7 @@ end -- -- awful.layout.suit.corner.se, -- } -- --- @field awful.tag.layouts +-- @tfield table awful.tag.layouts --- The tag client layout. -- diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 60e602c0..1aabd66f 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -38,9 +38,11 @@ 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. @@ -55,7 +57,7 @@ local titlebar = { --- The titlebar background image image. -- @beautiful beautiful.titlebar_bgimage_normal --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- The titlebar foreground (text) color. @@ -70,7 +72,7 @@ local titlebar = { --- The titlebar background image image. -- @beautiful beautiful.titlebar_bgimage --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- The focused titlebar foreground (text) color. @@ -85,347 +87,347 @@ local titlebar = { --- The focused titlebar background image image. -- @beautiful beautiful.titlebar_bgimage_focus --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_normal. -- @beautiful beautiful.titlebar_floating_button_normal --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_normal. -- @beautiful beautiful.titlebar_maximized_button_normal --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- minimize_button_normal. -- @beautiful beautiful.titlebar_minimize_button_normal --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- minimize_button_normal_hover. -- @beautiful beautiful.titlebar_minimize_button_normal_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- minimize_button_normal_press. -- @beautiful beautiful.titlebar_minimize_button_normal_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- close_button_normal. -- @beautiful beautiful.titlebar_close_button_normal --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- close_button_normal_hover. -- @beautiful beautiful.titlebar_close_button_normal_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- close_button_normal_press. -- @beautiful beautiful.titlebar_close_button_normal_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_normal. -- @beautiful beautiful.titlebar_ontop_button_normal --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_normal. -- @beautiful beautiful.titlebar_sticky_button_normal --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_focus. -- @beautiful beautiful.titlebar_floating_button_focus --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_focus. -- @beautiful beautiful.titlebar_maximized_button_focus --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- minimize_button_focus. -- @beautiful beautiful.titlebar_minimize_button_focus --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- minimize_button_focus_hover. -- @beautiful beautiful.titlebar_minimize_button_focus_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- minimize_button_focus_press. -- @beautiful beautiful.titlebar_minimize_button_focus_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- close_button_focus. -- @beautiful beautiful.titlebar_close_button_focus --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- close_button_focus_hover. -- @beautiful beautiful.titlebar_close_button_focus_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- close_button_focus_press. -- @beautiful beautiful.titlebar_close_button_focus_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_focus. -- @beautiful beautiful.titlebar_ontop_button_focus --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_focus. -- @beautiful beautiful.titlebar_sticky_button_focus --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_normal_active. -- @beautiful beautiful.titlebar_floating_button_normal_active --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_normal_active_hover. -- @beautiful beautiful.titlebar_floating_button_normal_active_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_normal_active_press. -- @beautiful beautiful.titlebar_floating_button_normal_active_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_normal_active. -- @beautiful beautiful.titlebar_maximized_button_normal_active --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_normal_active_hover. -- @beautiful beautiful.titlebar_maximized_button_normal_active_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_normal_active_press. -- @beautiful beautiful.titlebar_maximized_button_normal_active_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_normal_active. -- @beautiful beautiful.titlebar_ontop_button_normal_active --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_normal_active_hover. -- @beautiful beautiful.titlebar_ontop_button_normal_active_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_normal_active_press. -- @beautiful beautiful.titlebar_ontop_button_normal_active_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_normal_active. -- @beautiful beautiful.titlebar_sticky_button_normal_active --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_normal_active_hover. -- @beautiful beautiful.titlebar_sticky_button_normal_active_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_normal_active_press. -- @beautiful beautiful.titlebar_sticky_button_normal_active_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_focus_active. -- @beautiful beautiful.titlebar_floating_button_focus_active --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_focus_active_hover. -- @beautiful beautiful.titlebar_floating_button_focus_active_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_focus_active_press. -- @beautiful beautiful.titlebar_floating_button_focus_active_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_focus_active. -- @beautiful beautiful.titlebar_maximized_button_focus_active --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_focus_active_hover. -- @beautiful beautiful.titlebar_maximized_button_focus_active_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_focus_active_press. -- @beautiful beautiful.titlebar_maximized_button_focus_active_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_focus_active. -- @beautiful beautiful.titlebar_ontop_button_focus_active --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_focus_active_hover. -- @beautiful beautiful.titlebar_ontop_button_focus_active_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_focus_active_press. -- @beautiful beautiful.titlebar_ontop_button_focus_active_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_focus_active. -- @beautiful beautiful.titlebar_sticky_button_focus_active --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_focus_active_hover. -- @beautiful beautiful.titlebar_sticky_button_focus_active_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_focus_active_press. -- @beautiful beautiful.titlebar_sticky_button_focus_active_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_normal_inactive. -- @beautiful beautiful.titlebar_floating_button_normal_inactive --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_normal_inactive_hover. -- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_normal_inactive_press. -- @beautiful beautiful.titlebar_floating_button_normal_inactive_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_normal_inactive. -- @beautiful beautiful.titlebar_maximized_button_normal_inactive --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_normal_inactive_hover. -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_normal_inactive_press. -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_normal_inactive. -- @beautiful beautiful.titlebar_ontop_button_normal_inactive --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_normal_inactive_hover. -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_normal_inactive_press. -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_normal_inactive. -- @beautiful beautiful.titlebar_sticky_button_normal_inactive --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_normal_inactive_hover. -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_normal_inactive_press. -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_focus_inactive. -- @beautiful beautiful.titlebar_floating_button_focus_inactive --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_focus_inactive_hover. -- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- floating_button_focus_inactive_press. -- @beautiful beautiful.titlebar_floating_button_focus_inactive_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_focus_inactive. -- @beautiful beautiful.titlebar_maximized_button_focus_inactive --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_focus_inactive_hover. -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- maximized_button_focus_inactive_press. -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_focus_inactive. -- @beautiful beautiful.titlebar_ontop_button_focus_inactive --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_focus_inactive_hover. -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- ontop_button_focus_inactive_press. -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_focus_inactive. -- @beautiful beautiful.titlebar_sticky_button_focus_inactive --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_focus_inactive_hover. -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- sticky_button_focus_inactive_press. -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press --- @param surface +-- @tparam gears.surface|string path -- @see gears.surface --- Set a declarative widget hierarchy description. diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index 930010ad..44363d3d 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -86,27 +86,34 @@ local offset = { --- The tooltip border color. -- @beautiful beautiful.tooltip_border_color +-- @param color --- The tooltip background color. -- @beautiful beautiful.tooltip_bg +-- @param color --- The tooltip foregound (text) color. -- @beautiful beautiful.tooltip_fg +-- @param color --- The tooltip font. -- @beautiful beautiful.tooltip_font +-- @param string --- The tooltip border width. -- @beautiful beautiful.tooltip_border_width +-- @param number --- The tooltip opacity. -- @beautiful beautiful.tooltip_opacity +-- @param number opacity Between 0 and 1 --- The default tooltip shape. --- The default shape for all tooltips is a rectangle. However, by setting this variable --- they can default to rounded rectangle or stretched octogons. +-- The default shape for all tooltips is a rectangle. However, by setting +-- this variable they can default to rounded rectangle or stretched octogons. -- @beautiful beautiful.tooltip_shape --- @tparam[opt=gears.shape.rectangle] function shape A `gears.shape` compatible function +-- @tparam[opt=gears.shape.rectangle] gears.shape shape A `gears.shape` +-- compatible function -- @see shape -- @see gears.shape @@ -251,6 +258,7 @@ end -- * top -- -- @property align +-- @param string -- @see beautiful.tooltip_align -- @see mode -- @see preferred_positions @@ -280,6 +288,7 @@ end -- @DOC_awful_tooltip_shape_EXAMPLE@ -- -- @property shape +-- @tparam gears.shape shape -- @see gears.shape -- @see beautiful.tooltip_shape @@ -466,6 +475,7 @@ end -- @DOC_awful_tooltip_border_color_EXAMPLE@ -- -- @property border_color +-- @param color -- @param gears.color function tooltip:set_border_color(val) diff --git a/lib/awful/util.lua b/lib/awful/util.lua index d0a14d1f..c9d13f6a 100644 --- a/lib/awful/util.lua +++ b/lib/awful/util.lua @@ -31,6 +31,7 @@ local util = {} util.table = {} --- The default shell used when spawing processes. +-- @param string util.shell = os.getenv("SHELL") or "/bin/sh" --- Execute a system command and road the output. diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index 8be36dc5..4b39d4e9 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -153,7 +153,7 @@ taglist.filter, taglist.source = {}, {} -- This will be the fallback for state specific shapes. -- To get a shape for the whole taglist, use `wibox.container.background`. -- @beautiful beautiful.taglist_shape --- @param[opt=rectangle] gears.shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape -- @see beautiful.taglist_shape_empty -- @see beautiful.taglist_shape_focus @@ -172,7 +172,7 @@ taglist.filter, taglist.source = {}, {} --- The shape used for the empty elements. -- @beautiful beautiful.taglist_shape_empty --- @param[opt=rectangle] gears.shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The shape used for the empty elements border width. @@ -187,7 +187,7 @@ taglist.filter, taglist.source = {}, {} --- The shape used for the selected elements. -- @beautiful beautiful.taglist_shape_focus --- @param[opt=rectangle] gears.shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The shape used for the selected elements border width. @@ -202,7 +202,7 @@ taglist.filter, taglist.source = {}, {} --- The shape used for the urgent elements. -- @beautiful beautiful.taglist_shape_urgent --- @param[opt=rectangle] gears.shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The shape used for the urgent elements border width. @@ -217,7 +217,7 @@ taglist.filter, taglist.source = {}, {} --- The shape used for the volatile elements. -- @beautiful beautiful.taglist_shape_volatile --- @param[opt=rectangle] gears.shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The shape used for the volatile elements border width. diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index 5ab2d582..63ced04b 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -89,34 +89,44 @@ local active_font --- The default font. -- @beautiful beautiful.font +-- @param string -- The default background color. -- @beautiful beautiful.bg_normal +-- @param color -- The default focused element background color. -- @beautiful beautiful.bg_focus +-- @param color -- The default urgent element background color. -- @beautiful beautiful.bg_urgent +-- @param 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. -- @beautiful beautiful.fg_normal +-- @param color -- The default focused element foreground (text) color. -- @beautiful beautiful.fg_focus +-- @param color -- The default urgent element foreground (text) color. -- @beautiful beautiful.fg_urgent +-- @param color -- The default minimized element foreground (text) color. -- @beautiful beautiful.fg_minimize +-- @param color --- The gap between clients. -- @beautiful beautiful.useless_gap @@ -124,31 +134,39 @@ local active_font --- The client border width. -- @beautiful beautiful.border_width +-- @param number --- The default clients border color. -- Note that only solid colors are supported. -- @beautiful beautiful.border_normal +-- @param color --- The focused client border color. -- Note that only solid colors are supported. -- @beautiful beautiful.border_focus +-- @param color --- The marked clients border color. -- Note that only solid colors are supported. -- @beautiful beautiful.border_marked +-- @param color --- The wallpaper path. -- @beautiful beautiful.wallpaper +-- @tparam string|gears.surface wallpaper -- 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 --- The Awesome icon path. -- @beautiful beautiful.awesome_icon +-- @tparam string|gears.surface icon --- The current theme path (if any) -- @tfield string beautiful.theme_path +-- @param string --- Load a font from a string or a font description. -- diff --git a/lib/gears/matrix.lua b/lib/gears/matrix.lua index f66a4004..92878256 100644 --- a/lib/gears/matrix.lua +++ b/lib/gears/matrix.lua @@ -217,6 +217,7 @@ matrix_mt.__mul = matrix.multiply matrix_mt.__tostring = matrix.tostring --- A constant for the identity matrix. +-- @param matrix matrix.identity = matrix.create(1, 0, 0, 1, 0, 0) return matrix diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index 16cf5d5b..c76b58a6 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -48,9 +48,11 @@ end --- Menubar normal text color. -- @beautiful beautiful.menubar_fg_normal +-- @param color --- Menubar normal background color. -- @beautiful beautiful.menubar_bg_normal +-- @param color --- Menubar border width. -- @beautiful beautiful.menubar_border_width @@ -58,12 +60,15 @@ end --- Menubar border color. -- @beautiful beautiful.menubar_border_color +-- @param color --- Menubar selected item text color. -- @beautiful beautiful.menubar_fg_normal +-- @param color --- Menubar selected item background color. -- @beautiful beautiful.menubar_bg_normal +-- @param color -- menubar diff --git a/lib/menubar/utils.lua b/lib/menubar/utils.lua index ae081747..b112397a 100644 --- a/lib/menubar/utils.lua +++ b/lib/menubar/utils.lua @@ -32,6 +32,7 @@ local utils = {} -- Options section --- Terminal which applications that need terminal would open in. +-- @param[opt="xterm"] string utils.terminal = 'xterm' --- The default icon for applications that don't provide any icon in @@ -39,6 +40,7 @@ utils.terminal = 'xterm' local default_icon = nil --- Name of the WM for the OnlyShowIn entry in the .desktop file. +-- @param[opt="awesome"] string utils.wm_name = "awesome" -- Maps keys in desktop entries to suitable getter function. diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index bf98e712..28e0de03 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -41,7 +41,7 @@ local action = {} --- The action icon. -- @property icon --- @param gears.surface +-- @tparam gears.surface|string icon --- The notification. -- @property notification diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 4e00d58f..d7f2a77c 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -163,6 +163,7 @@ local notification = {} --- Widget shape. --@DOC_naughty_shape_EXAMPLE@ -- @property shape +-- @param gears.shape --- Widget opacity. -- @property opacity diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index 5b5f495a..2c5a0551 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -22,12 +22,15 @@ local arcchart = { mt = {} } --- The progressbar border background color. -- @beautiful beautiful.arcchart_border_color +-- @param color --- The progressbar foreground color. -- @beautiful beautiful.arcchart_color +-- @param color --- The progressbar border width. -- @beautiful beautiful.arcchart_border_width +-- @param number --- The padding between the outline and the progressbar. -- @beautiful beautiful.arcchart_paddings @@ -233,6 +236,7 @@ end --- The border background color. --@DOC_wibox_container_arcchart_border_color_EXAMPLE@ -- @property border_color +-- @param color --- The arcchart values foreground colors. --@DOC_wibox_container_arcchart_color_EXAMPLE@ @@ -246,9 +250,11 @@ end --- The minimum value. -- @property min_value +-- @param number --- The maximum value. -- @property max_value +-- @param number --- The radial background. --@DOC_wibox_container_arcchart_bg_EXAMPLE@ diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index 0d937707..756ddb03 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -62,6 +62,7 @@ end --- Set the strategy to use for the constraining. Valid values are 'max', -- 'min' or 'exact'. Throws an error on invalid values. -- @property strategy +-- @tparam string strategy Either 'max', 'min' or 'exact' function constraint:set_strategy(val) local func = { diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index 3d698792..b7bfa055 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -24,12 +24,15 @@ local radialprogressbar = { mt = {} } --- The progressbar border background color. -- @beautiful beautiful.radialprogressbar_border_color +-- @param color --- The progressbar foreground color. -- @beautiful beautiful.radialprogressbar_color +-- @param color --- The progressbar border width. -- @beautiful beautiful.radialprogressbar_border_width +-- @param number --- The padding between the outline and the progressbar. -- @beautiful beautiful.radialprogressbar_paddings @@ -190,10 +193,12 @@ end --- The border background color. --@DOC_wibox_container_radialprogressbar_border_color_EXAMPLE@ -- @property border_color +-- @param color --- The border foreground color. --@DOC_wibox_container_radialprogressbar_color_EXAMPLE@ -- @property color +-- @param color --- The border width. --@DOC_wibox_container_radialprogressbar_border_width_EXAMPLE@ @@ -202,9 +207,11 @@ end --- The minimum value. -- @property min_value +-- @param number --- The maximum value. -- @property max_value +-- @param number for _, prop in ipairs {"max_value", "min_value", "border_color", "color", "border_width", "paddings"} do diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index 283a395e..766c774e 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -142,6 +142,7 @@ end --- Set the layout's first widget. -- This is the widget that is at the left/top -- @property first +-- @param widget function align:set_first(widget) if self._private.first == widget then @@ -153,6 +154,7 @@ end --- Set the layout's second widget. This is the centered one. -- @property second +-- @param widget function align:set_second(widget) if self._private.second == widget then @@ -165,6 +167,7 @@ end --- Set the layout's third widget. -- This is the widget that is at the right/bottom -- @property third +-- @param widget function align:set_third(widget) if self._private.third == widget then @@ -184,6 +187,7 @@ end -- This can be used to replace all 3 widgets at once. -- @treturn table a list of all widgets -- @property children +-- @param table function align:get_children() return gtable.from_sparse {self._private.first, self._private.second, self._private.third} diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index aedfbeac..c9d2e74c 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -291,6 +291,7 @@ end -- widget will get all the space that is left. If this is false, the last widget -- won't be handled specially and there can be space left unused. -- @property fill_space +-- @param boolean function fixed:fill_space(val) if self._private.fill_space ~= val then diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index efe10ec4..53571ca4 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -21,29 +21,37 @@ local checkbox = {} --- The outer (unchecked area) border width. -- @beautiful beautiful.checkbox_border_width +-- @param number --- The outer (unchecked area) background color, pattern or gradient. -- @beautiful beautiful.checkbox_bg +-- @param color --- The outer (unchecked area) border color. -- @beautiful beautiful.checkbox_border_color +-- @param color --- The checked part border color. -- @beautiful beautiful.checkbox_check_border_color +-- @param color --- The checked part border width. -- @beautiful beautiful.checkbox_check_border_width +-- @param number --- The checked part filling color. -- @beautiful beautiful.checkbox_check_color +-- @param number --- The outer (unchecked area) shape. -- @beautiful beautiful.checkbox_shape +-- @tparam gears.shape shape -- @see gears.shape --- The checked part shape. -- If none is set, then the `shape` property will be used. -- @beautiful beautiful.checkbox_check_shape +-- @tparam gears.shape shape -- @see gears.shape --- The padding between the outline and the progressbar. @@ -59,35 +67,44 @@ local checkbox = {} -- filling color. Note that `check_color` and `border_color` have priority -- over this property. -- @beautiful beautiful.checkbox_color +-- @param color --- The outer (unchecked area) border width. -- @property border_width +-- @param number --- The outer (unchecked area) background color, pattern or gradient. --@DOC_wibox_widget_checkbox_bg_EXAMPLE@ -- @property bg +-- @param color --- The outer (unchecked area) border color. -- @property border_color +-- @param color --- The checked part border color. -- @property check_border_color +-- @param color --- The checked part border width. -- @property check_border_width +-- @param number --- The checked part filling color. -- @property check_color +-- @param color --- The outer (unchecked area) shape. --@DOC_wibox_widget_checkbox_shape_EXAMPLE@ -- @property shape +-- @tparam gears.shape shape -- @see gears.shape --- The checked part shape. -- 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 -- @see gears.shape --- The padding between the outline and the progressbar. @@ -103,6 +120,7 @@ local checkbox = {} -- filling color. Note that `check_color` and `border_color` have priority -- over this property. -- @property color +-- @param color local function outline_workarea(self, width, height) local offset = (self._private.border_width or @@ -210,9 +228,6 @@ for _, prop in ipairs {"border_width", "bg", "border_color", "check_border_color end end ---- The checkbox color. --- @property color - function checkbox:set_paddings(val) self._private.paddings = type(val) == "number" and { left = val, diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index 0482969f..3747a2a9 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -97,12 +97,15 @@ local graph = { mt = {} } --- The graph background color. -- @beautiful beautiful.graph_bg +-- @param color --- The graph foreground color. -- @beautiful beautiful.graph_fg +-- @param color --- The graph border color. -- @beautiful beautiful.graph_border_color +-- @param color local properties = { "width", "height", "border_color", "stack", "stack_colors", "color", "background_color", diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index 61e35f8c..76ee97a2 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -119,7 +119,7 @@ end -- is trimmed. -- -- @property clip_shape --- @tparam function clip_shape A `gears_shape` compatible shape function +-- @tparam gears.shape clip_shape A `gears_shape` compatible shape function -- @see gears.shape -- @see set_clip_shape diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index d6497476..0eb2bc62 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -41,6 +41,7 @@ local progressbar = { mt = {} } --- The progressbar border width. -- @property border_width +-- @param number --- The progressbar inner border color. -- If the value is nil, no border will be drawn. @@ -51,6 +52,7 @@ local progressbar = { mt = {} } --- The progressbar inner border width. -- @property bar_border_width +-- @param number --- The progressbar foreground color. -- @@ -114,29 +116,37 @@ local progressbar = { mt = {} } --- The progressbar background color. -- @beautiful beautiful.progressbar_bg +-- @param color --- The progressbar foreground color. -- @beautiful beautiful.progressbar_fg +-- @param color --- The progressbar shape. -- @beautiful beautiful.progressbar_shape +-- @tparam gears.shape shape -- @see gears.shape --- The progressbar border color. -- @beautiful beautiful.progressbar_border_color +-- @param color --- The progressbar outer border width. -- @beautiful beautiful.progressbar_border_width +-- @param number --- The progressbar inner shape. -- @beautiful beautiful.progressbar_bar_shape +-- @tparam gears.shape shape -- @see gears.shape --- The progressbar bar border width. -- @beautiful beautiful.progressbar_bar_border_width +-- @param number --- The progressbar bar border color. -- @beautiful beautiful.progressbar_bar_border_color +-- @param color --- The progressbar margins. -- Note that if the `clip` is disabled, this allows the background to be smaller diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index a02e8433..e56f9ba7 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -87,7 +87,7 @@ local separator = {} --- The separator border color. -- @beautiful beautiful.separator_border_color --- @param gears.color +-- @param color -- @see border_color --- The separator border width. diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index 6c70d6eb..2bb9998d 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -20,6 +20,7 @@ local textbox = { mt = {} } --- The textbox font. -- @beautiful beautiful.font +-- @param string --- Set the DPI of a Pango layout local function setup_dpi(box, dpi) From 3e3a298a3332ab6e8b458a179701b0fc2afeb61c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 8 Jun 2019 00:35:02 -0400 Subject: [PATCH 23/23] doc: Shape the methods and functions arguments in the summary. Given the full prototype can be quite long with all the optional argument definition, better help the eyes focus on the important part. --- docs/config.ld | 25 +++++++++++++++++++++---- docs/ldoc.css | 6 ++++++ 2 files changed, 27 insertions(+), 4 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 7ad68762..64bf0cb2 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -165,6 +165,21 @@ file = { } } +-- Wrap the module name for the CSS highlight. +local function wrap_modname(str, item) + if (not item.module) or str:sub(1, #item.module.name+1) ~= item.module.name.."." then return str end + + return ""..item.module.name.."." + .. str:sub(#item.module.name+2, 9999) +end + +-- Wrap the arguments for the CSS highlight. +local function wrap_args(item) + if not item.args then return "" end + return ""..item.args.."" +end + + -- Mimics the ldoc built-in method style, but better. -- -- This custom renderer exists because using ldoc built-in method detection @@ -177,7 +192,7 @@ local function render_methods(item) ret = ":"..ret end - return ret .. (item.args and " "..item.args or "") + return ret .. " " .. wrap_args(item) end -- Parse the magic parameters to type concention in something the template eats. @@ -210,7 +225,6 @@ local function sanitize_type(item, ldoc) -- It has to be set, otherwise the table will have different col count. item.display_type = "N/A" end - local no_prefix = { property = true, signal = true, clientruleproperty = true, deprecatedproperty = true, @@ -284,7 +298,7 @@ custom_display_name_handler = function(item, default_handler) end if item.type == "method" then - return render_methods(item) + ret = render_methods(item) end @@ -300,9 +314,12 @@ custom_display_name_handler = function(item, default_handler) -- It isn't there by default. if add_args[item.type] then - ret = ret .. " " .. item.args + ret = ret .. " " .. wrap_args(item) end + -- Beautify. + ret = wrap_modname(ret, item) + return ret end diff --git a/docs/ldoc.css b/docs/ldoc.css index 4a4412e4..2355bf2c 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -309,6 +309,12 @@ td.summarytype { text-align: right; } +table.function_list .function_args /*.function_modname*/ { + color: #94b1ff; + text-decoration: underline; + text-decoration-color: #bbd3ff; +} + dl.function { margin-right: 15px; margin-left: 15px;
$(display_name(item))$(dn)$(item.display_type)$(dn)$(M(item.summary,item))