From 2f3bce00e6d39e36b01e0c38faaf87b4b0529475 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 2 Nov 2021 21:59:56 -0700 Subject: [PATCH 001/134] tasklist: Refactor to base a normal widget. It was previously monkey-patching the input layout object into the final tasklist. This is a breaking change, but affects undocumented behaviors. By doing this, it becomes possible to expose the properties in the public API. This, in turn, allows to document them. Right now, the documentation is very vague on some behaviors. --- docs/89-NEWS.md | 4 + lib/awful/widget/tasklist.lua | 183 +++++++++++++++++++++++++++++----- 2 files changed, 164 insertions(+), 23 deletions(-) diff --git a/docs/89-NEWS.md b/docs/89-NEWS.md index 18d315cb1..4e19739fe 100644 --- a/docs/89-NEWS.md +++ b/docs/89-NEWS.md @@ -76,6 +76,10 @@ This document was last updated at commit v4.3-197-g9085ed631. old behavior, use `awful.rules.rules = {}; awful.rules.rules = my_new_rules`. * `client:relative_move()` now default `nil` values to zero. The previous behavior made no sense. + * The tasklist and taglist widgets are no longer directly an instance of + it's main layout. Use the `base_layout` property to access the layout. + This allows to replace the layout at runtime. The previous behavior + was undocumented. # Awesome window manager framework version 4.3 changes diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index aea5c23fb..1a4a646d1 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -94,6 +94,7 @@ local wmargin = require("wibox.container.margin") local wtextbox = require("wibox.widget.textbox") local clienticon = require("awful.widget.clienticon") local wbackground = require("wibox.container.background") +local gtable = require("gears.table") local function get_screen(s) return s and screen[s] @@ -479,7 +480,7 @@ end local function tasklist_update(s, w, buttons, filter, data, style, update_function, args) local clients = {} - local source = args and args.source or tasklist.source.all_clients or nil + local source = self.source or tasklist.source.all_clients or nil local list = source and source(s, args) or capi.client.get() for _, c in ipairs(list) do @@ -498,6 +499,117 @@ local function tasklist_update(s, w, buttons, filter, data, style, update_functi }) end +--- Set the tasklist layout. +-- +-- @property base_layout +-- @tparam[opt=wibox.layout.flex.horizontal] wibox.layout base_layout +-- @see wibox.layout.flex.horizontal + +function tasklist:set_base_layout(layout) + self._private.base_layout = base.make_widget_from_value( + layout or flex.horizontal + ) + + local spacing = self._private.style.spacing or beautiful.tasklist_spacing + + if self._private.base_layout.set_spacing and spacing then + self._private.base_layout:set_spacing(spacing) + end + + assert(self._private.base_layout.is_widget) + + self._do_tasklist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::base_layout", layout) +end + +function tasklist:layout(_, width, height) + if self._private.base_layout then + return { base.place_widget_at(self._private.base_layout, 0, 0, width, height) } + end +end + +function tasklist:fit(context, width, height) + if not self._private.base_layout then + return 0, 0 + end + + return base.fit_widget(self, context, self._private.base_layout, width, height) +end + +for _, prop in ipairs { "screen", "filter", "update_function", "widget_template", "source"} do + tasklist["set_"..prop] = function(self, value) + if value == self._private[prop] then return end + + self._private[prop] = value + + self._do_tasklist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::"..prop, value) + end + + tasklist["get_"..prop] = function(self) + return self._private[prop] + end +end + +local function update_screen(self, screen, old) + if not instances then return end + + if old and instances[old] then + for k, w in ipairs(instances[old]) do + if w == self then + table.remove(instances[old], k) + break + end + end + end + + local list = instances[screen] + + if not list then + list = setmetatable({}, { __mode = "v" }) + instances[screen] = list + end + + table.insert(list, self) +end + +function tasklist:set_screen(value) + value = get_screen(value) + + if value == self._private.screen then return end + + local old = self._private.screen + + self._private.screen = value + + update_screen(self, screen, old) + + self._do_tasklist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::screen", value) +end + +function tasklist:set_widget_template(widget_template) + self._private.widget_template = widget_template + + -- Remove the existing instances + self._private.data = setmetatable({}, { __mode = 'k' }) + + self._do_tasklist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::widget_template", widget_template) +end + --- Create a new tasklist widget. -- The last two arguments (update_function -- and layout) serve to customize the layout of the tasklist (eg. to @@ -530,7 +642,7 @@ end -- @tparam[opt=nil] string args.style.bg_image_focus -- @tparam[opt=nil] string args.style.bg_image_urgent -- @tparam[opt=nil] string args.style.bg_image_minimize --- @tparam[opt=nil] boolean args.style.tasklist_disable_icon +-- @tparam[opt=nil] boolean args.style.disable_icon -- @tparam[opt=nil] number args.style.icon_size The size of the icon -- @tparam[opt='▪'] string args.style.sticky Extra icon when client is sticky -- @tparam[opt='⌃'] string args.style.ontop Extra icon when client is ontop @@ -563,7 +675,7 @@ end -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function --- @param base_widget **DEPRECATED** use args.base_widget +-- @param base_widget **DEPRECATED** use args.base_layout -- @constructorfct awful.widget.tasklist function tasklist.new(args, filter, buttons, style, update_function, base_widget) local screen = nil @@ -596,23 +708,37 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget screen = screen or get_screen(args.screen) local uf = args.update_function or common.list_update - local w = base.make_widget_from_value(args.layout or flex.horizontal) - local data = setmetatable({}, { __mode = 'k' }) + local w = base.make_widget(nil, nil, { + enable_properties = true, + }) - local spacing = args.style and args.style.spacing or args.layout and args.layout.spacing - or beautiful.tasklist_spacing - if w.set_spacing and spacing then - w:set_spacing(spacing) - end + gtable.crush(w._private, { + disable_task_name = args.disable_task_name, + disable_icon = args.disable_icon, + update_function = args.update_function, + filter = args.filter, + buttons = args.buttons, + style = args.style or {}, + screen = screen, + widget_template = args.widget_template, + source = args.source, + data = setmetatable({}, { __mode = 'k' }) + }) + + gtable.crush(w, tasklist, true) + rawset(w, "filter", nil) + rawset(w, "source", nil) local queued_update = false -- For the tests function w._do_tasklist_update_now() queued_update = false - if screen.valid then - tasklist_update(screen, w, args.buttons, args.filter, data, args.style, uf, args) + if w._private.screen.valid then + tasklist_update( + w._private.screen, w, w._private.buttons, w._private.filter, w._private.data, args.style, uf, args + ) end end @@ -624,7 +750,7 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget end end function w._unmanage(c) - data[c] = nil + w._private.data[c] = nil end if instances == nil then instances = setmetatable({}, { __mode = "k" }) @@ -681,17 +807,20 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget instances[get_screen(s)] = nil end) end + + tasklist.set_base_layout(w, args.layout or args.base_layout) + w._do_tasklist_update() - local list = instances[screen] - if not list then - list = setmetatable({}, { __mode = "v" }) - instances[screen] = list - end - table.insert(list, w) + + update_screen(w, screen) + return w end --- Filtering function to include all clients. +-- +--@DOC_sequences_client_tasklist_filter_allscreen1_EXAMPLE@ +-- -- @return true -- @filterfunction awful.widget.tasklist.filter.allscreen function tasklist.filter.allscreen() @@ -699,8 +828,11 @@ function tasklist.filter.allscreen() end --- Filtering function to include the clients from all tags on the screen. --- @param c The client. --- @param screen The screen we are drawing on. +-- +--@DOC_sequences_client_tasklist_filter_alltags1_EXAMPLE@ +-- +-- @tparam client c The client. +-- @tparam screen screen The screen we are drawing on. -- @return true if c is on screen, false otherwise -- @filterfunction awful.widget.tasklist.filter.alltags function tasklist.filter.alltags(c, screen) @@ -709,8 +841,13 @@ function tasklist.filter.alltags(c, screen) end --- Filtering function to include only the clients from currently selected tags. --- @param c The client. --- @param screen The screen we are drawing on. +-- +-- This is the filter used in the default `rc.lua`. +-- +--@DOC_sequences_client_tasklist_filter_currenttags1_EXAMPLE@ +-- +-- @tparam client c The client. +-- @tparam screen screen The screen we are drawing on. -- @return true if c is in a selected tag on screen, false otherwise -- @filterfunction awful.widget.tasklist.filter.currenttags function tasklist.filter.currenttags(c, screen) From df59f5bdd3c1f389269bb56155dcc4e1bc027c2c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 4 Nov 2021 16:57:28 -0700 Subject: [PATCH 002/134] taglist: Convert into a real widget. It no longer monkey-patch the input layout widget. This allows the layout to be replaced at runtime. --- lib/awful/widget/taglist.lua | 68 ++++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 7 deletions(-) diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index b4843f66d..f05b5d9a5 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -54,6 +54,7 @@ local gcolor = require("gears.color") local gstring = require("gears.string") local gdebug = require("gears.debug") local base = require("wibox.widget.base") +local gtable = require("gears.table") local function get_screen(s) return s and capi.screen[s] @@ -410,6 +411,46 @@ local function taglist_update(s, w, buttons, filter, data, style, update_functio }) end +--- Set the taglist layout. +-- +-- @property base_layout +-- @tparam[opt=wibox.layout.fixed.horizontal] wibox.layout base_layout +-- @see wibox.layout.fixed.horizontal + +function taglist:set_base_layout(layout) + self._private.base_layout = base.make_widget_from_value( + layout or fixed.horizontal + ) + + local spacing = self._private.style.spacing or beautiful.taglist_spacing + + if self._private.base_layout.set_spacing and spacing then + self._private.base_layout:set_spacing(spacing) + end + + assert(self._private.base_layout.is_widget) + + self._do_taglist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::base_layout", layout) +end + +function taglist:layout(_, width, height) + if self._private.base_layout then + return { base.place_widget_at(self._private.base_layout, 0, 0, width, height) } + end +end + +function taglist:fit(context, width, height) + if not self._private.base_layout then + return 0, 0 + end + + return base.fit_widget(self, context, self._private.base_layout, width, height) +end + --- Create a new taglist widget. The last two arguments (update_function -- and layout) serve to customize the layout of the taglist (eg. to -- make it vertical). For that, you will need to copy the @@ -460,7 +501,7 @@ end -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function --- @param base_widget **DEPRECATED** use args.base_widget +-- @param base_widget **DEPRECATED** use args.base_layout -- @constructorfct awful.widget.taglist function taglist.new(args, filter, buttons, style, update_function, base_widget) @@ -495,19 +536,29 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget) screen = screen or get_screen(args.screen) local uf = args.update_function or common.list_update - local w = base.make_widget_from_value(args.layout or fixed.horizontal) - if w.set_spacing and (args.style and args.style.spacing or beautiful.taglist_spacing) then - w:set_spacing(args.style and args.style.spacing or beautiful.taglist_spacing) - end + local w = base.make_widget(nil, nil, { + enable_properties = true, + }) + + gtable.crush(w, taglist, true) + + gtable.crush(w._private, { + style = args.style or {}, + buttons = args.buttons, + filter = args.filter, + update_function = args.update_function, + }) local data = setmetatable({}, { __mode = 'k' }) local queued_update = {} function w._do_taglist_update_now() - if screen.valid then - taglist_update(screen, w, args.buttons, args.filter, data, args.style, uf, args) + if w._private.screen.valid then + taglist_update( + w._private.screen, w, w._private.buttons, w._private.filter, data, args.style, uf, args + ) end queued_update[screen] = false end @@ -558,6 +609,9 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget) instances[get_screen(s)] = nil end) end + + w:set_base_layout(args.base_layout or args.layout) + w._do_taglist_update() local list = instances[screen] if not list then From a3b753205638c6b75b3f3b2b624b0a9e20c57d94 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 4 Nov 2021 17:46:32 -0700 Subject: [PATCH 003/134] taglist: Expose more properties. They were passed in the constructor, but could not be changed. --- lib/awful/widget/taglist.lua | 76 +++++++++++++++++++++++++++++++----- 1 file changed, 66 insertions(+), 10 deletions(-) diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index f05b5d9a5..eefa0f265 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -391,10 +391,10 @@ local function create_callback(w, t) common._set_common_property(w, "tag", t) end -local function taglist_update(s, w, buttons, filter, data, style, update_function, args) +local function taglist_update(s, self, buttons, filter, data, style, update_function, args) local tags = {} - local source = args and args.source or taglist.source.for_screen or nil + local source = self._private.source or taglist.source.for_screen or nil local list = source and source(s, args) or s.tags for _, t in ipairs(list) do @@ -405,12 +405,17 @@ local function taglist_update(s, w, buttons, filter, data, style, update_functio local function label(c) return taglist.taglist_label(c, style) end - update_function(w, buttons, label, data, tags, { - widget_template = args.widget_template, + update_function(self._private.base_layout, buttons, label, data, tags, { + widget_template = self._private.widget_template, create_callback = create_callback, }) end +--- The taglist screen. +-- +-- @property screen +-- @tparam screen screen + --- Set the taglist layout. -- -- @property base_layout @@ -451,6 +456,54 @@ function taglist:fit(context, width, height) return base.fit_widget(self, context, self._private.base_layout, width, height) end +--- An alternative function to configure the content. +-- +-- You should use `widget_template` if it fits your use case first. This +-- API is very low level. +-- +-- @property update_function +-- @tparam function update_function. + +--- A function to restrict the content of the taglist. +-- +-- @property filter +-- @tparam function filter +-- @see source +-- @see awful.widget.taglist.filter.noempty +-- @see awful.widget.taglist.filter.selected +-- @see awful.widget.taglist.filter.all +-- @see awful.widget.taglist.source.for_screen + +--- The function used to gather the group of tags. +-- +-- @property source +-- @tparam function source +-- @see filter +-- @see awful.widget.taglist.source.for_screen + +--- A templete used to genetate the individual tag widgets. +-- +-- @property widget_template +-- @tparam table widget_template + +for _, prop in ipairs { "filter", "update_function", "widget_template", "source", "screen" } do + taglist["set_"..prop] = function(self, value) + if value == self._private[prop] then return end + + self._private[prop] = value + + self._do_taglist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::"..prop, value) + end + + taglist["get_"..prop] = function(self) + return self._private[prop] + end +end + --- Create a new taglist widget. The last two arguments (update_function -- and layout) serve to customize the layout of the taglist (eg. to -- make it vertical). For that, you will need to copy the @@ -544,10 +597,13 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget) gtable.crush(w, taglist, true) gtable.crush(w._private, { - style = args.style or {}, - buttons = args.buttons, - filter = args.filter, + style = args.style or {}, + buttons = args.buttons, + filter = args.filter, update_function = args.update_function, + widget_template = args.widget_template, + source = args.source, + screen = screen }) local data = setmetatable({}, { __mode = 'k' }) @@ -560,14 +616,14 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget) w._private.screen, w, w._private.buttons, w._private.filter, data, args.style, uf, args ) end - queued_update[screen] = false + queued_update[w._private.screen] = false end function w._do_taglist_update() -- Add a delayed callback for the first update. - if not queued_update[screen] then + if not queued_update[w._private.screen] then timer.delayed_call(w._do_taglist_update_now) - queued_update[screen] = true + queued_update[w._private.screen] = true end end if instances == nil then From 70c6821997701dc90982094058da10f7748d7293 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 9 Nov 2021 16:57:09 -0800 Subject: [PATCH 004/134] tasklist: Convert to a real widget. Previously, it was monkey-patching the input layout object. This will allow to replace the laoyut at runtime. For example, switching from `fixed.horizontal` to a grid when the number of client gets too large. --- lib/awful/widget/tasklist.lua | 40 ++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 1a4a646d1..41998c777 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -477,7 +477,7 @@ local function create_callback(w, t) common._set_common_property(w, "client", t) end -local function tasklist_update(s, w, buttons, filter, data, style, update_function, args) +local function tasklist_update(s, self, buttons, filter, data, style, update_function, args) local clients = {} local source = self.source or tasklist.source.all_clients or nil @@ -493,8 +493,8 @@ local function tasklist_update(s, w, buttons, filter, data, style, update_functi local function label(c, tb) return tasklist_label(c, style, tb) end - update_function(w, buttons, label, data, clients, { - widget_template = args.widget_template or default_template, + update_function(self._private.base_layout, buttons, label, data, clients, { + widget_template = self._private.widget_template or default_template, create_callback = create_callback, }) end @@ -503,8 +503,42 @@ end -- -- @property base_layout -- @tparam[opt=wibox.layout.flex.horizontal] wibox.layout base_layout +-- @propemits true false -- @see wibox.layout.flex.horizontal +--- The tasklist screen. +-- +-- @property screen +-- @tparam screen screen +-- @propemits true false + +--- A function to narrow down the list of clients. +-- +-- @property filter +-- @tparam function filter +-- @propemits true false + +--- A function called when the tasklist is refreshed. +-- +-- This is a very low level API, prefer `widget_template` whenever +-- you can. +-- +-- @property update_function +-- @tparam function update_function +-- @propemits true false + +--- A template for creating the client widgets. +-- +-- @property widget_template +-- @tparam table widget_template +-- @propemits true false + +--- A function to gather the clients to display. +-- +-- @property source +-- @tparam function source +-- @propemits true false + function tasklist:set_base_layout(layout) self._private.base_layout = base.make_widget_from_value( layout or flex.horizontal From b11a8fb52ce891481025b043a70b4a0762b4ad2f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 9 Nov 2021 23:10:43 -0800 Subject: [PATCH 005/134] tasklist: Add a `count` property. This is mostly for the signal handler. It will allow to do things like replace the template or layout based on the number of clients. --- lib/awful/widget/tasklist.lua | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 41998c777..5d269458a 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -491,6 +491,11 @@ local function tasklist_update(s, self, buttons, filter, data, style, update_fun end end + if self._private.last_count ~= #clients then + self:emit_signal("property::count", #clients, self._private.last_count) + self._private.last_count = #clients + end + local function label(c, tb) return tasklist_label(c, style, tb) end update_function(self._private.base_layout, buttons, label, data, clients, { @@ -499,6 +504,13 @@ local function tasklist_update(s, self, buttons, filter, data, style, update_fun }) end +--- The current number of clients. +-- +-- @property count +-- @readonly +-- @tparam number The number of client. +-- @propemits true false + --- Set the tasklist layout. -- -- @property base_layout @@ -559,6 +571,14 @@ function tasklist:set_base_layout(layout) self:emit_signal("property::base_layout", layout) end +function tasklist:get_count() + if not self._private.last_count then + self._do_tasklist_update_now() + end + + return self._private.last_count +end + function tasklist:layout(_, width, height) if self._private.base_layout then return { base.place_widget_at(self._private.base_layout, 0, 0, width, height) } From 798d31881df93b883bac5f70e1149b556596be7a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 9 Nov 2021 23:11:24 -0800 Subject: [PATCH 006/134] taglist: Add a `count` property. This is mostly for its signal handler. It will allow to replace the template or layout based on the number of tags. --- lib/awful/widget/taglist.lua | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index eefa0f265..e5792eb4c 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -403,6 +403,11 @@ local function taglist_update(s, self, buttons, filter, data, style, update_func end end + if self._private.last_count ~= #tags then + self:emit_signal("property::count", #tags, self._private.last_count) + self._private.last_count = #tags + end + local function label(c) return taglist.taglist_label(c, style) end update_function(self._private.base_layout, buttons, label, data, tags, { @@ -422,6 +427,13 @@ end -- @tparam[opt=wibox.layout.fixed.horizontal] wibox.layout base_layout -- @see wibox.layout.fixed.horizontal +--- The current number of tags. +-- +-- @property count +-- @readonly +-- @tparam number The number of tags. +-- @propemits true false + function taglist:set_base_layout(layout) self._private.base_layout = base.make_widget_from_value( layout or fixed.horizontal @@ -442,6 +454,14 @@ function taglist:set_base_layout(layout) self:emit_signal("property::base_layout", layout) end +function taglist:get_count() + if not self._private.last_count then + self._do_taglist_update_now() + end + + return self._private.last_count +end + function taglist:layout(_, width, height) if self._private.base_layout then return { base.place_widget_at(self._private.base_layout, 0, 0, width, height) } From 396bddb946770c2d067f07db614aa2134edfc0e8 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 9 Nov 2021 23:11:58 -0800 Subject: [PATCH 007/134] layoutlist: Add a `count` property. Because it was added to the `taglist` and `tasklist` and their API somewhat mirror each other. --- lib/awful/widget/layoutlist.lua | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index 5fac6cd86..d61030f3e 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -281,10 +281,25 @@ local layoutlist = {} -- @property current_layout -- @param layout +--- The current number of layouts. +-- +-- @property count +-- @readonly +-- @tparam number The number of layouts. +-- @propemits true false + function layoutlist:get_layouts() local f = self.source or self._private.source or module.source.for_screen - return f(self.screen) + local ret = f(self.screen) + + if self._private.last_count ~= #ret then + self:emit_signal("property::count", ret, self._private.last_count) + + self._private.last_count = ret + end + + return ret end function layoutlist:get_current_layout() @@ -329,6 +344,14 @@ function layoutlist:set_base_layout(layout) self:emit_signal("property::base_layout", layout) end +function layoutlist:get_count() + if not self._private.last_count then + self._do_() + end + + return self._private.last_count +end + function layoutlist:set_widget_template(widget_template) self._private.widget_template = widget_template From 686c4fec221588a0224ffd0d6819375d659b2c57 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 9 Nov 2021 23:16:24 -0800 Subject: [PATCH 008/134] doc: Add the ability to render random widgets to the sequence template. --- tests/examples/sequences/template.lua | 38 +++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/tests/examples/sequences/template.lua b/tests/examples/sequences/template.lua index 6110cce4a..5143ee71a 100644 --- a/tests/examples/sequences/template.lua +++ b/tests/examples/sequences/template.lua @@ -7,6 +7,7 @@ local file_path, image_path = ... require("_common_template")(...) local capi = {client = client, screen = screen} local Pango = require("lgi").Pango +local cairo = require("lgi").cairo local PangoCairo = require("lgi").PangoCairo require("awful.screen") require("awful.tag") @@ -714,7 +715,9 @@ local function gen_timeline(args) awesome.startup = false --luacheck: ignore for _, event in ipairs(history) do + require("gears.timer").run_delayed_calls_now() local ret = event.callback() + require("gears.timer").run_delayed_calls_now() if event.event == "event" then l:add(wrap_timeline(gen_vertical_space(5))) l:add(wrap_timeline(wibox.widget { @@ -725,6 +728,8 @@ local function gen_timeline(args) gen_noscreen(l, ret[1].tags, args) elseif event.event == "tags" and (#ret > 1 or args.display_screen) then gen_screens(l, ret, args) + elseif event.event == "widget" then + l:add(wrap_timeline(ret)) end end @@ -785,6 +790,39 @@ local function wrap_with_arrows(widget) } end +-- Use a recording surface to store the widget content. +function module.display_widget(wdg, width, height, context) + local function do_it() + context = context or {dpi=96} + + local w, h = wdg:fit(context, width or 9999, height or 9999) + + w, h = math.min(w, width or 9999), math.min(h, height or 9999) + + local memento = cairo.RecordingSurface( + cairo.Content.CAIRO_FORMAT_ARGB32, + cairo.Rectangle { x = 0, y = 0, width = w, height = h } + ) + + local cr = cairo.Context(memento) + + wibox.widget.draw_to_cairo_context(wdg, cr, w, h, context) + + return wibox.widget { + fit = function() + return w, h+5 + end, + draw = function(_, _, cr2) + cr2:translate(0, 5) + cr2:set_source_surface(memento) + cr2:paint() + end + } + end + + table.insert(history, {event="widget", callback = do_it}) +end + function module.display_tags() local function do_it() local ret = {} From b8dbba34db3dee639ec290788c46ba24ad2d15cc Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 13 Nov 2021 00:12:44 -0800 Subject: [PATCH 009/134] taglist/tasklist: Fix the fallback font. When beautiful.font isn't set, it fell back to "". That value isn't actually the same as the "default" Pango font. Better use `nil`. --- lib/awful/widget/taglist.lua | 4 ++-- lib/awful/widget/tasklist.lua | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index e5792eb4c..de24bac4d 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -251,7 +251,7 @@ function taglist.taglist_label(t, args) local taglist_squares_unsel_empty = args.squares_unsel_empty or theme.taglist_squares_unsel_empty local taglist_squares_resize = theme.taglist_squares_resize or args.squares_resize or "true" local taglist_disable_icon = args.taglist_disable_icon or theme.taglist_disable_icon or false - local font = args.font or theme.taglist_font or theme.font or "" + local font = args.font or theme.taglist_font or theme.font local text = nil local sel = capi.client.focus local bg_color = nil @@ -361,7 +361,7 @@ function taglist.taglist_label(t, args) end if not tag.getproperty(t, "icon_only") then - text = "" + text = "" if fg_color then text = text .. "" .. (gstring.xml_escape(t.name) or "") .. "" diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 5d269458a..d14d363fc 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -335,12 +335,12 @@ local function tasklist_label(c, args, tb) local bg_image_focus = args.bg_image_focus or theme.tasklist_bg_image_focus or theme.bg_image_focus local bg_image_urgent = args.bg_image_urgent or theme.tasklist_bg_image_urgent or theme.bg_image_urgent local bg_image_minimize = args.bg_image_minimize or theme.tasklist_bg_image_minimize or theme.bg_image_minimize - local tasklist_disable_icon = args.tasklist_disable_icon or theme.tasklist_disable_icon or false + local tasklist_disable_icon = args.disable_icon or args.tasklist_disable_icon or theme.tasklist_disable_icon or false local disable_task_name = args.disable_task_name or theme.tasklist_disable_task_name or false - local font = args.font or theme.tasklist_font or theme.font or "" - local font_focus = args.font_focus or theme.tasklist_font_focus or theme.font_focus or font or "" - local font_minimized = args.font_minimized or theme.tasklist_font_minimized or theme.font_minimized or font or "" - local font_urgent = args.font_urgent or theme.tasklist_font_urgent or theme.font_urgent or font or "" + local font = args.font or theme.tasklist_font or theme.font + local font_focus = args.font_focus or theme.tasklist_font_focus or theme.font_focus or font + local font_minimized = args.font_minimized or theme.tasklist_font_minimized or theme.font_minimized or font + local font_urgent = args.font_urgent or theme.tasklist_font_urgent or theme.font_urgent or font local text = "" local name = "" local bg From c7ed176586f6103417d81d5004bee55d6da49350 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 13 Nov 2021 00:14:29 -0800 Subject: [PATCH 010/134] tasklist: Fix `disable_icon`. It regressed when the tasklist switched to a template by default. This was done to support the icon size. Fix #3178 --- lib/awful/widget/tasklist.lua | 117 ++++++++++++++++++++++++++-------- 1 file changed, 91 insertions(+), 26 deletions(-) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index d14d363fc..b31c2a6f2 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -211,78 +211,136 @@ local instances -- @beautiful beautiful.tasklist_minimized -- @tparam[opt=nil] string minimized ---- The tasklist font. --- @beautiful beautiful.tasklist_font --- @tparam[opt=nil] string font - --- The focused client alignment. +-- +-- @DOC_wibox_awidget_tasklist_style_align_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_align -- @tparam[opt=left] string align *left*, *right* or *center* +--- The tasklist font. +-- +-- @DOC_wibox_awidget_tasklist_style_font_EXAMPLE@ +-- +-- @beautiful beautiful.tasklist_font +-- @tparam[opt=nil] string font +-- @see wibox.widget.textbox.font + --- The focused client title alignment. +-- +-- @DOC_wibox_awidget_tasklist_style_font_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_font_focus -- @tparam[opt=nil] string font_focus +-- @see wibox.widget.textbox.font --- The minimized clients font. +-- +-- @DOC_wibox_awidget_tasklist_style_font_minimized_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_font_minimized -- @tparam[opt=nil] string font_minimized +-- @see wibox.widget.textbox.font --- The urgent clients font. +-- +-- @DOC_wibox_awidget_tasklist_style_font_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_font_urgent -- @tparam[opt=nil] string font_urgent +-- @see wibox.widget.textbox.font --- The space between the tasklist elements. +-- +-- @DOC_wibox_awidget_tasklist_style_spacing_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_spacing -- @tparam[opt=0] number spacing The spacing between tasks. --- The default tasklist elements shape. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape -- @tparam[opt=nil] gears.shape shape --- The default tasklist elements border width. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_width_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_width -- @tparam[opt=0] number shape_border_width --- The default tasklist elements border color. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_color_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_color -- @tparam[opt=nil] string|color shape_border_color -- @see gears.color --- The focused client shape. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_focus -- @tparam[opt=nil] gears.shape shape_focus --- The focused client border width. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_focus_border_width_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_width_focus -- @tparam[opt=0] number shape_border_width_focus --- The focused client border color. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_focus_border_width_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_color_focus -- @tparam[opt=nil] string|color shape_border_color_focus -- @see gears.color --- The minimized clients shape. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_minimized_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_minimized -- @tparam[opt=nil] gears.shape shape_minimized --- The minimized clients border width. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_width_minimized_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_width_minimized -- @tparam[opt=0] number shape_border_width_minimized --- The minimized clients border color. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_color_minimized_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_color_minimized -- @tparam[opt=nil] string|color shape_border_color_minimized -- @see gears.color --- The urgent clients shape. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_urgent -- @tparam[opt=nil] gears.shape shape_urgent --- The urgent clients border width. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_width_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_width_urgent -- @tparam[opt=0] number shape_border_width_urgent --- The urgent clients border color. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_color_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_color_urgent -- @tparam[opt=nil] string|color shape_border_color_urgent -- @see gears.color @@ -291,30 +349,36 @@ local instances tasklist.filter, tasklist.source = {}, {} -- This is the same template as awful.widget.common, but with an clienticon widget -local default_template = { - { - { - clienticon, - id = "icon_margin_role", - left = dpi(4), - widget = wmargin - }, +local function default_template(self) + local has_no_icon = self._private.style.disable_icon + or self._private.style.tasklist_disable_icon + or beautiful.tasklist_disable_icon + + return { { + (not has_no_icon) and { + clienticon, + id = "icon_margin_role", + left = dpi(4), + widget = wmargin + } or nil, { - id = "text_role", - widget = wtextbox, + { + id = "text_role", + widget = wtextbox, + }, + id = "text_margin_role", + left = dpi(4), + right = dpi(4), + widget = wmargin }, - id = "text_margin_role", - left = dpi(4), - right = dpi(4), - widget = wmargin + fill_space = true, + layout = wfixed.horizontal }, - fill_space = true, - layout = wfixed.horizontal - }, - id = "background_role", - widget = wbackground -} + id = "background_role", + widget = wbackground + } +end local function tasklist_label(c, args, tb) if not args then args = {} end @@ -492,14 +556,15 @@ local function tasklist_update(s, self, buttons, filter, data, style, update_fun end if self._private.last_count ~= #clients then - self:emit_signal("property::count", #clients, self._private.last_count) + local old = self._private.last_count self._private.last_count = #clients + self:emit_signal("property::count", #clients, old) end local function label(c, tb) return tasklist_label(c, style, tb) end update_function(self._private.base_layout, buttons, label, data, clients, { - widget_template = self._private.widget_template or default_template, + widget_template = self._private.widget_template or default_template(self), create_callback = create_callback, }) end From cf2129b2fe940ededc2f25956e3c1c322d689f64 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 13 Nov 2021 00:20:21 -0800 Subject: [PATCH 011/134] doc: Add a memento widget for the wibox template. --- tests/examples/wibox/template.lua | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/tests/examples/wibox/template.lua b/tests/examples/wibox/template.lua index 8fd1925de..0c4975fd8 100644 --- a/tests/examples/wibox/template.lua +++ b/tests/examples/wibox/template.lua @@ -3,6 +3,37 @@ require("_common_template")(...) local wibox = require( "wibox" ) local surface = require( "gears.surface" ) +local cairo = require("lgi").cairo + +--- Create a copy of the widget frozen in time. +-- This is useful whe the global state is modified between the time this is +-- called and the time the final output is rendered. +function _memento(wdg, width, height, context, force) -- luacheck: globals _memento + context = context or {dpi=96} + + local w, h = wdg:fit(context, width or 9999, height or 9999) + + w, h = math.min(force and width or w, width or 9999), math.min(force and height or h, height or 9999) + + local memento = cairo.RecordingSurface( + cairo.Content.CAIRO_FORMAT_ARGB32, + cairo.Rectangle { x = 0, y = 0, width = w, height = h } + ) + + local cr = cairo.Context(memento) + + wibox.widget.draw_to_cairo_context(wdg, cr, w, h, context) + + return wibox.widget { + fit = function() + return w, h + end, + draw = function(_, _, cr2) + cr2:set_source_surface(memento) + cr2:paint() + end + } +end -- This is the main widget the tests will use as top level local container = wibox.layout.fixed.vertical() From 8f71ef6dff802476a1e7e9bea9a21bf87e030e57 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 13 Nov 2021 00:21:21 -0800 Subject: [PATCH 012/134] doc: Document the tasklist widget. --- lib/awful/widget/tasklist.lua | 64 +++++++++- .../client/tasklist_custom_filter1.lua | 96 ++++++++++++++ .../client/tasklist_custom_source1.lua | 102 +++++++++++++++ .../client/tasklist_filter_allscreen1.lua | 82 ++++++++++++ .../client/tasklist_filter_alltags1.lua | 79 ++++++++++++ .../client/tasklist_filter_currenttags1.lua | 80 ++++++++++++ .../client/tasklist_filter_focused1.lua | 73 +++++++++++ .../tasklist_filter_minimizedcurrenttags1.lua | 82 ++++++++++++ .../sequences/client/tasklist_layout1.lua | 117 ++++++++++++++++++ .../sequences/client/tasklist_screen1.lua | 87 +++++++++++++ .../client/tasklist_widget_template1.lua | 89 +++++++++++++ .../wibox/awidget/tasklist/style_align.lua | 39 ++++++ .../wibox/awidget/tasklist/style_bg_focus.lua | 64 ++++++++++ .../awidget/tasklist/style_bg_minimize.lua | 64 ++++++++++ .../awidget/tasklist/style_bg_normal.lua | 64 ++++++++++ .../awidget/tasklist/style_bg_urgent.lua | 64 ++++++++++ .../awidget/tasklist/style_disable_icon.lua | 38 ++++++ .../tasklist/style_disable_task_name.lua | 39 ++++++ .../wibox/awidget/tasklist/style_fg_focus.lua | 51 ++++++++ .../awidget/tasklist/style_fg_minimize.lua | 51 ++++++++ .../awidget/tasklist/style_fg_normal.lua | 51 ++++++++ .../awidget/tasklist/style_fg_urgent.lua | 51 ++++++++ .../wibox/awidget/tasklist/style_font.lua | 51 ++++++++ .../awidget/tasklist/style_font_focus.lua | 51 ++++++++ .../awidget/tasklist/style_font_minimized.lua | 51 ++++++++ .../awidget/tasklist/style_font_urgent.lua | 51 ++++++++ .../tasklist/style_plain_task_name.lua | 45 +++++++ .../wibox/awidget/tasklist/style_shape.lua | 51 ++++++++ .../tasklist/style_shape_border_color.lua | 58 +++++++++ .../style_shape_border_color_minimized.lua | 71 +++++++++++ .../style_shape_border_color_urgent.lua | 71 +++++++++++ .../tasklist/style_shape_border_width.lua | 46 +++++++ .../style_shape_border_width_minimized.lua | 57 +++++++++ .../style_shape_border_width_urgent.lua | 58 +++++++++ .../awidget/tasklist/style_shape_focus.lua | 63 ++++++++++ .../style_shape_focus_border_width.lua | 58 +++++++++ .../style_shape_focus_border_width_focus.lua | 71 +++++++++++ .../tasklist/style_shape_minimized.lua | 63 ++++++++++ .../awidget/tasklist/style_shape_urgent.lua | 63 ++++++++++ .../wibox/awidget/tasklist/style_spacing.lua | 39 ++++++ 40 files changed, 2541 insertions(+), 4 deletions(-) create mode 100644 tests/examples/sequences/client/tasklist_custom_filter1.lua create mode 100644 tests/examples/sequences/client/tasklist_custom_source1.lua create mode 100644 tests/examples/sequences/client/tasklist_filter_allscreen1.lua create mode 100644 tests/examples/sequences/client/tasklist_filter_alltags1.lua create mode 100644 tests/examples/sequences/client/tasklist_filter_currenttags1.lua create mode 100644 tests/examples/sequences/client/tasklist_filter_focused1.lua create mode 100644 tests/examples/sequences/client/tasklist_filter_minimizedcurrenttags1.lua create mode 100644 tests/examples/sequences/client/tasklist_layout1.lua create mode 100644 tests/examples/sequences/client/tasklist_screen1.lua create mode 100644 tests/examples/sequences/client/tasklist_widget_template1.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_align.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_bg_focus.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_bg_minimize.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_bg_normal.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_bg_urgent.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_disable_icon.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_disable_task_name.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_fg_focus.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_fg_minimize.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_fg_normal.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_fg_urgent.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_font.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_font_focus.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_font_minimized.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_font_urgent.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_plain_task_name.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_border_color.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_border_color_minimized.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_border_color_urgent.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_border_width.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_border_width_minimized.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_border_width_urgent.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_focus.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width_focus.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_minimized.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_shape_urgent.lua create mode 100644 tests/examples/wibox/awidget/tasklist/style_spacing.lua diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index b31c2a6f2..a2bdc40ef 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -105,41 +105,65 @@ local tasklist = { mt = {} } local instances --- The default foreground (text) color. +-- +-- @DOC_wibox_awidget_tasklist_style_fg_normal_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_fg_normal -- @tparam[opt=nil] string|pattern fg_normal -- @see gears.color --- The default background color. +-- +-- @DOC_wibox_awidget_tasklist_style_bg_normal_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_bg_normal -- @tparam[opt=nil] string|pattern bg_normal -- @see gears.color --- The focused client foreground (text) color. +-- +-- @DOC_wibox_awidget_tasklist_style_fg_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_fg_focus -- @tparam[opt=nil] string|pattern fg_focus -- @see gears.color --- The focused client background color. +-- +-- @DOC_wibox_awidget_tasklist_style_bg_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_bg_focus -- @tparam[opt=nil] string|pattern bg_focus -- @see gears.color --- The urgent clients foreground (text) color. +-- +-- @DOC_wibox_awidget_tasklist_style_fg_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_fg_urgent -- @tparam[opt=nil] string|pattern fg_urgent -- @see gears.color --- The urgent clients background color. +-- +-- @DOC_wibox_awidget_tasklist_style_bg_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_bg_urgent -- @tparam[opt=nil] string|pattern bg_urgent -- @see gears.color --- The minimized clients foreground (text) color. +-- +-- @DOC_wibox_awidget_tasklist_style_fg_minimize_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_fg_minimize -- @tparam[opt=nil] string|pattern fg_minimize -- @see gears.color --- The minimized clients background color. +-- +-- @DOC_wibox_awidget_tasklist_style_bg_minimize_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_bg_minimize -- @tparam[opt=nil] string|pattern bg_minimize -- @see gears.color @@ -161,10 +185,16 @@ local instances -- @tparam[opt=nil] string bg_image_minimize --- Disable the tasklist client icons. +-- +-- @DOC_wibox_awidget_tasklist_style_disable_icon_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_disable_icon -- @tparam[opt=false] boolean tasklist_disable_icon --- Disable the tasklist client titles. +-- +-- @DOC_wibox_awidget_tasklist_style_disable_task_name_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_disable_task_name -- @tparam[opt=false] boolean tasklist_disable_task_name @@ -172,6 +202,8 @@ local instances -- -- See the Status icons section for more details. -- +-- @DOC_wibox_awidget_tasklist_style_plain_task_name_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_plain_task_name -- @tparam[opt=false] boolean tasklist_plain_task_name @@ -578,6 +610,10 @@ end --- Set the tasklist layout. -- +-- This can be used to change the layout based on the number of clients: +-- +-- @DOC_sequences_client_tasklist_layout1_EXAMPLE@ +-- -- @property base_layout -- @tparam[opt=wibox.layout.flex.horizontal] wibox.layout base_layout -- @propemits true false @@ -585,15 +621,24 @@ end --- The tasklist screen. -- +-- @DOC_sequences_client_tasklist_screen1_EXAMPLE@ +-- -- @property screen -- @tparam screen screen -- @propemits true false --- A function to narrow down the list of clients. -- +-- @DOC_sequences_client_tasklist_custom_filter1_EXAMPLE@ +-- -- @property filter -- @tparam function filter -- @propemits true false +-- @see awful.widget.tasklist.filter.allscreen +-- @see awful.widget.tasklist.filter.alltags +-- @see awful.widget.tasklist.filter.currenttags +-- @see awful.widget.tasklist.filter.minimizedcurrenttags +-- @see awful.widget.tasklist.filter.focused --- A function called when the tasklist is refreshed. -- @@ -606,15 +651,20 @@ end --- A template for creating the client widgets. -- +-- @DOC_sequences_client_tasklist_widget_template1_EXAMPLE@ +-- -- @property widget_template -- @tparam table widget_template -- @propemits true false --- A function to gather the clients to display. -- +-- @DOC_sequences_client_tasklist_custom_source1_EXAMPLE@ +-- -- @property source -- @tparam function source -- @propemits true false +-- @see awful.widget.tasklist.source.all_clients function tasklist:set_base_layout(layout) self._private.base_layout = base.make_widget_from_value( @@ -990,8 +1040,11 @@ function tasklist.filter.currenttags(c, screen) end --- Filtering function to include only the minimized clients from currently selected tags. --- @param c The client. --- @param screen The screen we are drawing on. +-- +--@DOC_sequences_client_tasklist_filter_minimizedcurrenttags1_EXAMPLE@ +-- +-- @tparam client c The client. +-- @tparam screen screen The screen we are drawing on. -- @return true if c is in a selected tag on screen and is minimized, false otherwise -- @filterfunction awful.widget.tasklist.filter.minimizedcurrenttags function tasklist.filter.minimizedcurrenttags(c, screen) @@ -1018,8 +1071,11 @@ function tasklist.filter.minimizedcurrenttags(c, screen) end --- Filtering function to include only the currently focused client. --- @param c The client. --- @param screen The screen we are drawing on. +-- +--@DOC_sequences_client_tasklist_filter_focused1_EXAMPLE@ +-- +-- @tparam client c The client. +-- @tparam screen screen The screen we are drawing on. -- @return true if c is focused on screen, false otherwise -- @filterfunction awful.widget.tasklist.filter.focused function tasklist.filter.focused(c, screen) diff --git a/tests/examples/sequences/client/tasklist_custom_filter1.lua b/tests/examples/sequences/client/tasklist_custom_filter1.lua new file mode 100644 index 000000000..d9bd0ecc9 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_custom_filter1.lua @@ -0,0 +1,96 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 1024, 640) +screen.fake_add(1050, 0, 1024, 640).outputs = {["eVGA1"] = {mm_height=50, mm_width=80 }} --DOC_HIDE + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[2], awful.layout.suit.tile.left) + + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=args.screen} +end + + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + + -- Spawn 3 clients on screen 2. + for i=1, 3 do + awful.spawn("Client #"..(5+i), {screen = screen[2]}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to allscreen.", function() + --DOC_HIDE_END + -- Set the filter to allscreen. + tasklist.filter = awful.widget.tasklist.filter.allscreen + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.add_event("Set a custom filter function.", function() + --DOC_HIDE_END + -- Create a pointless demo filter to only have clients + -- with off numbers in the name. Because... example! + tasklist.filter = function(c, screen) -- luacheck: no unused args + return c.name:match("[13579]") and c or nil + end + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_custom_source1.lua b/tests/examples/sequences/client/tasklist_custom_source1.lua new file mode 100644 index 000000000..29dfa161d --- /dev/null +++ b/tests/examples/sequences/client/tasklist_custom_source1.lua @@ -0,0 +1,102 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 1024, 640) + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 600, height =300, screen=args.screen} +end + + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + + -- Make 2 clients floating. + client.get()[2].floating = true + client.get()[4].floating = true + + --DOC_NEWLINE + + --DOC_HIDE_START + client.get()[2]:geometry { + x = 150, y = 100, + } + client.get()[4]:geometry { + x = 300, y = 200, + } + + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set a custom source function.", function() + --DOC_HIDE_END + -- Only select the floating clients for the tasklist screen. + tasklist.source = function(screen) + local ret = {} + + --DOC_NEWLINE + for _, c in ipairs(screen.clients) do + if c.floating then + table.insert(ret, c) + end + end + --DOC_NEWLINE + + return ret + end + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_allscreen1.lua b/tests/examples/sequences/client/tasklist_filter_allscreen1.lua new file mode 100644 index 000000000..93400b192 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_allscreen1.lua @@ -0,0 +1,82 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 1024, 640) +screen.fake_add(1050, 0, 1024, 640).outputs = {["eVGA1"] = {mm_height=50, mm_width=80 }} --DOC_HIDE + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[2], awful.layout.suit.tile.left) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=args.screen} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + + -- Spawn 3 clients on screen 2. + for i=1, 3 do + awful.spawn("Client #"..(5+i), {screen = screen[2]}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to allscreen.", function() + --DOC_HIDE_END + -- Set the filter to allscreen. + tasklist.filter = awful.widget.tasklist.filter.allscreen + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_alltags1.lua b/tests/examples/sequences/client/tasklist_filter_alltags1.lua new file mode 100644 index 000000000..2823129f4 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_alltags1.lua @@ -0,0 +1,79 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, tags=args.tags} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {tags = {screen[1].tags[1]}}) + end + + --DOC_NEWLINE + + -- Spawn 3 clients on screen 2. + for i=1, 3 do + awful.spawn("Client #"..(5+i), {tags = {screen[1].tags[2]}}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to alltags.", function() + --DOC_HIDE_END + -- Set the filter to alltags. + tasklist.filter = awful.widget.tasklist.filter.alltags + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = false, display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_currenttags1.lua b/tests/examples/sequences/client/tasklist_filter_currenttags1.lua new file mode 100644 index 000000000..43f2ea635 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_currenttags1.lua @@ -0,0 +1,80 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, tags=args.tags} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for k, t in ipairs(screen[1].tags) do + for i= 1, 2 do + awful.spawn("Client #"..(k-1)*2 + i, {tags = {t}}) + end + end + + --DOC_NEWLINE + + -- Selected some tags. + screen[1].tags[3].selected = true + screen[1].tags[5].selected = true + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to currenttags.", function() + --DOC_HIDE_END + -- Set the filter to currenttags. + tasklist.filter = awful.widget.tasklist.filter.currenttags + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = false, display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_focused1.lua b/tests/examples/sequences/client/tasklist_filter_focused1.lua new file mode 100644 index 000000000..c85afc0d3 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_focused1.lua @@ -0,0 +1,73 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 1024, 640) + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=args.screen} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to focused.", function() + --DOC_HIDE_END + -- Set the filter to focused. + tasklist.filter = awful.widget.tasklist.filter.focused + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_minimizedcurrenttags1.lua b/tests/examples/sequences/client/tasklist_filter_minimizedcurrenttags1.lua new file mode 100644 index 000000000..07374239a --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_minimizedcurrenttags1.lua @@ -0,0 +1,82 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{ + class = name, name = name, x = 2094, y=10, width = 60, height =50, tags=args.tags, minimized=args.minimized + } +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for k, t in ipairs(screen[1].tags) do + for i= 1, 2 do + awful.spawn("Client #"..(k-1)*2 + i, {tags = {t}, minimized = i == 1}) + end + end + + --DOC_NEWLINE + + -- Selected some tags. + screen[1].tags[3].selected = true + screen[1].tags[5].selected = true + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to minimizedcurrenttags.", function() + --DOC_HIDE_END + -- Set the filter to minimizedcurrenttags. + tasklist.filter = awful.widget.tasklist.filter.minimizedcurrenttags + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = false, display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_layout1.lua b/tests/examples/sequences/client/tasklist_layout1.lua new file mode 100644 index 000000000..5619de919 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_layout1.lua @@ -0,0 +1,117 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 800, 480) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1]) +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + buttons = { + awful.button({ }, 1, function (c) + c:activate { + context = "tasklist", + action = "toggle_minimization" + } + end), + awful.button({ }, 3, function() awful.menu.client_list { theme = { width = 250 } } end), + awful.button({ }, 4, function() awful.client.focus.byidx(-1) end), + awful.button({ }, 5, function() awful.client.focus.byidx( 1) end), + }, + } + + --DOC_NEWLINE + + tasklist:connect_signal("property::count", function(self) + local count = self.count + --DOC_NEWLINE + if count > 5 and not self.is_grid then + self.base_layout = wibox.widget { + forced_num_rows = 2, + homogeneous = true, + expand = true, + spacing = 2, + layout = wibox.layout.grid.horizontal + } + --DOC_NEWLINE + self.is_grid = true + elseif count <= 5 and self.is_grid then + self.base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal + } + --DOC_NEWLINE + self.is_grid = false + end + end) + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} +end + + +--DOC_NEWLINE + +module.add_event("Spawn 5 clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients. + for i=1, 5 do + awful.spawn("Client #"..i) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_widget(_tl, nil, 22) + +module.add_event("Spawn another client.", function() + --DOC_HIDE_END + -- Spawn another client. + awful.spawn("Client #6") + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 44) + +module.add_event("Kill 3 clients.", function() + --DOC_HIDE_END + -- Kill 3 clients. + for _=1, 3 do + client.get()[1]:kill() + end + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_screen1.lua b/tests/examples/sequences/client/tasklist_screen1.lua new file mode 100644 index 000000000..392aa15b5 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_screen1.lua @@ -0,0 +1,87 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + layout = require("awful.layout"), + button = require("awful.button") +} +require("awful.ewmh") +screen[1]:fake_resize(0, 0, 1024, 640) +screen.fake_add(1050, 0, 1024, 640).outputs = {["eVGA1"] = {mm_height=50, mm_width=80 }} --DOC_HIDE + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[2], awful.layout.suit.tile.left) + +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = screen[1], + filter = awful.widget.tasklist.filter.currenttags, + buttons = { + awful.button({ }, 1, function (c) + c:activate { + context = "tasklist", + action = "toggle_minimization" + } + end), + awful.button({ }, 3, function() awful.menu.client_list { theme = { width = 250 } } end), + awful.button({ }, 4, function() awful.client.focus.byidx(-1) end), + awful.button({ }, 5, function() awful.client.focus.byidx( 1) end), + }, + } + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=args.screen} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + + -- Spawn 3 clients on screen 2. + for i=1, 3 do + awful.spawn("Client #"..(5+i), {screen = screen[2]}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +module.display_tags() + +--DOC_NEWLINE +module.display_widget(_tl, nil, 22) + +module.add_event("Change the tasklist screen.", function() + --DOC_HIDE_END + -- Change the tastlist screen. + tasklist.screen = screen[2] + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false , display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_widget_template1.lua b/tests/examples/sequences/client/tasklist_widget_template1.lua new file mode 100644 index 000000000..08e373cba --- /dev/null +++ b/tests/examples/sequences/client/tasklist_widget_template1.lua @@ -0,0 +1,89 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 800, 480) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1]) +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} +end + + +--DOC_NEWLINE + +module.add_event("Spawn 5 clients.", function() + + -- Spawn 5 clients. + for i=1, 5 do + awful.spawn("Client #"..i) + end + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_widget(_tl, nil, 22) + +module.add_event("Change the widget template.", function() + --DOC_HIDE_END + -- Change the widget template. + tasklist.widget_template = { + { + { + { + { + id = "icon_role", + widget = wibox.widget.imagebox, + }, + margins = 2, + widget = wibox.container.margin, + }, + { + id = "text_role", + widget = wibox.widget.textbox, + }, + layout = wibox.layout.fixed.horizontal, + }, + left = 10, + right = 10, + widget = wibox.container.margin + }, + id = "background_role", + widget = wibox.container.background, + } + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/wibox/awidget/tasklist/style_align.lua b/tests/examples/wibox/awidget/tasklist/style_align.lua new file mode 100644 index 000000000..5ca8c0a29 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_align.lua @@ -0,0 +1,39 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END +for _, value in ipairs { "left", "center", "right" } do + beautiful.tasklist_align = value + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.layout.flex.horizontal + } + + tasklist._do_tasklist_update_now() + tasklist.forced_width = 600 + parent:add(_memento(tasklist, 600, 22, nil, true)) --luacheck: globals _memento + --DOC_HIDE_END +end + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_bg_focus.lua b/tests/examples/wibox/awidget/tasklist/style_bg_focus.lua new file mode 100644 index 000000000..cc2a2848a --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_bg_focus.lua @@ -0,0 +1,64 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local gears = { color = require("gears.color") } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_bg_focus = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_bg_minimize.lua b/tests/examples/wibox/awidget/tasklist/style_bg_minimize.lua new file mode 100644 index 000000000..5653b25a8 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_bg_minimize.lua @@ -0,0 +1,64 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local gears = { color = require("gears.color") } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_bg_minimize = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_bg_normal.lua b/tests/examples/wibox/awidget/tasklist/style_bg_normal.lua new file mode 100644 index 000000000..8b75dcb16 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_bg_normal.lua @@ -0,0 +1,64 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local gears = { color = require("gears.color") } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_bg_normal = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_bg_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_bg_urgent.lua new file mode 100644 index 000000000..c29971a61 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_bg_urgent.lua @@ -0,0 +1,64 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local gears = { color = require("gears.color") } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_bg_urgent = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_disable_icon.lua b/tests/examples/wibox/awidget/tasklist/style_disable_icon.lua new file mode 100644 index 000000000..a03edd3fb --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_disable_icon.lua @@ -0,0 +1,38 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END +for _, value in ipairs { true, false } do + beautiful.tasklist_disable_icon = value + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_disable_task_name.lua b/tests/examples/wibox/awidget/tasklist/style_disable_task_name.lua new file mode 100644 index 000000000..76b6ebeaa --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_disable_task_name.lua @@ -0,0 +1,39 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END +for _, value in ipairs { true, false } do + beautiful.tasklist_disable_task_name = value + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_fg_focus.lua b/tests/examples/wibox/awidget/tasklist/style_fg_focus.lua new file mode 100644 index 000000000..84af9e8bd --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_fg_focus.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff" } do + beautiful.tasklist_fg_focus = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_fg_minimize.lua b/tests/examples/wibox/awidget/tasklist/style_fg_minimize.lua new file mode 100644 index 000000000..b0479f2ac --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_fg_minimize.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff" } do + beautiful.tasklist_fg_minimize = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_fg_normal.lua b/tests/examples/wibox/awidget/tasklist/style_fg_normal.lua new file mode 100644 index 000000000..029412f2c --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_fg_normal.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff" } do + beautiful.tasklist_fg_normal = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_fg_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_fg_urgent.lua new file mode 100644 index 000000000..cd51b5bc6 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_fg_urgent.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff" } do + beautiful.tasklist_fg_urgent = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_font.lua b/tests/examples/wibox/awidget/tasklist/style_font.lua new file mode 100644 index 000000000..c1ca3ea3c --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_font.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do + beautiful.tasklist_font = font + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_font_focus.lua b/tests/examples/wibox/awidget/tasklist/style_font_focus.lua new file mode 100644 index 000000000..609ebd2e3 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_font_focus.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do + beautiful.tasklist_font_focus = font + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_font_minimized.lua b/tests/examples/wibox/awidget/tasklist/style_font_minimized.lua new file mode 100644 index 000000000..65d761cd8 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_font_minimized.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do + beautiful.tasklist_font_minimized = font + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_font_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_font_urgent.lua new file mode 100644 index 000000000..34c638e2a --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_font_urgent.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do + beautiful.tasklist_font_urgent = font + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_plain_task_name.lua b/tests/examples/wibox/awidget/tasklist/style_plain_task_name.lua new file mode 100644 index 000000000..9585d5752 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_plain_task_name.lua @@ -0,0 +1,45 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" + +client.get()[1].floating = true +client.get()[2].sticky = true + +--DOC_HIDE_END +for _, value in ipairs { true, false } do + beautiful.tasklist_plain_task_name = value + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape.lua b/tests/examples/wibox/awidget/tasklist/style_shape.lua new file mode 100644 index 000000000..c5011281f --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 + +--DOC_NEWLINE + +local function customized(cr, width, height) + return gears.shape.parallelogram(cr, width, height, width - height) +end + +--DOC_NEWLINE + +for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do + beautiful.tasklist_shape = shape + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_color.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_color.lua new file mode 100644 index 000000000..9a0731aee --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_color.lua @@ -0,0 +1,58 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +beautiful.tasklist_shape_border_width = 2 + +--DOC_NEWLINE + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE + +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_shape_border_color = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_color_minimized.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_color_minimized.lua new file mode 100644 index 000000000..b5c91c197 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_color_minimized.lua @@ -0,0 +1,71 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +beautiful.tasklist_shape_border_width = 2 + +--DOC_NEWLINE + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE + +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_shape_border_color_minimized = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_color_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_color_urgent.lua new file mode 100644 index 000000000..fa6fe4e8e --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_color_urgent.lua @@ -0,0 +1,71 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +beautiful.tasklist_shape_border_width = 2 + +--DOC_NEWLINE + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE + +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_shape_border_color_urgent = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_width.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_width.lua new file mode 100644 index 000000000..85de4527d --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_width.lua @@ -0,0 +1,46 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect + +--DOC_NEWLINE + +for _, bw in ipairs { 0, 2, 4, 6 } do + beautiful.tasklist_shape_border_width = bw + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_width_minimized.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_width_minimized.lua new file mode 100644 index 000000000..95f4a36b5 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_width_minimized.lua @@ -0,0 +1,57 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +--DOC_NEWLINE + +for _, bw in ipairs { 0, 2, 4, 6 } do + beautiful.tasklist_shape_border_width_minimized = bw + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_width_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_width_urgent.lua new file mode 100644 index 000000000..cc81b854d --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_width_urgent.lua @@ -0,0 +1,58 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect + +--DOC_NEWLINE + +for _, bw in ipairs { 0, 2, 4, 6 } do + beautiful.tasklist_shape_border_width_urgent = bw + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_focus.lua b/tests/examples/wibox/awidget/tasklist/style_shape_focus.lua new file mode 100644 index 000000000..9ec34ad20 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_focus.lua @@ -0,0 +1,63 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 + +--DOC_NEWLINE + +local function customized(cr, width, height) + return gears.shape.parallelogram(cr, width, height, width - height) +end + +--DOC_NEWLINE + +for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do + beautiful.tasklist_shape_focus = shape + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width.lua b/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width.lua new file mode 100644 index 000000000..d83ad7f44 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width.lua @@ -0,0 +1,58 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect + +--DOC_NEWLINE + +for _, bw in ipairs { 0, 2, 4, 6 } do + beautiful.tasklist_shape_border_width_focus = bw + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width_focus.lua b/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width_focus.lua new file mode 100644 index 000000000..8bd7196b7 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width_focus.lua @@ -0,0 +1,71 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +beautiful.tasklist_shape_border_width = 2 + +--DOC_NEWLINE + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE + +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_shape_border_color_focus = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_minimized.lua b/tests/examples/wibox/awidget/tasklist/style_shape_minimized.lua new file mode 100644 index 000000000..bbbe20dd9 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_minimized.lua @@ -0,0 +1,63 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 + +--DOC_NEWLINE + +local function customized(cr, width, height) + return gears.shape.parallelogram(cr, width, height, width - height) +end + +--DOC_NEWLINE + +for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do + beautiful.tasklist_shape_minimized = shape + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_shape_urgent.lua new file mode 100644 index 000000000..9ec34ad20 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_urgent.lua @@ -0,0 +1,63 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 + +--DOC_NEWLINE + +local function customized(cr, width, height) + return gears.shape.parallelogram(cr, width, height, width - height) +end + +--DOC_NEWLINE + +for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do + beautiful.tasklist_shape_focus = shape + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_spacing.lua b/tests/examples/wibox/awidget/tasklist/style_spacing.lua new file mode 100644 index 000000000..66c4f8d6d --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_spacing.lua @@ -0,0 +1,39 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END +for _, spacing in ipairs { 0, 4, 8, 12 } do + beautiful.tasklist_spacing = spacing + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 From b6214af364fac07e2ac0ad4227b15dcbe3d7c516 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Wed, 8 Dec 2021 12:24:46 -0800 Subject: [PATCH 013/134] doc: Add a `deprecatedmethod` tag. Like all the others, but for a method. --- docs/config.ld | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 2e51ce765..dffe3ecf2 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -102,6 +102,8 @@ new_type("staticfct", "Static module functions", false, "Parameters") new_type("property", "Object properties", false, "Type constraints") -- Documentation for objects deprecated properties new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints") +-- Documentation for objects deprecated methods +new_type("deprecatedmethod", "Deprecated object methods", false, "Parameters") -- Use a custom type for the methods to bypass the faulty ldoc built-in detection. -- (yes, the space after Methods *is* on purpose to avoid clashing with ldoc -- internal "methods" concept) @@ -911,25 +913,28 @@ local display_type = { -- Add the `-> ret_type` annotation. local display_return_type = { - method = true, - staticfct = true, + method = true, + deprecatedmethod = true, + staticfct = true, } -- Show return values. local show_return = { - ["function"] = true, - constructorfct = true, - constructorfct2 = true, - legacylayout = true, - staticfct = true, - method = true, - deprecated = true, + ["function"] = true, + constructorfct = true, + constructorfct2 = true, + legacylayout = true, + staticfct = true, + method = true, + deprecated = true, + deprecatedmethod = true, } -- The different type of deprecation. local is_deprecated = { deprecated = true, deprecatedproperty = true, + deprecatedmethod = true, deprecatedsignal = true, } @@ -975,12 +980,12 @@ custom_display_name_handler = function(item, default_handler) end end - if is_deprecated[item.type] then - return ret .. " [deprecated]" + if item.type:match("method") then + ret = render_methods(item) end - if item.type == "method" then - ret = render_methods(item) + if is_deprecated[item.type] then + return ret .. " [deprecated]" end -- Get rid of the "module:" in front of method names. It is either wrong or From 91fe314e0b9d52f56ccc8c398767e10b1095c70f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 11 Dec 2021 09:29:27 -0800 Subject: [PATCH 014/134] gears.color: Fix color serialization. Some widgets like the tasklist serialize the theme colors to use them in Pango markup. If the theme color were already converted to pattern, that blew up. With this fix, pattern can be converted back into strings correctly. --- lib/gears/color.lua | 48 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/lib/gears/color.lua b/lib/gears/color.lua index 2d906ae0f..7497965b1 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -53,6 +53,7 @@ local surface = require("gears.surface") local color = { mt = {} } local pattern_cache +local color_string_cache = setmetatable({}, { __mode = "k" }) --- Parse a HTML-color. -- This function can parse colors like `#rrggbb` and `#rrggbbaa` and also `red`. @@ -354,12 +355,59 @@ function color.recolor_image(image, new_color) return image end +--- Convert a color back to an hexadecimal color code. +-- +-- This takes an input color, pattern or gradient and attempt to convert it +-- to a color. If this fails, `fallback` is returned. This is useful when a +-- color needs to be concatenated into a Pango markup string. +-- +-- @staticfct gears.color.to_rgba_string +-- @tparam pattern|string|gradient color Note that only solid colors can be +-- convedted to the `RGBA` format. +-- @tparam[opt=nil] pattern|string|gradient fallback The color to return +-- if `color` cannot be converted to a string. +-- @treturn string The color in `#rrggbbaa` format. +-- @see gears.color.ensure_pango_color + +function color.to_rgba_string(col, fallback) + if (not col) and (not fallback) then return nil end + + -- Prevent infinite recursion. + if not col then return color.to_rgba_string(fallback) end + + if color_string_cache[col] then + return color_string_cache[col] + end + + col = color.create_pattern(col) + + local error1, error2, r, g, b, a = pcall(function () return col:get_rgba() end) + + -- Surface patterns don't have an RGBA representation. + if (not error1) or error2 ~= "SUCCESS" then return color.to_rgba_string(fallback) end + + color_string_cache[col] = string.format( + "#%02x%02x%02x%02x", + math.floor(r*255), + math.floor(g*255), + math.floor(b*255), + math.floor(a*255) + ) + + return color_string_cache[col] +end + --- Get a valid color for Pango markup -- @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) + -- This will happen if `gears.color` has been called in the theme. + if type(check_color) == "userdata" then + return color.to_rgba_string(check_color, fallback) + end + check_color = tostring(check_color) -- Pango markup supports alpha, PangoColor does not. Thus, check for this. local len = #check_color From 18468d32dd54c92dc39a49e8d886fb4b11bb4258 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 11 Dec 2021 09:31:06 -0800 Subject: [PATCH 015/134] widget: Fix saving a widget to a file. Previously, if `beautiful.fg_normal` wasn't black, it would not render correctly. --- build-utils/check_for_invalid_requires.lua | 5 ++++- lib/gears/surface.lua | 18 ++++++++++++++---- lib/wibox/widget/init.lua | 10 ++++++++++ 3 files changed, 28 insertions(+), 5 deletions(-) diff --git a/build-utils/check_for_invalid_requires.lua b/build-utils/check_for_invalid_requires.lua index 1c9cd29c7..d0adad300 100755 --- a/build-utils/check_for_invalid_requires.lua +++ b/build-utils/check_for_invalid_requires.lua @@ -62,7 +62,10 @@ local allowed_deps = { naughty = true, }, -- TODO: Get rid of these - ["gears.surface"] = { ["wibox.hierarchy"] = true }, + ["gears.surface"] = { + ["wibox.hierarchy"] = true, + beautiful = true, + }, } -- Turn "foo.bar.baz" into "foo.bar". Returns nil if there is nothing more to diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index 55d22116b..38c05796c 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -9,7 +9,7 @@ local type = type local capi = { awesome = awesome } local cairo = require("lgi").cairo local GdkPixbuf = require("lgi").GdkPixbuf -local color = nil +local color, beautiful = nil, nil local gdebug = require("gears.debug") local hierarchy = require("wibox.hierarchy") @@ -232,7 +232,7 @@ 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 draw_to_svg_file +-- @deprecated widget_to_svg -- @tparam widget widget A widget -- @tparam string path The output file path -- @tparam number width The surface width @@ -243,17 +243,22 @@ end -- @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}) + "gears.surface.widget_to_svg", {deprecated_in=5}) local img = cairo.SvgSurface.create(path, width, height) local cr = cairo.Context(img) + -- Bad dependecy, but this is deprecated. + beautiful = beautiful or require("beautiful") + color = color or require("gears.color") + cr:set_source(color(beautiful.fg_normal)) + return img, run_in_hierarchy(widget, cr, width, height) 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 draw_to_image_surface +-- @deprecated widget_to_surface -- @tparam widget widget A widget -- @tparam number width The surface width -- @tparam number height The surface height @@ -268,6 +273,11 @@ function surface.widget_to_surface(widget, width, height, format) local img = cairo.ImageSurface(format or cairo.Format.ARGB32, width, height) local cr = cairo.Context(img) + -- Bad dependecy, but this is deprecated. + color = color or require("gears.color") + beautiful = beautiful or require("beautiful") + cr:set_source(color(beautiful.fg_normal)) + return img, run_in_hierarchy(widget, cr, width, height) end diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index 683e8bc7b..ccc49c9af 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -6,6 +6,8 @@ local cairo = require("lgi").cairo local hierarchy = require("wibox.hierarchy") +local gcolor = require("gears.color") +local beautiful = nil local widget = { base = require("wibox.widget.base"); @@ -55,6 +57,10 @@ end function widget.draw_to_svg_file(wdg, path, width, height, context) local img = cairo.SvgSurface.create(path, width, height) local cr = cairo.Context(img) + + beautiful = beautiful or require("beautiful") + cr:set_source(gcolor(beautiful.fg_normal)) + widget.draw_to_cairo_context(wdg, cr, width, height, context) img:finish() end @@ -70,6 +76,10 @@ end 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) + + beautiful = beautiful or require("beautiful") + cr:set_source(gcolor(beautiful.fg_normal)) + widget.draw_to_cairo_context(wdg, cr, width, height, context) return img end From 935da05be4441dab683f371723eab903fe3014e3 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 11 Dec 2021 09:32:04 -0800 Subject: [PATCH 016/134] layoutlist: Sanitize the color when building Pango strings. This was aready done in the `tasklist` and `taglist`. --- lib/awful/widget/layoutlist.lua | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index d61030f3e..2fffe2bbf 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -33,6 +33,7 @@ local gtable = require("gears.table") local beautiful= require("beautiful") local alayout = require("awful.layout") local surface = require("gears.surface") +local gcolor = require("gears.color") local module = {} @@ -84,7 +85,7 @@ local function wb_label(item, _, textbox) local text = "" if item.name then - text = ""..item.name..'' + text = ""..item.name..'' end return text, bg, nil, item.icon, { From caad1bec55397890bbd1bfe9973c4573dbedf795 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 11 Dec 2021 09:32:44 -0800 Subject: [PATCH 017/134] tooltip: Make the `args` optional. It would render a non-useful error when calling `awful.tooltip()`. --- lib/awful/tooltip.lua | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index d025fa8ae..2e4816cc7 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -633,6 +633,8 @@ end -- @see align -- @constructorfct awful.tooltip function tooltip.new(args) + args = args or {} + -- gears.object, properties are linked to set_/get_ functions local self = object { enable_properties = true, From f6f57e7ba0857eedb3065c8fb569b46bb3c8c947 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 09:49:00 -0800 Subject: [PATCH 018/134] gears.color: Add a function to apply the alpha to a color. Some code in awesome concatenate color strings. This means it blows up when the pattern are used instead of color, with this, it fails gracefully (by returning the unmodified pattern). --- lib/gears/color.lua | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/lib/gears/color.lua b/lib/gears/color.lua index 7497965b1..f872221a3 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -355,6 +355,22 @@ function color.recolor_image(image, new_color) return image end +--- Take an input color and set a different opacity. +-- +-- @staticfct gears.color.change_opacity +-- @tparam string|pattern input The input color. +-- @tparam number opacity A floating point number between 0 and 1. +-- @treturn The new color if successful or `input` if invalid. +function color.change_opacity(input, opacity) + input = color.create_pattern(input) + + local error, r, g, b, _ = input:get_rgba() + + if error ~= "SUCCESS" then return input end + + return cairo.Pattern.create_rgba(r, g, b, opacity) +end + --- Convert a color back to an hexadecimal color code. -- -- This takes an input color, pattern or gradient and attempt to convert it From 197ed41c2d0c047180f990b5553fb968a0315154 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 09:53:18 -0800 Subject: [PATCH 019/134] doc: Use the theme foreground color instead of black in the templates. This is a step toward adding a dark theme to the doc. Otherwise, the images were black on dark grey, which is impossible to read. --- tests/examples/screen/template.lua | 71 ++++++++++++++++++--------- tests/examples/sequences/template.lua | 17 ++++--- tests/examples/wibox/template.lua | 4 ++ 3 files changed, 62 insertions(+), 30 deletions(-) diff --git a/tests/examples/screen/template.lua b/tests/examples/screen/template.lua index 8fb87009c..98fcfa52c 100644 --- a/tests/examples/screen/template.lua +++ b/tests/examples/screen/template.lua @@ -10,6 +10,7 @@ local Pango = require("lgi").Pango local PangoCairo = require("lgi").PangoCairo local color = require("gears.color") local aclient = require("awful.client") +local beautiful = require("beautiful") -- Let the test request a size and file format local args = loadfile(file_path)() or 10 @@ -79,11 +80,11 @@ local function stripe_pat(col, angle, line_width, spacing) end local colors = { - geometry = "#000000", + geometry = beautiful.fg_normal, workarea = "#0000ff", tiling_area = "#ff0000", padding_area = "#ff0000", - wibar = "#000000", + wibar = beautiful.fg_normal, tiling_client = "#ff0000", gaps = "#9900ff", } @@ -94,12 +95,12 @@ local function draw_area(_, rect, name, offset, highlight) if highlight then cr:save() - cr:set_source(stripe_pat(colors[name].."22", nil, 1, 3)) + cr:set_source(stripe_pat(color.change_opacity(colors[name], 0.0863), nil, 1, 3)) cr:fill_preserve() cr:restore() end - cr:set_source(color(colors[name].."44")) + cr:set_source(color.change_opacity(colors[name], 0.1725)) cr:stroke() end @@ -115,16 +116,16 @@ local function draw_bounding_area(_, rect, hole, name, offset) end local function draw_solid_area(_, rect, name, offset, alpha) - alpha = alpha or "59" -- Defaults to 35% + alpha = alpha or 0.2314 -- Defaults to 35% local x, y = rect.x*factor+offset, rect.y*factor+offset cr:rectangle(x, y, rect.width*factor, rect.height*factor) cr:save() - cr:set_source(color.create_solid_pattern(colors[name] .. alpha)) + cr:set_source(color.change_opacity(colors[name], alpha)) cr:fill_preserve() cr:restore() - cr:set_source(color(colors[name].."44")) + cr:set_source(color.change_opacity(colors[name], 0.0863)) cr:stroke() end @@ -141,7 +142,7 @@ local function write_on_area_middle(rect, text, offset) local _, logical = playout:get_pixel_extents() local dx = (rect.x*factor+offset) + (rect.width*factor - logical.width) / 2 local dy = (rect.y*factor+offset) + (rect.height*factor - logical.height) / 2 - cr:set_source_rgb(0, 0, 0) + cr:set_source(beautiful.fg_normal) cr:move_to(dx, dy) cr:show_layout(playout) end @@ -265,7 +266,7 @@ end local function draw_vruler(s, dx2, sx, ruler, layer) local pad = 5+(layer-1)*dx2 - cr:set_source(color(ruler.color or (colors[ruler.label].."66"))) + cr:set_source(color(ruler.color or (color.change_opacity(colors[ruler.label], 0.2588)))) cr:move_to(sx+layer*dx2, ruler.y*factor) cr:line_to(sx+layer*dx2, ruler.y*factor+ruler.height*factor) cr:stroke() @@ -291,7 +292,7 @@ end local function draw_hruler(s, dx2, sy, ruler, layer) local pad = 10+(layer-1)*(dx2 or 0) - cr:set_source(color(ruler.color or (colors[ruler.label].."66"))) + cr:set_source(color(ruler.color or (color.change_opacity(colors[ruler.label], 0.2588)))) cr:move_to(ruler.x*factor, sy+pad) cr:line_to(ruler.x*factor+ruler.width*factor, sy+pad) cr:stroke() @@ -426,7 +427,7 @@ local function draw_gaps(s) x = offset.x+hgap[1]+tr_x, width = math.ceil(hgap[2]-hgap[1]), label = nil, - color = colors.gaps.."66", + color = color.change_opacity(colors.gaps, 0.2588), align = true }, 1 @@ -442,7 +443,7 @@ local function draw_gaps(s) y = offset.y+vgap[1]+tr_y, height = math.ceil(vgap[2]-vgap[1]), label = nil, - color = colors.gaps.."66", + color = color.change_opacity(colors.gaps, 0.2588), align = true }, 1 @@ -475,7 +476,12 @@ local function draw_struts(s) s, s.geometry.y*SCALE_FACTOR, get_text_height(), - {x = s.geometry.x+tr_x*2, width = left, color = colors.gaps.."66", align = true}, + { + x = s.geometry.x+tr_x*2, + width = left, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1 ) end @@ -485,7 +491,12 @@ local function draw_struts(s) s, get_text_height()*1.5, s.geometry.x*SCALE_FACTOR, - {y=s.geometry.y+tr_y*(1/factor), height = top, color = colors.gaps.."66", align = true}, + { + y = s.geometry.y+tr_y*(1/factor), + height = top, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1 ) end @@ -495,7 +506,12 @@ local function draw_struts(s) s, s.geometry.y*SCALE_FACTOR, get_text_height(), - {x = s.geometry.x, width = left, color = colors.gaps.."66", align = true}, + { + x = s.geometry.x, + width = left, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1 ) end @@ -508,7 +524,7 @@ local function draw_struts(s) { y = s.geometry.y+tr_y*(1/factor)+s.geometry.height - bottom, height = bottom, - color = colors.gaps.."66", + color = color.change_opacity(colors.gaps, 0.2588), align = true }, 1 @@ -528,8 +544,19 @@ local function draw_mwfact(s) local w1, w2 = math.ceil(width*mwfact), math.ceil(width*(1-mwfact)) - draw_hruler(s, offset, get_text_height(), {x=offset,width=w1,color = colors.gaps.."66", align=true}, 1) - draw_hruler(s, offset, get_text_height(), {x=offset+w1,width=w2,color = colors.gaps.."66", align=true}, 1) + draw_hruler(s, offset, get_text_height(), { + x = offset, + width = w1, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1) + + draw_hruler(s, offset, get_text_height(), { + x = offset+w1, + width = w2, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1) cr:translate(tr_x, tr_y) end @@ -560,7 +587,7 @@ local function draw_wfact(s) { y = math.floor(offset), height =math.ceil( (height/sum) * windowfacts[1][i]), - color = colors.gaps.."66", + color = color.change_opacity(colors.gaps, 0.2588), align = true, }, 1 @@ -634,7 +661,7 @@ end -- end local function draw_info(s) - cr:set_source_rgb(0, 0, 0) + cr:set_source(beautiful.fg_normal) local pctx = PangoCairo.font_map_get_default():create_context() local playout2 = Pango.Layout.new(pctx) @@ -792,7 +819,7 @@ for k=1, screen.count() do height = c.height + 2*gap, } - draw_client(s, proxy, 'gaps', (k-1)*10, nil, "11") + draw_client(s, proxy, 'gaps', (k-1)*10, nil, 0.0431) elseif args.draw_client_snap and c.floating then local proxy = { x = c.x - sd, @@ -801,7 +828,7 @@ for k=1, screen.count() do height = c.height + 2*sd, } - draw_client(s, proxy, 'gaps', (k-1)*10, nil, "11") + draw_client(s, proxy, 'gaps', (k-1)*10, nil, 0.0431) end draw_client(s, c, 'tiling_client', (k-1)*10, label) diff --git a/tests/examples/sequences/template.lua b/tests/examples/sequences/template.lua index 5143ee71a..719c5f06f 100644 --- a/tests/examples/sequences/template.lua +++ b/tests/examples/sequences/template.lua @@ -96,7 +96,7 @@ local function draw_lines() if (not self.widget_pos) or (not self.pager_pos) then return end cr:set_line_width(1) - cr:set_source_rgba(0,0,0,0.3) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.3)) local count = #self.widget_pos @@ -131,7 +131,7 @@ local function gen_vertical_line(args) local w = wibox.widget.base.make_widget() function w:draw(_, cr, w2, h) - cr:set_source_rgba(0,0,0,0.5) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.5)) if args.begin then cr:rectangle(w2/2-0.5, h/2, 1, h/2) @@ -147,7 +147,7 @@ local function gen_vertical_line(args) cr:arc(w2/2, args.center and h/2 or w2/2 ,bar_size/4, 0, 2*math.pi) cr:set_source_rgb(1,1,1) cr:fill_preserve() - cr:set_source_rgba(0,0,0,0.5) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.5)) cr:stroke() end end @@ -302,7 +302,8 @@ local function fake_arrange(tag) focus = focus_wrap, geometries = setmetatable({}, {__mode = "k"}), workarea = tag.screen.workarea, - useless_gap = tag.gaps or 4, + useless_gap = tag.gaps or beautiful.useless_gap or 4, + gap_single_client= tag.gap_single_client or beautiful.gap_single_client or nil, apply_size_hints = false, } @@ -355,14 +356,14 @@ local function gen_fake_clients(tag, args) cr:stroke() if show_name and type(geom.c) == "table" and geom.c.name then - cr:set_source_rgb(0, 0, 0) + cr:set_source(beautiful.fg_normal) cr:move_to(x + 2, y + height - 2) cr:show_text(geom.c.name) end end -- Draw the screen outline. - cr:set_source(color("#00000044")) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.1725)) cr:set_line_width(1.5) cr:set_dash({10,4},1) cr:rectangle(0, 0, w, h) @@ -447,7 +448,7 @@ local function gen_label(text) end local function draw_info(s, cr, factor) - cr:set_source_rgba(0, 0, 0, 0.4) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.4)) local pctx = PangoCairo.font_map_get_default():create_context() local playout = Pango.Layout.new(pctx) @@ -639,7 +640,7 @@ local function gen_screens(l, screens, args) end function s.widget:draw(_, cr, w, h) - cr:set_source(color("#00000044")) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.1725)) cr:set_line_width(1.5) cr:set_dash({10,4},1) cr:rectangle(1,1,w-2,h-2) diff --git a/tests/examples/wibox/template.lua b/tests/examples/wibox/template.lua index 0c4975fd8..409e0ee6e 100644 --- a/tests/examples/wibox/template.lua +++ b/tests/examples/wibox/template.lua @@ -4,6 +4,8 @@ require("_common_template")(...) local wibox = require( "wibox" ) local surface = require( "gears.surface" ) local cairo = require("lgi").cairo +local color = require("gears.color") +local beautiful = require("beautiful") --- Create a copy of the widget frozen in time. -- This is useful whe the global state is modified between the time this is @@ -22,6 +24,8 @@ function _memento(wdg, width, height, context, force) -- luacheck: globals _meme local cr = cairo.Context(memento) + cr:set_source(color(beautiful.fg_normal)) + wibox.widget.draw_to_cairo_context(wdg, cr, w, h, context) return wibox.widget { From 2c18547a6b5b46170d18ae771c1b897f3495e3c3 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 09:55:06 -0800 Subject: [PATCH 020/134] doc: Post-process all auto-generated SVG. This removes the hardcoded foreground color and inherit it from the browser and/or CSS stylesheet. This commit only support the foreground colors, future changes could extend it to support all standard colors. --- tests/examples/CMakeLists.txt | 42 +++++++++++++++------ tests/examples/_postprocess.lua | 66 +++++++++++++++++++++++++++++++++ 2 files changed, 97 insertions(+), 11 deletions(-) create mode 100755 tests/examples/_postprocess.lua diff --git a/tests/examples/CMakeLists.txt b/tests/examples/CMakeLists.txt index 71befc532..af3f28923 100644 --- a/tests/examples/CMakeLists.txt +++ b/tests/examples/CMakeLists.txt @@ -71,7 +71,9 @@ ${LUA_PATH_}") set(LUA_COV_RUNNER env -u LUA_PATH_5_1 -u LUA_PATH_5_2 -u LUA_PATH_5_3 "LUA_PATH=${LUA_PATH_}" "AWESOME_THEMES_PATH=${TOP_SOURCE_DIR}/themes/" "SOURCE_DIRECTORY=${TOP_SOURCE_DIR}" ${LUA_COV_RUNNER}) # The documentation images directory. +set(RAW_IMAGE_DIR "${CMAKE_BINARY_DIR}/raw_images") set(IMAGE_DIR "${CMAKE_BINARY_DIR}/doc/images") +file(MAKE_DIRECTORY "${RAW_IMAGE_DIR}") file(MAKE_DIRECTORY "${IMAGE_DIR}") # Escape potentially multiline strings to be part of the API doc. @@ -221,6 +223,7 @@ function(run_test test_path namespace escaped_content) # Get the file name without the extension. get_filename_component(${test_path} TEST_FILE_NAME NAME) + set(RAW_IMAGE_PATH "${RAW_IMAGE_DIR}/AUTOGEN${namespace}_${TEST_FILE_NAME}") set(IMAGE_PATH "${IMAGE_DIR}/AUTOGEN${namespace}_${TEST_FILE_NAME}") # Read the code and turn it into an usage example. @@ -231,12 +234,14 @@ function(run_test test_path namespace escaped_content) # Does the test generate an output image? if(tmp_content MATCHES "--DOC_GEN_IMAGE") + set(OUTPUT_RAW_IMAGE_PATH "${RAW_IMAGE_PATH}.svg") set(OUTPUT_IMAGE_PATH "${IMAGE_PATH}.svg") escape_string( "![Usage example](../images/AUTOGEN${namespace}_${TEST_FILE_NAME}.svg)\n" "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT "" ) else() + set(OUTPUT_RAW_IMAGE_PATH "") set(OUTPUT_IMAGE_PATH "") endif() @@ -294,30 +299,44 @@ function(run_test test_path namespace escaped_content) STRING(REPLACE "/" "-" TARGET_NAME ${TARGET_NAME}) set(EXAMPLE_DOC_TEST_TARGETS ${EXAMPLE_DOC_TEST_TARGETS} ${TARGET_NAME} PARENT_SCOPE) - add_custom_target(${TARGET_NAME} - COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} + add_custom_target(${TARGET_NAME}_RAW + COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${RAW_IMAGE_PATH} VERBATIM) - if(NOT ${OUTPUT_IMAGE_PATH} STREQUAL "") - file(RELATIVE_PATH rel_output "${TOP_SOURCE_DIR}" "${OUTPUT_IMAGE_PATH}") + add_custom_target(${TARGET_NAME} + COMMAND "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" ${OUTPUT_RAW_IMAGE_PATH} "${OUTPUT_IMAGE_PATH}" + VERBATIM + DEPENDS ${TARGET_NAME}_RAW "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" + ) + + + if(NOT ${OUTPUT_RAW_IMAGE_PATH} STREQUAL "") + file(RELATIVE_PATH rel_output "${TOP_SOURCE_DIR}" "${OUTPUT_RAW_IMAGE_PATH}") if(tmp_content MATCHES "--DOC_GEN_OUTPUT") add_custom_command( - COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} ${IGNORE_ERRORS} + COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${RAW_IMAGE_PATH} ${IGNORE_ERRORS} # COMMENT "Running ${rel_test_path} (via ${rel_template}, generating ${rel_output})" DEPENDS ${template} ${test_path} - OUTPUT ${OUTPUT_IMAGE_PATH} + OUTPUT ${OUTPUT_RAW_IMAGE_PATH} OUTPUT ${expected_output_path} VERBATIM) else() add_custom_command( - COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} ${IGNORE_ERRORS} + COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${RAW_IMAGE_PATH} ${IGNORE_ERRORS} # COMMENT "Running ${rel_test_path} (via ${rel_template}, generating ${rel_output})" DEPENDS ${template} ${test_path} - OUTPUT ${OUTPUT_IMAGE_PATH} + OUTPUT ${OUTPUT_RAW_IMAGE_PATH} VERBATIM) endif() - set(EXAMPLE_DOC_GENERATED_FILES ${OUTPUT_IMAGE_PATH} ${EXAMPLE_DOC_GENERATED_FILES} - PARENT_SCOPE) + + add_custom_command( + COMMAND "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" ${OUTPUT_RAW_IMAGE_PATH} "${OUTPUT_IMAGE_PATH}" + DEPENDS ${template} ${test_path} ${OUTPUT_RAW_IMAGE_PATH} "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" + OUTPUT "${OUTPUT_IMAGE_PATH}" + VERBATIM) + + set(EXAMPLE_DOC_GENERATED_FILES "${OUTPUT_IMAGE_PATH}" ${EXAMPLE_DOC_GENERATED_FILES} PARENT_SCOPE) + elseif(tmp_content MATCHES "--DOC_GEN_OUTPUT") add_custom_command( COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} "" ${IGNORE_ERRORS} @@ -338,7 +357,8 @@ file(GLOB_RECURSE test_files FOLLOW_SYMLINKS LIST_DIRECTORIES false # Find and run all test files. foreach(file ${test_files}) if ((NOT "${file}" MATCHES ".*/shims/.*") - AND (NOT "${file}" MATCHES ".*/template.lua")) + AND (NOT "${file}" MATCHES ".*/template.lua") + AND (NOT "${file}" MATCHES ".*/_.*[.]lua")) # Get the file name without the extension. get_filename_component(TEST_FILE_NAME ${file} NAME_WE) diff --git a/tests/examples/_postprocess.lua b/tests/examples/_postprocess.lua new file mode 100755 index 000000000..9f30166c2 --- /dev/null +++ b/tests/examples/_postprocess.lua @@ -0,0 +1,66 @@ +#!/usr/bin/env lua + +-- This script takes `.svg` file generated by Cairo or Inkscape and +-- replace hardcoded colors so they can be set using CSS or the +-- web browser itself. This makes the accessibility mode work and +-- allows themes to be created for the documentation. + +local input, output = ... + +-- The second 24bit is just the 32 bit converted to #010001 and back. +local FOREGROUNDS = { + "rgb[(]0[.]5%%,0%%,0[.]5%%[)];", + "rgb[(]0[.]392157%%,0%%,0[.]392157%%[)];", + "#010001", +} + +local CLASSES = { + stroke = "svg_stroke", + fill = "svg_fill" +} + +local i, o = io.open(input, "r"), io.open(output, "w") + +if (not i) or (not o) then return end + +local line, count = i:read("*line"), 0 + +while line do + -- Deduplicate and concatenate the classes. + local classes = {} + local token_found = {} + local class_str = {} + + for _, token in ipairs { "fill", "stroke" } do + + for _, color in ipairs(FOREGROUNDS) do + line, count = line:gsub(token .. ":" .. color, token .. ":currentcolor;") + + -- Add the CSS class. + if count > 0 then + classes[CLASSES[token]] = true + end + + line, count = line:gsub(token .. ":" .. color, token .. ":currentcolor;") + + -- Add the CSS class. + if count > 0 and not token_found[token] then + token_found[token] = true + table.insert(classes, CLASSES[token]) + end + end + end + + for class in pairs(classes) do + table.insert(class_str, class) + end + + if #class_str > 0 then + line = line:gsub(' style="', ' class="' .. table.concat(class_str, ",") .. '" style="') + end + + o:write(line .. "\n") + line = i:read("*line") +end + +o:close() From b3cf35d9881e66f41c58641a6b405e82297c65bd Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 10:05:27 -0800 Subject: [PATCH 021/134] doc: Replace hardcoded colors with CSS in the static images. find ../docs/images -iname '*.svg' | xargs -i ../tests/examples/_postprocess.lua {} {} --- docs/images/client_geo.svg | 48 +++++++++++++------------- docs/images/mouse.svg | 44 ++++++++++++------------ docs/images/progressbar.svg | 68 ++++++++++++++++++------------------- docs/images/tag_props.svg | 46 ++++++++++++------------- 4 files changed, 103 insertions(+), 103 deletions(-) diff --git a/docs/images/client_geo.svg b/docs/images/client_geo.svg index 34c970a2b..88da6ae53 100644 --- a/docs/images/client_geo.svg +++ b/docs/images/client_geo.svg @@ -67,11 +67,11 @@ inkscape:connector-curvature="0" id="path6072" d="m 58.889889,0.75 402.388891,0 0,238.5 -402.388891,0 z" - style="fill:none;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703" + class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703" sodipodi:nodetypes="ccccc" /> Top titlebar Left titlebar Right titlebar Shape clip outline @@ -353,27 +353,27 @@ inkscape:connector-curvature="0" id="path6355" d="m 445.91815,214.03874 3.33912,0 0,8.64241 -3.33912,0" - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.50971645;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.87379962;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> diff --git a/docs/images/progressbar.svg b/docs/images/progressbar.svg index ade0797ef..ac8ef2d0f 100644 --- a/docs/images/progressbar.svg +++ b/docs/images/progressbar.svg @@ -76,115 +76,115 @@ style="fill:#a800ff;fill-opacity:0.49019602;fill-rule:nonzero;stroke:#ffff00;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1" /> margins.left paddings.right margins.bottom paddings.left color background_color border_color bar_border_width paddings.top margins.right border_width + class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703" /> + class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.2" /> @@ -90,21 +90,21 @@ inkscape:connector-curvature="0" id="path7597" d="m 427.60318,224.3777 10.21376,0 0,15.32064 -10.14227,0" - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" sodipodi:nodetypes="cccc" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.36000001;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> Gaps + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> Screen area Date: Mon, 13 Dec 2021 10:21:43 -0800 Subject: [PATCH 022/134] doc: Update some examples not to hardcode the foreground color. --- tests/examples/awful/popup/defaultconfig.lua | 3 ++- tests/examples/awful/popup/wiboxtypes.lua | 3 ++- tests/examples/awful/titlebar/defaulttitlebar.lua | 3 ++- tests/examples/awful/wibar/defaultwibar.lua | 3 ++- tests/examples/wibox/nwidget/default.lua | 3 ++- 5 files changed, 10 insertions(+), 5 deletions(-) diff --git a/tests/examples/awful/popup/defaultconfig.lua b/tests/examples/awful/popup/defaultconfig.lua index be28439ad..b6c7ba176 100644 --- a/tests/examples/awful/popup/defaultconfig.lua +++ b/tests/examples/awful/popup/defaultconfig.lua @@ -9,6 +9,7 @@ local naughty = require("naughty") local wibox = require("wibox") local beautiful = require("beautiful") --DOC_HIDE local look = require("_default_look") +local color = require("gears.color") screen[1]._resize {width = 640, height = 340} @@ -75,7 +76,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/awful/popup/wiboxtypes.lua b/tests/examples/awful/popup/wiboxtypes.lua index ccbef7ba6..b36e1604e 100644 --- a/tests/examples/awful/popup/wiboxtypes.lua +++ b/tests/examples/awful/popup/wiboxtypes.lua @@ -10,6 +10,7 @@ local wibox = require("wibox") local beautiful = require("beautiful") --DOC_HIDE local assets = require("beautiful.theme_assets") local look = require("_default_look") +local color = require("gears.color") screen[1]._resize {width = 640, height = 480} @@ -233,7 +234,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/awful/titlebar/defaulttitlebar.lua b/tests/examples/awful/titlebar/defaulttitlebar.lua index 3e34f0b94..2db72c9c4 100644 --- a/tests/examples/awful/titlebar/defaulttitlebar.lua +++ b/tests/examples/awful/titlebar/defaulttitlebar.lua @@ -7,6 +7,7 @@ local gears = require("gears") local wibox = require("wibox") local beautiful = require("beautiful") --DOC_HIDE local look = require("_default_look") +local color = require("gears.color") local offset = 0 @@ -108,7 +109,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/awful/wibar/defaultwibar.lua b/tests/examples/awful/wibar/defaultwibar.lua index 309714e74..b4a90af89 100644 --- a/tests/examples/awful/wibar/defaultwibar.lua +++ b/tests/examples/awful/wibar/defaultwibar.lua @@ -7,6 +7,7 @@ local gears = require("gears") local wibox = require("wibox") local beautiful = require("beautiful") --DOC_HIDE local look = require("_default_look") +local color = require("gears.color") local offset = 60 @@ -99,7 +100,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/wibox/nwidget/default.lua b/tests/examples/wibox/nwidget/default.lua index 3f670c2ce..71b807967 100644 --- a/tests/examples/wibox/nwidget/default.lua +++ b/tests/examples/wibox/nwidget/default.lua @@ -7,6 +7,7 @@ local def = require("naughty.widget._default") local acommon = require("awful.widget.common") local aplace = require("awful.placement") local gears = require("gears") +local color = require("gears.color") beautiful.notification_bg = beautiful.bg_normal @@ -76,7 +77,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) From 93f7269081a7cc5cd62762d61872ca231b8bed17 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 10:22:10 -0800 Subject: [PATCH 023/134] doc: Change the default theme to use a "special" fg color. This magic color will be find&replaced by a post-processing script. --- tests/examples/shims/beautiful.lua | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/tests/examples/shims/beautiful.lua b/tests/examples/shims/beautiful.lua index 4798ec55a..396ace662 100644 --- a/tests/examples/shims/beautiful.lua +++ b/tests/examples/shims/beautiful.lua @@ -25,9 +25,18 @@ local function logo() return img end +-- Use a cairo pattern for the foreground to allow improve the +-- reliability of the find&replace documentation script. This +-- will be post-processed to ensure the foreground color is +-- inherited from the browser rather than hardcoded. In turn, +-- this allows the accessibility mode to work and to define the +-- color using our CSS template, which allows for light/dark +-- themes to be implemented with a single image. +local main_fg = cairo.Pattern.create_rgba(0.005, 0, 0.005, 1) + -- Default theme for the documentation examples local module = { - fg_normal = "#000000" , + fg_normal = main_fg, bg_normal = "#6181FF7D", bg_focus = "#AA00FF7D", bg_highlight = "#AA00FF7D", @@ -117,8 +126,9 @@ module.layout_cornersw = themes_path.."default/layouts/cornersww.png" module.layout_cornerse = themes_path.."default/layouts/cornersew.png" -- Taglist -module.taglist_bg_focus = module.bg_highlight -module.taglist_bg_used = module.bg_normal +module.taglist_bg_focus = module.bg_highlight +module.taglist_bg_used = module.bg_normal +module.taglist_bg_normal = module.bg_normal function module.get() From dd7492fa7c0cc3f39ee4e2ea9457f6efb0841d8c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 10:30:24 -0800 Subject: [PATCH 024/134] doc: Fix some broken links in the tasklist doc. --- lib/awful/widget/tasklist.lua | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index a2bdc40ef..c563f830a 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -14,14 +14,14 @@ -- Icon -- Client property -- --- ▪sticky --- ⌃ontop --- ▴above --- ▾below --- ✈floating --- +maximized --- ⬌maximized_horizontal --- ⬍maximized_vertical +-- ▪sticky +-- ⌃ontop +-- ▴above +-- ▾below +-- ✈floating +-- +maximized +-- ⬌maximized_horizontal +-- ⬍maximized_vertical -- -- -- **Customizing the tasklist:** From 2c1c37fb12b7bfbfa37e67f235fe14fd29ed3a55 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 11:04:32 -0800 Subject: [PATCH 025/134] doc: Merge the Inherited/Deprecated/Readonly tag style. They are on the right like Inherited, but use the "chip" style of ReadOnly. --- docs/config.ld | 25 ++++++++++++------------- docs/ldoc.css | 10 +++++++--- docs/ldoc.ltp | 17 ++++++++++------- 3 files changed, 29 insertions(+), 23 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index dffe3ecf2..49619d95e 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -591,12 +591,14 @@ local named_args = { -- Sections which are hidden by default, but visible when clicked. local summarize = { - emits = {index = 1, title = "signal" , count = true }, - propemits = {index = 2, title = "signal" , count = true }, - usebeautiful = {index = 3, title = "theme variable" , count = true }, - propbeautiful = {index = 4, title = "theme variable" , count = true }, - request = {index = 5, title = "permission" , count = true }, - classsignal = {index = 6, title = "Class level only", count = false}, + is_deprecated = {index = 1, title = "deprecated" , count = false}, + emits = {index = 2, title = "signal" , count = true }, + propemits = {index = 3, title = "signal" , count = true }, + usebeautiful = {index = 4, title = "theme variable" , count = true }, + propbeautiful = {index = 5, title = "theme variable" , count = true }, + request = {index = 6, title = "permission" , count = true }, + classsignal = {index = 7, title = "Class level only", count = false}, + readonly = {index = 8, title = "read only" , count = false}, } local delimiter_for_tag = { @@ -645,9 +647,6 @@ local function generate_summary(item) has_show_more = v.showcount or has_show_more end end - if item.tags.readonly then - ret[#ret+1] = {title = "read only"} - end item.extra_summary = #ret > 0 and ret or nil item.has_show_more = has_show_more @@ -939,6 +938,10 @@ local is_deprecated = { } custom_display_name_handler = function(item, default_handler) + if is_deprecated[item.type] then + item.tags.is_deprecated = {true} + end + init_custom_types(item) local ret = default_handler(item) @@ -984,10 +987,6 @@ custom_display_name_handler = function(item, default_handler) ret = render_methods(item) end - if is_deprecated[item.type] then - return ret .. " [deprecated]" - end - -- Get rid of the "module:" in front of method names. It is either wrong or -- just redundant. ret = ret:gsub("([^:]*)(:[^:])","%2") diff --git a/docs/ldoc.css b/docs/ldoc.css index 9857bcfb2..d9ea58596 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -346,14 +346,18 @@ span.inheritance { text-align: right; } -span.chips--readonly { +span.chips { border: 1px solid #9db9f3; border-radius: 25px; - padding: 1px 3px; - font-size: 70%; + padding-left: 5pt; + padding-right: 5pt; + padding-top: 1pt; + padding-bottom: 1pt; + font-size: 85%; color: #9db9f3; background-color: #FFF; margin-left: 10px; + vertical-align: middle; } table.function_list .function_args /*.function_modname*/ { diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 2c518e306..58a2a1e32 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -292,17 +292,20 @@ # end # end - + $(M(item.summary,item)) -# if item.tags.readonly then - read only -# end -# if inherited then - Inherited from $(item.baseclass) - +# if item.tags.is_deprecated then + Deprecated # end +# if item.tags.readonly then + Read only +# end +# if inherited then + Inherited from $(item.baseclass) +# end + # end end -- for items # last_kind = kind From e4b97282607008532663862342cbd2f569b5f4f2 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 11:33:19 -0800 Subject: [PATCH 026/134] doc: Add a mild hover color change to the summary. It is hard know to which row a "chip" like inherited belongs to. This fixes it for mouse users. I also tried using alternate row colors, but our colors are so "light" that there wasn't any good candidate between "white" and the background color. --- docs/ldoc.css | 14 ++++++++------ docs/ldoc.ltp | 2 +- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/ldoc.css b/docs/ldoc.css index d9ea58596..bf0529632 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -301,26 +301,22 @@ table.module_list td, table.function_list td { padding-bottom: 5px; } table.module_list td.name, table.function_list td.name { - background-color: white; min-width: 200px; border-left-width: 0px; border-right-width: 0px; } table.module_list td.summary, table.function_list td.summary { - background-color: white; width: 100%; border-left-width: 0px; border-right: none; } table.function_list td.shortname { - background-color: white; border-left-width: 0px; border-right-width: 0px; } table.function_list td.inheritance { - background-color: white; border-right-width: 0px; border-left-width: 0px; color: #a4c7ff; @@ -338,7 +334,6 @@ span.inheritance { } .summarytype { - background-color: white; color: #a4c7ff; font-size: 85%; border-left: none; @@ -386,7 +381,6 @@ table.function_list .function_named_args { } table.function_list td.baseclass { - background-color: white; color: #a4c7ff; min-width: 200px; border-left: none; @@ -567,3 +561,11 @@ pre .url { color: #272fc2; text-decoration: underline; } .extra-header__section { flex-grow: 1; } + +.summary_row { + background-color: white; +} + +.summary_row:hover { + background-color: #f7fbff; +} diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 58a2a1e32..dc73e1ca3 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -280,7 +280,7 @@ # local dn = display_name(item) # local inherited = (item.baseclass ~= module.name) # if item.sanitize_type then item.sanitize_type(item, ldoc) end - + # if item.display_type and not item.compact_signature then $(dn) $(item.display_type) From 87a69c4d4d458c54be0700bf73d8d2a5b24ea70c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 13:54:08 -0800 Subject: [PATCH 027/134] doc: Fix a problem which causes the SVG to be blurry. --- docs/ldoc.css | 5 +++++ tests/examples/CMakeLists.txt | 2 +- tests/examples/_postprocess.lua | 9 +++++++++ 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/ldoc.css b/docs/ldoc.css index bf0529632..3c4175e50 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -569,3 +569,8 @@ pre .url { color: #272fc2; text-decoration: underline; } .summary_row:hover { background-color: #f7fbff; } + +/* CSS for beautiful.fg_normal */ +.svg_stroke, .svg_fill { + color: black; +} diff --git a/tests/examples/CMakeLists.txt b/tests/examples/CMakeLists.txt index af3f28923..f7a9a68c8 100644 --- a/tests/examples/CMakeLists.txt +++ b/tests/examples/CMakeLists.txt @@ -237,7 +237,7 @@ function(run_test test_path namespace escaped_content) set(OUTPUT_RAW_IMAGE_PATH "${RAW_IMAGE_PATH}.svg") set(OUTPUT_IMAGE_PATH "${IMAGE_PATH}.svg") escape_string( - "![Usage example](../images/AUTOGEN${namespace}_${TEST_FILE_NAME}.svg)\n" + "\n" "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT "" ) else() diff --git a/tests/examples/_postprocess.lua b/tests/examples/_postprocess.lua index 9f30166c2..7ba00829b 100755 --- a/tests/examples/_postprocess.lua +++ b/tests/examples/_postprocess.lua @@ -25,6 +25,8 @@ if (not i) or (not o) then return end local line, count = i:read("*line"), 0 +local add_link = false + while line do -- Deduplicate and concatenate the classes. local classes = {} @@ -60,6 +62,13 @@ while line do end o:write(line .. "\n") + + -- Add the stylesheet. + if line:sub(1, 6) == "\n') + end + + -- Next line. line = i:read("*line") end From 69ab73aa232d258da68182b76673a5a8915a61e8 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 13:54:35 -0800 Subject: [PATCH 028/134] doc: Fix a popup doc issue. The variable name wasn't in the @param string, so it was called "The". --- lib/awful/popup.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index 22d8d76ee..8757634f1 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -367,10 +367,10 @@ end --- Set the placement function. -- --- @tparam[opt=next_to] function|string|boolean The placement function or name -- (or false to disable placement) +-- -- @property placement --- @param function +-- @tparam[opt=next_to] function|string|boolean placement The placement function or name -- @propemits true false -- @see awful.placement From f8f11a23f513313e426aee38de9963a3ecee8a44 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 13:55:17 -0800 Subject: [PATCH 029/134] doc: Add some @see to the shape doc. The `transform` function was unclear. --- lib/gears/shape.lua | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index 1c31e741e..4af3d326f 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -820,6 +820,12 @@ end -- @param shape A shape function -- @return A transformation handle, also act as a shape function -- @staticfct gears.shape.transform +-- @see gears.matrix.translate +-- @see gears.matrix.scale +-- @see gears.matrix.rotate +-- @see gears.matrix.rotate_at +-- @see gears.matrix.multiply +-- @see gears.matrix.invert function module.transform(shape) -- Apply the transformation matrix and apply the shape, then restore From 11a7c8c47baebde9bf96b385789c9ef7cec7ec46 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 13:55:50 -0800 Subject: [PATCH 030/134] doc: Fix the `layoutbox` doc. It didn't have a constructor. --- lib/awful/widget/layoutbox.lua | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/awful/widget/layoutbox.lua b/lib/awful/widget/layoutbox.lua index a12d892cb..b6a68d319 100644 --- a/lib/awful/widget/layoutbox.lua +++ b/lib/awful/widget/layoutbox.lua @@ -47,6 +47,7 @@ end --- Create a layoutbox widget. It draws a picture with the current layout -- symbol of the current tag. +-- @constructorfct awful.widget.layoutbox -- @tparam table args The arguments. -- @tparam screen args.screen The screen number that the layout will be represented for. -- @tparam table args.buttons The `awful.button`s for this layoutbox. From 86b6f1cb34c835f8b651d570c49e658b0545332e Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 14:19:15 -0800 Subject: [PATCH 031/134] doc: Fix another CMake related encoding problem. --- docs/ldoc.ltp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index dc73e1ca3..490f0c19f 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -38,7 +38,7 @@ # local use_li = ldoc.use_li # local display_name = ldoc.display_name # local iter = ldoc.modules.iter -# local function un_cmake(s) return s:gsub(";", ";"):gsub(""", '"') end +# local function un_cmake(s) return s:gsub(";", ";"):gsub(""", '"'):gsub('&#34', '"') end # local function M(txt,item) return ldoc.markup(txt and un_cmake(txt) or nil,item,ldoc.plain) end # local nowrap = ldoc.wrap and '' or 'nowrap' # local html_space = function(s) return s:gsub(" ", "%%20") end @@ -180,7 +180,7 @@
# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries - $(ldoc.body) + $(un_cmake(ldoc.body)) # elseif module then -- module documentation

Module: $(module.name)

$(M(module.summary,module))

From b8cd009b37d65d8f17578b65d1adf16b94b94e3a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 15:04:16 -0800 Subject: [PATCH 032/134] doc: Fix a rendering issue in @tfield and @field. It would render `tag.awful.tag.layouts` instead of `awful.tag.layouts. --- docs/config.ld | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/config.ld b/docs/config.ld index 49619d95e..d939d2f5c 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -867,6 +867,16 @@ local function sanitize_return_type(item, ldoc) item.compact_signature = true end +-- Work around the fact that tag/awful.tag client/awful.client pages +-- are merged. +local function compare_module_name(input, module) + for _, mod in ipairs { module, "awful."..module } do + if input:sub(1, #mod) == mod then return true end + end + + return false +end + local no_prefix = { property = true, signal = true, @@ -976,9 +986,11 @@ custom_display_name_handler = function(item, default_handler) -- 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] then + local is_field = item.type == "field" or item.type == "tfield" + 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 + elseif is_field and not compare_module_name(ret, item.module.name) then ret = item.module.name .. "." .. ret end end From 75ab36676920cf6a7a17af836f6bd9fff52f834d Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 13 Dec 2021 16:21:44 -0800 Subject: [PATCH 033/134] doc: Proof reading fixes. * Rendering problems * Incomplete type information * Obsolete type information * Missing type information * Missing return value * Incomplete return value type --- lib/awful/mouse/init.lua | 39 +++++++++------ lib/awful/mouse/resize.lua | 8 --- lib/awful/mouse/snap.lua | 14 +++--- lib/awful/screen.lua | 57 ++++++++++----------- lib/awful/tag.lua | 96 ++++++++++++++++++------------------ lib/naughty/core.lua | 26 +++++----- lib/naughty/notification.lua | 49 +++++++++--------- luaa.c | 31 ++++++------ mouse.c | 4 +- objects/client.c | 2 +- objects/screen.c | 32 ++++++------ objects/tag.c | 4 +- root.c | 19 +++---- 13 files changed, 193 insertions(+), 188 deletions(-) diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index 0411e3434..5a9890e70 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -35,12 +35,12 @@ mouse.wibox = {} -- -- @DOC_screen_client_snap_EXAMPLE@ -- --- @tfield integer snap.default_distance +-- @tfield integer awful.mouse.snap.default_distance -- @tparam[opt=8] integer default_distance -- @see awful.mouse.snap --- The default distance before activating screen edge snap. --- @tfield integer snap.aerosnap_distance +-- @tfield integer awful.mouse.snap.aerosnap_distance -- @tparam[opt=16] integer aerosnap_distance -- @see awful.mouse.snap @@ -48,15 +48,15 @@ mouse.wibox = {} -- --@DOC_awful_placement_aero_snap_EXAMPLE@ -- --- @tfield[opt=true] boolean snap.edge_enabled +-- @tfield[opt=true] boolean awful.mouse.snap.edge_enabled -- @tparam boolean edge_enabled --- Enable client to client snapping. --- @tfield[opt=true] boolean snap.client_enabled +-- @tfield[opt=true] boolean awful.mouse.snap.client_enabled -- @tparam boolean client_enabled --- Enable changing tag when a client is dragged to the edge of the screen. --- @tfield[opt=false] boolean drag_to_tag.enabled +-- @tfield[opt=false] boolean awful.mouse.drag_to_tag.enabled -- @tparam boolean enabled --- The snap outline background color. @@ -65,7 +65,7 @@ mouse.wibox = {} --- The snap outline width. -- @beautiful beautiful.snap_border_width --- @param integer +-- @tparam integer snap_border_width --- The snap outline shape. -- @beautiful beautiful.snap_shape @@ -75,9 +75,17 @@ mouse.wibox = {} -- @beautiful beautiful.snapper_gap -- @tparam[opt=0] number snapper_gap +--- The resize cursor name. +-- @beautiful beautiful.cursor_mouse_resize +-- @tparam[opt=cross] string cursor + +--- The move cursor name. +-- @beautiful beautiful.cursor_mouse_move +-- @tparam[opt=fleur] string cursor + --- Get the client object under the pointer. -- @deprecated awful.mouse.client_under_pointer --- @return The client object under the pointer, if one can be found. +-- @treturn client|nil The client object under the pointer, if one can be found. -- @see current_client function mouse.client_under_pointer() gdebug.deprecate("Use mouse.current_client instead of awful.mouse.client_under_pointer()", {deprecated_in=4}) @@ -222,15 +230,15 @@ end --- True if the left mouse button is pressed. -- @property is_left_mouse_button_pressed --- @param boolean +-- @tparam boolean is_left_mouse_button_pressed --- True if the right mouse button is pressed. -- @property is_right_mouse_button_pressed --- @param boolean +-- @tparam boolean is_right_mouse_button_pressed --- True if the middle mouse button is pressed. -- @property is_middle_mouse_button_pressed --- @param boolean +-- @tparam boolean is_right_mouse_button_pressed --- Add an `awful.button` based mousebinding to the global set. -- @@ -252,6 +260,7 @@ end -- no focused client. If your intent is too add a mousebinding which acts on -- the focused client do **not** use this -- +-- @staticfct awful.mouse.append_global_mousebindings -- @tparam table buttons A table of `awful.button` objects. Optionally, it can have -- a `group` entry. If set, the `group` property will be set on all `awful.buttons` -- objects. @@ -387,11 +396,13 @@ end) -- @tparam[opt=nil] integer coords_table.y The mouse vertical position -- @tparam[opt=false] boolean silent Disable mouse::enter or mouse::leave events that -- could be triggered by the pointer when moving. --- @treturn integer table.x The horizontal position --- @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. +-- @treturn table The coords. It contains the `x`, `y` and `buttons` keys. +-- `buttons` contains the button number as key and a boolean as value (if it is +-- pressed). -- @staticfct mouse.coords +-- @see is_left_mouse_button_pressed +-- @see is_right_mouse_button_pressed +-- @see is_middle_mouse_button_pressed capi.client.connect_signal("scanning", function() capi.client.emit_signal("request::default_mousebindings", "startup") diff --git a/lib/awful/mouse/resize.lua b/lib/awful/mouse/resize.lua index 7d6b7e349..a685bc599 100644 --- a/lib/awful/mouse/resize.lua +++ b/lib/awful/mouse/resize.lua @@ -33,14 +33,6 @@ local cursors = { ["mouse.resize_bottom_right"] = "bottom_right_corner", } ---- The resize cursor name. --- @beautiful beautiful.cursor_mouse_resize --- @tparam[opt=cross] string cursor - ---- The move cursor name. --- @beautiful beautiful.cursor_mouse_move --- @tparam[opt=fleur] string cursor - --- Set the resize mode. -- The available modes are: -- diff --git a/lib/awful/mouse/snap.lua b/lib/awful/mouse/snap.lua index 592bc3b4a..843425687 100644 --- a/lib/awful/mouse/snap.lua +++ b/lib/awful/mouse/snap.lua @@ -191,13 +191,15 @@ local function snap_inside(g, sg, snap) end --- Snap a client to the closest client or screen edge. +-- -- @function awful.mouse.snap --- @param c The client to snap. --- @param snap The pixel to snap clients. --- @param x The client x coordinate. --- @param y The client y coordinate. --- @param fixed_x True if the client isn't allowed to move in the x direction. --- @param fixed_y True if the client isn't allowed to move in the y direction. +-- @tparam[opt=client.focus] client c The client to snap. +-- @tparam integer snap The pixel to snap clients. +-- @tparam integer x The client x coordinate. +-- @tparam integer y The client y coordinate. +-- @tparam boolean fixed_x True if the client isn't allowed to move in the x direction. +-- @tparam boolean fixed_y True if the client isn't allowed to move in the y direction. +-- @treturn table The new geometry. function module.snap(c, snap, x, y, fixed_x, fixed_y) snap = snap or module.default_distance c = c or capi.client.focus diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index a73675828..346ed6b60 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -49,10 +49,10 @@ end --- Get the square distance between a `screen` and a point. -- @deprecated awful.screen.getdistance_sq --- @param s Screen --- @param x X coordinate of point --- @param y Y coordinate of point --- @return The squared distance of the screen to the provided point. +-- @tparam screen s Screen +-- @tparam integer x X coordinate of point +-- @tparam integer y Y coordinate of point +-- @treturn number The squared distance of the screen to the provided point. -- @see screen.get_square_distance function screen.getdistance_sq(s, x, y) gdebug.deprecate("Use s:get_square_distance(x, y) instead of awful.screen.getdistance_sq", {deprecated_in=4}) @@ -90,7 +90,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. -- @staticfct awful.screen.focus --- @tparam screen _screen Screen number (defaults / falls back to mouse.screen). +-- @tparam screen screen Screen number (defaults / falls back to mouse.screen). -- @request client activate screen.focus granted The most recent focused client -- for this screen should be re-activated. function screen.focus(_screen) @@ -134,8 +134,8 @@ end -- the specified direction. -- -- @method get_next_in_direction --- @param self Screen. --- @param dir The direction, can be either "up", "down", "left" or "right". +-- @tparam string dir The direction, can be either "up", "down", "left" or "right". +-- @treturn screen The next screen. function screen.object.get_next_in_direction(self, dir) local sel = get_screen(self) if not sel then @@ -156,7 +156,8 @@ end -- or keeps its position relative to the current focused screen. -- @staticfct awful.screen.focus_bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". --- @tparam screen s Screen. +-- @tparam[opt=awful.screen.focused()] screen s Screen. +-- @treturn screen The next screen. function screen.focus_bydirection(dir, s) local sel = get_screen(s or screen.focused()) local target = sel:get_next_in_direction(dir) @@ -228,8 +229,8 @@ end --- Get or set the screen padding. -- -- @deprecated awful.screen.padding --- @param s The screen object to change the padding on --- @param[opt=nil] padding The padding, a table with 'top', 'left', 'right' and/or +-- @tparam screen s The screen object to change the padding on. +-- @tparam[opt=nil] table|integer|nil padding The padding, a table with 'top', 'left', 'right' and/or -- 'bottom' or a number value to apply set the same padding on all sides. Can be -- nil if you only want to retrieve padding -- @treturn table A table with left, right, top and bottom number values. @@ -253,7 +254,7 @@ end -- @DOC_screen_padding_EXAMPLE@ -- -- @property padding --- @param table +-- @tparam table padding -- @tfield integer table.left The padding on the left. -- @tfield integer table.right The padding on the right. -- @tfield integer table.top The padding on the top. @@ -304,7 +305,7 @@ end -- * *property::outputs* -- -- @property outputs --- @param table +-- @tparam table outputs -- @tfield table table.name A table with the screen name as key (like `eDP1` on a laptop) -- @tfield integer table.mm_width The screen physical width. -- @tfield integer table.mm_height The screen physical height. @@ -439,7 +440,7 @@ end -- default. -- -- @property clients --- @param table The clients list, ordered from top to bottom. +-- @tparam table clients The clients list, ordered from top to bottom. -- @see all_clients -- @see hidden_clients -- @see client.get @@ -467,7 +468,7 @@ end -- This includes minimized clients and clients on hidden tags. -- -- @property hidden_clients --- @param table The clients list, ordered from top to bottom. +-- @tparam table hidden_clients The clients list, ordered from top to bottom. -- @see clients -- @see all_clients -- @see client.get @@ -486,7 +487,7 @@ end --- All clients assigned to the screen. -- -- @property all_clients --- @param table The clients list, ordered from top to bottom. +-- @tparam table all_clients The clients list, ordered from top to bottom. -- @see clients -- @see hidden_clients -- @see client.get @@ -513,7 +514,7 @@ end -- @DOC_screen_tiled_clients_EXAMPLE@ -- -- @property tiled_clients --- @param table The clients list, ordered from top to bottom. +-- @tparam table tiled_clients The clients list, ordered from top to bottom. --- Get tiled clients for the screen. -- @@ -548,7 +549,7 @@ function screen.connect_for_each_screen(func) capi.screen.connect_signal("added", func) end ---- Undo the effect of connect_for_each_screen. +--- Undo the effect of `awful.screen.connect_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) @@ -561,7 +562,7 @@ end -- `awful.tag.new` or `t:delete()` to alter this list. -- -- @property tags --- @param table +-- @tparam table tags -- @treturn table A table with all available tags. -- @readonly @@ -585,7 +586,7 @@ end --- A list of all selected tags on the screen. -- @property selected_tags --- @param table +-- @tparam table selected_tags -- @treturn table A table with all selected tags. -- @readonly -- @see tag.selected @@ -605,7 +606,7 @@ end --- The first selected tag. -- @property selected_tag --- @param tag +-- @tparam tag selected_tag -- @treturn ?tag The first selected tag or nil. -- @readonly -- @see tag.selected @@ -753,16 +754,16 @@ end -- screen is duplicated on a projector). -- -- @property dpi --- @param number the DPI value. +-- @tparam number dpi The DPI value. --- The lowest density DPI from all of the (physical) outputs. -- @property minimum_dpi --- @param number the DPI value. +-- @tparam number minimum_dpi The DPI value. -- @readonly --- The highest density DPI from all of the (physical) outputs. -- @property maximum_dpi --- @param number the DPI value. +-- @tparam number maximum_dpi The DPI value. -- @readonly --- The preferred DPI from all of the (physical) outputs. @@ -771,28 +772,28 @@ end -- the lowest of the resulting virtual DPIs. -- -- @property preferred_dpi --- @param number the DPI value. +-- @tparam number preferred_dpi the DPI value. -- @readonly --- The maximum diagonal size in millimeters. -- -- @property mm_maximum_size --- @param number +-- @tparam number mm_maximum_size --- The minimum diagonal size in millimeters. -- -- @property mm_minimum_size --- @param number +-- @tparam number mm_minimum_size --- The maximum diagonal size in inches. -- -- @property inch_maximum_size --- @param number +-- @tparam number inch_maximum_size --- The minimum diagonal size in inches. -- -- @property inch_minimum_size --- @param number +-- @tparam number inch_minimum_size --- Emitted when a new screen is added. -- diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 7bd7a008b..39fda931b 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -205,8 +205,8 @@ end --- Move a tag to an absolute position in the screen[]:tags() table. -- @deprecated awful.tag.move --- @param new_index Integer absolute position in the table to insert. --- @param target_tag The tag that should be moved. If null, the currently +-- @tparam integer new_index Integer absolute position in the table to insert. +-- @tparam tag target_tag The tag that should be moved. If null, the currently -- selected tag is used. -- @see index function tag.move(new_index, target_tag) @@ -243,8 +243,8 @@ end --- Swap 2 tags -- @deprecated awful.tag.swap -- @see tag.swap --- @param tag1 The first tag --- @param tag2 The second tag +-- @tparam tag tag1 The first tag +-- @tparam tag tag2 The second tag function tag.swap(tag1, tag2) gdebug.deprecate("Use t:swap(tag2) instead of awful.tag.swap", {deprecated_in=4}) @@ -263,7 +263,7 @@ end -- @constructorfct awful.tag.add -- @tparam string name The tag name, a string -- @tparam[opt=nil] table|nil props The tags initial properties, a table --- @return The created tag +-- @treturn tag The created tag. -- @see tag.delete function tag.add(name, props) local properties = props or {} @@ -397,7 +397,7 @@ end -- stickied tags to. -- @tparam[opt=false] boolean force Move even non-sticky clients to the fallback -- tag. --- @return Returns true if the tag is successfully deleted. +-- @treturn boolean Returns true if the tag is successfully deleted. -- If there are no clients exclusively on this tag then delete it. Any -- stickied clients are assigned to the optional 'fallback_tag'. -- If after deleting the tag there is no selected tag, try and restore from @@ -465,9 +465,9 @@ end --- Delete a tag. -- @deprecated awful.tag.delete -- @see tag.delete --- @param target_tag Optional tag object to delete. [selected()] --- @param fallback_tag Tag to assign stickied tags to. [~selected()] --- @return Returns true if the tag is successfully deleted, nil otherwise. +-- @tparam tag target_tag Optional tag object to delete. [selected()] +-- @tparam tag|nil fallback_tag Tag to assign stickied tags to. [~selected()] +-- @treturn boolean Returns true if the tag is successfully deleted, nil otherwise. -- If there are no clients exclusively on this tag then delete it. Any -- stickied clients are assigned to the optional 'fallback_tag'. -- If after deleting the tag there is no selected tag, try and restore from @@ -558,7 +558,7 @@ end --- Get a list of all tags on a screen -- @deprecated awful.tag.gettags -- @tparam screen s Screen --- @return A table with all available tags +-- @treturn table A table with all available tags -- @see screen.tags function tag.gettags(s) gdebug.deprecate("Use s.tags instead of awful.tag.gettags", {deprecated_in=4}) @@ -571,7 +571,7 @@ end --- Find a tag by name. -- @tparam screen s The screen of the tag -- @tparam string name The name of the tag --- @return The tag found, or `nil` +-- @treturn tag|nil 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") @@ -637,8 +637,8 @@ end --- Set a tag's screen -- @deprecated awful.tag.setscreen -- @see screen --- @param s Screen --- @param t tag object +-- @tparam screen s Screen +-- @tparam tag t tag object function tag.setscreen(s, t) -- For API consistency, the arguments have been swapped for Awesome 3.6 -- this method is already deprecated, so be silent and swap the args @@ -654,8 +654,8 @@ end --- Get a tag's screen -- @deprecated awful.tag.getscreen -- @see screen --- @param[opt] t tag object --- @return Screen number +-- @tparam[opt] tag|nil t tag object +-- @treturn screen The tag screen. function tag.getscreen(t) gdebug.deprecate("Use t.screen instead of awful.tag.getscreen(t)", {deprecated_in=4}) @@ -668,8 +668,8 @@ end --- Return a table with all visible tags -- @deprecated awful.tag.selectedlist --- @param s Screen. --- @return A table with all selected tags. +-- @tparam screen s Screen. +-- @treturn table A table with all selected tags. -- @see screen.selected_tags function tag.selectedlist(s) gdebug.deprecate("Use s.selected_tags instead of awful.tag.selectedlist", {deprecated_in=4}) @@ -681,7 +681,7 @@ end --- Return only the first visible tag. -- @deprecated awful.tag.selected --- @param s Screen. +-- @tparam screen s Screen. -- @see screen.selected_tag function tag.selected(s) gdebug.deprecate("Use s.selected_tag instead of awful.tag.selected", {deprecated_in=4}) @@ -694,7 +694,7 @@ end --- The default master width factor -- -- @beautiful beautiful.master_width_factor --- @param number (default: 0.5) +-- @tparam number master_width_factor (default: 0.5) -- @see master_width_factor -- @see gap @@ -740,8 +740,8 @@ end -- @deprecated awful.tag.setmwfact -- @see master_fill_policy -- @see master_width_factor --- @param mwfact Master width factor. --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam number mwfact Master width factor. +-- @tparam tag t The tag to modify, if null tag.selected() is used. function tag.setmwfact(mwfact, t) gdebug.deprecate("Use t.master_width_factor = mwfact instead of awful.tag.setmwfact", {deprecated_in=4}) @@ -762,7 +762,7 @@ end -- @deprecated awful.tag.getmwfact -- @see master_width_factor -- @see master_fill_policy --- @param[opt] t The tag. +-- @tparam[opt] tag|nil t The tag. function tag.getmwfact(t) gdebug.deprecate("Use t.master_width_factor instead of awful.tag.getmwfact", {deprecated_in=4}) @@ -795,6 +795,8 @@ end -- } -- -- @tfield table awful.tag.layouts +-- @tparam[opt={}] table awful.tag.layouts +-- @see request::layouts --- The tag client layout. -- @@ -1003,7 +1005,7 @@ end -- @deprecated awful.tag.setlayout -- @see layout -- @param layout a layout table or a constructor function --- @param t The tag to modify +-- @tparam tag t The tag to modify -- @return The layout function tag.setlayout(layout, t) gdebug.deprecate("Use t.layout = layout instead of awful.tag.setlayout", {deprecated_in=4}) @@ -1053,7 +1055,7 @@ end -- @deprecated awful.tag.setvolatile -- @see volatile -- @tparam boolean volatile If the tag must be deleted when the last client is untagged --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam tag t The tag to modify, if null tag.selected() is used. function tag.setvolatile(volatile, t) gdebug.deprecate("Use t.volatile = volatile instead of awful.tag.setvolatile", {deprecated_in=4}) @@ -1063,7 +1065,7 @@ end --- Get if the tag must be deleted when the last client closes -- @deprecated awful.tag.getvolatile -- @see volatile --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam tag t The tag to modify, if null tag.selected() is used. -- @treturn boolean If the tag will be deleted when the last client is untagged function tag.getvolatile(t) gdebug.deprecate("Use t.volatile instead of awful.tag.getvolatile", {deprecated_in=4}) @@ -1074,7 +1076,7 @@ end --- The default gap. -- -- @beautiful beautiful.useless_gap --- @param number (default: 0) +-- @tparam tag number (default: 0) -- @see gap -- @see gap_single_client @@ -1112,8 +1114,8 @@ end --- Set the spacing between clients -- @deprecated awful.tag.setgap -- @see gap --- @param useless_gap The spacing between clients --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam number|nil useless_gap The spacing between clients +-- @tparam tag t The tag to modify, if null tag.selected() is used. function tag.setgap(useless_gap, t) gdebug.deprecate("Use t.gap = useless_gap instead of awful.tag.setgap", {deprecated_in=4}) @@ -1133,7 +1135,7 @@ end --- Enable gaps for a single client. -- -- @beautiful beautiful.gap_single_client --- @param boolean (default: true) +-- @tparam boolean gap_single_client (default: true) -- @see gap -- @see gap_single_client @@ -1199,7 +1201,7 @@ end -- `master_width_factor` -- -- @beautiful beautiful.master_fill_policy --- @param string (default: "expand") +-- @tparam string master_fill_policy (default: "expand") -- @see master_fill_policy --- Set size fill policy for the master client(s). @@ -1283,7 +1285,7 @@ end --- The default number of master windows. -- -- @beautiful beautiful.master_count --- @param integer (default: 1) +-- @tparam integer master_count (default: 1) -- @see master_count --- Set the number of master windows. @@ -1312,8 +1314,8 @@ end --- The number of master clients. -- @deprecated awful.tag.setnmaster -- @see master_count --- @param nmaster The number of master windows. --- @param[opt] t The tag. +-- @tparam nmaster The number of master windows. +-- @tparam[opt] tag t The tag. function tag.setnmaster(nmaster, t) gdebug.deprecate("Use t.master_count = nmaster instead of awful.tag.setnmaster", {deprecated_in=4}) @@ -1323,7 +1325,7 @@ end --- Get the number of master windows. -- @deprecated awful.tag.getnmaster -- @see master_count --- @param[opt] t The tag. +-- @tparam[opt] tag t The tag. function tag.getnmaster(t) gdebug.deprecate("Use t.master_count instead of awful.tag.setnmaster", {deprecated_in=4}) @@ -1375,7 +1377,7 @@ end --- Set the tag icon -- @deprecated awful.tag.seticon -- @see icon --- @param icon the icon to set, either path or image object +-- @tparam gears.surface|string icon the icon to set, either path or image object -- @tparam tag tag the tag function tag.seticon(icon, _tag) gdebug.deprecate("Use t.icon = icon instead of awful.tag.seticon", {deprecated_in=4}) @@ -1398,7 +1400,7 @@ end --- The default number of columns. -- -- @beautiful beautiful.column_count --- @param integer (default: 1) +-- @tparam integer column_count (default: 1) -- @see column_count --- Set the number of columns. @@ -1427,8 +1429,8 @@ end --- Set number of column windows. -- @deprecated awful.tag.setncol -- @see column_count --- @param ncol The number of column. --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam integer ncol The number of column. +-- @tparam tag t The tag to modify, if null tag.selected() is used. function tag.setncol(ncol, t) gdebug.deprecate("Use t.column_count = new_index instead of awful.tag.setncol", {deprecated_in=4}) @@ -1442,7 +1444,7 @@ end --- Get number of column windows. -- @deprecated awful.tag.getncol -- @see column_count --- @param[opt] t The tag. +-- @tparam[opt] tag t The tag. function tag.getncol(t) gdebug.deprecate("Use t.column_count instead of awful.tag.getncol", {deprecated_in=4}) @@ -1530,8 +1532,8 @@ end --- Get a tag's index in the gettags() table. -- @deprecated awful.tag.getidx -- @see index --- @param query_tag The tag object to find. [selected()] --- @return The index of the tag, nil if the tag is not found. +-- @tparam tag query_tag The tag object to find. [selected()] +-- @treturn integer|nil The index of the tag, nil if the tag is not found. function tag.getidx(query_tag) gdebug.deprecate("Use t.index instead of awful.tag.getidx", {deprecated_in=4}) @@ -1651,7 +1653,7 @@ end -- -- @deprecated awful.tag.getdata -- @tparam tag t The tag. --- @return The data table. +-- @treturn table The data table. function tag.getdata(t) return t._private.awful_tag_properties end @@ -1679,8 +1681,8 @@ end -- Use `t.prop = value` -- -- @deprecated awful.tag.setproperty --- @param t The tag. --- @param prop The property name. +-- @tparam tag t The tag. +-- @tparam string prop The property name. -- @param value The value. function tag.setproperty(t, prop, value) if not t._private.awful_tag_properties then @@ -1695,7 +1697,7 @@ end --- Tag a client with the set of current tags. -- @deprecated awful.tag.withcurrent --- @param c The client to tag. +-- @tparam client c The client to tag. function tag.withcurrent(c) gdebug.deprecate("Use c:to_selected_tags() instead of awful.tag.selectedlist", {deprecated_in=4}) @@ -1809,12 +1811,12 @@ capi.tag.connect_signal("request::select", tag.object.view_only) --- Emitted when the number of urgent clients on this tag changes. -- @signal property::urgent --- @param boolean `true` if there is at least one urgent client on the tag. +-- @tparam boolean urgent `true` if there is at least one urgent client on the tag. -- @see client.urgent --- Emitted when the number of urgent clients on this tag changes. -- @signal property::urgent_count --- @param integer The number of urgent clients on the tag. +-- @tparam integer count The number of urgent clients on the tag. -- @see client.urgent --- Emitted when a screen is removed. diff --git a/lib/naughty/core.lua b/lib/naughty/core.lua index 046ff0586..bedb3ede3 100644 --- a/lib/naughty/core.lua +++ b/lib/naughty/core.lua @@ -102,7 +102,7 @@ gtable.crush(naughty, require("naughty.constants")) -- useful when watching movies or doing presentations. -- -- @property suspended --- @param boolean +-- @tparam boolean suspended -- @emits added -- @propemits true false @@ -113,7 +113,7 @@ gtable.crush(naughty, require("naughty.constants")) -- just vanish. -- -- @property expiration_paused --- @param[opt=false] boolean +-- @tparam[opt=false] boolean expiration_paused -- @propemits true false --- A table with all active notifications. @@ -125,12 +125,12 @@ gtable.crush(naughty, require("naughty.constants")) -- * property::active -- -- @property active --- @param table +-- @tparam table active -- @propemits false false --- True when there is a handler connected to `request::display`. -- @property has_display_handler --- @param boolean +-- @tparam boolean has_display_handler --- If the timeout needs to be reset when a property changes. -- @@ -148,7 +148,7 @@ gtable.crush(naughty, require("naughty.constants")) -- support for this and enabling it will cause bugs. -- -- @property image_animations_enabled --- @param[opt=false] boolean +-- @tparam[opt=false] boolean image_animations_enabled -- @propemits true false --- Enable or disable the persistent notifications. @@ -164,7 +164,7 @@ gtable.crush(naughty, require("naughty.constants")) -- that. -- -- @property persistence_enabled --- @param[opt=false] boolean +-- @tparam[opt=false] boolean persistence_enabled -- @propemits true false local properties = { @@ -339,9 +339,9 @@ end -- This function is deprecated in favor of -- `notification:destroy(reason, keep_visible)`. -- --- @param notification Notification object to be destroyed --- @param reason One of the reasons from `notification_closed_reason` --- @param[opt=false] keep_visible If true, keep the notification visible +-- @tparam naughty.notification notification Notification object to be destroyed +-- @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, nil otherwise -- @deprecated naughty.destroy function naughty.destroy(notification, reason, keep_visible) @@ -385,8 +385,8 @@ end --- Get notification by ID -- --- @param id ID of the notification --- @return notification object if it was found, nil otherwise +-- @tparam integer id ID of the notification +-- @treturn naughty.notification|nil notification object if it was found, nil otherwise -- @deprecated naughty.getById function naughty.getById(id) gdebug.deprecate("Use naughty.get_by_id", {deprecated_in=5}) @@ -395,8 +395,8 @@ end --- Get notification by ID -- --- @param id ID of the notification --- @return notification object if it was found, nil otherwise +-- @tparam integer id ID of the notification +-- @treturn naughty.notification|nil 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 diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 446521191..40ff87aae 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -901,49 +901,50 @@ end --- Create a notification. -- --- @tparam table args The argument table containing any of the arguments below. --- @string[opt=""] args.text Text of the notification. --- @string[opt] args.title Title of the notification. --- @int[opt=5] args.timeout Time in seconds after which popup expires. +-- @tparam[opt={}] table args The argument table containing any of the arguments below. +-- @tparam[opt=""] string args.text Text of the notification. +-- @tparam[opt] string args.title Title of the notification. +-- @tparam[opt=5] integer args.timeout Time in seconds after which popup expires. -- Set 0 for no timeout. --- @int[opt] args.hover_timeout Delay in seconds after which hovered popup disappears. +-- @tparam[opt] number args.hover_timeout Delay in seconds after which hovered popup disappears. -- @tparam[opt=focused] integer|screen args.screen Target screen for the notification. --- @string[opt="top_right"] args.position Corner of the workarea displaying the popups. +-- @tparam[opt="top_right"] string args.position Corner of the workarea displaying the popups. -- Values: `"top_right"`, `"top_left"`, `"bottom_left"`, -- `"bottom_right"`, `"top_middle"`, `"bottom_middle"`, `"middle"`. --- @bool[opt=true] args.ontop Boolean forcing popups to display on top. --- @int[opt=`beautiful.notification_height` or auto] args.height Popup height. --- @int[opt=`beautiful.notification_width` or auto] args.width Popup width. --- @string[opt=`beautiful.notification_font` or `beautiful.font` or `awesome.font`] args.font Notification font. --- @string[opt] args.icon Path to icon. --- @int[opt] args.icon_size Desired icon size in px. --- @string[opt=`beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`] args.fg Foreground color. --- @string[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] args.bg Background color. --- @int[opt=`beautiful.notification_border_width` or 1] args.border_width Border width. --- @string[opt=`beautiful.notification_border_color` or --- `beautiful.border_color_active` or `'#535d6c'`] args.border_color Border color. +-- @tparam[opt=true] boolean args.ontop Boolean forcing popups to display on top. +-- @tparam[opt=`beautiful.notification_height` or auto] integer args.height Popup height. +-- @tparam[opt=`beautiful.notification_width` or auto] integer args.width Popup width. +-- @tparam[opt=`beautiful.notification_font` or `beautiful.font` or `awesome.font`] string|lgi.Pango.FontDescription args.font Notification font. +-- @tparam[opt] gears.surface args.icon Path to icon. +-- @tparam[opt] integer args.icon_size Desired icon size in px. +-- @tparam[opt=`beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`] string args.fg Foreground color. +-- @tparam[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] string args.bg Background color. +-- @tparam[opt=`beautiful.notification_border_width` or 1] integer args.border_width Border width. +-- @tparam[opt=`beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'`] gears.color args.border_color Border color. -- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape. -- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity. -- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin. --- @tparam[opt] func args.run Function to run on left click. The notification +-- @tparam[opt] function args.run Function to run on left click. The notification -- object will be passed to it as an argument. -- You need to call e.g. -- `notification.die(naughty.notification_closed_reason.dismissedByUser)` from -- there to dismiss the notification yourself. --- @tparam[opt] func args.destroy Function to run when notification is destroyed. +-- @tparam[opt] function args.destroy Function to run when notification is destroyed. -- @tparam[opt] table args.preset Table with any of the above parameters. -- Note: Any parameters specified directly in args will override ones defined -- in the preset. --- @tparam[opt] func args.callback Function that will be called with all arguments. +-- @tparam[opt] function args.callback Function that will be called with all arguments. -- The notification will only be displayed if the function returns true. -- Note: this function is only relevant to notifications sent via dbus. -- @tparam[opt] table args.actions A list of `naughty.action`s. --- @bool[opt=false] args.ignore_suspend If set to true this notification +-- @tparam[opt=false] boolean args.ignore_suspend If set to true this notification -- will be shown even if notifications are suspended via `naughty.suspend`. --- @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. +-- @treturn naughty.notification A new notification object. -- @constructorfct naughty.notification +-- @usage naughty.notification { +-- title = "Achtung!", +-- message = "You're idling", timeout = 0 +-- } local function create(args) if cst.config.notify_callback then args = cst.config.notify_callback(args) diff --git a/luaa.c b/luaa.c index 233174ef0..4ebf17d5f 100644 --- a/luaa.c +++ b/luaa.c @@ -97,7 +97,7 @@ signal_array_t global_signals; * * This signal is used in the example configuration, @{05-awesomerc.md}, * to let a notification box pop up. - * @param err Table with the error object, can be converted to a string with + * @tparam table err Table with the error object, can be converted to a string with * `tostring(err)`. * @signal debug::error */ @@ -151,7 +151,7 @@ signal_array_t global_signals; /** Keyboard group has changed. * * It's used in `awful.widget.keyboardlayout` to redraw the layout. - * @param group Integer containing the changed group + * @tparam number group Integer containing the changed group * @signal xkb::group_changed. */ @@ -172,8 +172,8 @@ signal_array_t global_signals; * * This signal is emitted in the `atexit` handler as well when awesome * restarts. - * @param reason_restart Boolean value is true if the signal was sent - * because of a restart. + * @tparam boolean reason_restart Boolean value is true if the signal was sent + * because of a restart. * @signal exit */ @@ -244,7 +244,7 @@ luaA_quit(lua_State *L) /** Execute another application, probably a window manager, to replace * awesome. * - * @param cmd The command line to execute. + * @tparam string cmd The command line to execute. * @staticfct exec */ static int @@ -302,7 +302,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. + * @treturn gears.surface A cairo surface as light user datum. * @staticfct pixbuf_to_surface */ static int @@ -318,10 +318,9 @@ luaA_pixbuf_to_surface(lua_State *L) /** Load an image from a given path. * - * @param name The file name. - * @return[1] A cairo surface as light user datum. - * @return[2] nil - * @treturn[2] string Error message + * @tparam string name The file name. + * @treturn gears.surface A cairo surface as light user datum. + * @treturn nil|string The error message, if any. * @staticfct load_image */ static int @@ -351,7 +350,7 @@ luaA_load_image(lua_State *L) * The closest equal or bigger size is picked if present, otherwise the closest * smaller size is picked. The default is 0 pixels, ie. the smallest icon. * - * @param size The size of the icons in pixels. + * @tparam integer size The size of the icons in pixels. * @staticfct set_preferred_icon_size */ static int @@ -806,8 +805,8 @@ luaA_awesome_index(lua_State *L) /** Add a global signal. * - * @param name A string with the event name. - * @param func The function to call. + * @tparam string name A string with the event name. + * @tparam function func The function to call. * @staticfct connect_signal */ static int @@ -821,8 +820,8 @@ luaA_awesome_connect_signal(lua_State *L) /** Remove a global signal. * - * @param name A string with the event name. - * @param func The function to call. + * @tparam string name A string with the event name. + * @tparam function func The function to call. * @staticfct disconnect_signal */ static int @@ -838,7 +837,7 @@ luaA_awesome_disconnect_signal(lua_State *L) /** Emit a global signal. * - * @param name A string with the event name. + * @tparam function name A string with the event name. * @param ... The signal arguments. * @staticfct emit_signal */ diff --git a/mouse.c b/mouse.c index 42d0b382d..c7214a595 100644 --- a/mouse.c +++ b/mouse.c @@ -76,7 +76,7 @@ static int miss_newindex_handler = LUA_REFNIL; /** * The `screen` under the cursor * @property screen - * @param screen + * @tparam screen screen */ /** Get the pointer position. @@ -273,7 +273,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. + * @treturn client|wibox|nil A client, wibox or nil. * @staticfct object_under_pointer */ static int diff --git a/objects/client.c b/objects/client.c index bc3a76c9a..fbabe7897 100644 --- a/objects/client.c +++ b/objects/client.c @@ -4351,7 +4351,7 @@ luaA_client_get_icon_sizes(lua_State *L, client_t *c) * (by raising an error, the function will be stopped and nothing will be * returned to the caller). * - * @tparam interger index The index in the list of icons to get. + * @tparam integer index The index in the list of icons to get. * @treturn surface A lightuserdata for a cairo surface. This reference must be * destroyed! * @method get_icon diff --git a/objects/screen.c b/objects/screen.c index c2e00f1b8..9eccdc206 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -167,18 +167,17 @@ /** * The screen coordinates. * - * **Signal:** - * - * * *property::geometry* + * The returned table contains the `x`, `y`, `width` and `height` keys. * * @DOC_screen_geometry_EXAMPLE@ * * @property geometry - * @param table - * @tfield integer table.x The horizontal position - * @tfield integer table.y The vertical position - * @tfield integer table.width The width - * @tfield integer table.height The height + * @tparam table geometry + * @tfield integer table.x The horizontal position. + * @tfield integer table.y The vertical position. + * @tfield integer table.width The width. + * @tfield integer table.height The height. + * @propemits false false * @readonly */ @@ -208,7 +207,7 @@ * screen[1].answer = 42 * * @property index - * @param integer + * @tparam integer index * @see screen * @readonly */ @@ -222,26 +221,23 @@ * * It can be modified be altering the `wibox` or `client` struts. * - * **Signal:** - * - * * *property::workarea* - * * @DOC_screen_workarea_EXAMPLE@ * * @property workarea - * @see client.struts - * @param table + * @tparam table workarea * @tfield integer table.x The horizontal position * @tfield integer table.y The vertical position * @tfield integer table.width The width * @tfield integer table.height The height + * @propemits false false + * @see client.struts * @readonly */ /** Get the number of instances. * - * @return The number of screen objects alive. + * @treturn table The number of screen objects alive. * @staticfct instances */ @@ -1657,7 +1653,7 @@ luaA_screen_get_name(lua_State *L, screen_t *s) /** Get the number of screens. * - * @return The screen count, at least 1. + * @treturn number The screen count. * @staticfct count */ static int @@ -1683,7 +1679,7 @@ luaA_screen_count(lua_State *L) * @tparam integer y Y-coordinate for screen. * @tparam integer width width for screen. * @tparam integer height height for screen. - * @return The new screen. + * @treturn screen The new screen. * @constructorfct fake_add */ static int diff --git a/objects/tag.c b/objects/tag.c index 80d74b6ea..b76e9ea89 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -286,7 +286,7 @@ lua_class_t tag_class; /** Get the number of instances. * - * @return The number of tag objects alive. + * @treturn table The number of tag objects alive. * @staticfct instances */ @@ -457,7 +457,7 @@ luaA_tag_new(lua_State *L) * * @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. + * @treturn table A table with the clients attached to this tags. * @method clients */ static int diff --git a/root.c b/root.c index 2b8030893..4dcca6ad1 100644 --- a/root.c +++ b/root.c @@ -427,7 +427,7 @@ luaA_root_buttons(lua_State *L) * *@DOC_cursor_c_COMMON@ * - * @param cursor_name A X cursor name. + * @tparam string cursor_name A X cursor name. * @staticfct cursor */ static int @@ -453,7 +453,7 @@ luaA_root_cursor(lua_State *L) /** Get the drawins attached to a screen. * - * @return A table with all drawins. + * @treturn table A table with all drawins. * @staticfct drawins */ static int @@ -474,7 +474,8 @@ luaA_root_drawins(lua_State *L) * * @param pattern A cairo pattern as light userdata * @return A cairo surface or nothing. - * @staticfct wallpaper + * @deprecated wallpaper + * @see awful.wallpaper */ static int luaA_root_wallpaper(lua_State *L) @@ -515,7 +516,7 @@ luaA_root_get_content(lua_State *L) surface = cairo_xcb_surface_create(globalconf.connection, globalconf.screen->root, globalconf.default_visual, - globalconf.screen->width_in_pixels, + globalconf.screen->width_in_pixels, globalconf.screen->height_in_pixels); lua_pushlightuserdata(L, surface); @@ -525,8 +526,8 @@ luaA_root_get_content(lua_State *L) /** Get the size of the root window. * - * @return Width of the root window. - * @return height of the root window. + * @treturn integer Width of the root window. + * @treturn integer height of the root window. * @staticfct size */ static int @@ -539,8 +540,8 @@ luaA_root_size(lua_State *L) /** Get the physical size of the root window, in millimeter. * - * @return Width of the root window, in millimeters. - * @return height of the root window, in millimeters. + * @treturn integer Width of the root window, in millimeters. + * @treturn integer height of the root window, in millimeters. * @staticfct size_mm */ static int @@ -552,7 +553,7 @@ luaA_root_size_mm(lua_State *L) } /** Get the attached tags. - * @return A table with all tags. + * @treturn table A table with all tags. * @staticfct tags */ static int From 345de1e9d9f340999db1ce1b2afc76a42553f873 Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski Date: Tue, 14 Dec 2021 11:30:04 +0100 Subject: [PATCH 034/134] bug: Add workaround for new image paths --- docs/ldoc.css | 54 +++++++++++- .../examples/uml/nav_tables/client.output.txt | 87 ++++--------------- .../examples/uml/nav_tables/screen.output.txt | 87 ++++--------------- tests/examples/uml/nav_tables/tag.output.txt | 69 +++------------ tests/examples/uml/template.lua | 36 +++----- 5 files changed, 104 insertions(+), 229 deletions(-) diff --git a/docs/ldoc.css b/docs/ldoc.css index 3c4175e50..15682208f 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -64,6 +64,10 @@ dd > code { margin-right: 5px; } +#main { + display: flex; +} + #navigation { float: left; background-color: white; @@ -185,10 +189,6 @@ table.index td { margin: 0px 3px 0px -1em; } -#content { - margin-left: 14em; -} - #content p { padding-left: 15px; padding-right: 15px; @@ -574,3 +574,49 @@ pre .url { color: #272fc2; text-decoration: underline; } .svg_stroke, .svg_fill { color: black; } + +#content > .components-relationship { + margin-left: 15px; + margin-right: 15px; +} + +.components-relationship--diagrams { + display: flex; + flex-direction: column; +} + +.components-relationship--diagram { + flex-grow: 1; + flex-basis: 100%; +} + +.components-relationship--diagram > table { + margin: 0; + width: 100%; +} + +.components-relationship--diagram + .components-relationship--diagram { + margin-top: 15px; +} + +/* on wide displays, put both diagrams next to each other */ +@media all and (min-width: 1100px) { + .components-relationship--diagrams { + flex-direction: row; + } + + .components-relationship--diagram { + flex-grow: 1; + flex-basis: 50%; + } + + .components-relationship--diagram + .components-relationship--diagram { + margin-top: 0; + margin-left: 15px; + } +} + +.components-relationship--legend { + color: #00000044; + margin-top: 15px; +} diff --git a/tests/examples/uml/nav_tables/client.output.txt b/tests/examples/uml/nav_tables/client.output.txt index 65bc1681b..b4802f4b8 100644 --- a/tests/examples/uml/nav_tables/client.output.txt +++ b/tests/examples/uml/nav_tables/client.output.txt @@ -3,75 +3,18 @@ Core components relationship === - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Acquire other objects from a client
ClassProperty
tagc.tags
screenc.screen
awful.keyc:keys()
awful.buttonc:buttons()
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Acquire a client from other objects
ClassProperty
tagt:clients()
screens.clients
screens.hidden_clients
screens.tiled_clients
mousemouse.current_client
- Legend: c: a client object, t: a tag object, - s: a screen object, k: an awful.key object, - b: a awful.button object, n: a naughty.notification object -
+
+
+ + + + +
Acquire other objects from a client
ClassProperty
tagc.tags
screenc.screen
awful.keyc:keys()
awful.buttonc:buttons()
+
+ + + + + +
Acquire a client from other objects
ClassProperty
tagt:clients()
screens.clients
screens.hidden_clients
screens.tiled_clients
mousemouse.current_client
+
Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object, n: a naughty.notification object
diff --git a/tests/examples/uml/nav_tables/screen.output.txt b/tests/examples/uml/nav_tables/screen.output.txt index d7b307854..a60e8acdb 100644 --- a/tests/examples/uml/nav_tables/screen.output.txt +++ b/tests/examples/uml/nav_tables/screen.output.txt @@ -3,75 +3,18 @@ Core components relationship === - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Acquire other objects from a screen
ClassProperty
tags.tags
tags.selected_tag
tags.selected_tags
clients.clients
clients.hidden_clients
clients.tiled_clients
 - - - - - - - - - - - - - - - - - - - - - - -
Acquire a screen from other objects
ClassProperty
tagt.screen
clientc.screen
naughty.notificationn.screen
- Legend: c: a client object, t: a tag object, - s: a screen object, k: an awful.key object, - b: a awful.button object, n: a naughty.notification object -
+
+
+ + + + + + +
Acquire other objects from a screen
ClassProperty
tags.tags
tags.selected_tag
tags.selected_tags
clients.clients
clients.hidden_clients
clients.tiled_clients
+
+ + + +
Acquire a screen from other objects
ClassProperty
tagt.screen
clientc.screen
naughty.notificationn.screen
+
Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object, n: a naughty.notification object
diff --git a/tests/examples/uml/nav_tables/tag.output.txt b/tests/examples/uml/nav_tables/tag.output.txt index 55b9ac223..2f25497dd 100644 --- a/tests/examples/uml/nav_tables/tag.output.txt +++ b/tests/examples/uml/nav_tables/tag.output.txt @@ -3,60 +3,15 @@ Core components relationship === - - - - - - -
- - - - - - - - - - - - - - - - - -
Acquire other objects from a tag
ClassProperty
clientt:clients()
screent.screen
 - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Acquire a tag from other objects
ClassProperty
clientc.tags
screens.tags
screens.selected_tag
screens.selected_tags
- Legend: c: a client object, t: a tag object, - s: a screen object, k: an awful.key object, - b: a awful.button object, n: a naughty.notification object -
+
+
+ + +
Acquire other objects from a tag
ClassProperty
clientt:clients()
screent.screen
+
+ + + + +
Acquire a tag from other objects
ClassProperty
clientc.tags
screens.tags
screens.selected_tag
screens.selected_tags
+
Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object, n: a naughty.notification object
diff --git a/tests/examples/uml/template.lua b/tests/examples/uml/template.lua index 399c50b4c..da46a298f 100644 --- a/tests/examples/uml/template.lua +++ b/tests/examples/uml/template.lua @@ -6,7 +6,11 @@ local wibox = require("wibox") local beautiful = require("beautiful") -- Make the path relative. -local relative_image_path = "../" .. image_path:match("/(images/[^/]+)$") +local path = image_path:match("/(images/[^/]+)$") +if not path then + path = image_path:match("/(raw_images/[^/]+)$"):gsub("raw_", "") +end +local relative_image_path = "../" .. path -- This template generates an HTML table with how other classes are associated -- with a given class. @@ -162,27 +166,16 @@ local map = { } local function gen_table_header(title, o) - print([[ - - - - - - - ]]) + print([[
]]..map[title](o)..[[
ClassProperty
]]) end local function get_table_row(path, class, prop) - print([[ - - - - ]]) + print([[]]) end local function get_table_footer() - print '
]]..map[title](o)..[[
ClassProperty
]].. class ..[[]].. prop ..[[
]].. class ..[[]].. prop ..[[
' + print '
' end local module = {} @@ -193,7 +186,7 @@ function module.generate_nav_table(t) assert(t.content and t.class) print("\n\nCore components relationship\n===\n") - print '' + print('
') -- Validate early to avoid debugging cryptic backtraces. for _, tab in ipairs {"to", "from"} do @@ -214,14 +207,9 @@ function module.generate_nav_table(t) end get_table_footer() end - print([[
- - -
- Legend: c: a client object, t: a tag object, - s: a screen object, k: an awful.key object, - b: a awful.button object, n: a naughty.notification object -
]]) + + -- End the last section and add a footer + print([[
Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object, n: a naughty.notification object
]]) end loadfile(file_path)(module) From 37114f61819fd57471fb11dfe26794bbf1c47580 Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski Date: Tue, 14 Dec 2021 13:31:37 +0100 Subject: [PATCH 035/134] doc: Remove empty containers --- docs/ldoc.ltp | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 490f0c19f..29e8ac1d0 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -24,14 +24,6 @@
- -
- -
-
-
- -
# local no_spaces = ldoc.no_spaces From 20ab3a5fb636eb403357523fdd823aaedd757cc8 Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski Date: Tue, 14 Dec 2021 13:39:34 +0100 Subject: [PATCH 036/134] doc: Fix example code header showing in page --- .../wibox/awidget/defaults/button.lua | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/tests/examples/wibox/awidget/defaults/button.lua b/tests/examples/wibox/awidget/defaults/button.lua index a08be8e9c..9894743db 100644 --- a/tests/examples/wibox/awidget/defaults/button.lua +++ b/tests/examples/wibox/awidget/defaults/button.lua @@ -1,12 +1,13 @@ ---DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE -local parent = ... --DOC_NO_USAGE --DOC_HIDE -local awful = {--DOC_HIDE - button = require("awful.button"), --DOC_HIDE - widget = {button = require("awful.widget.button")} --DOC_HIDE -}--DOC_HIDE -local beautiful = require("beautiful") --DOC_HIDE +--DOC_HIDE_START --DOC_GEN_IMAGE --DOC_NO_USAGE +local parent = ... +local awful = { + button = require("awful.button"), + widget = {button = require("awful.widget.button")} +} +local beautiful = require("beautiful") - local button = --DOC_HIDE + local button = + --DOC_HIDE_END awful.widget.button { image = beautiful.awesome_icon, buttons = { @@ -16,7 +17,8 @@ local beautiful = require("beautiful") --DOC_HIDE } } -button.forced_height = 24 --DOC_HIDE -button.forced_width = 24 --DOC_HIDE +--DOC_HIDE_START +button.forced_height = 24 +button.forced_width = 24 -parent:add(button) --DOC_HIDE +parent:add(button) From df45322eac9d8ddc41e5230e1ca1cd7a9f43cf93 Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski Date: Tue, 14 Dec 2021 16:32:47 +0100 Subject: [PATCH 037/134] doc: Implement responsive, toggleable sidebar Below a screen width of 768px (Bootstrap's "medium" breakpoint) the sidebar will collapse to a small strip. Hovering the sidebar will fully reveal it until the mouse leaves it. Clicking the sidebar will reveal it until another part of the page is clicked. --- docs/ldoc.css | 37 +++++++++++++++++++++++++++++++++---- docs/ldoc.ltp | 31 ++++++++++++++++++++++++++++++- 2 files changed, 63 insertions(+), 5 deletions(-) diff --git a/docs/ldoc.css b/docs/ldoc.css index 15682208f..3381d9cc4 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -69,14 +69,34 @@ dd > code { } #navigation { - float: left; + --sidebar-width: 14em; + --sidebar-toggle-width: 24px; + background-color: white; border-right: 1px solid #d3dbec; border-bottom: 1px solid #d3dbec; - width: 14em; - vertical-align: top; + width: var(--sidebar-width); overflow: visible; + + margin-left: calc(-1 * var(--sidebar-width) + var(--sidebar-toggle-width)); + transition: margin-left 0.2s ease-out; +} + +#navigation.open { + margin-left: 0; +} + +@media (hover: hover) { + #navigation:hover { + margin-left: 0; + } +} + +@media all and (min-width: 768px) { + #navigation { + margin-left: 0; + } } #navigation br { @@ -103,6 +123,10 @@ dd > code { margin-bottom: 0px; } +#content { + overflow: hidden; +} + #content h1 { background-color: #2c3e67; color: white; @@ -280,12 +304,17 @@ table th, table td { #about { padding: 15px; - padding-left: 16em; background-color: white; border-top: 1px solid #d3dbec; border-bottom: 1px solid #d3dbec; } +@media all and (min-width: 768px) { + #about { + padding-left: calc(14em + 15px); + } +} + table.module_list, table.function_list { border-width: 1px; border-style: solid; diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 29e8ac1d0..c306780f7 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -113,7 +113,6 @@
+ + + From fb8f7cfaddd530203fd7de62a0e4028f51d7bcaf Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 14 Dec 2021 10:31:00 -0800 Subject: [PATCH 038/134] hotkey/calendar: Fix rendering when the theme color is a pattern. It blew up. --- lib/awful/hotkeys_popup/widget.lua | 5 +++-- lib/awful/widget/calendar_popup.lua | 8 +++++--- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index 8d1254130..144f2b0ed 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -74,6 +74,7 @@ local gtable = require("gears.table") local gstring = require("gears.string") local wibox = require("wibox") local beautiful = require("beautiful") +local rgba = require("gears.color").to_rgba_string local dpi = beautiful.xresources.apply_dpi local matcher = require("gears.matcher")() @@ -86,11 +87,11 @@ function markup.font(font, text) end -- Set the foreground. function markup.fg(color, text) - return '' .. tostring(text) .. '' + return '' .. tostring(text) .. '' end -- Set the background. function markup.bg(color, text) - return '' .. tostring(text) .. '' + return '' .. tostring(text) .. '' end local function join_plus_sort(modifiers) diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 6da667ae0..50f76ecb2 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -141,8 +141,10 @@ local function parse_cell_options(cell, args) props[prop] = args[prop] or beautiful["calendar_" .. cell .. "_" .. prop] or bl_style[prop] or default end if cell == "focus" and props.markup == nil then - local fg = props.fg_color and string.format('foreground="%s"', props.fg_color) or "" - local bg = props.bg_color and string.format('background="%s"', props.bg_color) or "" + local fg = props.fg_color + and string.format('foreground="%s"', gears.color.to_rgba_string(props.fg_color)) or "" + local bg = props.bg_color + and string.format('background="%s"', gears.color.to_rgba_string(props.bg_color)) or "" props.markup = string.format( '%s', fg, bg, "%s" @@ -426,4 +428,4 @@ end return setmetatable(calendar_popup, calendar_popup.mt) --- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 \ No newline at end of file +-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 From e50b41b10d85ae02aa46178545eb5e8ab39d8045 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Sun, 2 Jan 2022 17:12:38 +0100 Subject: [PATCH 039/134] add(ltp) .function anchor copy link to clipboard --- docs/ldoc.css | 14 ++++++++++++++ docs/ldoc.ltp | 45 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 58 insertions(+), 1 deletion(-) diff --git a/docs/ldoc.css b/docs/ldoc.css index 3381d9cc4..d8564cfe1 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -649,3 +649,17 @@ pre .url { color: #272fc2; text-decoration: underline; } color: #00000044; margin-top: 15px; } + +.copy-link { + font-size: 9px; + padding: 2px; + border-radius: 9px; + vertical-align: middle; + text-decoration: none; +} +.copy-link--success { + background-color: green; +} +.copy-link--failure { + background-color: red; +} diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index c306780f7..94255cb17 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -339,7 +339,7 @@ # end # for item in iter(k.items) do if not item.tags.hidden then
- + 🔗 $(display_name(item)) # if item.display_inheritance then @@ -559,6 +559,49 @@ target.classList.remove("open"); } }); + + const copyResultClasses = { + success : "copy-link--success", + failure: "copy-link--failure" + }; + + const removeCopyResultClasses = ($target) => + Object.values(copyResultClasses).forEach(c => $target.classList.remove(c)); + + document.querySelectorAll(".js-copy-link").forEach(copyLink => { + copyLink.addEventListener("click", function(e) { + e.preventDefault(); + const $target = e.target; + + removeCopyResultClasses($target); + + let link = $target.href; + if (!link) { + return; + } + if (link.startsWith("#")) { + const curr = window.location.pathname; + link = curr.substring(0, curr.indexOf("#")) + link; + } + + // We need to create a fake element to copy the text from + const fakeElement = document.createElement("textarea"); + fakeElement.value = link; + document.body.appendChild(fakeElement); + fakeElement.select(); + + let success = false; + try { + success = document.execCommand("copy"); + } catch(err) { + success = false; + } + + fakeElement.remove(); + $target.classList.add(success ? copyResultClasses.success : copyResultClasses.failure); + setInterval(() => removeCopyResultClasses($target), 1500); + }); + }); From e15205a5486df7546182b2f67ebb4edd51533c74 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Mon, 3 Jan 2022 02:52:23 +0100 Subject: [PATCH 040/134] add(css) .image-object max-size (#17) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Emmanuel Lepage Vallée --- docs/config.ld | 4 +++- docs/ldoc.css | 5 +++++ tests/examples/CMakeLists.txt | 2 +- 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index d939d2f5c..bfa4022fb 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -31,7 +31,9 @@ should be useful for you. ### Default configuration components name: -
+
+ +
### Guides diff --git a/docs/ldoc.css b/docs/ldoc.css index d8564cfe1..8ed72fdde 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -650,6 +650,11 @@ pre .url { color: #272fc2; text-decoration: underline; } margin-top: 15px; } +.img-object { + max-width: 100%; + padding: 5px; +} + .copy-link { font-size: 9px; padding: 2px; diff --git a/tests/examples/CMakeLists.txt b/tests/examples/CMakeLists.txt index f7a9a68c8..2a63c4c43 100644 --- a/tests/examples/CMakeLists.txt +++ b/tests/examples/CMakeLists.txt @@ -237,7 +237,7 @@ function(run_test test_path namespace escaped_content) set(OUTPUT_RAW_IMAGE_PATH "${RAW_IMAGE_PATH}.svg") set(OUTPUT_IMAGE_PATH "${IMAGE_PATH}.svg") escape_string( - "\n" + "\n" "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT "" ) else() From 1f5b759306e2a85459303d98ceebd4b9c5114852 Mon Sep 17 00:00:00 2001 From: Grzegorz Bednarski Date: Tue, 21 Dec 2021 20:48:53 +0100 Subject: [PATCH 041/134] Support minimized client property in tasklist icons (#3526) --- lib/awful/widget/tasklist.lua | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index c563f830a..09be966ff 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -243,13 +243,6 @@ local instances -- @beautiful beautiful.tasklist_minimized -- @tparam[opt=nil] string minimized ---- The focused client alignment. --- --- @DOC_wibox_awidget_tasklist_style_align_EXAMPLE@ --- --- @beautiful beautiful.tasklist_align --- @tparam[opt=left] string align *left*, *right* or *center* - --- The tasklist font. -- -- @DOC_wibox_awidget_tasklist_style_font_EXAMPLE@ @@ -258,6 +251,14 @@ local instances -- @tparam[opt=nil] string font -- @see wibox.widget.textbox.font +--- The focused client alignment. +-- +-- @DOC_wibox_awidget_tasklist_style_align_EXAMPLE@ +-- +-- @beautiful beautiful.tasklist_align +-- @tparam[opt=left] string align *left*, *right* or *center* + + --- The focused client title alignment. -- -- @DOC_wibox_awidget_tasklist_style_font_focus_EXAMPLE@ From af3e62ae64d7a79cb098881a9df09d9812933316 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 13 Nov 2021 00:14:29 -0800 Subject: [PATCH 042/134] tasklist: Fix `disable_icon`. It regressed when the tasklist switched to a template by default. This was done to support the icon size. Fix #3178 --- lib/awful/widget/tasklist.lua | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 09be966ff..c563f830a 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -243,14 +243,6 @@ local instances -- @beautiful beautiful.tasklist_minimized -- @tparam[opt=nil] string minimized ---- The tasklist font. --- --- @DOC_wibox_awidget_tasklist_style_font_EXAMPLE@ --- --- @beautiful beautiful.tasklist_font --- @tparam[opt=nil] string font --- @see wibox.widget.textbox.font - --- The focused client alignment. -- -- @DOC_wibox_awidget_tasklist_style_align_EXAMPLE@ @@ -258,6 +250,13 @@ local instances -- @beautiful beautiful.tasklist_align -- @tparam[opt=left] string align *left*, *right* or *center* +--- The tasklist font. +-- +-- @DOC_wibox_awidget_tasklist_style_font_EXAMPLE@ +-- +-- @beautiful beautiful.tasklist_font +-- @tparam[opt=nil] string font +-- @see wibox.widget.textbox.font --- The focused client title alignment. -- From 16f84ec87a990521bf041f1612316de807a886cd Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 14 Dec 2021 12:14:32 -0800 Subject: [PATCH 043/134] doc: Improve the "See also" section. Now display: * The description summary. * The item kind. * The module name (if non-local). --- docs/ldoc.css | 14 ++++++++++++++ docs/ldoc.ltp | 21 ++++++++++++++++----- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/ldoc.css b/docs/ldoc.css index 8ed72fdde..9e3458c42 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -233,6 +233,20 @@ table th, table td { padding: 2px; } +.see_also, .see_also td { + border-style: hidden !important; +} + +.see_also tr td:nth-of-type(1) { + display: list-item; + list-style-type: disc; + list-style-position: inside; +} + +.see_also tr:hover { + background-color: #f7fbff; +} + .widget_list td { padding-top: 10px; padding-bottom: 10px; diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 94255cb17..f23c51fb1 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -35,6 +35,7 @@ # local nowrap = ldoc.wrap and '' or 'nowrap' # local html_space = function(s) return s:gsub(" ", "%%20") end # local no_underscores = function(s) return s:gsub("_", " ") end +# local get_item = function(mod, name) for item in iter(mod.items) do if item.name == name then return item end end; return name == "" and mod or nil end # --------- modules hierarchy ------------- # local hierarchy = {} @@ -247,7 +248,7 @@

See also:

<$(list_or_p)> # for see in iter(module.see) do - $(li)$(see.label)$(il) + $(li)$(see.label) BOB$(il) # end -- for
@@ -438,11 +439,21 @@ # if item.see then # local li,il = use_li(item.see)

See also:

-
    -# for see in iter(item.see) do - $(li)$(see.label)$(il) + +# for see in iter(item.see) do +# local see_item = see.mod and get_item(see.mod, see.name) +# local see_mod = (see_item and see.mod and see.mod ~= item.module and see.mod.name ~= see_item.name) and "("..see.mod.name..")" or "" + + + + + # end -- for - +
    $(see.label)$(see_item and M(see_item.summary)) $(see_mod) +# if see_item or see.name == "" then + $(see.name == "" and "module" or (see_item and see_item.kind)) +# end +
    # end -- if see # if item.usage then From 292b657aea81bf054963373ac799ca6413013da4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 16 Dec 2021 09:50:52 -0800 Subject: [PATCH 044/134] doc: Disable the ldoc optional function parameter mangling. It no longer does `foo(bar[,bar=42])` and will rather do `(foo, bar)`. This is easier to read and some new user are no familiar with the optional parameter convention. They copy/paste the mangled value in their config and end up with invalid Lua. --- docs/config.ld | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/config.ld b/docs/config.ld index bfa4022fb..25b4d1b36 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -956,6 +956,25 @@ custom_display_name_handler = function(item, default_handler) init_custom_types(item) + -- Do not use the default handler. It encodes the parameters using + -- the optchain convention. Not everybody is confortable with this. + -- It is also unreadable. + item.args = "" + + if item.params then + item.args = "(" + for key, line in ipairs(item.params) do + local name, comment = item:split_param(line) + local def = item:default_of_param(line) + if def then + item.args = item.args .. '' .. name .. "" .. (key < #item.params and ", " or "") + else + item.args = item.args .. name .. (key < #item.params and ", " or "") + end + end + item.args = item.args .. ")" + end + local ret = default_handler(item) -- Edit the input so the template is notified. From f26642f037ffcccc592c744067cb1b91986ad039 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 17 Dec 2021 13:07:56 -0800 Subject: [PATCH 045/134] doc: Fix mnor rendering issues. The module name wasn't present when it should have been. Same for the function params. --- docs/config.ld | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/config.ld b/docs/config.ld index 25b4d1b36..fd12514e9 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -744,6 +744,7 @@ local function wrap_args(item) -- Display named args with `{}` and ordered args with `()` if named_args[item.args] then + item.is_named_call = true return "{[args]}" end @@ -902,6 +903,8 @@ local add_mod = { staticfct = true, deprecated = true, field = true, + signalhandler = true, + table = true, } -- Add the arguments. @@ -909,6 +912,9 @@ local add_args = { constructorfct = true, constructorfct2 = true, staticfct = true, + signalhandler = true, + callback = true, + deprecated = true, } -- Add a type column to the summary and type field in the description. From 4a6385cf40ed3057e1ced72f7c23152b8c8f33b5 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 17 Dec 2021 13:34:49 -0800 Subject: [PATCH 046/134] doc: Replace the function argument rendering. This is an attempt at solving several problems reported by novice users. The old rendering was very compact and quite fine once you got used to its, ..., "conventions". But it was also sometime rather hard to read. First of all, it abused bold and italic. It also "merged" optional parameters and parameters with default content. It got worst when the documentation was spread over mutiple lines. For property types and constructors with large number of parameters, it was also quite unreadable. The new representation, while far from perfect, is less dense and more explicit. It has a separate column for "optional" using the new "metadata chip" documentation concept. It is also an aligned table and correctly renders multi-line documentation. Finally, it adds a "note" message when the named parameter convention is used. This way the users looking at the examples will be less confused. --- docs/images/warning_icon.svg | 84 ++++++++++++++++++++++++++++++++++++ docs/ldoc.css | 83 +++++++++++++++++++++++++++++++---- docs/ldoc.ltp | 82 ++++++++++++++++++++++++++--------- 3 files changed, 219 insertions(+), 30 deletions(-) create mode 100644 docs/images/warning_icon.svg diff --git a/docs/images/warning_icon.svg b/docs/images/warning_icon.svg new file mode 100644 index 000000000..83fc10da3 --- /dev/null +++ b/docs/images/warning_icon.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/docs/ldoc.css b/docs/ldoc.css index 9e3458c42..9451f6f35 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -25,22 +25,37 @@ hr { tt { font-family: monospace; } + span.parameter { font-family: monospace; font-weight: bold; color: rgb(99, 115, 131); } -span.parameter:after { - content:":"; + +span.optional_param { + font-style: italic; + color: rgb(143, 166, 230); } -span.types:before { - content:"("; + +.types { + white-space: pre; } -span.types:after { - content:")"; + +td span.types { + flex-flow: nowrap; + display: inline-flex; + width: 100%; } + .type { - font-weight: bold; font-style:italic + flex-basis: auto; + font-weight: bold; + font-style:italic; + pointer-events: none; + text-decoration: none; + color: #008fee; + text-align: center; + flex-grow: 1; } p.name { @@ -51,7 +66,12 @@ kbd, p code, ol code, ul code, -dd > code { +dd > code, +td code, +span.default_value, +.see_also_description code, +.important_box code +{ background-color: #eaedf587; padding-left: 3px; padding-right: 3px; @@ -161,6 +181,7 @@ dd > code { margin-left: 15px; margin-bottom: 5px; border-bottom: solid 1px #bcd; + font-weight: normal; } #content h4 { @@ -233,8 +254,24 @@ table th, table td { padding: 2px; } -.see_also, .see_also td { +.important_box { + padding-left: 40px; + min-height: 32px; + max-width: 640px; + vertical-align: middle; + background-image: url("images/warning_icon.svg"); + background-size: 32px 32px; + background-repeat: no-repeat; + background-position: left center; + margin-top: 15px; + margin-bottom: 5px; + margin-left: 10px; +} + +.see_also, .see_also td, .see_also th { border-style: hidden !important; + padding-left: 5pt; + padding-right: 5pt; } .see_also tr td:nth-of-type(1) { @@ -247,6 +284,26 @@ table th, table td { background-color: #f7fbff; } +.see_also tr th { + color: rgb(168, 168, 168); + padding-top: 15px; + padding-bottom: 4px; + font-weight: normal; + text-decoration: none; + font-style:italic; + font-size: 85%; +} + +.see_also_description { + max-width: 640px; +} + +.see_also_sublist td:nth-of-type(1) { + margin-left: 10px; + padding-left: 15px; + border-left: 1px solid rgb(200, 200, 200) !important; +} + .widget_list td { padding-top: 10px; padding-bottom: 10px; @@ -376,6 +433,14 @@ span.inheritance { font-weight: normal; } +span.not_applicable { + color: rgb(200, 200, 200); + font-style:italic; + font-size: 85%; + text-align: center; + display: block; +} + .summarytype { color: #a4c7ff; font-size: 85%; diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index f23c51fb1..93497ac32 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -139,7 +139,7 @@ # if ldoc.no_summary and module and not ldoc.one then -- bang out the functions on the side # for kind, items in module.kinds() do # if not kind:match("^ldoc_skip") then -

    $(kind)dasdasd

    +

    $(kind)

      # end # for item in items() do @@ -373,35 +373,75 @@ # if subnames then

      $(subnames):

      # end -
        +# local has_optional, has_named_call = false, false +# for parm in iter(item.params) do +# local param,sublist = item:subparam(parm) +# has_named_call = has_named_call or (sublist and item.is_named_call) +# for p in iter(param) do +# local def = item:default_of_param(p) +# has_optional = has_optional or (def and def ~= true) +# end +# end +# if has_named_call then +
        + Note: This $(item.kind) uses named parameters calling convention. It + means you call it with $(M('`{}`')) and omit the parantheses. For example, + calling this will all default argument would be $(item.name){}. + This is a Lua shortcut syntax equivalent to $(item.name)({}). + args is only a placeholder name for the "lone table argument" + used in named parameters calls. +
        +# end + + + + + + +# if has_optional then + +# end + # for parm in iter(item.params) do # local param,sublist = item:subparam(parm) # if sublist then -
      • $(sublist)$(M(item.params.map[sublist],item)) -
          +# local def = item:default_of_param(sublist) +
        • + + + + +# if has_optional then +# if def and def ~= true then + +# elseif def then + +# else + +# end +# end + # end # for p in iter(param) do # local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p) -
      • $(name) -# if tp ~= '' then - $(tp) + +
        • + + + +# if has_optional then +# if def and def ~= true then + +# elseif def then + +# else + # end - $(M(item.params.map[p],item)) -# if def == true then - (optional) -# elseif def then - (default$(def)) -# end -# if item:readonly(p) then - readonly -# end - -# end -# if sublist then - +# end + # end # end -- for - +
        NameType(s)DescriptionDefault value
        $(sublist)$(def and 'Optional' or '')table$(M(item.params.map[sublist],item)) $(def)UndefinedNot applicable
        $(name)$(def and 'Optional' or '')$(tp)$(M(item.params.map[p],item))$(def)UndefinedNot applicable
        # end -- if params # if show_return and item.retgroups then local groups = item.retgroups From f3987f43b68c77ad6ca3b90ae56184cfcb5ae81a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 17 Dec 2021 13:46:08 -0800 Subject: [PATCH 047/134] doc: More proof reading fixes. --- docs/common/signals.ldoc | 6 +- lib/awful/client.lua | 75 +++++++++++++--------- lib/awful/mouse/init.lua | 4 +- lib/awful/permissions/init.lua | 44 ++++++++++--- lib/awful/popup.lua | 10 +-- lib/awful/tag.lua | 63 ++++++++++--------- lib/awful/titlebar.lua | 4 +- lib/awful/widget/layoutlist.lua | 2 +- lib/awful/widget/taglist.lua | 8 +-- lib/awful/widget/tasklist.lua | 4 +- lib/gears/surface.lua | 4 +- lib/naughty/core.lua | 86 ++++++++++++++------------ tests/examples/sequences/tag/clear.lua | 2 +- 13 files changed, 185 insertions(+), 127 deletions(-) diff --git a/docs/common/signals.ldoc b/docs/common/signals.ldoc index 2c636169b..30499a8ef 100644 --- a/docs/common/signals.ldoc +++ b/docs/common/signals.ldoc @@ -10,7 +10,7 @@ -- -- @tparam string name The name of the signal -- @tparam function func The function to attach --- @function naughty.connect_signal +-- @staticfct naughty.connect_signal -- @usage naughty.connect_signal("added", function(notif) -- -- do something -- end) @@ -18,10 +18,10 @@ --- Emit a module signal. -- @tparam string name The signal name. -- @param ... The signal callback arguments --- @function naughty.emit_signal +-- @staticfct naughty.emit_signal --- Disconnect a signal from a source. -- @tparam string name The name of the signal -- @tparam function func The attached function --- @function naughty.disconnect_signal +-- @staticfct naughty.disconnect_signal -- @treturn boolean If the disconnection was successful diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 3d2336a7c..98f41b6bf 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -174,7 +174,7 @@ end -- @DOC_sequences_client_jump_to1_EXAMPLE@ -- -- @method jump_to --- @tparam bool|function merge If true then merge tags (select the client's +-- @tparam[opt] 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 -- tag as arguments. @@ -212,7 +212,7 @@ end -- -- @deprecated awful.client.visible -- @see screen.clients --- @tparam[opt] integer|screen s The screen, or nil for all screens. +-- @tparam[opt] nil|integer|screen s The screen, or nil for all screens. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @treturn table A table with all visible clients. function client.visible(s, stacked) @@ -230,7 +230,7 @@ end -- -- @deprecated awful.client.tiled -- @see screen.tiled_clients --- @tparam integer|screen s The screen, or nil for all screens. +-- @tparam nil|integer|screen s The screen, or nil for all screens. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @treturn table A table with all visible and tiled clients. function client.tiled(s, stacked) @@ -253,8 +253,8 @@ end -- If no client is passed, the focused client will be used. -- -- @staticfct awful.client.next --- @tparam int i The index. Use 1 to get the next, -1 to get the previous. --- @tparam[opt] client sel The client. +-- @tparam int i The index. Use `1` to get the next, `-1` to get the previous. +-- @tparam[opt=client.focus] client sel The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @treturn[opt] client|nil A client, or nil if no client is available. -- @see client.get @@ -296,7 +296,7 @@ end -- -- @staticfct awful.client.swap.bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". --- @tparam[opt=focused] client c The client. +-- @tparam[opt="focused"] client c The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @see swap -- @see swapped @@ -328,7 +328,7 @@ end -- -- @staticfct awful.client.swap.global_bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". --- @tparam[opt] client sel The client. +-- @tparam[opt=client.focus] client sel The client. -- @request client activate client.swap.global_bydirection granted When a client -- could be activated because `awful.client.swap.global_bydirection` was called. -- @see swap @@ -370,13 +370,14 @@ end -- @DOC_sequences_client_swap_byidx1_EXAMPLE@ -- -- @staticfct awful.client.swap.byidx --- @tparam integer i The index. --- @tparam[opt] client c The client, otherwise focused one is used. +-- @tparam integer i The index. Use `1` to get the next, `-1` to get the previous. +-- @tparam[opt=client.focus] client c The client, otherwise focused one is used. -- @see swap -- @see swapped -- @see awful.client.swap.bydirection -- @see awful.client.swap.global_bydirection -- @see awful.client.cycle +-- @see awful.client.next function client.swap.byidx(i, c) local sel = c or capi.client.focus local target = client.next(i, sel) @@ -393,8 +394,8 @@ end -- @DOC_sequences_client_cycle1_EXAMPLE@ -- -- @staticfct awful.client.cycle --- @tparam boolean clockwise True to cycle clients clockwise. --- @tparam[opt] screen s The screen where to cycle clients. +-- @tparam[opt=false] boolean clockwise True to cycle clients clockwise. +-- @tparam[opt=awful.screen.focused()] screen s The screen where to cycle clients. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @see swap -- @see swapped @@ -510,7 +511,7 @@ end -- @tparam integer y The relative y coordinate. -- @tparam integer w The relative width. -- @tparam integer h The relative height. --- @tparam[opt] client c The client, otherwise focused one is used. +-- @tparam[opt=client.focus] client c The client, otherwise focused one is used. -- @see client.relative_move function client.moveresize(x, y, w, h, c) gdebug.deprecate("Use c:relative_move(x, y, w, h) instead of awful.client.moveresize", {deprecated_in=4}) @@ -522,11 +523,16 @@ end -- @DOC_sequences_client_relative_move1_EXAMPLE@ -- -- @method relative_move +-- @tparam[opt=0] integer x The relative x coordinate. +-- @tparam[opt=0] integer y The relative y coordinate. +-- @tparam[opt=0] integer w The relative width. +-- @tparam[opt=0] integer h The relative height. -- @see geometry --- @tparam[opt=0] number x The relative x coordinate. --- @tparam[opt=0] number y The relative y coordinate. --- @tparam[opt=0] number w The relative width. --- @tparam[opt=0] number h The relative height. +-- @see x +-- @see y +-- @see width +-- @see height +-- @see floating function client.object.relative_move(self, x, y, w, h) local geometry = self:geometry() geometry['x'] = geometry['x'] + (x or 0) @@ -571,7 +577,7 @@ end -- -- @deprecated awful.client.toggletag -- @tparam tag target The tag to toggle. --- @tparam[opt] client c The client to toggle, otherwise the focused one is used. +-- @tparam[opt=client.focus] client c The client to toggle, otherwise the focused one is used. -- @see client.toggle_tag -- @see tags function client.toggletag(target, c) @@ -610,7 +616,7 @@ end --- Move a client to a screen. Default is next screen, cycling. -- @deprecated awful.client.movetoscreen --- @tparam client c The client to move. +-- @tparam[opt=client.focus] client c The client to move. -- @tparam screen s The screen, default to current + 1. -- @see screen -- @see client.move_to_screen @@ -791,16 +797,27 @@ end -- Floating client are not handled by tiling layouts. -- @deprecated awful.client.floating.set -- @tparam client c A client. --- @tparam boolean s True or false. +-- @tparam boolean s `true` is the client is to become floating or `false`. function client.floating.set(c, s) gdebug.deprecate("Use c.floating = true instead of awful.client.floating.set", {deprecated_in=4}) client.object.set_floating(c, s) end -- Set a client floating state, overriding auto-detection. --- Floating client are not handled by tiling layouts. +-- +-- Floating client are not handled by tiling layouts. They can be +-- moved around and resized freely unless other restriction, such as `maximized` +-- or the `size_hints` restrict their geometry. +-- +-- An easy way to position floating clients is to use the `awful.placement` +-- module. +-- -- @tparam client c A client. --- @tparam boolan s True or false. +-- @tparam boolean floating. +-- @see is_immobilized_vertical +-- @see is_immobilized_horizontal +-- @see is_fixed +-- @see size_hints function client.object.set_floating(c, s) c = c or capi.client.focus if c and client.property.get(c, "floating") ~= s then @@ -838,7 +855,7 @@ capi.client.connect_signal("property::geometry", store_floating_geometry) --- Return if a client has a fixed size or not. -- This function is deprecated, use `c.is_fixed` --- @tparam client c The client. +-- @tparam[opt=client.focus] client c The client. -- @deprecated awful.client.isfixed -- @see is_fixed -- @see size_hints_honor @@ -851,7 +868,7 @@ end --- Return if a client has a fixed size or not. -- -- @property is_fixed --- @tparam[opt=false] boolean is_fixed The fixed size state +-- @tparam[opt=false] boolean is_fixed The fixed size state. -- @propemits false false -- @readonly -- @see size_hints @@ -874,10 +891,10 @@ end --- Is the client immobilized horizontally? -- -- Does the client have a fixed horizontal position and width, i.e. is it --- fullscreen, maximized, or horizontally maximized? +-- `fullscreen`, `maximized`, or `maximized_horizontal`? -- -- @property immobilized_horizontal --- @tparam[opt=false] boolean immobilized_horizontal The immobilized state +-- @tparam[opt=false] boolean immobilized_horizontal The immobilized state. -- @readonly -- @see maximized -- @see maximized_horizontal @@ -1274,7 +1291,7 @@ end -- @tparam number add Amount to increase/decrease the client's window factor by. -- Should be between `-current_window_factor` and something close to -- infinite. Normalisation then ensures that the sum of all factors is 1. --- @tparam client c the client. +-- @tparam[opt=client.focus] client c the client. -- @emits property::windowfact function client.incwfact(add, c) c = c or capi.client.focus @@ -1448,7 +1465,7 @@ end -- @tparam function filter a function that returns true to indicate a positive match. -- @tparam integer start what index to start iterating from. Defaults to using the -- index of the currently focused client. --- @tparam screen s which screen to use. nil means all screens. +-- @tparam[opt=nil] screen s which screen to use. nil means all screens. -- -- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances @@ -1640,7 +1657,7 @@ end -- -- @method activate -- @tparam table args --- @tparam[opt=other] string args.context Why was this activate called? +-- @tparam[opt="other"] string args.context Why was this activate called? -- @tparam[opt=true] boolean args.raise Raise the client to the top of its layer -- and unminimize it (if needed). -- @tparam[opt=false] boolean args.force Force the activation even for unfocusable @@ -1649,6 +1666,8 @@ end -- @tparam[opt=false] boolean args.switch_to_tag -- @tparam[opt=false] boolean args.action Once activated, perform an action. -- @tparam[opt=false] boolean args.toggle_minimization +-- @request client activate args.context granted Will use the context defined in +-- `args.context`. -- @see awful.permissions.add_activate_filter -- @see awful.permissions.activate -- @see request::activate diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index 5a9890e70..92c9ac462 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -77,11 +77,11 @@ mouse.wibox = {} --- The resize cursor name. -- @beautiful beautiful.cursor_mouse_resize --- @tparam[opt=cross] string cursor +-- @tparam[opt="cross"] string cursor --- The move cursor name. -- @beautiful beautiful.cursor_mouse_move --- @tparam[opt=fleur] string cursor +-- @tparam[opt="fleur"] string cursor --- Get the client object under the pointer. -- @deprecated awful.mouse.client_under_pointer diff --git a/lib/awful/permissions/init.lua b/lib/awful/permissions/init.lua index 64673d3f7..93be8eb95 100644 --- a/lib/awful/permissions/init.lua +++ b/lib/awful/permissions/init.lua @@ -38,18 +38,18 @@ local permissions = { -- @beautiful beautiful.maximized_hide_border -- @tparam[opt=false] boolean maximized_hide_border ---- The list of all registered generic request::activate (focus stealing) +--- The list of all registered generic `request::activate` (focus stealing) -- filters. If a filter is added to only one context, it will be in -- `permissions.contextual_activate_filters`["context_name"]. --- @table[opt={}] generic_activate_filters +-- @table[opt={}] awful.permissions.generic_activate_filters -- @see permissions.activate -- @see permissions.add_activate_filter -- @see permissions.remove_activate_filter ---- The list of all registered contextual request::activate (focus stealing) +--- The list of all registered contextual `request::activate` (focus stealing) -- filters. If a filter is added to only one context, it will be in -- `permissions.generic_activate_filters`. --- @table[opt={}] contextual_activate_filters +-- @table[opt={}] awful.permissions.contextual_activate_filters -- @see permissions.activate -- @see permissions.add_activate_filter -- @see permissions.remove_activate_filter @@ -288,8 +288,9 @@ end -- -- @signalhandler awful.permissions.tag -- @tparam client c A client to tag --- @tparam[opt] tag|boolean t A tag to use. If true, then the client is made sticky. --- @tparam[opt={}] table hints Extra information +-- @tparam[opt] tag|boolean t A tag to use. If `true`, then the client is made `sticky`. +-- @tparam[opt={}] table hints Extra information. +-- @tparam[opt=nil] nil|string hints.reason Why the tag is being changed. function permissions.tag(c, t, hints) --luacheck: no unused -- There is nothing to do if not t and #get_valid_tags(c, c.screen) > 0 then return end @@ -338,6 +339,10 @@ local context_mapper = { -- @tparam client c The client -- @tparam string context The context -- @tparam[opt={}] table hints The hints to pass to the handler +-- @tparam[opt=true] boolean hints.store_geometry Create a memento of the +-- previous geometry in case it has to be restored. +-- @tparam[opt=true] boolean hints.honor_workarea Avoid overlapping the `wibar`s +-- or other desktop decoration when applying the geometry. function permissions.geometry(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -407,6 +412,10 @@ end -- @tparam wibox w The wibox. -- @tparam string context The context -- @tparam[opt={}] table hints The hints to pass to the handler +-- @tparam[opt] integer hints.x The horizontal position. +-- @tparam[opt] integer hints.y The vertical position. +-- @tparam[opt] integer hints.width The wibox width. +-- @tparam[opt] integer hints.height The wibox height. function permissions.wibox_geometry(w, context, hints) if not pcommon.check(w, "wibox", "geometry", context) then return end @@ -416,14 +425,16 @@ end --- Merge the 2 requests sent by clients wanting to be maximized. -- -- The X clients set 2 flags (atoms) when they want to be maximized. This caused --- 2 request::geometry to be sent. This code gives some time for them to arrive +-- 2 `request::geometry` to be sent. This code gives some time for them to arrive -- and send a new `request::geometry` (through the property change) with the -- combined state. -- -- @signalhandler awful.permissions.merge_maximization -- @tparam client c The client -- @tparam string context The context --- @tparam[opt={}] table hints The hints to pass to the handler +-- @tparam[opt={}] table hints The hints to pass to the handler. +-- @tparam[opt=false] boolean hints.toggle Toggle the maximization state rather +-- than set it to `true`. function permissions.merge_maximization(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -506,7 +517,11 @@ end -- @signalhandler awful.permissions.client_geometry_requests -- @tparam client c The client -- @tparam string context The context --- @tparam[opt={}] table hints The hints to pass to the handler +-- @tparam[opt={}] table hints The hints to pass to the handler. +-- @tparam[opt] integer hints.x The horizontal position. +-- @tparam[opt] integer hints.y The vertical position. +-- @tparam[opt] integer hints.width The client width. +-- @tparam[opt] integer hints.height The client height. function permissions.client_geometry_requests(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -539,13 +554,15 @@ end, "mouse_enter") -- -- To replace this handler with your own, use: -- --- client.disconnect_signal("request::border", awful.ewmh.update_border) +-- client.disconnect_signal("request::border", awful.permisions.update_border) -- -- The default implementation chooses from dozens beautiful theme variables -- depending if the client is tiled, floating, maximized and then from its state -- (urgent, new, active, normal) -- -- @signalhandler awful.permissions.update_border +-- @tparam client c The client. +-- @tparam string context Why is the border changed. -- @usebeautiful beautiful.border_color_marked -- @usebeautiful beautiful.border_color_active -- @usebeautiful beautiful.border_color_normal @@ -604,6 +621,8 @@ end, "mouse_enter") -- @usebeautiful beautiful.opacity_normal -- @usebeautiful beautiful.opacity_new -- @usebeautiful beautiful.opacity_urgent +-- @see client.border_width +-- @see client.border_color function permissions.update_border(c, context) if not pcommon.check(c, "client", "border", context) then return end @@ -729,6 +748,11 @@ local activate_context_map = { -- * history : *autofocus.check_focus* -- -- @signalhandler awful.permissions.autoactivate +-- @tparam client c The client. +-- @tparam string context Why is the client auto-activated. +-- @tparam[opt={}] table hints Extra arguments. +-- @see activate +-- @see client:activate function permissions.autoactivate(c, context, args) if not pcommon.check(c, "client", "autoactivate", context) then return end diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index 8757634f1..cde263434 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -338,9 +338,9 @@ end -- -- @DOC_awful_popup_position3_EXAMPLE@ -- @property offset --- @tparam table|number offset An integer value or a `{x=, y=}` table. --- @tparam[opt=offset] number offset.x The horizontal distance. --- @tparam[opt=offset] number offset.y The vertical distance. +-- @tparam table|integer offset An integer value or a `{x=, y=}` table. +-- @tparam[opt=offset] integer offset.x The horizontal distance. +-- @tparam[opt=offset] integer offset.y The vertical distance. -- @propemits true false function popup:set_offset(offset) @@ -370,7 +370,7 @@ end -- (or false to disable placement) -- -- @property placement --- @tparam[opt=next_to] function|string|boolean placement The placement function or name +-- @tparam[opt=awful.placement.next_to] function|string|boolean placement The placement function or name -- @propemits true false -- @see awful.placement @@ -496,4 +496,6 @@ end --@DOC_wibox_COMMON@ +--@DOC_object_COMMON@ + return setmetatable(module, {__call = create_popup}) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 39fda931b..d5ceeee5f 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -203,11 +203,10 @@ function tag.object.get_index(query_tag) end end ---- Move a tag to an absolute position in the screen[]:tags() table. +--- Move a tag to an absolute position in the `screen[]:tags()` table. -- @deprecated awful.tag.move -- @tparam integer new_index Integer absolute position in the table to insert. --- @tparam tag target_tag The tag that should be moved. If null, the currently --- selected tag is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag target_tag The tag that should be moved. -- @see index function tag.move(new_index, target_tag) gdebug.deprecate("Use t.index = new_index instead of awful.tag.move", {deprecated_in=4}) @@ -308,7 +307,7 @@ end -- -- @staticfct awful.tag.new -- @tparam table names The tag name, in a table --- @tparam[opt=1] screen|number screen The tag screen (defaults to screen 1). +-- @tparam[opt=1] screen|number screen The tag screen. -- @tparam table layout The layout or layout table to set for this tags by default. -- @treturn table A table with all created tags. function tag.new(names, screen, layout) @@ -334,8 +333,8 @@ end --- Find a suitable fallback tag. -- @staticfct awful.tag.find_fallback --- @tparam screen screen The screen to look for a tag on. [awful.screen.focused()] --- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. [selectedlist(scr)] +-- @tparam[opt=awful.screen.focused()] screen screen The screen to look for a tag on. +-- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. function tag.find_fallback(screen, invalids) local scr = screen or ascreen.focused() local t = invalids or scr.selected_tags @@ -465,8 +464,8 @@ end --- Delete a tag. -- @deprecated awful.tag.delete -- @see tag.delete --- @tparam tag target_tag Optional tag object to delete. [selected()] --- @tparam tag|nil fallback_tag Tag to assign stickied tags to. [~selected()] +-- @tparam[opt=mouse.screen.selected_tag] tag target_tag Optional tag object to delete. +-- @tparam[opt] tag|nil fallback_tag Tag to assign stickied tags to. -- @treturn boolean Returns true if the tag is successfully deleted, nil otherwise. -- If there are no clients exclusively on this tag then delete it. Any -- stickied clients are assigned to the optional 'fallback_tag'. @@ -694,7 +693,7 @@ end --- The default master width factor -- -- @beautiful beautiful.master_width_factor --- @tparam number master_width_factor (default: 0.5) +-- @tparam[opt=0.5] number master_width_factor -- @see master_width_factor -- @see gap @@ -741,7 +740,7 @@ end -- @see master_fill_policy -- @see master_width_factor -- @tparam number mwfact Master width factor. --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.setmwfact(mwfact, t) gdebug.deprecate("Use t.master_width_factor = mwfact instead of awful.tag.setmwfact", {deprecated_in=4}) @@ -752,7 +751,7 @@ end -- @staticfct awful.tag.incmwfact -- @see master_width_factor -- @tparam number add Value to add to master width factor. --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.incmwfact(add, t) t = t or t or ascreen.focused().selected_tag tag.object.set_master_width_factor(t, tag.object.get_master_width_factor(t) + add) @@ -797,6 +796,9 @@ end -- @tfield table awful.tag.layouts -- @tparam[opt={}] table awful.tag.layouts -- @see request::layouts +-- @see awful.layout.append_default_layouts +-- @see awful.layout.append_default_layout +-- @see awful.layout.remove_default_layout --- The tag client layout. -- @@ -1055,7 +1057,7 @@ end -- @deprecated awful.tag.setvolatile -- @see volatile -- @tparam boolean volatile If the tag must be deleted when the last client is untagged --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.setvolatile(volatile, t) gdebug.deprecate("Use t.volatile = volatile instead of awful.tag.setvolatile", {deprecated_in=4}) @@ -1065,7 +1067,7 @@ end --- Get if the tag must be deleted when the last client closes -- @deprecated awful.tag.getvolatile -- @see volatile --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @treturn boolean If the tag will be deleted when the last client is untagged function tag.getvolatile(t) gdebug.deprecate("Use t.volatile instead of awful.tag.getvolatile", {deprecated_in=4}) @@ -1076,7 +1078,7 @@ end --- The default gap. -- -- @beautiful beautiful.useless_gap --- @tparam tag number (default: 0) +-- @tparam[opt=0] number useless_gap -- @see gap -- @see gap_single_client @@ -1115,7 +1117,7 @@ end -- @deprecated awful.tag.setgap -- @see gap -- @tparam number|nil useless_gap The spacing between clients --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.setgap(useless_gap, t) gdebug.deprecate("Use t.gap = useless_gap instead of awful.tag.setgap", {deprecated_in=4}) @@ -1124,9 +1126,10 @@ end --- Increase the spacing between clients -- @staticfct awful.tag.incgap --- @see gap -- @tparam number add Value to add to the spacing between clients --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. +-- @see gap +-- @see beautiful.useless_gap function tag.incgap(add, t) t = t or t or ascreen.focused().selected_tag tag.object.set_gap(t, tag.object.get_gap(t) + add) @@ -1135,7 +1138,7 @@ end --- Enable gaps for a single client. -- -- @beautiful beautiful.gap_single_client --- @tparam boolean gap_single_client (default: true) +-- @tparam[opt=true] boolean gap_single_client -- @see gap -- @see gap_single_client @@ -1201,7 +1204,7 @@ end -- `master_width_factor` -- -- @beautiful beautiful.master_fill_policy --- @tparam string master_fill_policy (default: "expand") +-- @tparam[opt="expand"] string master_fill_policy -- @see master_fill_policy --- Set size fill policy for the master client(s). @@ -1227,7 +1230,7 @@ end -- redistributed on both side. -- -- @property master_fill_policy --- @tparam string master_fill_policy "expand" or "master_width_factor" +-- @tparam string master_fill_policy "expand" or "master\_width\_factor" -- @propemits false false -- @see awful.tag.togglemfpol @@ -1252,10 +1255,10 @@ function tag.setmfpol(policy, t) end --- Toggle size fill policy for the master client(s) --- between "expand" and "master_width_factor". +-- between "expand" and `master_width_factor`. -- @staticfct awful.tag.togglemfpol -- @see master_fill_policy --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.togglemfpol(t) t = t or ascreen.focused().selected_tag @@ -1285,7 +1288,7 @@ end --- The default number of master windows. -- -- @beautiful beautiful.master_count --- @tparam integer master_count (default: 1) +-- @tparam[opt=1] integer master_count -- @see master_count --- Set the number of master windows. @@ -1337,7 +1340,7 @@ end -- @staticfct awful.tag.incnmaster -- @see master_count -- @tparam number add Value to add to number of master windows. --- @tparam[opt] tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @tparam[opt=false] boolean sensible Limit nmaster based on the number of -- visible tiled windows? function tag.incnmaster(add, t, sensible) @@ -1400,7 +1403,7 @@ end --- The default number of columns. -- -- @beautiful beautiful.column_count --- @tparam integer column_count (default: 1) +-- @tparam[opt=1] integer column_count -- @see column_count --- Set the number of columns. @@ -1430,7 +1433,7 @@ end -- @deprecated awful.tag.setncol -- @see column_count -- @tparam integer ncol The number of column. --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.setncol(ncol, t) gdebug.deprecate("Use t.column_count = new_index instead of awful.tag.setncol", {deprecated_in=4}) @@ -1455,7 +1458,7 @@ end --- Increase number of column windows. -- @staticfct awful.tag.incncol -- @tparam number add Value to add to number of column windows. --- @tparam[opt] tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @tparam[opt=false] boolean sensible Limit column_count based on the number -- of visible tiled windows? function tag.incncol(add, t, sensible) @@ -1734,9 +1737,9 @@ end -- future. When a tag is detached from the screen, its signal is removed. -- -- @staticfct awful.tag.attached_connect_signal --- @tparam screen screen The screen concerned, or all if nil. --- @tparam[opt] string signal The signal name. --- @tparam[opt] function Callback +-- @tparam screen|nil screen The screen concerned, or all if `nil`. +-- @tparam string signal The signal name. +-- @tparam function Callback function tag.attached_connect_signal(screen, ...) if screen then attached_connect_signal_screen(screen, ...) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 9952a743a..5345851f6 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -1,6 +1,8 @@ --------------------------------------------------------------------------- --- Titlebars for awful. ---**Create a titlebar:** +-- +-- Create a titlebar +-- ================= -- -- This example reproduces what the default `rc.lua` does. It shows how to -- handle the titlebars on a lower level. diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index 2fffe2bbf..9edc97e23 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -238,7 +238,7 @@ local layoutlist = {} --- The selected layout alignment. -- @beautiful beautiful.layoutlist_align --- @tparam[opt=left] string align *left*, *right* or *center* +-- @tparam[opt="left"] string align *left*, *right* or *center* --- The selected layout title font. -- @beautiful beautiful.layoutlist_font_selected diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index de24bac4d..3b8f895f5 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -65,22 +65,22 @@ taglist.filter, taglist.source = {}, {} --- The tag list main foreground (text) color. -- @beautiful beautiful.taglist_fg_focus --- @param[opt=fg_focus] color +-- @param[opt=beautiful.fg_focus] color -- @see gears.color --- The tag list main background color. -- @beautiful beautiful.taglist_bg_focus --- @param[opt=bg_focus] color +-- @param[opt=beautiful.bg_focus] color -- @see gears.color --- The tag list urgent elements foreground (text) color. -- @beautiful beautiful.taglist_fg_urgent --- @param[opt=fg_urgent] color +-- @param[opt=beautiful.fg_urgent] color -- @see gears.color --- The tag list urgent elements background color. -- @beautiful beautiful.taglist_bg_urgent --- @param[opt=bg_urgent] color +-- @param[opt=beautiful.bg_urgent] color -- @see gears.color --- The tag list occupied elements background color. diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index c563f830a..7fbff70c3 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -248,7 +248,7 @@ local instances -- @DOC_wibox_awidget_tasklist_style_align_EXAMPLE@ -- -- @beautiful beautiful.tasklist_align --- @tparam[opt=left] string align *left*, *right* or *center* +-- @tparam[opt="left"] string align *left*, *right* or *center* --- The tasklist font. -- @@ -823,7 +823,7 @@ end -- @tparam[opt='⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical -- @tparam[opt=false] boolean args.style.disable_task_name -- @tparam[opt=nil] string args.style.font --- @tparam[opt=left] string args.style.align *left*, *right* or *center* +-- @tparam[opt="left"] string args.style.align *left*, *right* or *center* -- @tparam[opt=nil] string args.style.font_focus -- @tparam[opt=nil] string args.style.font_minimized -- @tparam[opt=nil] string args.style.font_urgent diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index 38c05796c..a0c2d2b8f 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -169,8 +169,8 @@ end -- @tparam number width The surface width -- @tparam number height The surface height -- @param shape A `gears.shape` compatible function --- @param[opt=white] shape_color The shape color or pattern --- @param[opt=transparent] bg_color The surface background color +-- @param[opt="#000000"] shape_color The shape color or pattern +-- @param[opt="#00000000"] 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, ...) diff --git a/lib/naughty/core.lua b/lib/naughty/core.lua index bedb3ede3..98106ef33 100644 --- a/lib/naughty/core.lua +++ b/lib/naughty/core.lua @@ -24,20 +24,23 @@ local naughty = {} --- Naughty configuration - a table containing common popup settings. -- +-- The callback has the follwing format: +-- +-- naughty.config.notify_callback = function(args) +-- args.text = 'prefix: ' .. args.text +-- return args +-- end +-- -- @table naughty.config --- @tfield[opt=apply_dpi(4)] int padding Space between popups and edge of the +-- @tfield[opt=beautiful.xresources.apply_dpi(4)] integer padding Space between popups and edge of the -- workarea. --- @tfield[opt=apply_dpi(1)] int spacing Spacing between popups. +-- @tfield[opt=beautiful.xresources.apply_dpi(1)] integer spacing Spacing between popups. -- @tfield[opt={"/usr/share/pixmaps/"}] table icon_dirs List of directories -- that will be checked by `getIcon()`. -- @tfield[opt={ "png", "gif" }] table icon_formats List of formats that will be -- checked by `getIcon()`. -- @tfield[opt] function notify_callback Callback used to modify or reject -- notifications, e.g. --- naughty.config.notify_callback = function(args) --- args.text = 'prefix: ' .. args.text --- return args --- end -- To reject a notification return `nil` from the callback. -- If the notification is a freedesktop notification received via DBUS, you can -- access the freedesktop hints via `args.freedesktop_hints` if any where @@ -45,7 +48,7 @@ local naughty = {} -- -- @tfield table presets Notification presets. See `config.presets`. -- --- @tfield table defaults Default values for the params to `notify()`. These can +-- @tfield table defaults Default values for the params to `naughty.notification{}`. These can -- optionally be overridden by specifying a preset. See `config.defaults`. -- It's done that way to preserve compatibility with Awesome 4.0 while allowing @@ -55,46 +58,61 @@ gtable.crush(naughty, require("naughty.constants")) --- Notification presets for `naughty.notify`. -- This holds presets for different purposes. A preset is a table of any --- parameters for `notify()`, overriding the default values +-- parameters for `naughty.notification{}`, overriding the default values -- (`naughty.config.defaults`). -- --- You have to pass a reference of a preset in your `notify()` as the `preset` +-- You have to pass a reference of a preset in your `naughty.notification{}` as the `preset` -- argument. -- -- The presets `"low"`, `"normal"` and `"critical"` are used for notifications -- over DBUS. -- --- @table config.presets +-- @table naughty.config.presets -- @tfield table low The preset for notifications with low urgency level. --- @tfield[opt=5] int low.timeout --- @tfield[opt=empty] table normal The default preset for every notification without a +-- @tfield[opt=5] integer low.timeout +-- @tfield[opt={}] table normal The default preset for every notification without a -- preset that will also be used for normal urgency level. +-- @tfield table ok +-- @tfield[opt="#00bb00"] string ok.bg +-- @tfield[opt="#ffffff"] string ok.fg +-- @tfield[opt=5] integer ok.timeout -- @tfield table critical The preset for notifications with a critical urgency -- level. -- @tfield[opt="#ff0000"] string critical.bg -- @tfield[opt="#ffffff"] string critical.fg --- @tfield[opt=0] string critical.timeout +-- @tfield[opt=0] integer critical.timeout +-- @tfield table info +-- @tfield[opt="#0000ff"] string info.bg +-- @tfield[opt="#ffffff"] string info.fg +-- @tfield[opt=5] integer info.timeout +-- @tfield table warn +-- @tfield[opt="#ffaa00"] string warn.bg +-- @tfield[opt="#00000"] string warn.fg +-- @tfield[opt=5] integer warn.timeout --- Defaults for `naughty.notify`. -- --- @table config.defaults --- @tfield[opt=5] int timeout +-- @table naughty.config.defaults +-- @tfield[opt=5] integer timeout -- @tfield[opt=""] string text --- @tfield[opt] int screen Defaults to `awful.screen.focused`. +-- @tfield[opt=awful.screen.focused()] integer screen -- @tfield[opt=true] boolean ontop --- @tfield[opt=apply_dpi(5)] int margin --- @tfield[opt=apply_dpi(1)] int border_width +-- @tfield[opt=beautiful.xresources.apply_dpi(5)] integer margin +-- @tfield[opt=beautiful.xresources.apply_dpi(1)] integer border_width -- @tfield[opt="top_right"] string position --- The reason why a notification is to be closed. +-- -- See [the specification](https://developer.gnome.org/notification-spec/#signals) -- for more details. --- @tfield number silent --- @tfield number expired --- @tfield number dismissed_by_user --- @tfield number dismissed_by_command --- @tfield number undefined --- @table notification_closed_reason +-- +-- @table naughty.notification_closed_reason +-- @tfield[opt=-2] number too_many_on_screen +-- @tfield[opt=-1] number silent +-- @tfield[opt=1] number expired +-- @tfield[opt=2] number dismissed_by_user +-- @tfield[opt=3] number dismissed_by_command +-- @tfield[opt=4] number undefined --- The global suspension state. -- @@ -177,16 +195,6 @@ local properties = { --TODO v5 Deprecate the public `naughty.notifications` (to make it private) ---- Index of notifications per screen and position. --- See config table for valid 'position' values. --- Each element is a table consisting of: --- --- @field box Wibox object containing the popup --- @field height Popup height --- @field width Popup width --- @field die Function to be executed on timeout --- @field id Unique notification id based on a counter --- @table notifications naughty.notifications = { suspended = { }, _expired = {{}} } naughty._active = {} @@ -749,7 +757,7 @@ end -- @int[opt=5] args.timeout Time in seconds after which popup expires. -- Set 0 for no timeout. -- @int[opt] args.hover_timeout Delay in seconds after which hovered popup disappears. --- @tparam[opt=focused] integer|screen args.screen Target screen for the notification. +-- @tparam[opt=awful.screen.focused()] integer|screen args.screen Target screen for the notification. -- @string[opt="top_right"] args.position Corner of the workarea displaying the popups. -- Values: `"top_right"`, `"top_left"`, `"bottom_left"`, -- `"bottom_right"`, `"top_middle"`, `"bottom_middle"`, `"middle"`. @@ -766,17 +774,17 @@ end -- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape. -- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity. -- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin. --- @tparam[opt] func args.run Function to run on left click. The notification +-- @tparam[opt] function args.run Function to run on left click. The notification -- object will be passed to it as an argument. -- You need to call e.g. -- `notification.die(naughty.notification_closed_reason.dismissedByUser)` from -- there to dismiss the notification yourself. --- @tparam[opt] func args.destroy Function to run when notification is destroyed. +-- @tparam[opt] function args.destroy Function to run when notification is destroyed. -- @tparam[opt] table args.preset Table with any of the above parameters. -- Note: Any parameters specified directly in args will override ones defined -- in the preset. --- @tparam[opt] int args.replaces_id Replace the notification with the given ID. --- @tparam[opt] func args.callback Function that will be called with all arguments. +-- @tparam[opt] integer args.replaces_id Replace the notification with the given ID. +-- @tparam[opt] function args.callback Function that will be called with all arguments. -- The notification will only be displayed if the function returns true. -- Note: this function is only relevant to notifications sent via dbus. -- @tparam[opt] table args.actions A list of `naughty.action`s. diff --git a/tests/examples/sequences/tag/clear.lua b/tests/examples/sequences/tag/clear.lua index 586f5da6b..2161176ad 100644 --- a/tests/examples/sequences/tag/clear.lua +++ b/tests/examples/sequences/tag/clear.lua @@ -43,7 +43,7 @@ module.display_tags() --DOC_HIDE module.add_event("Call `:clear()` on the first tag.", function() --DOC_HIDE -- Call :clear() on the first tag. screen[1].tags[1]:clear{} -end) +end) --DOC_HIDE module.display_tags() --DOC_HIDE From b4c989bcf8bd0780c384e1c1a4864a90899205e6 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 18 Dec 2021 12:05:00 -0800 Subject: [PATCH 048/134] doc: Fix some regression introduced when fixing the shims behavior. Previously, clients were displayed even when they were not tagged or minimized. This was fixed in the shims. However, some examples never created tags, so the client were never tagged, thus no longer displayed. --- tests/examples/awful/mouse/coords.lua | 1 + tests/examples/awful/placement/aero_snap.lua | 4 +++ tests/examples/awful/placement/align.lua | 3 ++ tests/examples/awful/placement/bottom.lua | 1 + .../examples/awful/placement/bottom_left.lua | 1 + .../examples/awful/placement/bottom_right.lua | 1 + .../awful/placement/center_horizontal.lua | 1 + .../awful/placement/center_vertical.lua | 1 + tests/examples/awful/placement/centered.lua | 1 + .../awful/placement/closest_mouse.lua | 1 + tests/examples/awful/placement/compose.lua | 1 + tests/examples/awful/placement/compose2.lua | 1 + tests/examples/awful/placement/left.lua | 1 + tests/examples/awful/placement/maximize.lua | 5 ++++ .../awful/placement/maximize_horizontally.lua | 1 + .../awful/placement/maximize_vertically.lua | 1 + tests/examples/awful/placement/next_to.lua | 2 ++ .../awful/placement/next_to_mouse.lua | 1 + .../examples/awful/placement/no_offscreen.lua | 2 ++ tests/examples/awful/placement/no_overlap.lua | 1 + .../awful/placement/resize_to_mouse.lua | 5 +++- tests/examples/awful/placement/right.lua | 1 + .../skip_fullscreen-no_fullscreen.lua | 2 ++ .../awful/placement/skip_fullscreen.lua | 1 + tests/examples/awful/placement/stretch.lua | 3 ++ .../examples/awful/placement/stretch_down.lua | 1 + .../examples/awful/placement/stretch_left.lua | 1 + .../awful/placement/stretch_right.lua | 1 + tests/examples/awful/placement/stretch_up.lua | 1 + tests/examples/awful/placement/top.lua | 1 + tests/examples/awful/placement/top_left.lua | 1 + tests/examples/awful/placement/top_right.lua | 1 + .../examples/awful/placement/under_mouse.lua | 1 + tests/examples/awful/titlebar/constructor.lua | 12 ++++++-- tests/examples/awful/titlebar/default.lua | 30 ++++++++++++------- 35 files changed, 79 insertions(+), 14 deletions(-) diff --git a/tests/examples/awful/mouse/coords.lua b/tests/examples/awful/mouse/coords.lua index 7b2ed7074..7f68e4222 100644 --- a/tests/examples/awful/mouse/coords.lua +++ b/tests/examples/awful/mouse/coords.lua @@ -1,4 +1,5 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x = 175, width = 128, height = 96} --DOC_HIDE mouse.coords {x=175+60,y=60} --DOC_HIDE diff --git a/tests/examples/awful/placement/aero_snap.lua b/tests/examples/awful/placement/aero_snap.lua index 6ab50a1a0..ec191f3ae 100644 --- a/tests/examples/awful/placement/aero_snap.lua +++ b/tests/examples/awful/placement/aero_snap.lua @@ -5,6 +5,10 @@ screen[1]._resize {width = 180, height = 120} --DOC_HIDE screen._add_screen {x = 190, y = 0, width = 180, height = 120} --DOC_HIDE screen._add_screen {x = 380, y = 0, width = 180, height = 120} --DOC_HIDE +for s in screen do + require("awful.tag").add("1", {screen=s, selected=true}) --DOC_HIDE +end + for _, pos in ipairs{"left", "right"} do local c1 = client.gen_fake {x = 80, y = 55, width=78, height=50} placement.align(client.focus, {position = pos, honor_workarea=true}) diff --git a/tests/examples/awful/placement/align.lua b/tests/examples/awful/placement/align.lua index 69e6b9cd6..ea0c3fda5 100644 --- a/tests/examples/awful/placement/align.lua +++ b/tests/examples/awful/placement/align.lua @@ -1,6 +1,7 @@ --DOC_HIDE_ALL --DOC_GEN_IMAGE local placement = require("awful.placement") +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x= 50} for _, pos in ipairs{ "top_left", "top_right", "bottom_left", "bottom_right", @@ -14,6 +15,8 @@ end screen._add_screen {x = 70, y = 260 , width = 128, height = 96} screen._add_screen {x = 210, y = 260 , width = 128, height = 96} +require("awful.tag").add("1", {screen=screen[2], selected=true}) --DOC_HIDE +require("awful.tag").add("1", {screen=screen[3], selected=true}) --DOC_HIDE local c diff --git a/tests/examples/awful/placement/bottom.lua b/tests/examples/awful/placement/bottom.lua index c70ee710e..da7715da5 100644 --- a/tests/examples/awful/placement/bottom.lua +++ b/tests/examples/awful/placement/bottom.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.bottom --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/bottom_left.lua b/tests/examples/awful/placement/bottom_left.lua index 125a0e648..a5afb9dab 100644 --- a/tests/examples/awful/placement/bottom_left.lua +++ b/tests/examples/awful/placement/bottom_left.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.bottom_left --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/bottom_right.lua b/tests/examples/awful/placement/bottom_right.lua index b0d450821..5b95f2cef 100644 --- a/tests/examples/awful/placement/bottom_right.lua +++ b/tests/examples/awful/placement/bottom_right.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.bottom_right --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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_horizontal.lua b/tests/examples/awful/placement/center_horizontal.lua index 1ab1eee22..c77f7f009 100644 --- a/tests/examples/awful/placement/center_horizontal.lua +++ b/tests/examples/awful/placement/center_horizontal.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.center_horizontal --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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 a867eab20..0817921df 100644 --- a/tests/examples/awful/placement/center_vertical.lua +++ b/tests/examples/awful/placement/center_vertical.lua @@ -4,6 +4,7 @@ -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @staticfct awful.placement.center_vertical --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/centered.lua b/tests/examples/awful/placement/centered.lua index c7af1052d..08523a424 100644 --- a/tests/examples/awful/placement/centered.lua +++ b/tests/examples/awful/placement/centered.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.centered --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/closest_mouse.lua b/tests/examples/awful/placement/closest_mouse.lua index 815b0568f..b0cd346a7 100644 --- a/tests/examples/awful/placement/closest_mouse.lua +++ b/tests/examples/awful/placement/closest_mouse.lua @@ -1,6 +1,7 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE local c = client.gen_fake {x = 20, y = 20, width= 280, height=200, screen =screen[1]} --DOC_HIDE local bw = c.border_width --DOC_HIDE diff --git a/tests/examples/awful/placement/compose.lua b/tests/examples/awful/placement/compose.lua index 750afb29d..83b4cce01 100644 --- a/tests/examples/awful/placement/compose.lua +++ b/tests/examples/awful/placement/compose.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x = 175, width = 128, height = 96} --DOC_NO_USAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 220, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/compose2.lua b/tests/examples/awful/placement/compose2.lua index b0112684d..820bfafb4 100644 --- a/tests/examples/awful/placement/compose2.lua +++ b/tests/examples/awful/placement/compose2.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x = 175, width = 128, height = 96} --DOC_NO_USAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 220, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/left.lua b/tests/examples/awful/placement/left.lua index 3621383d7..6c9e29dfb 100644 --- a/tests/examples/awful/placement/left.lua +++ b/tests/examples/awful/placement/left.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.left --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/maximize.lua b/tests/examples/awful/placement/maximize.lua index aa40c2bf9..8466b0acd 100644 --- a/tests/examples/awful/placement/maximize.lua +++ b/tests/examples/awful/placement/maximize.lua @@ -2,6 +2,11 @@ screen[1]._resize {width = 128, height = 96} --DOC_HIDE screen._add_screen {x = 140, y = 0, width = 128, height = 96} --DOC_HIDE screen._add_screen {x = 280, y = 0, width = 128, height = 96} --DOC_HIDE + +for s in screen do --DOC_HIDE + require("awful.tag").add("1", {screen=s, selected=true}) --DOC_HIDE +end --DOC_HIDE + local placement = require("awful.placement") --DOC_HIDE for k, pos in ipairs{ --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_horizontally.lua b/tests/examples/awful/placement/maximize_horizontally.lua index de0f85b2a..7fad3db57 100644 --- a/tests/examples/awful/placement/maximize_horizontally.lua +++ b/tests/examples/awful/placement/maximize_horizontally.lua @@ -4,6 +4,7 @@ -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @staticfct awful.placement.maximize_horizontally --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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 d3ef034bd..e5011b56a 100644 --- a/tests/examples/awful/placement/maximize_vertically.lua +++ b/tests/examples/awful/placement/maximize_vertically.lua @@ -4,6 +4,7 @@ -- @tparam[opt={}] table args Other arguments") --DOC_HEADER -- @staticfct awful.placement.maximize_vertically --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/next_to.lua b/tests/examples/awful/placement/next_to.lua index ccaa893e1..833fccecb 100644 --- a/tests/examples/awful/placement/next_to.lua +++ b/tests/examples/awful/placement/next_to.lua @@ -1,5 +1,7 @@ --DOC_GEN_IMAGE --DOC_HIDE local awful = { placement = require("awful.placement") }--DOC_HIDE + +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x= 0, width = 640, height=200} --DOC_HIDE local parent_client = client.gen_fake {x = 0, y = 0, width=350, height=70} --DOC_HIDE diff --git a/tests/examples/awful/placement/next_to_mouse.lua b/tests/examples/awful/placement/next_to_mouse.lua index 2e34e0ade..c7328f302 100644 --- a/tests/examples/awful/placement/next_to_mouse.lua +++ b/tests/examples/awful/placement/next_to_mouse.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE client.gen_fake {x = 10, y = 10, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/no_offscreen.lua b/tests/examples/awful/placement/no_offscreen.lua index 4b4054ef0..95246b3d6 100644 --- a/tests/examples/awful/placement/no_offscreen.lua +++ b/tests/examples/awful/placement/no_offscreen.lua @@ -1,6 +1,8 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE + --DOC_HIDE no_offscreen is auto-called when startup is true, avoid this. awesome.startup = false -- luacheck: globals awesome.startup --DOC_HIDE diff --git a/tests/examples/awful/placement/no_overlap.lua b/tests/examples/awful/placement/no_overlap.lua index d0fe9b1f2..f295202f7 100644 --- a/tests/examples/awful/placement/no_overlap.lua +++ b/tests/examples/awful/placement/no_overlap.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE screen._add_screen {x = 140, y = 0 , width = 128, height = 96} --DOC_HIDE screen._add_screen {x = 0 , y = 110, width = 128, height = 96} --DOC_HIDE diff --git a/tests/examples/awful/placement/resize_to_mouse.lua b/tests/examples/awful/placement/resize_to_mouse.lua index 01cf64166..fb13b06aa 100644 --- a/tests/examples/awful/placement/resize_to_mouse.lua +++ b/tests/examples/awful/placement/resize_to_mouse.lua @@ -2,9 +2,12 @@ --DOC_GEN_IMAGE local awful = {placement = require("awful.placement")} local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1) - screen._setup_grid(64, 48, {4, 4, 4, 4}, {workarea_sides=0}) +for s in screen do + require("awful.tag").add("1", {screen=s, selected=true}) --DOC_HIDE +end + local function test_touch_mouse(c) local coords = mouse.coords() diff --git a/tests/examples/awful/placement/right.lua b/tests/examples/awful/placement/right.lua index b1f63b66a..c6227532c 100644 --- a/tests/examples/awful/placement/right.lua +++ b/tests/examples/awful/placement/right.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.right --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/skip_fullscreen-no_fullscreen.lua b/tests/examples/awful/placement/skip_fullscreen-no_fullscreen.lua index 7207f4600..060cbcf12 100644 --- a/tests/examples/awful/placement/skip_fullscreen-no_fullscreen.lua +++ b/tests/examples/awful/placement/skip_fullscreen-no_fullscreen.lua @@ -1,6 +1,8 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE + --DOC_HIDE no_offscreen is auto-called when startup is true, avoid this. awesome.startup = false -- luacheck: globals awesome.startup --DOC_HIDE diff --git a/tests/examples/awful/placement/skip_fullscreen.lua b/tests/examples/awful/placement/skip_fullscreen.lua index 2e1e749e8..b3d5ee532 100644 --- a/tests/examples/awful/placement/skip_fullscreen.lua +++ b/tests/examples/awful/placement/skip_fullscreen.lua @@ -1,5 +1,6 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE --DOC_HIDE no_offscreen is auto-called when startup is true, avoid this. awesome.startup = false -- luacheck: globals awesome.startup --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch.lua b/tests/examples/awful/placement/stretch.lua index 696981140..cd1024852 100644 --- a/tests/examples/awful/placement/stretch.lua +++ b/tests/examples/awful/placement/stretch.lua @@ -4,6 +4,9 @@ screen[1]._resize {width = 128, height = 96} screen._add_screen {x = 140, y = 0 , width = 128, height = 96} screen._add_screen {x = 0 , y = 110, width = 128, height = 96} screen._add_screen {x = 140, y = 110, width = 128, height = 96} +for s in screen do + require("awful.tag").add("1", {screen=s, selected=true}) +end local placement = require("awful.placement") for k, pos in ipairs{ diff --git a/tests/examples/awful/placement/stretch_down.lua b/tests/examples/awful/placement/stretch_down.lua index e22caf5d8..2c39c7dbd 100644 --- a/tests/examples/awful/placement/stretch_down.lua +++ b/tests/examples/awful/placement/stretch_down.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.stretch_down --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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 db81f765d..e043abe6d 100644 --- a/tests/examples/awful/placement/stretch_left.lua +++ b/tests/examples/awful/placement/stretch_left.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.stretch_left --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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 d217a781d..9fe5ac579 100644 --- a/tests/examples/awful/placement/stretch_right.lua +++ b/tests/examples/awful/placement/stretch_right.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.stretch_right --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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 67a2bea75..d569f6ed7 100644 --- a/tests/examples/awful/placement/stretch_up.lua +++ b/tests/examples/awful/placement/stretch_up.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.stretch_up --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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 60fc17006..756c26162 100644 --- a/tests/examples/awful/placement/top.lua +++ b/tests/examples/awful/placement/top.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.top --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/top_left.lua b/tests/examples/awful/placement/top_left.lua index 339bd9e10..fda50a9dd 100644 --- a/tests/examples/awful/placement/top_left.lua +++ b/tests/examples/awful/placement/top_left.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.top_left --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/top_right.lua b/tests/examples/awful/placement/top_right.lua index 2df7c70a2..7d5b25296 100644 --- a/tests/examples/awful/placement/top_right.lua +++ b/tests/examples/awful/placement/top_right.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.top_right --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE 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/under_mouse.lua b/tests/examples/awful/placement/under_mouse.lua index 13c034047..53efa7cae 100644 --- a/tests/examples/awful/placement/under_mouse.lua +++ b/tests/examples/awful/placement/under_mouse.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE client.gen_fake {x = 10, y = 10, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/titlebar/constructor.lua b/tests/examples/awful/titlebar/constructor.lua index a35f0adbd..687bf97c2 100644 --- a/tests/examples/awful/titlebar/constructor.lua +++ b/tests/examples/awful/titlebar/constructor.lua @@ -5,6 +5,8 @@ local awful = { titlebar = require("awful.titlebar"), local beautiful = require("beautiful") local wibox = require("wibox") +require("awful.tag").add("1", {screen=screen[1], selected = true}) + screen[1]._resize { width = 646, height = 182 } local c @@ -38,27 +40,31 @@ c = clients[1] setup( --DOC_HIDE_END - -- Create default titlebar + -- Create default titlebar. awful.titlebar(c) +--DOC_NEWLINE --DOC_HIDE_START ) + c = clients[2] setup( --DOC_HIDE_END - -- Create titlebar on the client's bottom edge + -- Create titlebar on the client's bottom edge. awful.titlebar(c, { position = "bottom" }) --DOC_HIDE_START ) + c = clients[3] setup( --DOC_HIDE_END +--DOC_NEWLINE - -- Create titlebar with inverted colors + -- Create titlebar with inverted colors. awful.titlebar(c, { bg_normal = beautiful.fg_normal, fg_normal = beautiful.bg_normal }) --DOC_HIDE_START diff --git a/tests/examples/awful/titlebar/default.lua b/tests/examples/awful/titlebar/default.lua index 853d04ae5..1ca78a857 100644 --- a/tests/examples/awful/titlebar/default.lua +++ b/tests/examples/awful/titlebar/default.lua @@ -1,14 +1,19 @@ ---DOC_GEN_IMAGE --DOC_HIDE +--DOC_GEN_IMAGE --DOC_NO_USAGE -local place = require("awful.placement") --DOC_HIDE -local awful = { titlebar = require("awful.titlebar"), --DOC_HIDE - button = require("awful.button"), --DOC_HIDE - } --DOC_HIDE -local wibox = require("wibox") --DOC_HIDE -local gears = {table = require("gears.table")} --DOC_HIDE +--DOC_HIDE_START +local place = require("awful.placement") +local awful = { titlebar = require("awful.titlebar"), + button = require("awful.button"), + tag = require("awful.tag"), + } +local wibox = require("wibox") +local gears = {table = require("gears.table")} -local c = client.gen_fake {hide_first=true} --DOC_HIDE -place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE +awful.tag.add("1", {screen=screen[1], selected = true}) + +local c = client.gen_fake {hide_first=true} +place.maximize(c, {honor_padding=true, honor_workarea=true}) +--DOC_HIDE_END -- Create a titlebar for the client. -- By default, `ruled.client` will create one, but all it does is to call this @@ -19,6 +24,8 @@ place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE bg_normal = "#ff0000", }) + --DOC_NEWLINE + -- buttons for the titlebar local buttons = gears.table.join( awful.button({ }, 1, function() @@ -33,7 +40,9 @@ place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE end) ) - top_titlebar : setup { + --DOC_NEWLINE + + top_titlebar.widget = { { -- Left awful.titlebar.widget.iconwidget(c), buttons = buttons, @@ -59,3 +68,4 @@ place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE } --DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + From 4bd90f0f35d0f93235f0bcf207ca16baa174f8a1 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 20 Dec 2021 21:54:15 -0800 Subject: [PATCH 049/134] doc: Add documentation linting and fix all issues it found. --- dbus.c | 17 +- docs/05-awesomerc.md.lua | 2 + docs/common/client_theme.ldoc | 66 +- docs/common/notification_rules_index.ldoc | 1 + docs/common/wibox.ldoc | 71 +- docs/common/widget.ldoc | 20 +- docs/config.ld | 759 ++++++++++++++++++++-- docs/ldoc.css | 4 +- docs/ldoc.ltp | 19 +- lib/awful/button.lua | 13 +- lib/awful/client.lua | 24 +- lib/awful/completion.lua | 16 +- lib/awful/hotkeys_popup/init.lua | 2 +- lib/awful/hotkeys_popup/widget.lua | 23 +- lib/awful/key.lua | 12 +- lib/awful/keygrabber.lua | 18 +- lib/awful/layout/init.lua | 26 +- lib/awful/layout/suit/corner.lua | 4 + lib/awful/layout/suit/fair.lua | 2 + lib/awful/layout/suit/floating.lua | 1 + lib/awful/layout/suit/magnifier.lua | 1 + lib/awful/layout/suit/max.lua | 2 + lib/awful/layout/suit/spiral.lua | 2 + lib/awful/layout/suit/tile.lua | 4 + lib/awful/menu.lua | 52 +- lib/awful/mouse/client.lua | 4 +- lib/awful/mouse/init.lua | 14 +- lib/awful/mouse/resize.lua | 10 +- lib/awful/mouse/snap.lua | 4 + lib/awful/permissions/init.lua | 29 +- lib/awful/prompt.lua | 18 +- lib/awful/screen.lua | 10 +- lib/awful/spawn.lua | 2 +- lib/awful/tag.lua | 30 +- lib/awful/titlebar.lua | 341 +++++++--- lib/awful/tooltip.lua | 44 +- lib/awful/util.lua | 51 +- lib/awful/wallpaper.lua | 2 + lib/awful/wibar.lua | 13 + lib/awful/widget/button.lua | 2 +- lib/awful/widget/calendar_popup.lua | 3 +- lib/awful/widget/clienticon.lua | 2 +- lib/awful/widget/common.lua | 6 + lib/awful/widget/keyboardlayout.lua | 7 +- lib/awful/widget/layoutlist.lua | 53 +- lib/awful/widget/only_on_screen.lua | 2 +- lib/awful/widget/prompt.lua | 12 +- lib/awful/widget/taglist.lua | 71 +- lib/awful/widget/tasklist.lua | 89 +-- lib/awful/widget/watch.lua | 33 +- lib/beautiful/init.lua | 48 +- lib/gears/debug.lua | 4 +- lib/gears/filesystem.lua | 5 +- lib/gears/math.lua | 2 + lib/gears/protected_call.lua | 5 + lib/gears/shape.lua | 6 +- lib/gears/sort/init.lua | 2 +- lib/gears/string.lua | 6 +- lib/gears/surface.lua | 9 +- lib/gears/table.lua | 4 +- lib/gears/timer.lua | 17 +- lib/menubar/icon_theme.lua | 1 + lib/menubar/init.lua | 7 + lib/menubar/utils.lua | 4 +- lib/naughty/action.lua | 6 +- lib/naughty/container/background.lua | 3 +- lib/naughty/init.lua | 2 + lib/naughty/layout/box.lua | 2 +- lib/naughty/layout/legacy.lua | 2 +- lib/naughty/notification.lua | 64 +- lib/naughty/widget/icon.lua | 10 +- lib/naughty/widget/message.lua | 3 +- lib/naughty/widget/title.lua | 3 +- lib/ruled/client.lua | 2 +- lib/ruled/notification.lua | 2 +- lib/wibox/container/arcchart.lua | 29 +- lib/wibox/container/background.lua | 8 +- lib/wibox/container/margin.lua | 18 +- lib/wibox/container/radialprogressbar.lua | 2 +- lib/wibox/container/rotate.lua | 2 +- lib/wibox/container/tile.lua | 16 +- lib/wibox/drawable.lua | 2 +- lib/wibox/init.lua | 2 + lib/wibox/layout/align.lua | 2 +- lib/wibox/layout/fixed.lua | 2 + lib/wibox/layout/flex.lua | 5 +- lib/wibox/layout/grid.lua | 40 +- lib/wibox/layout/stack.lua | 6 +- lib/wibox/widget/background.lua | 2 +- lib/wibox/widget/base.lua | 20 +- lib/wibox/widget/calendar.lua | 31 +- lib/wibox/widget/checkbox.lua | 4 +- lib/wibox/widget/graph.lua | 4 +- lib/wibox/widget/imagebox.lua | 2 +- lib/wibox/widget/init.lua | 2 + lib/wibox/widget/piechart.lua | 2 +- lib/wibox/widget/progressbar.lua | 32 +- lib/wibox/widget/separator.lua | 11 +- lib/wibox/widget/slider.lua | 30 +- lib/wibox/widget/systray.lua | 24 +- lib/wibox/widget/textbox.lua | 13 +- lib/wibox/widget/textclock.lua | 2 +- luaa.c | 2 +- mouse.c | 2 +- mousegrabber.c | 2 +- objects/client.c | 27 +- objects/drawable.c | 7 +- objects/screen.c | 11 +- objects/tag.c | 2 +- root.c | 15 +- xkb.c | 2 +- 111 files changed, 1891 insertions(+), 724 deletions(-) diff --git a/dbus.c b/dbus.c index f339fcddc..97069858c 100644 --- a/dbus.c +++ b/dbus.c @@ -19,7 +19,14 @@ * */ -/** awesome D-Bus API +/** A deprecated low-level D-Bus API **DO NOT USE**. + * + * `lgi.GDBus` is always better. This module will eventually be removed. + * If it ever breaks due to an upstream API change, it wont be fixed. + * + * It still exists for compatibility reasons since some user have used it + * in the past. + * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @module dbus @@ -798,10 +805,10 @@ luaA_dbus_disconnect_signal(lua_State *L) * @param path A string with the dbus path. * @param interface A string with the dbus interface. * @param method A string with the dbus method name. - * @param type_1st_arg type of 1st argument - * @param value_1st_arg value of 1st argument - * @param type_2nd_arg type of 2nd argument - * @param value_2nd_arg value of 2nd argument + * @param type_1st_arg Type of 1st argument + * @param value_1st_arg Value of 1st argument + * @param type_2nd_arg Type of 2nd argument + * @param value_2nd_arg Value of 2nd argument * ... etc * @function emit_signal */ diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index 50965a470..d49fee9cb 100644 --- a/docs/05-awesomerc.md.lua +++ b/docs/05-awesomerc.md.lua @@ -324,6 +324,8 @@ rc_lua:close() table.insert(output_script, "-- @script rc.lua") +table.insert(output_script, "-- @usebeautiful beautiful.awesome_icon") +table.insert(output_script, "-- @usebeautiful beautiful.wallpaper") rc_script = assert(io.open(rc_script, "w")) rc_script:write(table.concat(output_script, "\n")) diff --git a/docs/common/client_theme.ldoc b/docs/common/client_theme.ldoc index 672b41b37..f62085619 100644 --- a/docs/common/client_theme.ldoc +++ b/docs/common/client_theme.ldoc @@ -344,6 +344,21 @@ * @see request::border */ +/** + * The client border width for the fullscreen clients. + * + * This is the fallback if the more stateful version, like + * `beautiful.border_width_fullscreen_urgent` isn't set. + * + * @beautiful beautiful.border_width_fullscreen + * @param integer + * @see request::border + * @see beautiful.border_width_fullscreen_active + * @see beautiful.border_width_fullscreen_normal + * @see beautiful.border_width_fullscreen_urgent + * @see beautiful.border_width_fullscreen_new + */ + /** * The client opacity for the normal clients. * @@ -391,7 +406,6 @@ * * @beautiful beautiful.opacity_floating_normal * @param[opt=1] number - * @see request::border */ /** @@ -424,6 +438,21 @@ * @see request::border */ +/** + * The client opacity for the floating clients. + * + * A number between 0 and 1. This is the fallback if the more stateful + * variables, like `beautiful.opacity_floating_new` are not set. + * + * @beautiful beautiful.opacity_floating + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_floating_normal + * @see beautiful.opacity_floating_active + * @see beautiful.opacity_floating_urgent + * @see beautiful.opacity_floating_new + */ + /** * The client opacity for the normal maximized clients. * @@ -431,7 +460,6 @@ * * @beautiful beautiful.opacity_maximized_normal * @param[opt=1] number - * @see request::border */ /** @@ -463,6 +491,22 @@ * @param[opt=1] number * @see request::border */ + +/** + * The client opacity for the maximized clients. + * + * A number between 0 and 1. This is the fallback if a more stateful + * variable, like `beautiful.opacity_maximized_urgent`, isn't set. + * + * @beautiful beautiful.opacity_maximized + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_maximized_normal + * @see beautiful.opacity_maximized_active + * @see beautiful.opacity_maximized_urgent + * @see beautiful.opacity_maximized_new + */ + /** * The client opacity for the normal fullscreen clients. * @@ -470,7 +514,6 @@ * * @beautiful beautiful.opacity_fullscreen_normal * @param[opt=1] number - * @see request::border */ /** @@ -503,4 +546,21 @@ * @see request::border */ +/** + * The client opacity for the fullscreen clients. + * + * A number between 0 and 1. This is the fallback if the variables + * for more stateful versions, like `beautiful.opacity_fullscreen_urgent`, + * are not set. + * + * @beautiful beautiful.opacity_fullscreen + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_fullscreen_new + * @see beautiful.opacity_fullscreen_urgent + * @see beautiful.opacity_fullscreen_active + * @see beautiful.opacity_fullscreen_normal + */ + + /* diff --git a/docs/common/notification_rules_index.ldoc b/docs/common/notification_rules_index.ldoc index 35fc30f79..1387c2fdb 100644 --- a/docs/common/notification_rules_index.ldoc +++ b/docs/common/notification_rules_index.ldoc @@ -37,6 +37,7 @@ -- auto\_reset\_timeoutIf the timeout needs to be reset when a property changes -- ignore\_suspend -- clientsA list of clients associated with this notification +-- max\_widthThe maximum popup width -- app\_nameThe application name specified by the notification -- widget\_templateThe widget template used to represent the notification -- diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc index dc46c6ea8..b12440524 100644 --- a/docs/common/wibox.ldoc +++ b/docs/common/wibox.ldoc @@ -2,7 +2,7 @@ -- -- @baseclass wibox -- @property border_width --- @param integer +-- @tparam[opt=0] integer border_width -- @propemits false false --- Border color. @@ -25,21 +25,21 @@ -- -- @baseclass wibox -- @property border_color --- @param string +-- @tparam[opt=beautiful.fg_normal] string border_color -- @propemits false false --- On top of other windows. -- -- @baseclass wibox -- @property ontop --- @param boolean +-- @tparam[opt=false] boolean ontop -- @propemits false false --- The mouse cursor. -- -- @baseclass wibox -- @property cursor --- @param string +-- @tparam string cursor -- @see mouse -- @propemits false false @@ -47,7 +47,7 @@ -- -- @baseclass wibox -- @property visible --- @param boolean +-- @tparam boolean visible -- @propemits false false --- The opacity of the wibox, between 0 and 1. @@ -61,7 +61,7 @@ -- -- @baseclass wibox -- @property type --- @param string +-- @tparam string type -- @see client.type -- @propemits false false @@ -69,35 +69,35 @@ -- -- @baseclass wibox -- @property x --- @param integer +-- @tparam integer x -- @propemits false false --- The y coordinates. -- -- @baseclass wibox -- @property y --- @param integer +-- @tparam integer y -- @propemits false false --- The width of the wibox. -- -- @baseclass wibox -- @property width --- @param width +-- @tparam integer width -- @propemits false false --- The height of the wibox. -- -- @baseclass wibox -- @property height --- @param height +-- @tparam integer height -- @propemits false false --- The wibox screen. -- -- @baseclass wibox -- @property screen --- @param screen +-- @tparam screen screen -- @propemits true false --- The wibox's `drawable`. @@ -110,14 +110,14 @@ --- The widget that the `wibox` displays. -- @baseclass wibox -- @property widget --- @param widget +-- @tparam[opt=nil] wibox.widget widget -- @propemits true false --- The X window id. -- -- @baseclass wibox -- @property window --- @param string +-- @tparam string window -- @see client.window -- @propemits false false @@ -129,7 +129,7 @@ -- -- @baseclass wibox -- @property shape_bounding --- @param surface._native +-- @tparam surface._native shape_bounding -- @propemits false false -- @see shape @@ -140,7 +140,7 @@ -- -- @baseclass wibox -- @property shape_clip --- @param surface._native +-- @tparam surface._native shape_clip -- @propemits false false -- @see shape @@ -152,7 +152,7 @@ -- -- @baseclass wibox -- @property shape_input --- @param surface._native +-- @tparam surface._native shape_input -- @propemits false false -- @see input_passthrough @@ -174,7 +174,7 @@ -- -- @baseclass wibox -- @property input_passthrough --- @param[opt=false] boolean +-- @tparam[opt=false] boolean input_passthrough -- @see shape_input -- @propemits true false @@ -182,14 +182,15 @@ -- -- @baseclass wibox -- @property buttons --- @param buttons_table A table of buttons objects, or nothing. +-- @tparam table buttons A table of buttons objects, or nothing. -- @propemits false false --- Get or set wibox geometry. That's the same as accessing or setting the x, -- y, width or height properties of a wibox. -- -- @baseclass wibox --- @param A table with coordinates to modify. +-- @tparam[opt=nil] table|nil geo A table with coordinates to modify. If +-- nothing is specified, it only returns the current geometry. -- @return A table with wibox coordinates and geometry. -- @method geometry -- @emits property::geometry When the geometry change. @@ -205,31 +206,12 @@ -- the side of the screen). -- -- @baseclass wibox --- @param strut A table with new strut, or nothing -- @return The wibox strut in a table. -- @method struts +-- @tparam table struts A table with new strut, or nothing. -- @see client.struts -- @emits property::struts ---- The default background color. --- --- The background color can be transparent. If there is a --- compositing manager such as compton, then it will be --- real transparency and may include blur (provided by the --- compositor). When there is no compositor, it will take --- a picture of the wallpaper and blend it. --- --- @baseclass wibox --- @beautiful beautiful.bg_normal --- @param color --- @see bg - ---- The default foreground (text) color. --- @baseclass wibox --- @beautiful beautiful.fg_normal --- @param color --- @see fg - --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @param args An array containing the widgets disposition @@ -246,8 +228,8 @@ -- -- @baseclass wibox -- @property bg --- @tparam c The background to use. This must either be a cairo pattern object, --- nil or a string that gears.color() understands. +-- @tparam[opt=beautiful.bg_normal] color bg The background to use. This +-- must either be a cairo pattern object, nil or a string that gears.color() understands. -- @see gears.color -- @propemits true false -- @usebeautiful beautiful.bg_normal The default (fallback) bg color. @@ -257,18 +239,17 @@ -- If `image` is a function, it will be called with `(context, cr, width, height)` -- as arguments. Any other arguments passed to this method will be appended. -- --- @tparam gears.suface|string|function image A background image or a function. -- @baseclass wibox -- @property bgimage +-- @tparam gears.suface|string|function bgimage A background image or a function. -- @see gears.surface -- @propemits true false --- The foreground (text) of the wibox. --- @tparam color c The foreground to use. This must either be a cairo pattern object, --- nil or a string that gears.color() understands. +-- -- @baseclass wibox -- @property fg --- @param color +-- @tparam[opt=beautiful.fg_normal] gears.color fg -- @see gears.color -- @propemits true false -- @usebeautiful beautiful.fg_normal The default (fallback) fg color. diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index 36e994d5f..a08fdc75c 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -19,23 +19,23 @@ -- Warning: This method it prone to stack overflow id the widget, or any of its -- children, contain (directly or indirectly) itself. -- @property all_children --- @tparam table children The children. +-- @tparam table all_children The children. -- @baseclass wibox.widget --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) --- @param args An array containing the widgets disposition +-- @tparam table args An array containing the widgets disposition -- @method setup -- @baseclass wibox.widget --- Force a widget height. -- @property forced_height --- @tparam number|nil height The height (`nil` for automatic) +-- @tparam number|nil forced_height The height (`nil` for automatic) -- @baseclass wibox.widget --- Force a widget width. -- @property forced_width --- @tparam number|nil width The width (`nil` for automatic) +-- @tparam number|nil forced_width The width (`nil` for automatic) -- @baseclass wibox.widget --- The widget opacity (transparency). @@ -45,7 +45,7 @@ --- The widget visibility. -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @baseclass wibox.widget --- The widget buttons. @@ -53,7 +53,7 @@ -- The table contains a list of `awful.button` objects. -- -- @property buttons --- @param table +-- @tparam table buttons -- @see awful.button -- @baseclass wibox.widget @@ -96,7 +96,7 @@ -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -127,7 +127,7 @@ -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -152,7 +152,7 @@ -- @signal mouse::enter -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -177,7 +177,7 @@ -- @signal mouse::leave -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. diff --git a/docs/config.ld b/docs/config.ld index fd12514e9..a92528d74 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -1,24 +1,27 @@ local args = ... +local ldoc = nil +-- luacheck: globals new_type -- Configuration file for ldoc -project='awesome' -title='awesome API documentation' -description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).' +project='awesome' -- luacheck: globals project +title='awesome API documentation' -- luacheck: globals title +description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).' -- luacheck: globals description --- More on it: https://github.com/stevedonovan/LDoc/blob/master/doc/doc.md#markdown-support -format='discount' -dir='../doc' +format='discount' -- luacheck: globals format +dir='../doc' -- luacheck: globals dir -- Make the docs prettier -pretty='lua' -style=true -template=true -backtick_references=true -merge=true -use_markdown_titles=true -wrap=true +pretty='lua' -- luacheck: globals pretty +style=true -- luacheck: globals style +template=true -- luacheck: globals template +backtick_references=true -- luacheck: globals backtick_references +merge=true -- luacheck: globals merge +use_markdown_titles=true -- luacheck: globals use_markdown_titles +wrap=true -- luacheck: globals wrap + + -- luacheck: globals full_description full_description = [[ Welcome to the documentation for the Awesome window manager. Below you find an overview of the individual parts which links to the full documentation. @@ -92,52 +95,327 @@ topics={ '89-NEWS.md', } +local databases, named_tags, item_id, is_init = {}, {}, 1, false +local all_theme_vars, delayed_collect = nil, {} + +local function collect_item_common(tab, mod, item) + tab[item.name] = tab[item.name] or {} + + local var = tab[item.name] + var[mod.name] = var[mod.name] or {} + var[mod.name][#var[mod.name] + 1] = item +end + +--- Add another custom tag **value** to an existing item. +-- @tparam string tag_data The raw/unparsed string for the +-- tag. It will be parsed like any other tags. +local function add_custom_tag_common(item, tag_name, meta_tag, tag_data) + item.tags = item.tags or {} + + item.tags[tag_name] = item.tags[tag_name] or {} + + item.tags[tag_name][#item.tags[tag_name] + 1] = tag_data + + if meta_tag.collect_callback then + delayed_collect[#delayed_collect+1] = {item, item.module, tag_name, tag_data} + end +end + +-- Wrap the global `new_type` to allow us to extend what types can do, the +-- same is done below for custom tags. +local function create_type(args) + new_type(args.name, args.title, args.project_level, args.subfield_title) + + databases[args.name] = databases[args.name] or {} + databases[args.name].collect = args.collect_callback + databases[args.name].finish = args.finish_callback + + return args +end + +-- Add the @usebeautiful from the optional/default value. +local function auto_add_usebeautiful(item) + local vars, var_names = {}, {} + + -- Datamine the default values to autogenerate the @usebeautiful. + for parm in ldoc.modules.iter(item.params) do + for p in ldoc.modules.iter(item:subparam(parm)) do + local def = item:default_of_param(p) + + if def and def ~= true then + for var in def:gmatch("beautiful[.][a-z_]+") do + if not var_names[var] then + vars[#vars+1] = var + end + var_names[var] = true + end + end + end + end + + for _, var in ipairs(vars) do + named_tags.usebeautiful:add_to_item(item, var) + end + end + -- The first stereotype are the constructors. -new_type("constructorfct", "Constructors", false, "Parameters") -new_type("constructorfct2", "ldoc_skip", false, "Parameters") +create_type { + name = "constructorfct", + title = "Constructors", + project_level = false, + subfield_title = "Parameters", + collect_callback = auto_add_usebeautiful, +} + +-- Some constructors like `awful.key` have both a named parameter +-- syntax and a multiple function parameter syntax. +create_type { + name = "constructorfct2", + title = "ldoc_skip", + project_level = false, + subfield_title = "Parameters", +} + -- Hack to get the functions on top of the signals and properties -new_type("function", "Functions", false, "Parameters") +create_type { + name = "function", + title = "Functions", + project_level = false, + subfield_title = "Parameters", +} + -- For "classes", use an explicit type for static functions. This allows -- @function and its implicit cousin to be banned in the CI. -new_type("staticfct", "Static module functions", false, "Parameters") +create_type { + name = "staticfct", + title = "Static module functions", + project_level = false, + subfield_title = "Parameters", +} + -- Documentation for objects properties -new_type("property", "Object properties", false, "Type constraints") +create_type { + name = "property", + title = "Object properties", + project_level = false, + subfield_title = "Type constraints", + collect_callback = auto_add_usebeautiful, + finish_callback = function(item) + -- All properties need to have a type. Otherwise they don't render + -- properly. Also, because typed properties are kind of the point of + -- switching to ldoc in the first place. + if (not item.params) or not item.params[1] then + print( + "WARNING: The ".. item.name .." property from "..item.module.name.." is missing it's type." + ) + return + end + + local param = item:subparam(item.params[1]) + local type = item:type_of_param(param[1]) + + -- Force people to use @tparam because it is easier to lint and allows + -- multiple types. + if (not type) or type == "" then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.." either ".. + " doesn't have a type or uses @param instead of @tparam. @tparam is required".. + " because it allows multi-type and better default value handling." + ) + end + + -- One of the repeated problem we have is the first word of the + -- description being removed because it is used as the property name. + -- This "rule" might be stupid, but it prevents it from accidentally + -- happening again. + if item.params[1] ~= item.name:match("[.]?("..item.params[1]..")$") then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.." @tparam name".. + " doesn't match the property name. For linting purpose, please fix this." + ) + end + end +} + -- Documentation for objects deprecated properties -new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints") +create_type { + name = "deprecatedproperty", + title = "Deprecated object properties", + project_level = false, + subfield_title = "Type constraints", +} + -- Documentation for objects deprecated methods -new_type("deprecatedmethod", "Deprecated object methods", false, "Parameters") +create_type { + name = "deprecatedmethod", + title = "Deprecated object methods", + project_level = false, + subfield_title = "Parameters", +} + -- Use a custom type for the methods to bypass the faulty ldoc built-in detection. -- (yes, the space after Methods *is* on purpose to avoid clashing with ldoc -- internal "methods" concept) -new_type("method", "Object methods ", false, "Parameters") --- New type for signals -new_type("signal", "Signals", false, "Arguments") +create_type { + name = "method", + title = "Object methods ", + project_level = false, + subfield_title = "Parameters", +} + +-- New type for signals. +local all_signals +all_signals = create_type { + name = "signal", + title = "Signals", + project_level = false, + subfield_title = "Arguments", + collection = {}, + collect_callback = function(item, mod) + collect_item_common(all_signals.collection, mod, item) + end, +} + -- Deprecated signals. -new_type("deprecatedsignal", "Deprecated signals", false, "Arguments") +create_type { + name = "deprecatedsignal", + title = "Deprecated signals", + project_level = false, + subfield_title = "Arguments", +} + -- New type for signals connections -new_type("signalhandler", "Request handlers", false, "Arguments") +create_type { + name = "signalhandler", + title = "Request handlers", + project_level = false, + subfield_title = "Arguments", +} + -- Allow objects to define a set of beautiful properties affecting them -new_type("beautiful", "Theme variables", false, "Type constraints") +all_theme_vars = create_type { + name = "beautiful", + title = "Theme variables", + project_level = false, + subfield_title = "Type constraints", + collection = {}, + collect_callback = function(item, mod) + if item.name:sub(1,4) ~= "beau" then + -- This would be a bug. + if item.name:match("[.]") then + print("WANRING: A beautiful variable is called `", item.name, "`. This name is invalid.") + end + + -- This happens because the `ldoc` messes with the name. All variables + if item.module.name == "beautiful" then + item.name = "beautiful." .. item.name + else + print( + "WARNING: All theme variable need a `beautiful.` prefix. It appears", + item.name, + " lacks it" + ) + end + end + + collect_item_common(all_theme_vars.collection, mod, item) + + -- Those are global variables, there can be only one per name. + if all_theme_vars.collection[item.name] then + local mod = pairs(all_theme_vars.collection[item.name])(all_theme_vars.collection[item.name]) + + if mod ~= item.module.name then + print("ERROR: "..item.name, "from", item.module.name, "is already defined in module ", mod) + end + end + end, + finish_callback = function(item) + if item.tags["beautiful_used_by"] then return end + + -- Every variable should be consumed by something. Better "park" some + -- variable in the constructors than leave them disconnected from the + -- global model. + print("WARNING: ", item.name, "is not used by anything, add @usebeautiful or @propbeautiful") + end +} + -- Put deprecated methods in their own section -new_type("deprecated", "Deprecated functions", false, "Parameters") +create_type { + name = "deprecated", + title = "Deprecated functions", + project_level = false, + subfield_title = "Parameters", +} + -- For the legacy stateless layout related functions -new_type("legacylayout", "Layout related functions", false, "Parameters") +create_type { + name = "legacylayout", + title = "Layout related functions", + project_level = false, + subfield_title = "Parameters", +} + -- Have a category for the client layouts -new_type("clientlayout", "Client layouts", false, "Parameters") +create_type { + name = "clientlayout", + title = "Client layouts", + project_level = false, + subfield_title = "Parameters", +} + -- Source functions for the taglist/tasklist/layoutlist -new_type("sourcefunction", "List source functions", false) +create_type { + name = "sourcefunction", + title = "List source functions", + project_level = false, +} + -- Document some callback prototypes -new_type("callback", "Callback functions prototype", false, "Parameters") +create_type { + name = "callback", + title = "Callback functions prototype", + project_level = false, + subfield_title = "Parameters", +} + -- gears.matcher / awful.rules sources -new_type("rulesources", "Rule sources", false, "Parameters") +create_type { + name = "rulesources", + title = "Rule sources", + project_level = false, + subfield_title = "Parameters", +} + -- gears.matcher / awful.rules rule components -new_type("rulecomponent", "Rule components", false, "Type") +create_type { + name = "rulecomponent", + title = "Rule components", + project_level = false, + subfield_title = "Type", +} + -- Filter functions for the taglist/tasklist/layoutlist -new_type("filterfunction", "List filters", false) +create_type { + name = "filterfunction", + title = "List filters", + project_level = false, +} + -- Extra client properties available only in awful.rules/spawn constructs -new_type("clientruleproperty", "Extra properties available in the rules", false, "Type") +create_type { + name = "clientruleproperty", + title = "Extra properties available in the rules", + project_level = false, + subfield_title = "Type", +} + -- Extra *matching* properties for rules. -new_type("matchingproperty", "Extra matching properties used in rules", false, "Type") +create_type { + name = "matchingproperty", + title = "Extra matching properties used in rules", + project_level = false, + subfield_title = "Type", +} -- Simulate the default "params" parser format, except the optional "[]" section -- needs a space. @@ -224,16 +502,18 @@ local function default_format_callback(self, params, _, md) end -- Generate a format function. -local function default_format(self, callback) +local function default_format(self, callback, name) return function(raw, item, md) - return (callback or default_format_callback)( - self, parse_custom_tags(raw, self.params or {}), item, md - ) + local p = name and item.parsed_tags and item.parsed_tags[name] and item.parsed_tags[name][raw] + + if not p then + p = parse_custom_tags(raw, self.params or {}) + end + + return (callback or default_format_callback)(self, p, item, md) end end -local named_tags, item_id = {}, 1 - -- Add a new @something which can be used in any types. -- @tparam table args -- @tparam string args.name The name. @@ -250,9 +530,26 @@ add_custom_tag = function(args) custom_tags = custom_tags or {} + databases[name] = databases[name] or {} + databases[name].collect = args.collect_callback + local f = args.format - args.format = default_format(args, f) + args.format = default_format(args, f, name) + + function args:add_to_item(item, tag_value) + add_custom_tag_common(item, name, args, tag_value) + + local parsed = parse_custom_tags(tag_value, args.params or {}) + + if parsed then + item.parsed_tags = item.parsed_tags or {} + item.parsed_tags[name] = item.parsed_tags[name] or {} + item.parsed_tags[name][tag_value] = parsed + end + + item.has_show_more = item.has_show_more or (not args.hidden) + end custom_tags[#custom_tags+1] = args named_tags[name] = args @@ -288,7 +585,17 @@ add_custom_tag { { name = "name" } - } + }, + collect_callback = function(item, mod, tag, value) + local parsed = parse_custom_tags(value, named_tags.emits.params) + + all_signals.collection[parsed.name.value] = all_signals.collection[parsed.name.value] or {} + + local var = all_signals.collection[parsed.name.value] + + var[mod.name] = var[mod.name] or {} + var[mod.name][#var[mod.name] + 1] = item + end } -- Avoid repetitive boilerplate code for property signals. @@ -349,7 +656,25 @@ add_custom_tag { name = "name", markdown = true, } - } + }, + collect_callback = function(item, mod, tag, value) + local params = parse_custom_tags(value, named_tags.usebeautiful.params) + + if all_theme_vars.collection[params.name.value] then + local sig_mods = all_theme_vars.collection[params.name.value] + local _, themed_items = pairs(sig_mods)(sig_mods) + local themed_item = themed_items[1] + + named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary) + + -- Auto fill the description if its empty. + if (not params.description) or params.description == "" then + params.description = themed_item.summary + end + else + print("WARNING: Could not find theme variable", params.name.value) + end + end } -- For all properties which have a standard `@beautiful` variable for them @@ -380,6 +705,18 @@ add_custom_tag { end return ret + end, + finish_callback = function(item, raw, params, modules) + local modname = item.module.name:gmatch("[^.]+$")() + local name = "beautiful."..(modname.."_"..item.name):gsub("[.]", "_") + + if all_theme_vars.collection[name] then + local sig_mods = all_theme_vars.collection[name] + local _, themed_items = pairs(sig_mods)(sig_mods) + local themed_item = themed_items[1] + + named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary) + end end } @@ -476,7 +813,6 @@ add_custom_tag { add_custom_tag { name = "hidden", hidden = true, - auto_subtags = false } -- Mark the item as readonly. @@ -487,6 +823,87 @@ add_custom_tag { hidden = true, auto_subtags = false } + +add_custom_tag { + name = "signalhandler", + hidden = false, + title = "Request handler", + auto_subtags = false, + params = { + { name = "source" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description + end +} + +add_custom_tag { + name = "beautiful_used_by", + hidden = false, + title = "Used by", + auto_subtags = false, + params = { + { name = "source" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description + end +} + +-- Auto generate some code for replacing request handlers. +add_custom_tag { + name = "sourcesignal", + title = "Source signal", + hidden = false, + params = { + { name = "class" }, + { name = "signal" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.signal.value.."` from the `"..params.class.value.."` module.").. + " This code allows to disconnect this handler and implement your own:" + end, + finish_callback = function(item, raw, params, modules) + if all_signals.collection[params.signal.value] then + local sig_mods = all_signals.collection[params.signal.value] + local _, signal_items = pairs(sig_mods)(sig_mods) + local signal_item = signal_items[1] + + -- Auto generate some code. + local code = "-- Disconnect the original handler.\n" + code = code .. signal_item.module.name .. ".disconnect_signal('".. params.signal.value .."', "..item.name..")\n\n" + code = code .. "-- Connect a custom handler.\n" + code = code .. signal_item.module.name .. ".connect_signal('".. params.signal.value .."', function(" + + + if signal_item.type == "signal" then + for idx, parm in ipairs(signal_item.params) do + code = code .. parm .. (idx == #signal_item.params and "" or ", ") + end + + code = code .. ")\n -- code here\nend)" + + named_tags.signalhandler:add_to_item(signal_item, item.name.." "..item.summary) + end + + item.tag_extra_data = item.tag_extra_data or {} + item.tag_extra_data["sourcesignal"] = item.tag_extra_data["sourcesignal"] or {} + item.tag_extra_data["sourcesignal"][raw] = item.tag_extra_data["sourcesignal"][raw] or {} + item.tag_extra_data["sourcesignal"][raw].usage = ldoc.prettify(code) + + item.has_show_more = true + end + end +} + +-- @rangestart +-- @rangeend +-- @minimumvalue +-- @maximumvalue +-- @tenumvalue +-- @increments +-- @tablekey or not? + -- More fitting section names kind_names={topic='Documentation', module='Libraries', script='Sample files'} @@ -514,7 +931,6 @@ file = { '../selection.c', '../spawn.c', '../xkb.c', - '../common/luaobject.c', '../objects/client.c', '../objects/drawable.c', '../objects/screen.c', @@ -573,6 +989,7 @@ file = { '../lib/wibox/layout/rotate.lua', '../lib/wibox/layout/scroll.lua', '../lib/wibox/widget/background.lua', + '../lib/wibox/drawable.lua', } } @@ -585,10 +1002,16 @@ local function wrap_modname(str, item) end local named_args = { - [ "(args)" ] = true, - [ "([args])" ] = true, - [ "([args=nil])" ] = true, - [ "([args={}])" ] = true + [ "(args)" ] = true, + [ "([args])" ] = true, + [ "([args=nil])" ] = true, + [ "([args={}])" ] = true, + [ '(args)' ] = true, +} + +local param_name_whitelist = { + Mod2 = true, + Lock = true, } -- Sections which are hidden by default, but visible when clicked. @@ -607,6 +1030,27 @@ local delimiter_for_tag = { usebeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}}, propbeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}}, request = { "table class='widget_list' border=1", "table", "tr", "tr", {"Class", "Permission", "Context", "Default", "Description"}}, + sourcesignal = { "div", "div", "span", "span" } +} + +--- If the title is short and descritive, there is no point to bloat it. +-- +-- That test is mostly to catch empty or lazy description (such as the module +-- name and nothing else). +local short_title_whitelist = { + [ "rc.lua" ] = true, + [ "naughty.action" ] = true, + [ "naughty.layout.box" ] = true, + [ "naughty.widget.title" ] = true, + [ "theme.lua" ] = true, + [ "wibox.container.margin" ] = true, + [ "wibox.container.arcchart"] = true, + [ "wibox.widget.checkbox" ] = true, + [ "wibox.widget.imagebox" ] = true, + [ "wibox.widget.separator" ] = true, + [ "wibox.widget.progressbar"] = true, + [ "naughty" ] = true, + [ "xproperties" ] = true, } -- Use the first word of the subtag content to map it to its tag. @@ -636,7 +1080,7 @@ local function generate_summary(item) end end - local ret, has_show_more = {}, false + local ret, has_show_more = {}, item.has_show_more or false for k, v in ipairs(tgs) do if v.count > 0 then @@ -719,20 +1163,26 @@ local function init_custom_types(item) -- Allow the template to fetch the right sub-tags. function item.get_auto_params(tag, value) + local extra = (item.tag_extra_data and item.tag_extra_data[tag] and item.tag_extra_data[tag][value]) or {} + -- Makes auto-generated subtags easier to implement. if item.auto_params[tag.."tparam_override"] then - return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"] + return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"], extra end - if not item.auto_params[tag.."tparam"] then return nil, nil end + local parsed = nil - local parsed = parse_custom_tags(value, named_tags[tag].params) + if item.parsed_tags and item.parsed_tags[tag] and item.parsed_tags[tag][value] then + parsed = item.parsed_tags[tag][value] + end + + if not item.auto_params[tag.."tparam"] then return nil, nil, extra end if parsed.name and item.auto_params[tag.."tparam"][parsed.name.value] then - return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"] + return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"], extra end - return nil, nil + return nil, nil, extra end item.is_init = true @@ -780,8 +1230,7 @@ local function pipe_to_or(s) end -- Parse the magic parameters to type in something the template eats. -local function sanitize_type(item, ldoc) - +local function sanitize_type(item) for parm in ldoc.modules.iter(item.params) do local t = item:type_of_param(parm) @@ -810,9 +1259,37 @@ local function sanitize_type(item, ldoc) item.display_type = "N/A" end +-- Detect error prone markdown formatting. +local function detect_markdown_footguns(string) + for line in string:gmatch("[^\n]*") do + if line:sub(1,4) ~= " " then + local is_tick = false + + -- Detect unquoted code with 2 underscores. They will render as italic, + -- which is definitively not wanted. Add "`" to fix. + for part in line:gmatch("[^`]*") do + if not is_tick then + local count = 0 + + for under in part:gmatch("[^\\]_") do + count = count + 1 + end + + if count > 1 then + return false + end + end + + is_tick = not is_tick + end + end + end + + return true +end -- Add parentheses when there is alternative return types. -local function generate_return_tuple(item, group, ldoc) +local function generate_return_tuple(item, group) local tuple = {} for r in group:iter() do @@ -843,7 +1320,7 @@ local function generate_return_tuple(item, group, ldoc) end -- Create a return type string. -local function sanitize_return_type(item, ldoc) +local function sanitize_return_type(item) local groups = item.retgroups @@ -870,6 +1347,164 @@ local function sanitize_return_type(item, ldoc) item.compact_signature = true end +-- Traverse the entire doc and reverse-map the links between our custom +-- tags and the content it is pointing toward. From that, we add some +-- "consumers"/"providers" tables to each (relevant) item. +local function global_init(_ldoc) + ldoc = _ldoc + + if is_init then return end + is_init = true + + local module_by_name = {} + + -- First pass, gather the providers. + for _, mod in ipairs(ldoc.modules) do + module_by_name[mod.name] = mod + + if mod.type ~= "topic" and ((not mod.summary) or mod.summary == "" or mod.summary:lower():sub(1,8) == "awesome") then + print("WARNING: Each module needs a good summary as its first line", mod.name, "doesn't") + end + + local sum_count = 0 + + for line in (mod.summary or ""):gmatch("[^\n]*") do + sum_count = sum_count + 1 + end + + if sum_count > 1 and #mod.summary > 120 then + print("WARNING:", mod.name, "summary has to be only 1 line.") + end + + if mod.summary and #mod.summary < 30 and not short_title_whitelist[mod.name] then + print("WARNING:", mod.name, "summary is too short.") + end + + for tag, values in pairs(mod.tags) do + for _, value in ipairs(values.gmatch and {values} or values) do + -- Collect instances of some types. + if databases[tag] and databases[tag].collect then + delayed_collect[#delayed_collect+1] = {mod, mod, tag, value} + end + end + end + + for kind, items in mod.kinds() do + for item in items() do + -- Decorate the item with our customizations. + init_custom_types(item) + + -- print(item.description) + + if item.summary and not detect_markdown_footguns(item.summary) then + print( + "WARNING: "..item.name.." from "..item.module.name.." seems to have".. + " ambiguous markdown in its summary, probably underscores. Please either".. + " use '`' or HTML." + ) + end + + -- Collect instances of some types. + if databases[item.type] and databases[item.type].collect then + databases[item.type].collect(item, mod) + end + + for tag, values in pairs(item.tags) do + for _, value in ipairs(values.gmatch and {values} or values) do + -- Collect instances of some types. + if databases[tag] and databases[tag].collect then + delayed_collect[#delayed_collect+1] = {item, mod, tag, value} + end + end + end + + -- Lint the parameters too. + for parm in ldoc.modules.iter(item.params) do + local first = parm:match("^[ ]*(.)") + + -- If the first letter of a parameter is capital, the type is probably missing. + -- That's what happen if you rename @param to @tparam without actually adding the type. + if first and first ~= first:lower() and parm:upper() ~= parm and not param_name_whitelist[parm] then + print( + "ERROR: Parameter "..parm.." from ".. item.name .. " ".. item.module.name.. + " starts with a capital letter. This is forbidden." + ) + end + + for p in ldoc.modules.iter(item:subparam(parm)) do + local desc = item.params.map[p] + + if not detect_markdown_footguns(desc) then + print( + "WARNING: Always use '`' to encapsulate code in the parameters." .. + p .. " from " .. item.name .. " " .. item.module.name .. " contains " .. + "some ambiguous markup. If this is a false positive, use HTML." + ) + end + + -- It *sometime* works, but is at risk if being interpreted as code by markdown. + if desc:match("^ [ ]+") then + print( + "WARNING: ", item.name, "from", item.module.name, "has a parameter description ".. + "with leading spaces. This will not render correctly", "'"..desc.."'" + ) + end + + first = desc:match("^[ ]*([a-z])") + + if first and first ~= first:upper() then + print("WARNING: Sentences starts with a capital letter. Please fix", item.module.name, item.name) + end + + --TODO convert @propbeautiful to @usebeautiful and lint them + --TODO check the module summary. + end + end + end + end + end + + -- Second pass, collect the custom tags. This is delayed because + -- the tags depend on the items. Not all items have been processed if + -- this was called during the first pass. Also, collect callbacks can + -- themselves create more delayed_collect entries recursively. + for _, to_collect in ipairs(delayed_collect) do + databases[to_collect[3]].collect(to_collect[1], to_collect[2], to_collect[3], to_collect[4]) + end + + -- Third pass, parse every custom tags and fill the consumers tables. + for _, mod in ipairs(ldoc.modules) do + for kind, items in mod.kinds() do + for item in items() do + for tag_name, values in pairs(item.tags) do + for _, tag in ipairs(values.gmatch and {values} or values) do + local parsed = named_tags[tag_name] + and named_tags[tag_name].params + and parse_custom_tags(tag, named_tags[tag_name].params) + + -- Allow the tags to, ie, auto-generate some extra content. + if named_tags[tag_name] and named_tags[tag_name].finish_callback then + named_tags[tag_name].finish_callback(item, tag, parsed, module_by_name) + end + + -- Save the parsed content to be used in get_auto_params. + if parsed then + item.parsed_tags = item.parsed_tags or {} + item.parsed_tags[tag_name] = item.parsed_tags[tag_name] or {} + item.parsed_tags[tag_name][tag] = parsed + end + end + end + + -- Mostly for linting. + if databases[item.type] and databases[item.type].finish then + databases[item.type].finish(item, mod, module_by_name) + end + end + end + end +end + -- Work around the fact that tag/awful.tag client/awful.client pages -- are merged. local function compare_module_name(input, module) @@ -956,6 +1591,8 @@ local is_deprecated = { } custom_display_name_handler = function(item, default_handler) + item.global_init = global_init + if is_deprecated[item.type] then item.tags.is_deprecated = {true} end diff --git a/docs/ldoc.css b/docs/ldoc.css index 9451f6f35..4c1397014 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -190,11 +190,11 @@ span.default_value, border-bottom: solid 1px #bcd; } -#content pre { +#content pre, .auto_genenerated_code { margin: 15px; } -pre { +pre, .auto_genenerated_code { background-color: rgb(50, 55, 68); color: white; border-radius: 3px; diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 93497ac32..a054d99cd 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -37,6 +37,15 @@ # local no_underscores = function(s) return s:gsub("_", " ") end # local get_item = function(mod, name) for item in iter(mod.items) do if item.name == name then return item end end; return name == "" and mod or nil end +# -- Poke a hole to allow config.ld code to have a global initialization. +# for m in iter(ldoc.modules) do +# if #m.items > 0 then +# display_name(m.items[1]) +# m.items[1].global_init(ldoc) +# break +# end +# end + # --------- modules hierarchy ------------- # local hierarchy = {} # local curr = module @@ -67,7 +76,7 @@ # local myitems = {} # for item in items() do # myitems[#myitems + 1] = item -# end +# end # all_module_kinds[#all_module_kinds + 1] = { kind = kind, items = myitems } # end # local filtered_kinds = { "Constructors", "Static module functions", @@ -532,7 +541,7 @@ # end -- if group_header then # for value in iter(tag) do <$(row_type_begin)>$(custom.format and custom.format(value, item, M) or M(value)) -# local sub_values, sub_custom = item.get_auto_params(custom[1], value) +# local sub_values, sub_custom, extra_data = item.get_auto_params(custom[1], value) # if sub_values then
          # for _, value in ldoc.ipairs(sub_values) do @@ -540,6 +549,12 @@ # end -- for auto_params
        # end -- if item.auto_params +# if extra_data.usage then +
        +

        + 

        $(extra_data.usage)
        +# end -- extra_data.usage + # end -- for # end -- if tag diff --git a/lib/awful/button.lua b/lib/awful/button.lua index cf3bf1c7d..21c46c7f7 100644 --- a/lib/awful/button.lua +++ b/lib/awful/button.lua @@ -70,38 +70,39 @@ button.names = { -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock). -- -- @property modifiers +-- @tparam table modifiers --- The mouse button identifier. -- -- ![Mouse buttons](../images/mouse.svg) -- -- @property button --- @param integer +-- @tparam integer button --- The button description. -- -- @property description --- @param string +-- @tparam string description --- The button name. -- -- @property name --- @param string +-- @tparam string name --- The button group. -- -- @property group --- @param string +-- @tparam string group --- The callback when this button is pressed. -- -- @property on_press --- @param function +-- @tparam function on_press --- The callback when this button is released. -- -- @property on_release --- @param function +-- @tparam function on_release --- Execute this mousebinding. -- @method :trigger diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 98f41b6bf..28df06d51 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -157,7 +157,7 @@ client.focus = require("awful.client.focus") -- -- @deprecated awful.client.jumpto -- @see client.jump_to --- @tparam client c the client to jump to +-- @tparam client c The client to jump to -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client and its first @@ -1153,7 +1153,7 @@ end -- @DOC_screen_wfact4_EXAMPLE@ -- -- @legacylayout awful.client.idx --- @tparam client c the client +-- @tparam client c The client -- @treturn table data A table with "col", "idx" and "num" keys. -- @treturn integer data.col The column number. -- @treturn integer data.idx Index of the client in the column. @@ -1224,8 +1224,8 @@ end -- @DOC_screen_wfact3_EXAMPLE@ -- -- @legacylayout awful.client.setwfact --- @tparam number wfact the window factor value --- @tparam client c the client +-- @tparam number wfact The window factor value +-- @tparam client c The client -- @emits property::windowfact Emitted on the c.first_tag object. -- @see tag.master_width_factor function client.setwfact(wfact, c) @@ -1291,7 +1291,7 @@ end -- @tparam number add Amount to increase/decrease the client's window factor by. -- Should be between `-current_window_factor` and something close to -- infinite. Normalisation then ensures that the sum of all factors is 1. --- @tparam[opt=client.focus] client c the client. +-- @tparam[opt=client.focus] client c The client. -- @emits property::windowfact function client.incwfact(add, c) c = c or capi.client.focus @@ -1462,10 +1462,10 @@ end -- Starting from the client in focus or the given index, all clients that match -- a given criteria. -- --- @tparam function filter a function that returns true to indicate a positive match. --- @tparam integer start what index to start iterating from. Defaults to using the +-- @tparam function filter A function that returns true to indicate a positive match. +-- @tparam integer start What index to start iterating from. Defaults to using the -- index of the currently focused client. --- @tparam[opt=nil] screen s which screen to use. nil means all screens. +-- @tparam[opt=nil] screen s Which screen to use. nil means all screens. -- -- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances @@ -1487,8 +1487,8 @@ end -- If multiple clients match the given condition then the next one is -- focused. -- --- @tparam string cmd the command to execute --- @tparam function matcher a function that returns true to indicate a matching client +-- @tparam string cmd The command to execute +-- @tparam function matcher A function that returns true to indicate a matching client -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client as argument. @@ -1611,7 +1611,7 @@ end, true, true, "keybinding") -- @DOC_awful_client_shape1_EXAMPLE@ -- -- @property shape --- @tparam gears.shape A gears.shape compatible function. +-- @tparam gears.shape shape A gears.shape compatible function. -- @propemits true false -- @see gears.shape function client.object.set_shape(self, shape) @@ -1811,6 +1811,7 @@ end) --- Emitted when a client need to get a titlebar. -- @signal request::titlebars +-- @tparam client c The client. -- @tparam[opt=nil] string content The context (like "rules") -- @tparam[opt=nil] table hints Some hints. -- @classsignal @@ -1834,6 +1835,7 @@ end) -- * **floating**: When the floating or maximization state changes. -- -- @signal request::border +-- @tparam client c The client. -- @tparam string context The context. -- @tparam table hints The hints. -- @classsignal diff --git a/lib/awful/completion.lua b/lib/awful/completion.lua index f374c9094..45ca4598d 100644 --- a/lib/awful/completion.lua +++ b/lib/awful/completion.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Completion module. +--- Helper utilities for bash-like completion lists. -- -- This module store a set of function using shell to complete commands name. -- @@ -31,7 +31,7 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion" --- Enable programmable bash completion in awful.completion.bash at the price of -- a slight overhead. --- @param src The bash completion source file, /etc/bash_completion by default. +-- @tparam string src The bash completion source file, `/etc/bash_completion` by default. -- @staticfct awful.completion.bashcomp_load function completion.bashcomp_load(src) if src then bashcomp_src = src end @@ -189,11 +189,13 @@ end --- Run a generic completion. -- For this function to run properly the awful.completion.keyword table should -- be fed up with all keywords. The completion is run against these keywords. --- @param text The current text the user had typed yet. --- @param cur_pos The current cursor position. --- @param ncomp The number of yet requested completion using current text. --- @param keywords The keywords table uised for completion. --- @return The new match, the new cursor position, the table of all matches. +-- @tparam string text The current text the user had typed yet. +-- @tparam number cur_pos The current cursor position. +-- @tparam number ncomp The number of yet requested completion using current text. +-- @tparam table keywords The keywords table uised for completion. +-- @treturn string The new match. +-- @treturn number The new cursor position. +-- @treturn table The table of all matches. -- @staticfct awful.completion.generic function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args -- The keywords table may be empty diff --git a/lib/awful/hotkeys_popup/init.lua b/lib/awful/hotkeys_popup/init.lua index 8aaa75445..4cb6e4772 100644 --- a/lib/awful/hotkeys_popup/init.lua +++ b/lib/awful/hotkeys_popup/init.lua @@ -10,7 +10,7 @@ local hotkeys_popup = { widget = require("awful.hotkeys_popup.widget"), } ---- This is the same as awful.hotkeys_popup.widget.show_help. +--- This is the same as `awful.hotkeys_popup.widget.show_help`. -- -- example usage: -- diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index 144f2b0ed..e0d5a5613 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -249,6 +249,21 @@ widget.labels = { -- @tparam[opt] table args.group_rules Rules for showing 3rd-party hotkeys. @see `awful.hotkeys_popup.keys.vim`. -- @return Widget instance. -- @constructorfct awful.widget.hotkeys_popup.widget.new +-- @usebeautiful beautiful.hotkeys_fg +-- @usebeautiful beautiful.hotkeys_bg +-- @usebeautiful beautiful.hotkeys_border_width +-- @usebeautiful beautiful.hotkeys_border_color +-- @usebeautiful beautiful.hotkeys_shape +-- @usebeautiful beautiful.hotkeys_modifiers_fg +-- @usebeautiful beautiful.hotkeys_label_bg +-- @usebeautiful beautiful.hotkeys_label_fg +-- @usebeautiful beautiful.hotkeys_font +-- @usebeautiful beautiful.hotkeys_description_font +-- @usebeautiful beautiful.hotkeys_group_margin +-- @usebeautiful beautiful.bg_normal Fallback. +-- @usebeautiful beautiful.fg_normal Fallback. +-- @usebeautiful beautiful.fg_minimize Fallback. +-- @usebeautiful beautiful.border_width Fallback. function widget.new(args) args = args or {} local widget_instance = { @@ -755,8 +770,8 @@ function widget.new(args) end --- Add hotkey group rules for third-party applications. - -- @tparam string group hotkeys group name, - -- @tparam table data rule data for the group + -- @tparam string group Hotkeys group name, + -- @tparam table data Rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. -- @method add_group_rules function widget_instance:add_group_rules(group, data) @@ -795,8 +810,8 @@ end --- Add hotkey group rules for third-party applications -- (default widget instance will be used). --- @tparam string group rule group name, --- @tparam table data rule data for the group +-- @tparam string group Rule group name, +-- @tparam table data Rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. -- @staticfct awful.hotkeys_popup.widget.add_group_rules function widget.add_group_rules(group, data) diff --git a/lib/awful/key.lua b/lib/awful/key.lua index ec111ce52..efb07a52e 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -43,7 +43,7 @@ local gobject = require("gears.object") -- keycode such as `#65`. -- -- @property key --- @param string +-- @tparam string key --- The table of modifier keys. -- @@ -75,31 +75,31 @@ local gobject = require("gears.object") -- This is used, for example, by `awful.hotkeys_popup`. -- -- @property description --- @param string +-- @tparam string description --- The key name. -- -- This can be useful when searching for keybindings by keywords. -- -- @property name --- @param string +-- @tparam string name --- The key group bound to a function in a key binding. -- -- This is used, for example, by `awful.hotkeys_popup`. -- -- @property group --- @param string +-- @tparam string group --- The callback when this key is pressed. -- -- @property on_press --- @param function +-- @tparam function on_press --- The callback when this key is released. -- -- @property on_release --- @param function +-- @tparam function on_release local key = { mt = {}, hotkeys = {} } diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index e457f53c4..f28cce404 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -296,7 +296,7 @@ end -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@ -- -- @property timeout --- @param number +-- @tparam number timeout -- @see gears.timer -- @see timeout_callback @@ -321,7 +321,7 @@ end -- their corresponding key names such as `Control_L`. -- -- @property stop_key --- @param[opt=nil] string|table stop_key +-- @tparam[opt=nil] string|table stop_key -- @see stop_event --- The event on which the keygrabbing will be terminated. @@ -332,7 +332,7 @@ end -- * "release" -- -- @property stop_event --- @param string +-- @tparam string stop_event -- @see stop_key --- Whether or not to execute the key press/release callbacks when keybindings are called. @@ -344,14 +344,14 @@ end -- By default, keybindings block those callbacks from being executed. -- -- @property mask_event_callback --- @param[opt=true] boolean +-- @tparam[opt=true] boolean mask_event_callback -- @see keybindings -- @see keyreleased_callback -- @see keypressed_callback --- Do not call the callbacks on modifier keys (like `Control` or `Mod4`) events. -- @property mask_modkeys --- @param[opt=false] boolean +-- @tparam[opt=false] boolean mask_modkeys -- @see mask_event_callback --- Export all keygrabber keybindings as root (global) keybindings. @@ -365,7 +365,7 @@ end -- have a single instance. -- -- @property export_keybindings --- @param[opt=false] boolean +-- @tparam[opt=false] boolean export_keybindings --- The root (global) keybinding to start this keygrabber. -- @@ -376,7 +376,7 @@ end -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@ -- -- @property root_keybindings --- @param table +-- @tparam table root_keybindings -- @see export_keybindings -- @see keybindings @@ -385,7 +385,7 @@ end -- This property contains a table of `awful.key` objects. -- -- @property keybindings --- @param table +-- @tparam table keybindings -- @see export_keybindings -- @see root_keybindings -- @see awful.key @@ -415,7 +415,7 @@ end -- @DOC_text_awful_keygrabber_autostart_EXAMPLE@ -- -- @property sequence --- @param string +-- @tparam string sequence -- --- The current (running) instance of this keygrabber. diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua index fc8af8ec9..ba7106234 100644 --- a/lib/awful/layout/init.lua +++ b/lib/awful/layout/init.lua @@ -1,5 +1,29 @@ --------------------------------------------------------------------------- ---- Layout module for awful. +--- Deterministically lay the clients in a screen workarea. +-- +-- The `awful.layout` module contains many sub-modules. Each of them contain +-- one or more layout. `awful.layout` offers static layouts rather than +-- tree based like other WMs. The layout have a small number of configuration +-- variables: +-- +-- * `master_width_factor`: The ratio between the main (master) section of the +-- layout and a sub-section. For example, in the `tile.left` layout, the main +-- (master) part contains `master_count` clients and the secondary part contains +-- all other clients. +-- * `master_count`: The number of clients which belong to the main (master) area. +-- * `column_count`: The number of columns to store the clients in the secondary +-- area. +-- * `master_fill_policy`: When the number of clients is below `master_count`, +-- how is the remaining space used. +-- * `gaps`: The empty space between the clients. +-- * `gap_single_client`: Same as gap, but when there is a single client. Gaps +-- are often useful as a visual cue to know where a client starts and ends. +-- This makes no sense when there is only one. +-- +-- Not all layouts make use of all variables. Having such an overloaded meaning +-- to a small set of variable is useful to attach those values to keybindings +-- without having special logic for each layouts. AwesomeWM keybindings are not +-- modal, so such "limitation" actually improves usability. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou diff --git a/lib/awful/layout/suit/corner.lua b/lib/awful/layout/suit/corner.lua index be6e82002..60029b35e 100644 --- a/lib/awful/layout/suit/corner.lua +++ b/lib/awful/layout/suit/corner.lua @@ -171,6 +171,7 @@ end -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.nw +-- @usebeautiful beautiful.layout_cornernw corner.nw = { name = "cornernw", arrange = function (p) return do_corner(p, "NW") end, @@ -181,6 +182,7 @@ corner.nw = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.ne +-- @usebeautiful beautiful.layout_cornerne corner.ne = { name = "cornerne", arrange = function (p) return do_corner(p, "NE") end, @@ -191,6 +193,7 @@ corner.ne = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.sw +-- @usebeautiful beautiful.layout_cornersw corner.sw = { name = "cornersw", arrange = function (p) return do_corner(p, "SW") end, @@ -201,6 +204,7 @@ corner.sw = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.se +-- @usebeautiful beautiful.layout_cornerse corner.se = { name = "cornerse", arrange = function (p) return do_corner(p, "SE") end, diff --git a/lib/awful/layout/suit/fair.lua b/lib/awful/layout/suit/fair.lua index 6930a09e7..c01c4a153 100644 --- a/lib/awful/layout/suit/fair.lua +++ b/lib/awful/layout/suit/fair.lua @@ -107,10 +107,12 @@ end --- The fair layout. -- Try to give all clients the same size. -- @clientlayout awful.layout.suit.fair +-- @usebeautiful beautiful.layout_fairv --- The horizontal fair layout. -- Try to give all clients the same size. -- @clientlayout awful.layout.suit.fair.horizontal +-- @usebeautiful beautiful.layout_fairh return fair diff --git a/lib/awful/layout/suit/floating.lua b/lib/awful/layout/suit/floating.lua index f3a9a9b7e..e65ccfa92 100644 --- a/lib/awful/layout/suit/floating.lua +++ b/lib/awful/layout/suit/floating.lua @@ -114,6 +114,7 @@ end --- The floating layout. -- @clientlayout awful.layout.suit.floating +-- @usebeautiful beautiful.layout_floating floating.name = "floating" diff --git a/lib/awful/layout/suit/magnifier.lua b/lib/awful/layout/suit/magnifier.lua index c2c56883d..23acddcf3 100644 --- a/lib/awful/layout/suit/magnifier.lua +++ b/lib/awful/layout/suit/magnifier.lua @@ -143,6 +143,7 @@ end --- The magnifier layout. -- @clientlayout awful.layout.suit.magnifier +-- @usebeautiful beautiful.layout_magnifier magnifier.name = "magnifier" diff --git a/lib/awful/layout/suit/max.lua b/lib/awful/layout/suit/max.lua index 731c7a8ea..1d27856ca 100644 --- a/lib/awful/layout/suit/max.lua +++ b/lib/awful/layout/suit/max.lua @@ -43,6 +43,7 @@ end --- Maximized layout. -- @clientlayout awful.layout.suit.max +-- @usebeautiful beautiful.layout_max max.name = "max" function max.arrange(p) return fmax(p, false) @@ -53,6 +54,7 @@ end --- Fullscreen layout. -- @clientlayout awful.layout.suit.max.fullscreen +-- @usebeautiful beautiful.layout_fullscreen max.fullscreen = {} max.fullscreen.name = "fullscreen" max.fullscreen.skip_gap = max.skip_gap diff --git a/lib/awful/layout/suit/spiral.lua b/lib/awful/layout/suit/spiral.lua index 629d9828a..fe608dfa2 100644 --- a/lib/awful/layout/suit/spiral.lua +++ b/lib/awful/layout/suit/spiral.lua @@ -71,6 +71,7 @@ end --- Dwindle layout. -- @clientlayout awful.layout.suit.spiral.dwindle +-- @usebeautiful beautiful.layout_dwindle spiral.dwindle = {} spiral.dwindle.name = "dwindle" function spiral.dwindle.arrange(p) @@ -79,6 +80,7 @@ end --- Spiral layout. -- @clientlayout awful.layout.suit.spiral.name +-- @usebeautiful beautiful.layout_spiral spiral.name = "spiral" function spiral.arrange(p) return do_spiral(p, true) diff --git a/lib/awful/layout/suit/tile.lua b/lib/awful/layout/suit/tile.lua index 4609a0579..85922c8b9 100644 --- a/lib/awful/layout/suit/tile.lua +++ b/lib/awful/layout/suit/tile.lua @@ -312,6 +312,7 @@ end --- The main tile algo, on the right. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.right +-- @usebeautiful beautiful.layout_tile tile.right = {} tile.right.name = "tile" tile.right.arrange = do_tile @@ -323,6 +324,7 @@ end --- The main tile algo, on the left. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.left +-- @usebeautiful beautiful.layout_tileleft tile.left = {} tile.left.name = "tileleft" tile.left.skip_gap = tile.skip_gap @@ -336,6 +338,7 @@ end --- The main tile algo, on the bottom. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.bottom +-- @usebeautiful beautiful.layout_tilebottom tile.bottom = {} tile.bottom.name = "tilebottom" tile.bottom.skip_gap = tile.skip_gap @@ -349,6 +352,7 @@ end --- The main tile algo, on the top. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.top +-- @usebeautiful beautiful.layout_tiletop tile.top = {} tile.top.name = "tiletop" tile.top.skip_gap = tile.skip_gap diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index 4e87ee232..33caa8ceb 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -1,5 +1,5 @@ -------------------------------------------------------------------------------- ---- A menu for awful. +--- Create context menus, optionally with sub-menus. -- -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> @@ -93,7 +93,7 @@ end -- @param color -- @see gears.color ---- The default sub-menu indicator if no menu_submenu_icon is provided. +--- The default sub-menu indicator if no `menu_submenu_icon` is provided. -- @beautiful beautiful.menu_submenu -- @tparam[opt="▶"] string menu_submenu The sub-menu text. -- @see beautiful.menu_submenu_icon @@ -357,8 +357,9 @@ end --- Show a menu. --- @param args The arguments --- @param args.coords Menu position defaulting to mouse.coords() +-- @tparam[opt={}] table args The arguments +-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with +-- `x` and `y` as keys and position (in pixels) as values. -- @method show function menu:show(args) args = args or {} @@ -390,8 +391,9 @@ function menu:hide() end --- Toggle menu visibility. --- @param args The arguments --- @param args.coords Menu position {x,y} +-- @tparam table args The arguments. +-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with +-- `x` and `y` as keys and position (in pixels) as values. -- @method toggle function menu:toggle(args) if self.wibox.visible then @@ -419,10 +421,10 @@ end --- Add a new menu entry. -- args.* params needed for the menu entry constructor. --- @param args The item params --- @param args.new (Default: awful.menu.entry) The menu entry constructor. --- @param[opt] args.theme The menu entry theme. --- @param[opt] index The index where the new entry will inserted. +-- @tparam table args The item params. +-- @tparam[opt=awful.menu.entry] function args.new The menu entry constructor. +-- @tparam[opt] table args.theme The menu entry theme. +-- @tparam[opt] number index The index where the new entry will inserted. -- @method add function menu:add(args, index) if not args then return end @@ -479,7 +481,7 @@ function menu:add(args, index) end --- Delete menu entry at given position. --- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself. +-- @tparam table|number num The index in the table of the menu entry to be deleted; can be also the menu entry itself. -- @method delete function menu:delete(num) if type(num) == "table" then @@ -580,8 +582,8 @@ end --- Default awful.menu.entry constructor. -- @param parent The parent menu (TODO: This is apparently unused) --- @param args the item params --- @return table with 'widget', 'cmd', 'akey' and all the properties the user wants to change +-- @param args The item params +-- @return table With 'widget', 'cmd', 'akey' and all the properties the user wants to change -- @constructorfct awful.menu.entry function menu.entry(parent, args) -- luacheck: no unused args args = args or {} @@ -673,14 +675,24 @@ end -------------------------------------------------------------------------------- --- Create a menu popup. --- @param args Table containing the menu information. --- --- * Key items: Table containing the displayed items. Each element is a table by default (when element 'new' is --- awful.menu.entry) containing: item name, triggered action (submenu table or function), item icon (optional). --- * Keys theme.[fg|bg]_[focus|normal], theme.border_color, theme.border_width, theme.submenu_icon, theme.height --- and theme.width override the default display for your menu and/or of your menu entry, each of them are optional. --- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false. -- +-- @tparam table args Table containing the menu information. +-- @tparam[opt=true] boolean args.auto_expand Controls the submenu auto expand behaviour. +-- @tparam table args.items Table containing the displayed items. Each element is a +-- table by default (when element 'new' is awful.menu.entry) containing: item +-- name, triggered action (submenu table or function), item icon (optional). +-- @tparam table args.theme +-- @tparam[opt=beautiful.menu_fg_normal] color args.theme.fg_normal +-- @tparam[opt=beautiful.menu_bg_normal] color args.theme.bg_normal +-- @tparam[opt=beautiful.menu_fg_focus] color args.theme.fg_focus +-- @tparam[opt=beautiful.menu_bg_focus] color args.theme.bg_focus +-- @tparam[opt=beautiful.menu_border_color] color args.theme.border +-- @tparam[opt=beautiful.menu_border_width] integer args.theme.border_width +-- @tparam[opt=beautiful.menu_height] integer args.theme.height +-- @tparam[opt=beautiful.menu_width] integer args.theme.width +-- @tparam[opt=beautiful.menu_font] string args.theme.font +-- @tparam[opt=beautiful.menu_submenu_icon] gears.surface|string args.theme.submenu_icon +-- @tparam[opt=beautiful.menu_submenu] string args.theme.submenu -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user. -- @constructorfct awful.menu -- @usage -- The following function builds and shows a menu of clients that match diff --git a/lib/awful/mouse/client.lua b/lib/awful/mouse/client.lua index d6191b723..5170eb3a1 100644 --- a/lib/awful/mouse/client.lua +++ b/lib/awful/mouse/client.lua @@ -69,8 +69,8 @@ end --- Get a client corner coordinates. -- @deprecated awful.mouse.client.corner -- @tparam[opt=client.focus] client c The client to get corner from, focused one by default. --- @tparam string corner The corner to use: auto, top_left, top_right, bottom_left, --- bottom_right, left, right, top bottom. Default is auto, and auto find the +-- @tparam string corner The corner to use: `auto`, `top_left`, `top_right`, `bottom_left`, +-- `bottom_right`, `left`, `right`, `top` or `bottom`. Default is `auto`. `auto` finds the -- nearest corner. -- @treturn string The corner name -- @treturn number x The horizontal position diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index 92c9ac462..b4d620360 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -116,7 +116,7 @@ end, "mouse.resize") --- Get the client currently under the mouse cursor. -- @property current_client --- @tparam client|nil The client +-- @tparam client|nil current_client The client function mouse.object.get_current_client() local obj = capi.mouse.object_under_pointer() @@ -127,7 +127,7 @@ end --- Get the wibox currently under the mouse cursor. -- @property current_wibox --- @tparam wibox|nil The wibox +-- @tparam wibox|nil current_wibox The wibox function mouse.object.get_current_wibox() local obj = capi.mouse.object_under_pointer() @@ -139,7 +139,7 @@ end --- Get the widgets currently under the mouse cursor. -- -- @property current_widgets --- @tparam nil|table list The widget list +-- @tparam nil|table current_widgets The widget list -- @treturn table The list of widgets.The first element is the biggest -- container while the last is the topmost widget. The table contains *x*, *y*, -- *width*, *height* and *widget*. @@ -164,7 +164,7 @@ end --- Get the topmost widget currently under the mouse cursor. -- @property current_widget --- @tparam widget|nil widget The widget +-- @tparam widget|nil current_widget The widget -- @treturn ?widget The widget -- @see current_widget_geometry @@ -178,7 +178,7 @@ end --- Get the current widget geometry. -- @property current_widget_geometry --- @tparam ?table The geometry. +-- @tparam ?table current_widget_geometry The geometry. -- @see current_widget function mouse.object.get_current_widget_geometry() @@ -189,7 +189,7 @@ end --- Get the current widget geometries. -- @property current_widget_geometries --- @tparam ?table A list of geometry tables. +-- @tparam ?table current_widget_geometries A list of geometry tables. -- @see current_widgets function mouse.object.get_current_widget_geometries() @@ -238,7 +238,7 @@ end --- True if the middle mouse button is pressed. -- @property is_middle_mouse_button_pressed --- @tparam boolean is_right_mouse_button_pressed +-- @tparam boolean is_middle_mouse_button_pressed --- Add an `awful.button` based mousebinding to the global set. -- diff --git a/lib/awful/mouse/resize.lua b/lib/awful/mouse/resize.lua index a685bc599..e1ca82281 100644 --- a/lib/awful/mouse/resize.lua +++ b/lib/awful/mouse/resize.lua @@ -52,7 +52,7 @@ end -- This callback will be executed before the mouse grabbing starts. -- @function awful.mouse.resize.add_enter_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_enter_callback(cb, context) context = context or "other" callbacks.enter[context] = callbacks.enter[context] or {} @@ -64,7 +64,7 @@ end -- applying the operation. -- @function awful.mouse.resize.add_move_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_move_callback(cb, context) context = context or "other" callbacks.move[context] = callbacks.move[context] or {} @@ -75,7 +75,7 @@ end -- This callback is executed just before the `mousegrabber` stop -- @function awful.mouse.resize.add_leave_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_leave_callback(cb, context) context = context or "other" callbacks.leave[context] = callbacks.leave[context] or {} @@ -93,9 +93,11 @@ end -- -- @function awful.mouse.resize -- @tparam client client A client. --- @tparam[default=mouse.resize] string context The resizing context. +-- @tparam[opt=mouse.resize] string context The resizing context. -- @tparam[opt={}] table args A set of `awful.placement` arguments. -- @request wibox geometry mouse.resize granted Requests to resize the wibox. +-- @usebeautiful beautiful.cursor_mouse_move +-- @usebeautiful beautiful.cursor_mouse_resize local function handler(_, client, context, args) --luacheck: no unused_args args = args or {} context = context or "mouse.resize" diff --git a/lib/awful/mouse/snap.lua b/lib/awful/mouse/snap.lua index 843425687..0b7a05fad 100644 --- a/lib/awful/mouse/snap.lua +++ b/lib/awful/mouse/snap.lua @@ -200,6 +200,10 @@ end -- @tparam boolean fixed_x True if the client isn't allowed to move in the x direction. -- @tparam boolean fixed_y True if the client isn't allowed to move in the y direction. -- @treturn table The new geometry. +-- @usebeautiful beautiful.snap_bg +-- @usebeautiful beautiful.snap_border_width +-- @usebeautiful beautiful.snap_shape +-- @usebeautiful beautiful.snapper_gap function module.snap(c, snap, x, y, fixed_x, fixed_y) snap = snap or module.default_distance c = c or capi.client.focus diff --git a/lib/awful/permissions/init.lua b/lib/awful/permissions/init.lua index 93be8eb95..5b59b8e1a 100644 --- a/lib/awful/permissions/init.lua +++ b/lib/awful/permissions/init.lua @@ -1,5 +1,19 @@ --------------------------------------------------------------------------- ---- Implements EWMH requests handling. +--- Default implementation of the various requests handers. +-- +-- AwesomeWM has many `request::` signals across the core APIs. They help +-- decouple the default behavior from the core API. The request handlers +-- can be disconnected and replaced by module or `rc.lua` to alter +-- AwesomeWM behavior. +-- +-- This module provides the default implementation of those request handlers. +-- Beside some legacy signals, most request handlers have a main object, a +-- named context and a table containing any low-level hints the core code is +-- aware of. Each default handler implement a context based filter mechanism. +-- This filter is called the "permissions". It allows requests to be denied. +-- For example, if a tiled client asks to be resized or moved, the permission +-- and deny it. In the documentation, many objects and properties have a +-- "permissions" section you can display by clicking "show more". -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou @@ -143,12 +157,13 @@ end -- @tparam client c A client to use -- @tparam string context The context where this signal was used. -- @tparam[opt] table hints A table with additional hints: --- @tparam[opt=false] boolean hints.raise should the client be unminimized +-- @tparam[opt=false] boolean hints.raise Should the client be unminimized -- and raised? --- @tparam[opt=false] boolean hints.switch_to_tag should the client's first tag +-- @tparam[opt=false] boolean hints.switch_to_tag Should the client's first tag -- be selected if none of the client's tags are selected? -- @tparam[opt=false] boolean hints.switch_to_tags Select all tags associated -- with the client. +-- @sourcesignal client request::activate function permissions.activate(c, context, hints) -- luacheck: no unused args if not pcommon.check(c, "client", "activate", context) then return end @@ -291,6 +306,7 @@ end -- @tparam[opt] tag|boolean t A tag to use. If `true`, then the client is made `sticky`. -- @tparam[opt={}] table hints Extra information. -- @tparam[opt=nil] nil|string hints.reason Why the tag is being changed. +-- @sourcesignal client request::tag function permissions.tag(c, t, hints) --luacheck: no unused -- There is nothing to do if not t and #get_valid_tags(c, c.screen) > 0 then return end @@ -317,6 +333,7 @@ end -- @signalhandler awful.permissions.urgent -- @tparam client c A client -- @tparam boolean urgent If the client should be urgent +-- @sourcesignal client request::urgent function permissions.urgent(c, urgent) if c ~= client.focus and not aclient.property.get(c,"ignore_urgent") then c.urgent = urgent @@ -343,6 +360,7 @@ local context_mapper = { -- previous geometry in case it has to be restored. -- @tparam[opt=true] boolean hints.honor_workarea Avoid overlapping the `wibar`s -- or other desktop decoration when applying the geometry. +-- @sourcesignal client request::geometry function permissions.geometry(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -416,6 +434,7 @@ end -- @tparam[opt] integer hints.y The vertical position. -- @tparam[opt] integer hints.width The wibox width. -- @tparam[opt] integer hints.height The wibox height. +-- @sourcesignal client request::geometry function permissions.wibox_geometry(w, context, hints) if not pcommon.check(w, "wibox", "geometry", context) then return end @@ -435,6 +454,7 @@ end -- @tparam[opt={}] table hints The hints to pass to the handler. -- @tparam[opt=false] boolean hints.toggle Toggle the maximization state rather -- than set it to `true`. +-- @sourcesignal client request::geometry function permissions.merge_maximization(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -522,6 +542,7 @@ end -- @tparam[opt] integer hints.y The vertical position. -- @tparam[opt] integer hints.width The client width. -- @tparam[opt] integer hints.height The client height. +-- @sourcesignal client request::geometry function permissions.client_geometry_requests(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -563,6 +584,7 @@ end, "mouse_enter") -- @signalhandler awful.permissions.update_border -- @tparam client c The client. -- @tparam string context Why is the border changed. +-- @sourcesignal client request::border -- @usebeautiful beautiful.border_color_marked -- @usebeautiful beautiful.border_color_active -- @usebeautiful beautiful.border_color_normal @@ -751,6 +773,7 @@ local activate_context_map = { -- @tparam client c The client. -- @tparam string context Why is the client auto-activated. -- @tparam[opt={}] table hints Extra arguments. +-- @sourcesignal client request::activated -- @see activate -- @see client:activate function permissions.autoactivate(c, context, args) diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index d559ca70e..caf3c57b0 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Prompt module for awful. +--- Convert a `wibox.widget.textbox` into an input prompt. -- -- **Keyboard navigation**: -- @@ -444,21 +444,21 @@ end -- return command -- end} -- } --- @param textbox The textbox to use for the prompt. [**DEPRECATED**] --- @param exe_callback The callback function to call with command as argument +-- @tparam wibox.widget.textbox textbox The textbox to use for the prompt. [**DEPRECATED**] +-- @tparam[opt] function|nil exe_callback The callback function to call with command as argument -- when finished. [**DEPRECATED**] --- @param completion_callback The callback function to call to get completion. +-- @tparam[opt] function completion_callback The callback function to call to get completion. -- [**DEPRECATED**] --- @param[opt] history_path File path where the history should be +-- @tparam[opt] string history_path File path where the history should be -- saved, set nil to disable history [**DEPRECATED**] --- @param[opt] history_max Set the maximum entries in history +-- @tparam[opt] number history_max Set the maximum entries in history -- file, 50 by default [**DEPRECATED**] --- @param[opt] done_callback The callback function to always call +-- @tparam[opt] function done_callback The callback function to always call -- without arguments, regardless of whether the prompt was cancelled. -- [**DEPRECATED**] --- @param[opt] changed_callback The callback function to call +-- @tparam[opt] function changed_callback The callback function to call -- with command as argument when a command was changed. [**DEPRECATED**] --- @param[opt] keypressed_callback The callback function to call +-- @tparam[opt] function keypressed_callback The callback function to call -- with mod table, key and command as arguments when a key was pressed. -- [**DEPRECATED**] -- @see gears.color diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index 346ed6b60..6d931bda3 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -380,7 +380,7 @@ end -- -- This method computes the different variants of the "usable" screen geometry. -- --- @staticfct screen.get_bounding_geometry +-- @method screen.get_bounding_geometry -- @tparam[opt={}] table args The arguments -- @tparam[opt=false] boolean args.honor_padding Whether to honor the screen's padding. -- @tparam[opt=false] boolean args.honor_workarea Whether to honor the screen's workarea. @@ -772,7 +772,7 @@ end -- the lowest of the resulting virtual DPIs. -- -- @property preferred_dpi --- @tparam number preferred_dpi the DPI value. +-- @tparam number preferred_dpi The DPI value. -- @readonly --- The maximum diagonal size in millimeters. @@ -953,6 +953,8 @@ end -- `request::remove` and `request::resize`. -- -- @signalhandler awful.screen.create_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::create -- @see request::create --- Default handler for `request::remove`. @@ -972,6 +974,8 @@ end -- end -- -- @signalhandler awful.screen.remove_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::remove -- @see request::remove --- Default handler for `request::resize`. @@ -993,6 +997,8 @@ end -- end -- -- @signalhandler awful.screen.resize_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::resize -- @see request::resize -- Add the DPI properties. diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua index ecada47b9..beae02d0a 100644 --- a/lib/awful/spawn.lua +++ b/lib/awful/spawn.lua @@ -1,7 +1,7 @@ --luacheck: no max line length --------------------------------------------------------------------------- ---- Spawning of programs. +--- Spawn sub-processes and optionally get their output. -- -- This module provides methods to start programs and supports startup -- notifications, which allows for callbacks and applying properties to the diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index d5ceeee5f..958da3937 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -637,7 +637,7 @@ end -- @deprecated awful.tag.setscreen -- @see screen -- @tparam screen s Screen --- @tparam tag t tag object +-- @tparam tag t The tag object function tag.setscreen(s, t) -- For API consistency, the arguments have been swapped for Awesome 3.6 -- this method is already deprecated, so be silent and swap the args @@ -653,7 +653,7 @@ end --- Get a tag's screen -- @deprecated awful.tag.getscreen -- @see screen --- @tparam[opt] tag|nil t tag object +-- @tparam[opt=awful.screen.focused().selected_taga] tag|nil t Tag object -- @treturn screen The tag screen. function tag.getscreen(t) gdebug.deprecate("Use t.screen instead of awful.tag.getscreen(t)", {deprecated_in=4}) @@ -713,7 +713,7 @@ end -- @DOC_screen_mwfact2_EXAMPLE@ -- -- @property master_width_factor --- @tparam number master_width_factor Between 0 and 1 +-- @tparam[opt=beautiful.master_width_factor] number master_width_factor Between 0 and 1 -- @emits property::mwfact When the value changes (deprecated). -- @emits property::master_width_factor When the value changes. -- @see master_count @@ -1006,7 +1006,7 @@ end --- Set layout. -- @deprecated awful.tag.setlayout -- @see layout --- @param layout a layout table or a constructor function +-- @param layout A layout table or a constructor function -- @tparam tag t The tag to modify -- @return The layout function tag.setlayout(layout, t) @@ -1096,7 +1096,7 @@ end -- @DOC_screen_gaps2_EXAMPLE@ -- -- @property gap --- @tparam number gap The value has to be greater than zero. +-- @tparam[opt=beautiful.useless_gap] number gap The value has to be greater than zero. -- @emits property::useless_gap When the gap changes. -- @see gap_single_client -- @see awful.tag.incgap @@ -1158,7 +1158,7 @@ end -- @DOC_screen_gap_single_client_false_EXAMPLE@ -- -- @property gap_single_client --- @tparam boolean gap_single_client Enable gaps for a single client +-- @tparam[opt=beautiful.gap_single_client] boolean gap_single_client Enable gaps for a single client -- @propemits false false -- @see awful.tag.incgap @@ -1230,7 +1230,7 @@ end -- redistributed on both side. -- -- @property master_fill_policy --- @tparam string master_fill_policy "expand" or "master\_width\_factor" +-- @tparam[opt=beautiful.master_fill_policy] string master_fill_policy "expand" or "master\_width\_factor" -- @propemits false false -- @see awful.tag.togglemfpol @@ -1245,7 +1245,7 @@ end -- @see master_fill_policy -- @tparam string policy Can be set to -- "expand" (fill all the available workarea) or --- "master_width_factor" (fill only an area inside the master width factor) +-- `master_width_factor` (fill only an area inside the master width factor) -- @tparam[opt=tag.selected()] tag t The tag to modify function tag.setmfpol(policy, t) gdebug.deprecate("Use t.master_fill_policy = policy instead of awful.tag.setmfpol", {deprecated_in=4}) @@ -1296,7 +1296,7 @@ end -- @DOC_sequences_tag_master_count_EXAMPLE@ -- -- @property master_count --- @tparam integer master_count nmaster Only positive values are accepted +-- @tparam[opt=beautiful.master_count] integer master_count Only positive values are accepted -- @emits property::nmaster Deprecated. -- @emits property::master_count When the value changes. -- @see awful.tag.incnmaster @@ -1317,7 +1317,7 @@ end --- The number of master clients. -- @deprecated awful.tag.setnmaster -- @see master_count --- @tparam nmaster The number of master windows. +-- @tparam number nmaster The number of master windows. -- @tparam[opt] tag t The tag. function tag.setnmaster(nmaster, t) gdebug.deprecate("Use t.master_count = nmaster instead of awful.tag.setnmaster", {deprecated_in=4}) @@ -1379,9 +1379,9 @@ end --- Set the tag icon -- @deprecated awful.tag.seticon +-- @tparam gears.surface|string icon The icon to set, either path or image object +-- @tparam tag tag The tag -- @see icon --- @tparam gears.surface|string icon the icon to set, either path or image object --- @tparam tag tag the tag function tag.seticon(icon, _tag) gdebug.deprecate("Use t.icon = icon instead of awful.tag.seticon", {deprecated_in=4}) @@ -1392,7 +1392,7 @@ end --- Get the tag icon -- @deprecated awful.tag.geticon -- @see icon --- @tparam tag tag the tag +-- @tparam tag tag The tag function tag.geticon(_tag) gdebug.deprecate("Use t.icon instead of awful.tag.geticon", {deprecated_in=4}) @@ -1411,7 +1411,7 @@ end -- @DOC_sequences_tag_column_count_EXAMPLE@ -- -- @property column_count --- @tparam integer ncol Has to be greater than 1 +-- @tparam[opt=beautiful.column_count or 1] integer column_count Has to be greater than 1 -- @emits property::ncol Deprecated. -- @emits property::column_count When the value changes. -- @see awful.tag.incncol @@ -1739,7 +1739,7 @@ end -- @staticfct awful.tag.attached_connect_signal -- @tparam screen|nil screen The screen concerned, or all if `nil`. -- @tparam string signal The signal name. --- @tparam function Callback +-- @tparam function callback function tag.attached_connect_signal(screen, ...) if screen then attached_connect_signal_screen(screen, ...) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 5345851f6..db59510c0 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Titlebars for awful. +--- Create widget area on the edge of a client. -- -- Create a titlebar -- ================= @@ -41,417 +41,499 @@ local titlebar = { --- Show tooltips when hover on titlebar buttons. +-- -- @tfield[opt=true] boolean awful.titlebar.enable_tooltip -- @param boolean --- Title to display if client name is not set. +-- -- @field[opt='\'] awful.titlebar.fallback_name -- @tparam[opt='\'] string fallback_name - --- The titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_normal -- @param color -- @see gears.color --- The titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_normal -- @param color -- @see gears.color --- The titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage_normal -- @tparam gears.surface|string path -- @see gears.surface --- The titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg -- @param color -- @see gears.color --- The titlebar background color. +-- -- @beautiful beautiful.titlebar_bg -- @param color -- @see gears.color --- The titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage -- @tparam gears.surface|string path -- @see gears.surface --- The focused titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_focus -- @param color -- @see gears.color --- The focused titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_focus -- @param color -- @see gears.color --- The focused titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage_focus -- @tparam gears.surface|string path -- @see gears.surface --- The urgent titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_urgent -- @param color -- @see gears.color --- The urgent titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_urgent -- @param color -- @see gears.color ---- The urgent titlebar background image image. +--- The urgent titlebar background image. +-- -- @beautiful beautiful.titlebar_bgimage_urgent -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal. +--- The normal non-floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal. +--- The normal non-maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal. +--- The normal minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal_hover. +--- The hovered minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal_hover -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal_press. +--- The pressed minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal_press -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal. +--- The normal close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal_hover. +--- The hovered close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal_hover -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal_press. +--- The pressed close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal. +--- The normal non-ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal. +--- The normal non-sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus. +--- The focused client non-floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus. +--- The focused client non-maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus. +--- The focused client minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus_hover. +--- The hovered+focused client minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus_hover -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus_press. +--- The pressed+focused minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus_press -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus. +--- The focused client close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus_hover. +--- The hovered+focused close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus_hover -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus_press. +--- The pressed+focused close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus. +--- The focused client non-ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus. +--- The focused client sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active. +--- The normal floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active_hover. +--- The hovered floating client button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active_press. +--- The pressed floating client button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active. +--- The maximized client button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active_hover. +--- The hozered+maximized client button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active_press. +--- The pressed+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active. +--- The ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active_hover. +--- The hovered+ontop client button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active_press. +--- The pressed+ontop client button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active. +--- The sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active_hover. +--- The hovered+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active_press. +--- The pressed+sticky client button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active. +--- The floating+focused client button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active_hover. +--- The hovered+floating+focused button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active_press. +--- The pressed+floating+focused button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active. +--- The maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active_hover. +--- The hovered+maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active_press. +--- The pressed+maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active. +--- The ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active_hover. +--- The hovered+ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active_press. +--- The pressed+ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active. +--- The sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active_hover. +--- The hovered+sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active_press. +--- The pressed+sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive. +--- The inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive_hover. +--- The hovered+inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive_press. +--- The pressed+inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive. +--- The inactive+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive_hover. +--- The hovered+inactive+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive_press. +--- The pressed+maximized+inactive button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive. +--- The inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive_hover. +--- The hovered+inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive_press. +--- The pressed+inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive. +--- The inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive_hover. +--- The hovered+inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive_press. +--- The pressed+inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive. +--- The inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive_hover. +--- The hovered+inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive_press. +--- The pressed+inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive. +--- The inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive_hover. +--- The hovered+inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive_press. +--- The pressed+inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive. +--- The inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive_hover. +--- The hovered+inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive_press. +--- The pressed+inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive. +--- The inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive_hover. +--- The hovered+inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive_press. +--- The pressed+inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface --- Set a declarative widget hierarchy description. +-- -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) --- @param args An array containing the widgets disposition +-- @tparam table args An array containing the widgets disposition -- @method setup @@ -554,6 +636,18 @@ end -- @tparam[opt] string args.font -- @constructorfct awful.titlebar -- @treturn wibox.drawable The newly created titlebar object. +-- @usebeautiful beautiful.titlebar_fg_normal +-- @usebeautiful beautiful.titlebar_bg_normal +-- @usebeautiful beautiful.titlebar_bgimage_normal +-- @usebeautiful beautiful.titlebar_fg +-- @usebeautiful beautiful.titlebar_bg +-- @usebeautiful beautiful.titlebar_bgimage +-- @usebeautiful beautiful.titlebar_fg_focus +-- @usebeautiful beautiful.titlebar_bg_focus +-- @usebeautiful beautiful.titlebar_bgimage_focus +-- @usebeautiful beautiful.titlebar_fg_urgent +-- @usebeautiful beautiful.titlebar_bg_urgent +-- @usebeautiful beautiful.titlebar_bgimage_urgent local function new(c, args) args = args or {} local position = args.position or "top" @@ -616,7 +710,7 @@ local function new(c, args) end --- Show the client's titlebar. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.show @@ -632,7 +726,7 @@ function titlebar.show(c, position) end --- Hide the client's titlebar. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.hide @@ -642,7 +736,7 @@ function titlebar.hide(c, position) end --- Toggle the client's titlebar, hiding it if it is visible, otherwise showing it. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.toggle @@ -706,7 +800,7 @@ end -- Please note that this returns a textbox and all of textbox' API is available. -- This way, you can e.g. modify the font that is used. -- --- @param c The client for which a titlewidget should be created. +-- @tparam client c The client for which a titlewidget should be created. -- @return The title widget. -- @constructorfct awful.titlebar.widget.titlewidget function titlebar.widget.titlewidget(c) @@ -730,7 +824,7 @@ end -- Please note that this returns an imagebox and all of the imagebox' API is -- available. This way, you can e.g. disallow resizes. -- --- @param c The client for which an icon widget should be created. +-- @tparam client c The client for which an icon widget should be created. -- @return The icon widget. -- @constructorfct awful.titlebar.widget.iconwidget function titlebar.widget.iconwidget(c) @@ -747,12 +841,12 @@ end -- then found in the theme as `titlebar_[name]_button_[normal/focus]_[state]`. -- If that value does not exist, the focused state is ignored for the next try. -- --- @param c The client for which a button is created. +-- @tparam client c The client for which a button is created. -- @tparam string name Name of the button, used for accessing the theme and -- in the tooltip. --- @param selector A function that selects the image that should be displayed. --- @param action Function that is called when the button is clicked. --- @return The widget +-- @tparam function selector A function that selects the image that should be displayed. +-- @tparam function action Function that is called when the button is clicked. +-- @treturn wibox.widget The widget -- @constructorfct awful.titlebar.widget.button function titlebar.widget.button(c, name, selector, action) local ret = imagebox() @@ -840,8 +934,23 @@ function titlebar.widget.button(c, name, selector, action) end --- Create a new float button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.floatingbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_floating_button_normal +-- @usebeautiful beautiful.titlebar_floating_button_focus +-- @usebeautiful beautiful.titlebar_floating_button_normal_active +-- @usebeautiful beautiful.titlebar_floating_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_floating_button_normal_active_press +-- @usebeautiful beautiful.titlebar_floating_button_focus_active +-- @usebeautiful beautiful.titlebar_floating_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_floating_button_focus_active_press +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_press function titlebar.widget.floatingbutton(c) local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle) update_on_signal(c, "property::floating", widget) @@ -849,8 +958,23 @@ function titlebar.widget.floatingbutton(c) end --- Create a new maximize button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.maximizedbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_press +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_press +-- @usebeautiful beautiful.titlebar_maximized_button_normal +-- @usebeautiful beautiful.titlebar_maximized_button_focus +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_press function titlebar.widget.maximizedbutton(c) local widget = titlebar.widget.button(c, "maximized", function(cl) return cl.maximized @@ -862,8 +986,15 @@ function titlebar.widget.maximizedbutton(c) end --- Create a new minimize button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.minimizebutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_minimize_button_normal +-- @usebeautiful beautiful.titlebar_minimize_button_normal_hover +-- @usebeautiful beautiful.titlebar_minimize_button_normal_press +-- @usebeautiful beautiful.titlebar_minimize_button_focus +-- @usebeautiful beautiful.titlebar_minimize_button_focus_hover +-- @usebeautiful beautiful.titlebar_minimize_button_focus_press function titlebar.widget.minimizebutton(c) local widget = titlebar.widget.button(c, "minimize", function() return "" end, @@ -873,15 +1004,37 @@ function titlebar.widget.minimizebutton(c) end --- Create a new closing button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.closebutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_close_button_normal +-- @usebeautiful beautiful.titlebar_close_button_normal_hover +-- @usebeautiful beautiful.titlebar_close_button_normal_press +-- @usebeautiful beautiful.titlebar_close_button_focus +-- @usebeautiful beautiful.titlebar_close_button_focus_hover +-- @usebeautiful beautiful.titlebar_close_button_focus_press function titlebar.widget.closebutton(c) return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end) end --- Create a new ontop button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.ontopbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_ontop_button_normal +-- @usebeautiful beautiful.titlebar_ontop_button_focus +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_press +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_press +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_press function titlebar.widget.ontopbutton(c) local widget = titlebar.widget.button(c, "ontop", function(cl) return cl.ontop end, @@ -891,8 +1044,22 @@ function titlebar.widget.ontopbutton(c) end --- Create a new sticky button for a client. --- @param c The client for which the button is wanted. -- @constructorfct awful.titlebar.widget.stickybutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_sticky_button_normal +-- @usebeautiful beautiful.titlebar_sticky_button_focus +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_press +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_press +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_press function titlebar.widget.stickybutton(c) local widget = titlebar.widget.button(c, "sticky", function(cl) return cl.sticky end, diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index 2e4816cc7..e06ecbeaf 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -107,7 +107,7 @@ local offset = { --- The tooltip opacity. -- @beautiful beautiful.tooltip_opacity --- @param number opacity Between 0 and 1 +-- @tparam number opacity Between 0 and 1 --- The tooltip margins. -- @beautiful beautiful.tooltip_gaps @@ -206,7 +206,7 @@ end --- The wibox containing the tooltip widgets. -- @property wibox --- @param wibox +-- @tparam wibox wibox function tooltip:get_wibox() if self._private.wibox then @@ -229,7 +229,7 @@ end --- Is the tooltip visible? -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @propemits true false function tooltip:get_visible() @@ -269,7 +269,7 @@ end -- * top -- -- @property align --- @param string +-- @tparam string align -- @see mode -- @see preferred_positions -- @propemits true false @@ -277,7 +277,7 @@ end --- The default tooltip alignment. -- @beautiful beautiful.tooltip_align --- @param string +-- @tparam string tooltip_align -- @see align function tooltip:get_align() @@ -330,7 +330,7 @@ end -- * "outside": Outside of the widget -- -- @property mode --- @param string +-- @tparam string mode -- @propemits true false function tooltip:set_mode(mode) @@ -410,7 +410,7 @@ end -- {"front", "back", "middle"} -- -- @property preferred_alignments --- @param string +-- @tparam string preferred_alignments -- @propemits true false -- @see preferred_positions @@ -447,7 +447,7 @@ end --- Change displayed markup. -- -- @property markup --- @tparam string text New tooltip markup, passed to +-- @tparam string markup New tooltip markup, passed to -- `wibox.widget.textbox.set_markup`. -- @propemits true false -- @see wibox.widget.textbox @@ -479,7 +479,7 @@ end -- @DOC_awful_tooltip_margins_EXAMPLE@ -- -- @property margins --- @tparam number|table New margins value. +-- @tparam number|table margins New margins value. -- @propemits true false function tooltip:set_margins(val) @@ -492,7 +492,7 @@ end -- @DOC_awful_tooltip_border_width_EXAMPLE@ -- -- @property border_width --- @param number +-- @tparam[opt=0] number border_width -- @propemits true false -- @propbeautiful @@ -506,8 +506,10 @@ end -- @DOC_awful_tooltip_border_color_EXAMPLE@ -- -- @property border_color --- @param color +-- @tparam[opt=beautiful.tooltip_border_color or beautiful.border_color_normal or beautiful.fg_normal] +-- gears.color border_color -- @propemits true false +-- @propbeautiful function tooltip:set_border_color(val) self.widget.border_color = val @@ -519,7 +521,7 @@ end -- @DOC_awful_tooltip_margins_leftright_EXAMPLE@ -- -- @property margins_leftright --- @tparam number New margins value. +-- @tparam number margins_leftright New margins value. -- @propemits true false function tooltip:set_margin_leftright(val) @@ -538,7 +540,7 @@ end -- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@ -- -- @property margins_topbottom --- @tparam number New margins value. +-- @tparam number margins_topbottom New margins value. -- @propemits true false function tooltip:set_margin_topbottom(val) @@ -557,7 +559,7 @@ end -- @DOC_awful_tooltip_gaps_EXAMPLE@ -- -- @property gaps --- @tparam number|table New margins value. +-- @tparam number|table gaps New margins value. -- @propemits true false function tooltip:set_gaps(val) @@ -617,14 +619,14 @@ end -- @tparam[opt=apply_dpi(5)] integer args.margin_leftright The left/right margin for the text. -- @tparam[opt=apply_dpi(3)] integer args.margin_topbottom The top/bottom margin for the text. -- @tparam[opt=nil] gears.shape args.shape The shape. --- @tparam[opt] string args.bg The background color. --- @tparam[opt] string args.fg The foreground color. --- @tparam[opt] string args.border_color The tooltip border color. --- @tparam[opt] number args.border_width The tooltip border width. +-- @tparam[opt=beautiful.tooltip_bg] string args.bg The background color. +-- @tparam[opt=beautiful.tooltip_fg] string args.fg The foreground color. +-- @tparam[opt=beautiful.tooltip_border_color] string args.border_color The tooltip border color. +-- @tparam[opt=beautiful.tooltip_border_width] number args.border_width The tooltip border width. -- @tparam[opt] string args.align The horizontal alignment. --- @tparam[opt] string args.font The tooltip font. --- @tparam[opt] number args.opacity The tooltip opacity. --- @tparam[opt] table|number args.gaps The tooltip margins. +-- @tparam[opt=beautiful.tooltip_font] string args.font The tooltip font. +-- @tparam[opt=beautiful.tooltip_opacity] number args.opacity The tooltip opacity. +-- @tparam[opt=beautiful.tooltip_gaps] table|number args.gaps The tooltip margins. -- @treturn awful.tooltip The created tooltip. -- @see add_to_object -- @see timeout diff --git a/lib/awful/util.lua b/lib/awful/util.lua index 3d4677c7a..70ac0607b 100644 --- a/lib/awful/util.lua +++ b/lib/awful/util.lua @@ -1,5 +1,8 @@ --------------------------------------------------------------------------- ---- Utility module for awful. +--- Various small utility functions not worth putting into new modules. +-- +-- Most functions in this module are eventually moved into new modules are +-- deprecated. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou @@ -19,11 +22,7 @@ local gstring = require("gears.string") local grect = require("gears.geometry").rectangle local gcolor = require("gears.color") local gfs = require("gears.filesystem") -local capi = -{ - awesome = awesome, - mouse = mouse -} +local capi = { awesome = awesome } local gdebug = require("gears.debug") local gmath = require("gears.math") @@ -38,6 +37,7 @@ util.shell = os.getenv("SHELL") or "/bin/sh" -- This function implementation **has been removed** and no longer -- do anything. Use `awful.spawn.easy_async`. -- @deprecated awful.util.pread +-- @see awful.spawn.easy_async --- Display a deprecation notice, but only once per traceback. -- @deprecated deprecate @@ -99,6 +99,12 @@ function util.mkdir(dir) end --- Eval Lua code. +-- +-- It can either be "real" code or expressions like `2 ~= 3`. +-- If the expression cannot be interpreted or returns false, this +-- function calls `error`. +-- +-- @tparam string code The code to evaluate. -- @return The return value of Lua code. -- @staticfct awful.util.eval function util.eval(s) @@ -128,7 +134,7 @@ end --- Check if a file is a Lua valid file. -- This is done by loading the content and compiling it with loadfile(). --- @param path The file path. +-- @tparam string path The file path. -- @return A function if everything is alright, a string with the error -- otherwise. -- @staticfct awful.util.checkfile @@ -222,13 +228,16 @@ function util.getdir(d) end --- Search for an icon and return the full path. +-- -- It searches for the icon path under the given directories with respect to the -- given extensions for the icon filename. --- @param iconname The name of the icon to search for. --- @param exts Table of image extensions allowed, otherwise { 'png', gif' } --- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' } +-- @tparam string iconname The name of the icon to search for. +-- @tparam[opt={'png','gif'}] table exts Table of image extensions allowed. +-- @tparam[opt={'/usr/share/pixmaps/','/usr/share/icons/hicolor/'}] table dirs +-- Table of dirs to search. -- @tparam[opt] string size The size. If this is specified, subdirectories `x` -- of the dirs are searched first. +-- @treturn string|nil The icon path or `nil` if not found. -- @staticfct awful.util.geticonpath function util.geticonpath(iconname, exts, dirs, size) exts = exts or { 'png', 'gif' } @@ -326,8 +335,8 @@ end -- -- Note that this method doesn't copy entries found in `__index`. -- @deprecated util.table.crush --- @tparam table t the table to be overridden --- @tparam table set the table used to override members of `t` +-- @tparam table t The table to be overridden +-- @tparam table set The table used to override members of `t` -- @tparam[opt=false] boolean raw Use rawset (avoid the metatable) -- @treturn table t (for convenience) -- @see gears.table @@ -387,7 +396,7 @@ end --- Get a sorted table with all keys from a table. -- @deprecated util.table.keys --- @param t the table for which the keys to get +-- @param t The table for which the keys to get -- @return A table with keys -- @see gears.table function util.table.keys(t) @@ -398,7 +407,7 @@ end --- Filter a tables keys for certain content types -- @deprecated util.table.keys_filter -- @param t The table to retrieve the keys for --- @param ... the types to look for +-- @param ... The types to look for -- @return A filtered table with keys -- @see gears.table function util.table.keys_filter(t, ...) @@ -408,7 +417,7 @@ end --- Reverse a table -- @deprecated util.table.reverse --- @param t the table to reverse +-- @param t The table to reverse -- @return the reversed table -- @see gears.table function util.table.reverse(t) @@ -418,7 +427,7 @@ end --- Clone a table -- @deprecated util.table.clone --- @param t the table to clone +-- @param t The table to clone -- @param deep Create a deep clone? (default: true) -- @return a clone of t -- @see gears.table @@ -432,9 +441,9 @@ end -- given index, all elements of a table that match a given criteria. -- -- @deprecated util.table.iterate --- @param t the table to iterate --- @param filter a function that returns true to indicate a positive match --- @param start what index to start iterating from. Default is 1 (=> start of +-- @tparam table t The table to iterate. +-- @tparam function filter A function that returns true to indicate a positive match +-- @param start What index to start iterating from. Default is 1 (=> start of -- the table) -- @see gears.table function util.table.iterate(t, filter, start) @@ -445,8 +454,8 @@ end --- Merge items from the one table to another one -- @deprecated util.table.merge --- @tparam table t the container table --- @tparam table set the mixin table +-- @tparam table t The container table +-- @tparam table set The mixin table -- @treturn table Return `t` for convenience -- @see gears.table function util.table.merge(t, set) diff --git a/lib/awful/wallpaper.lua b/lib/awful/wallpaper.lua index e9374d1ba..19dd08c9f 100644 --- a/lib/awful/wallpaper.lua +++ b/lib/awful/wallpaper.lua @@ -470,6 +470,7 @@ end) -- -- @property bg -- @tparam gears.color bg +-- @usebeautiful beautiful.wallpaper_bg -- @see gears.color --- The foreground color. @@ -485,6 +486,7 @@ end) --- The default wallpaper background color. -- @beautiful beautiful.wallpaper_bg -- @tparam gears.color wallpaper_bg +-- @usebeautiful beautiful.wallpaper_fg -- @see bg --- The default wallpaper foreground color. diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index b3043a117..02377e292 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -537,6 +537,19 @@ end --@DOC_wibox_constructor_COMMON@ -- @return The new wibar -- @constructorfct awful.wibar +-- @usebeautiful beautiful.wibar_favor_vertical +-- @usebeautiful beautiful.wibar_border_width +-- @usebeautiful beautiful.wibar_border_color +-- @usebeautiful beautiful.wibar_ontop +-- @usebeautiful beautiful.wibar_cursor +-- @usebeautiful beautiful.wibar_opacity +-- @usebeautiful beautiful.wibar_type +-- @usebeautiful beautiful.wibar_width +-- @usebeautiful beautiful.wibar_height +-- @usebeautiful beautiful.wibar_bg +-- @usebeautiful beautiful.wibar_bgimage +-- @usebeautiful beautiful.wibar_fg +-- @usebeautiful beautiful.wibar_shape function awfulwibar.new(args) args = args or {} local position = args.position or "top" diff --git a/lib/awful/widget/button.lua b/lib/awful/widget/button.lua index c5b4282bd..c71dc8831 100644 --- a/lib/awful/widget/button.lua +++ b/lib/awful/widget/button.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A simple button widget. +-- A simple button widget based on a background image. -- -- @DOC_wibox_awidget_defaults_button_EXAMPLE@ -- diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 50f76ecb2..5ec6effa9 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A calendar popup wibox. +-- A popup wibox containing a `wibox.widget,calendar` widget. -- -- Display a month or year calendar popup using `calendar_popup.month` or `calendar_popup.year`. -- The calendar style can be tweaked by providing tables of style properties at creation: @@ -386,6 +386,7 @@ end -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`) -- @treturn wibox A wibox containing the calendar -- @constructorfct awful.widget.calendar_popup.month +-- @usebeautiful beautiful.calendar_style function calendar_popup.month(args) return get_cal_wibox("month", args) end diff --git a/lib/awful/widget/clienticon.lua b/lib/awful/widget/clienticon.lua index 1ddc3f1bb..a3151899b 100644 --- a/lib/awful/widget/clienticon.lua +++ b/lib/awful/widget/clienticon.lua @@ -86,7 +86,7 @@ end --- The widget's @{client}. -- -- @property client --- @param client +-- @tparam client client -- @propemits true false function clienticon:get_client() diff --git a/lib/awful/widget/common.lua b/lib/awful/widget/common.lua index c45143fa4..ef665229d 100644 --- a/lib/awful/widget/common.lua +++ b/lib/awful/widget/common.lua @@ -1,4 +1,10 @@ --------------------------------------------------------------------------- +-- This module contains helper functions to manage a layout widgets. +-- +-- This is the boilerplate code to manage a "list" of objects and display +-- them in a `wibox.layout`. It uses signals to detect when an object change +-- and its widget be updated. +-- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou -- @classmod awful.widget.common diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index ecb2a26e1..a512d9fdc 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -1,4 +1,7 @@ --------------------------------------------------------------------------- +-- Display the current keyboard layout name in a widget. +-- +-- -- @author Aleksey Fedotov <lexa@cfotr.com> -- @copyright 2015 Aleksey Fedotov -- @widgetmod awful.widget.keyboardlayout @@ -132,7 +135,7 @@ end -- Create an array whose element is a table consisting of the four fields: -- vendor, file, section and group_idx, which all correspond to the -- xkb_symbols pattern "vendor/file(section):group_idx". --- @tparam string group_names The string awesome.xkb_get_group_names() returns. +-- @tparam string group_names The string `awesome.xkb_get_group_names()` returns. -- @treturn table An array of tables whose keys are vendor, file, section, and group_idx. -- @staticfct awful.keyboardlayout.get_groups_from_group_names function keyboardlayout.get_groups_from_group_names(group_names) @@ -260,7 +263,7 @@ end -- It shows current keyboard layout name in a textbox. -- -- @constructorfct awful.widget.keyboardlayout --- @return A keyboard layout widget. +-- @treturn awful.widget.keyboardlayout A keyboard layout widget. function keyboardlayout.new() local widget = textbox() local self = widget_base.make_widget(widget, nil, {enable_properties=true}) diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index 9edc97e23..ba44437b9 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -178,33 +178,38 @@ end local layoutlist = {} --- The layoutlist default widget layout. +-- -- If no layout is specified, a `wibox.layout.fixed.vertical` will be created -- automatically. -- @property base_layout --- @param widget +-- @tparam[opt=wibox.layout.fixed.vertical] wibox.layout base_layout -- @propemits true false -- @see wibox.layout.fixed.vertical -- @see base_layout --- The delegate widget template. +-- -- @property widget_template --- @param table +-- @tparam[opt=nil] table widget_template -- @propemits true false --- The layoutlist screen. +-- -- @property screen --- @param screen +-- @tparam screen screen --- A function that returns the list of layout to display. -- -- @property source --- @param[opt=awful.widget.layoutlist.source.for_screen] function +-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function source --- The layoutlist filter function. +-- -- @property filter --- @param[opt=awful.widget.layoutlist.source.for_screen] function +-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function filter --- The default foreground (text) color. +-- -- @beautiful beautiful.layoutlist_fg_normal -- @tparam[opt=nil] string|pattern fg_normal -- @see gears.color @@ -276,17 +281,17 @@ local layoutlist = {} --- The currenly displayed layouts. -- @property layouts --- @param table +-- @tparam table layouts --- The currently selected layout. -- @property current_layout --- @param layout +-- @tparam layout current_layout --- The current number of layouts. -- -- @property count -- @readonly --- @tparam number The number of layouts. +-- @tparam number count The number of layouts. -- @propemits true false function layoutlist:get_layouts() @@ -395,22 +400,22 @@ end -- @tparam[opt] table args.widget_template A custom widget to be used for each action. -- @tparam[opt=ascreen.focused()] screen args.screen A screen -- @tparam[opt={}] table args.style Extra look and feel parameters --- @tparam boolean args.style.disable_icon --- @tparam boolean args.style.disable_name --- @tparam string|pattern args.style.fg_normal --- @tparam string|pattern args.style.bg_normal --- @tparam string|pattern args.style.fg_selected --- @tparam string|pattern args.style.bg_selected --- @tparam string args.style.font --- @tparam string args.style.font_selected --- @tparam string args.style.align *left*, *right* or *center* --- @tparam number args.style.spacing --- @tparam gears.shape args.style.shape --- @tparam number args.style.shape_border_width --- @tparam string|pattern args.style.shape_border_color --- @tparam gears.shape args.style.shape_selected --- @tparam string|pattern args.style.shape_border_width_selected --- @tparam string|pattern args.style.shape_border_color_selected +-- @tparam[opt=beautiful.layoutlist_disable_icon] boolean args.style.disable_icon +-- @tparam[opt=beautiful.layoutlist_disable_name] boolean args.style.disable_name +-- @tparam[opt=beautiful.layoutlist_fg_normal] string|pattern args.style.fg_normal +-- @tparam[opt=beautiful.layoutlist_bg_normal] string|pattern args.style.bg_normal +-- @tparam[opt=beautiful.layoutlist_fg_selected] string|pattern args.style.fg_selected +-- @tparam[opt=beautiful.layoutlist_bg_selected] string|pattern args.style.bg_selected +-- @tparam[opt=beautiful.layoutlist_font] string args.style.font +-- @tparam[opt=beautiful.layoutlist_font_selected] string args.style.font_selected +-- @tparam[opt=beautiful.layoutlist_align] string args.style.align *left*, *right* or *center* +-- @tparam[opt=beautiful.layoutlist_spacing] number args.style.spacing +-- @tparam[opt=beautiful.layoutlist_shape] gears.shape args.style.shape +-- @tparam[opt=beautiful.layoutlist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.layoutlist_shape_border_color] string|pattern args.style.shape_border_color +-- @tparam[opt=beautiful.layoutlist_shape_selected] gears.shape args.style.shape_selected +-- @tparam[opt=beautiful.layoutlist_shape_border_width_selected] string|pattern args.style.shape_border_width_selected +-- @tparam[opt=beautiful.layoutlist_shape_border_color_selected] string|pattern args.style.shape_border_color_selected -- @treturn widget The action widget. -- @constructorfct awful.widget.layoutlist diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua index 368a6add8..3dfa0519a 100644 --- a/lib/awful/widget/only_on_screen.lua +++ b/lib/awful/widget/only_on_screen.lua @@ -80,7 +80,7 @@ function only_on_screen:get_screen() return self._private.screen end ---- Returns a new only_on_screen container. +--- Returns a new `awful.widget.only_on_screen` container. -- This widget makes some other widget visible on just some screens. Use -- `:set_widget()` to set the widget and `:set_screen()` to set the screen. -- @param[opt] widget The widget to display. diff --git a/lib/awful/widget/prompt.lua b/lib/awful/widget/prompt.lua index 4dfaef49f..f1a38257d 100644 --- a/lib/awful/widget/prompt.lua +++ b/lib/awful/widget/prompt.lua @@ -73,7 +73,7 @@ end -- of `awful.spawn`. Depending on the amount of customization to your shell -- environment, this can increase startup time. -- @property with_shell --- @param[opt=false] boolean +-- @tparam[opt=false] boolean with_shell --- Create a prompt widget which will launch a command. -- For additional documentation about `args` parameter, please refer to @@ -85,10 +85,10 @@ end -- Prompt background color. -- @tparam[opt=`beautiful.prompt_fg` or `beautiful.fg_normal`] color args.fg -- Prompt foreground color. --- @tparam[opt] gears.color args.fg_cursor --- @tparam[opt] gears.color args.bg_cursor +-- @tparam[opt=beautiful.prompt_fg_cursor] gears.color args.fg_cursor +-- @tparam[opt=beautiful.prompt_bg_cursor] gears.color args.bg_cursor -- @tparam[opt] gears.color args.ul_cursor --- @tparam[opt] string args.font +-- @tparam[opt=beautiful.prompt_font] string args.font -- @tparam[opt] boolean args.autoexec -- @tparam[opt] function args.highlighter A function to add syntax highlighting -- to the command. @@ -116,6 +116,10 @@ end -- @return An instance of prompt widget, inherits from -- `wibox.container.background`. -- @constructorfct awful.widget.prompt +-- @usebeautiful beautiful.prompt_fg +-- @usebeautiful beautiful.prompt_bg +-- @usebeautiful beautiful.fg_normal When `beautiful.prompt_fg` isn't set. +-- @usebeautiful beautiful.bg_normal When `beautiful.prompt_bg` isn't set. function widgetprompt.new(args) args = args or {} local promptbox = background() diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index 3b8f895f5..9894c35b9 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -431,7 +431,7 @@ end -- -- @property count -- @readonly --- @tparam number The number of tags. +-- @tparam number count The number of tags. -- @propemits true false function taglist:set_base_layout(layout) @@ -482,7 +482,7 @@ end -- API is very low level. -- -- @property update_function --- @tparam function update_function. +-- @tparam function update_function --- A function to restrict the content of the taglist. -- @@ -542,34 +542,45 @@ end -- function used to generate the list of tag. -- @tparam[opt] table args.widget_template A custom widget to be used for each tag -- @tparam[opt={}] table args.style The style overrides default theme. --- @tparam[opt=nil] string|pattern args.style.fg_focus --- @tparam[opt=nil] string|pattern args.style.bg_focus --- @tparam[opt=nil] string|pattern args.style.fg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_occupied --- @tparam[opt=nil] string|pattern args.style.fg_occupied --- @tparam[opt=nil] string|pattern args.style.bg_empty --- @tparam[opt=nil] string|pattern args.style.fg_empty --- @tparam[opt=nil] string|pattern args.style.bg_volatile --- @tparam[opt=nil] string|pattern args.style.fg_volatile --- @tparam[opt=nil] string args.style.squares_sel --- @tparam[opt=nil] string args.style.squares_unsel --- @tparam[opt=nil] string args.style.squares_sel_empty --- @tparam[opt=nil] string args.style.squares_unsel_empty --- @tparam[opt=nil] string args.style.squares_resize --- @tparam[opt=nil] string args.style.disable_icon --- @tparam[opt=nil] string args.style.font --- @tparam[opt=nil] number args.style.spacing The spacing between tags. --- @tparam[opt] string args.style.squares_sel A user provided image for selected squares. --- @tparam[opt] string args.style.squares_unsel A user provided image for unselected squares. --- @tparam[opt] string args.style.squares_sel_empty A user provided image for selected squares for empty tags. --- @tparam[opt] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags. --- @tparam[opt] boolean args.style.squares_resize True or false to resize squares. --- @tparam string|pattern args.style.bg_focus The background color for focused client. --- @tparam string|pattern args.style.fg_focus The foreground color for focused client. --- @tparam string|pattern args.style.bg_urgent The background color for urgent clients. --- @tparam string|pattern args.style.fg_urgent The foreground color for urgent clients. --- @tparam string args.style.font The font. +-- @tparam[opt=beautiful.taglist_fg_focus] string|pattern args.style.fg_focus +-- @tparam[opt=beautiful.taglist_bg_focus] string|pattern args.style.bg_focus +-- @tparam[opt=beautiful.taglist_fg_urgent] string|pattern args.style.fg_urgent +-- @tparam[opt=beautiful.taglist_bg_urgent] string|pattern args.style.bg_urgent +-- @tparam[opt=beautiful.taglist_bg_occupied] string|pattern args.style.bg_occupied +-- @tparam[opt=beautiful.taglist_fg_occupied] string|pattern args.style.fg_occupied +-- @tparam[opt=beautiful.taglist_bg_empty] string|pattern args.style.bg_empty +-- @tparam[opt=beautiful.taglist_fg_empty] string|pattern args.style.fg_empty +-- @tparam[opt=beautiful.taglist_bg_volatile] string|pattern args.style.bg_volatile +-- @tparam[opt=beautiful.taglist_fg_volatile] string|pattern args.style.fg_volatile +-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel +-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel +-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty +-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty +-- @tparam[opt=beautiful.taglist_squares_resize] string args.style.squares_resize +-- @tparam[opt=beautiful.taglist_disable_icon] string args.style.disable_icon +-- @tparam[opt=beautiful.taglist_font] string args.style.font +-- @tparam[opt=beautiful.taglist_spacing] number args.style.spacing The spacing between tags. +-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel A user provided image for selected squares. +-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel A user provided image for unselected squares. +-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty A user provided image for selected squares for empty tags. +-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags. +-- @tparam[opt=beautiful.taglist_squares_resize] boolean args.style.squares_resize True or false to resize squares. +-- @tparam[opt=beautiful.taglist_font] string args.style.font The font. +-- @tparam[opt=beautiful.taglist_shape] gears.shape|function args.style.shape +-- @tparam[opt=beautiful.taglist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.taglist_shape_border_color] string args.style.shape_border_color +-- @tparam[opt=beautiful.taglist_shape_empty] gears.shape|function args.style.shape_empty +-- @tparam[opt=beautiful.taglist_shape_border_width_empty] number args.style.shape_border_width_empty +-- @tparam[opt=beautiful.taglist_shape_border_color_empty] string args.style.border_color_empty +-- @tparam[opt=beautiful.taglist_shape_focus] gears.shape|function args.style.shape_focus +-- @tparam[opt=beautiful.taglist_shape_border_width_focus] number args.style.shape_border_width_focus +-- @tparam[opt=beautiful.taglist_shape_border_color_focus] string args.style.shape_border_color_focus +-- @tparam[opt=beautiful.taglist_shape_urgent] gears.shape|function args.style.shape_urgent +-- @tparam[opt=beautiful.taglist_shape_border_width_urgent] number args.style.shape_border_width_urgent +-- @tparam[opt=beautiful.taglist_shape_border_color_urgent] string args.style.shape_border_color_urgent +-- @tparam[opt=beautiful.taglist_shape_volatile] gears.shape|function args.style.shape_volatile +-- @tparam[opt=beautiful.taglist_shape_border_width_volatile] number args.style.shape_border_width_volatile +-- @tparam[opt=beautiful.taglist_shape_border_color_volatile] string args.style.shape_border_color_volatile -- @param filter **DEPRECATED** use args.filter -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 7fbff70c3..d352ff104 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -377,6 +377,10 @@ local instances -- @tparam[opt=nil] string|color shape_border_color_urgent -- @see gears.color +--- The icon size. +-- @beautiful beautiful.tasklist_icon_size +-- @tparam[opt=nil] integer tasklist_icon_size + -- Public structures tasklist.filter, tasklist.source = {}, {} @@ -605,7 +609,7 @@ end -- -- @property count -- @readonly --- @tparam number The number of client. +-- @tparam number count The number of client. -- @propemits true false --- Set the tasklist layout. @@ -799,53 +803,54 @@ end -- function used to generate the list of client. -- @tparam[opt] table args.widget_template A custom widget to be used for each client -- @tparam[opt={}] table args.style The style overrides default theme. --- @tparam[opt=nil] string|pattern args.style.fg_normal --- @tparam[opt=nil] string|pattern args.style.bg_normal --- @tparam[opt=nil] string|pattern args.style.fg_focus --- @tparam[opt=nil] string|pattern args.style.bg_focus --- @tparam[opt=nil] string|pattern args.style.fg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_urgent --- @tparam[opt=nil] string|pattern args.style.fg_minimize --- @tparam[opt=nil] string|pattern args.style.bg_minimize --- @tparam[opt=nil] string args.style.bg_image_normal --- @tparam[opt=nil] string args.style.bg_image_focus --- @tparam[opt=nil] string args.style.bg_image_urgent --- @tparam[opt=nil] string args.style.bg_image_minimize --- @tparam[opt=nil] boolean args.style.disable_icon --- @tparam[opt=nil] number args.style.icon_size The size of the icon --- @tparam[opt='▪'] string args.style.sticky Extra icon when client is sticky --- @tparam[opt='⌃'] string args.style.ontop Extra icon when client is ontop --- @tparam[opt='▴'] string args.style.above Extra icon when client is above --- @tparam[opt='▾'] string args.style.below Extra icon when client is below --- @tparam[opt='✈'] string args.style.floating Extra icon when client is floating --- @tparam[opt='+'] string args.style.maximized Extra icon when client is maximized --- @tparam[opt='⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal --- @tparam[opt='⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical --- @tparam[opt=false] boolean args.style.disable_task_name --- @tparam[opt=nil] string args.style.font --- @tparam[opt="left"] string args.style.align *left*, *right* or *center* --- @tparam[opt=nil] string args.style.font_focus --- @tparam[opt=nil] string args.style.font_minimized --- @tparam[opt=nil] string args.style.font_urgent --- @tparam[opt=nil] number args.style.spacing The spacing between tags. --- @tparam[opt=nil] gears.shape args.style.shape --- @tparam[opt=nil] number args.style.shape_border_width --- @tparam[opt=nil] string|color args.style.shape_border_color --- @tparam[opt=nil] gears.shape args.style.shape_focus --- @tparam[opt=nil] number args.style.shape_border_width_focus --- @tparam[opt=nil] string|color args.style.shape_border_color_focus --- @tparam[opt=nil] gears.shape args.style.shape_minimized --- @tparam[opt=nil] number args.style.shape_border_width_minimized --- @tparam[opt=nil] string|color args.style.shape_border_color_minimized --- @tparam[opt=nil] gears.shape args.style.shape_urgent --- @tparam[opt=nil] number args.style.shape_border_width_urgent --- @tparam[opt=nil] string|color args.style.shape_border_color_urgent +-- @tparam[opt=beautiful.tasklist_fg_normal] string|pattern args.style.fg_normal +-- @tparam[opt=beautiful.tasklist_bg_normal] string|pattern args.style.bg_normal +-- @tparam[opt=beautiful.tasklist_fg_focus or beautiful.fg_focus] string|pattern args.style.fg_focus +-- @tparam[opt=beautiful.tasklist_bg_focus or beautiful.bg_focus] string|pattern args.style.bg_focus +-- @tparam[opt=beautiful.tasklist_fg_urgent or beautiful.fg_urgent] string|pattern args.style.fg_urgent +-- @tparam[opt=beautiful.tasklist_bg_urgent or beautiful.bg_urgent] string|pattern args.style.bg_urgent +-- @tparam[opt=beautiful.tasklist_fg_minimize or beautiful.fg_minimize] string|pattern args.style.fg_minimize +-- @tparam[opt=beautiful.tasklist_bg_minimize or beautiful.bg_minimize] string|pattern args.style.bg_minimize +-- @tparam[opt=beautiful.tasklist_bg_image_normal] string args.style.bg_image_normal +-- @tparam[opt=beautiful.tasklist_bg_image_focus] string args.style.bg_image_focus +-- @tparam[opt=beautiful.tasklist_bg_image_urgent] string args.style.bg_image_urgent +-- @tparam[opt=beautiful.tasklist_bg_image_minimize] string args.style.bg_image_minimize +-- @tparam[opt=beautiful.tasklist_disable_icon] boolean args.style.disable_icon +-- @tparam[opt=beautiful.tasklist_icon_size] number args.style.icon_size The size of the icon +-- @tparam[opt=beautiful.tasklist_sticky or '▪'] string args.style.sticky Extra icon when client is sticky +-- @tparam[opt=beautiful.tasklist_ontop or '⌃'] string args.style.ontop Extra icon when client is ontop +-- @tparam[opt=beautiful.tasklist_above or '▴'] string args.style.above Extra icon when client is above +-- @tparam[opt=beautiful.tasklist_below or '▾'] string args.style.below Extra icon when client is below +-- @tparam[opt=beautiful.tasklist_floating or '✈'] string args.style.floating Extra icon when client is floating +-- @tparam[opt=beautiful.tasklist_maximized or '+'] string args.style.maximized Extra icon when client is maximized +-- @tparam[opt=beautiful.tasklist_maximized_horizontal or '⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal +-- @tparam[opt=beautiful.tasklist_maximized_vertical or '⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical +-- @tparam[opt=beautiful.tasklist_disable_task_name or false] boolean args.style.disable_task_name +-- @tparam[opt=beautiful.tasklist_font] string args.style.font +-- @tparam[opt=beautiful.tasklist_align or "left"] string args.style.align *left*, *right* or *center* +-- @tparam[opt=beautiful.tasklist_font_focus] string args.style.font_focus +-- @tparam[opt=beautiful.tasklist_font_minimized] string args.style.font_minimized +-- @tparam[opt=beautiful.tasklist_font_urgent] string args.style.font_urgent +-- @tparam[opt=beautiful.tasklist_spacing] number args.style.spacing The spacing between tags. +-- @tparam[opt=beautiful.tasklist_shape] gears.shape args.style.shape +-- @tparam[opt=beautiful.tasklist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.tasklist_shape_border_color] string|color args.style.shape_border_color +-- @tparam[opt=beautiful.tasklist_shape_focus] gears.shape args.style.shape_focus +-- @tparam[opt=beautiful.tasklist_shape_border_width_focus] number args.style.shape_border_width_focus +-- @tparam[opt=beautiful.tasklist_shape_border_color_focus] string|color args.style.shape_border_color_focus +-- @tparam[opt=beautiful.tasklist_shape_minimized] gears.shape args.style.shape_minimized +-- @tparam[opt=beautiful.tasklist_shape_border_width_minimized] number args.style.shape_border_width_minimized +-- @tparam[opt=beautiful.tasklist_shape_border_color_minimized] string|color args.style.shape_border_color_minimized +-- @tparam[opt=beautiful.tasklist_shape_urgent] gears.shape args.style.shape_urgent +-- @tparam[opt=beautiful.tasklist_shape_border_width_urgent] number args.style.shape_border_width_urgent +-- @tparam[opt=beautiful.tasklist_shape_border_color_urgent] string|color args.style.shape_border_color_urgent -- @param filter **DEPRECATED** use args.filter -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function -- @param base_widget **DEPRECATED** use args.base_layout -- @constructorfct awful.widget.tasklist +-- @usebeautiful beautiful.tasklist_plain_task_name function tasklist.new(args, filter, buttons, style, update_function, base_widget) local screen = nil diff --git a/lib/awful/widget/watch.lua b/lib/awful/widget/watch.lua index 090fcb9e0..9dfca6f16 100644 --- a/lib/awful/widget/watch.lua +++ b/lib/awful/widget/watch.lua @@ -1,5 +1,6 @@ --------------------------------------------------------------------------- ---- Watch widget. +--- Execute a command at a set interval and display its output. +-- -- Here is an example of simple temperature widget which will update each 15 -- seconds implemented in two different ways. -- The first, simpler one, will just display the return command output @@ -7,20 +8,18 @@ -- In the other example `sensors` returns to the widget its full output -- and it's trimmed in the widget callback function: -- --- 211 mytextclock, --- 212 wibox.widget.textbox(' | '), --- 213 -- one way to do that: --- 214 awful.widget.watch('bash -c "sensors | grep temp1"', 15), --- 215 -- another way: --- 216 awful.widget.watch('sensors', 15, function(widget, stdout) --- 217 for line in stdout:gmatch("[^\r\n]+") do --- 218 if line:match("temp1") then --- 219 widget:set_text(line) --- 220 return --- 221 end --- 222 end --- 223 end), --- 224 s.mylayoutbox, +-- -- one way to do that: +-- local w = awful.widget.watch('bash -c "sensors | grep temp1"', 15) +-- +-- -- another way: +-- local w = awful.widget.watch('sensors', 15, function(widget, stdout) +-- for line in stdout:gmatch("[^\r\n]+") do +-- if line:match("temp1") then +-- widget:set_text(line) +-- return +-- end +-- end +-- end) -- -- ![Example screenshot](../images/awful_widget_watch.png) -- @@ -55,7 +54,7 @@ local watch = { mt = {} } -- function(widget, stdout, stderr, exitreason, exitcode) -- widget:set_text(stdout) -- end --- @param callback.widget Base widget instance. +-- @tparam wibox.widget callback.widget Base widget instance. -- @tparam string callback.stdout Output on stdout. -- @tparam string callback.stderr Output on stderr. -- @tparam string callback.exitreason Exit Reason. @@ -64,7 +63,7 @@ local watch = { mt = {} } -- For "exit" reason it's the exit code. -- For "signal" reason — the signal causing process termination. -- --- @param[opt=wibox.widget.textbox()] base_widget Base widget. +-- @tparam[opt=wibox.widget.textbox()] wibox.widget base_widget Base widget. -- -- @return The widget used by this watch. -- @return Its gears.timer. diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index 9db96f254..44601324c 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- Theme library. +--- Key+value based theme library and associated utility modules. -- -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> @@ -89,62 +89,52 @@ local active_font --- The default font. -- @beautiful beautiful.font --- @param string +-- @param[opt="sans 8"] string --- The default background color. +--- The default background color. +-- +-- The background color can be transparent. If there is a +-- compositing manager such as compton, then it will be +-- real transparency and may include blur (provided by the +-- compositor). When there is no compositor, it will take +-- a picture of the wallpaper and blend it. +-- -- @beautiful beautiful.bg_normal -- @param color --- The default focused element background color. +--- The default focused element background color. -- @beautiful beautiful.bg_focus -- @param color --- The default urgent element background color. +--- The default urgent element background color. -- @beautiful beautiful.bg_urgent -- @param color --- The default minimized element background color. +--- The default minimized element background color. -- @beautiful beautiful.bg_minimize -- @param color --- The system tray background color. --- Please note that only solid colors are currently supported. --- @beautiful beautiful.bg_systray --- @param color - --- The default focused element foreground (text) color. +--- The default focused element foreground (text) color. -- @beautiful beautiful.fg_normal -- @param color --- The default focused element foreground (text) color. +--- The default focused element foreground (text) color. -- @beautiful beautiful.fg_focus -- @param color --- The default urgent element foreground (text) color. +--- The default urgent element foreground (text) color. -- @beautiful beautiful.fg_urgent -- @param color --- The default minimized element foreground (text) color. +--- The default minimized element foreground (text) color. -- @beautiful beautiful.fg_minimize -- @param color ---- The gap between clients. --- @beautiful beautiful.useless_gap --- @param[opt=0] number - ---- The fallback border width. --- @beautiful beautiful.border_width --- @param number - ---- The fallback border color. --- @beautiful beautiful.border_color --- @param color - --- The wallpaper path. -- @beautiful beautiful.wallpaper -- @tparam string|gears.surface wallpaper --- The icon theme name. +--- The icon theme name. -- It has to be a directory in `/usr/share/icons` or an XDG icon folder. -- @beautiful beautiful.icon_theme -- @param string @@ -234,7 +224,7 @@ end --- Get the height of a font. -- --- @param name Name of the font. +-- @tparam string name Name of the font. -- @staticfct beautiful.get_font_height function beautiful.get_font_height(name) return load_font(name).height diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua index 49aac58e5..835e099fd 100644 --- a/lib/gears/debug.lua +++ b/lib/gears/debug.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Utility functions to make development easier. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @utillib gears.debug @@ -141,7 +143,7 @@ end -- @tparam table fallback The new class. -- @tparam string old_name The old class name. -- @tparam string new_name The new class name. --- @tparam[opt={}] args The name. +-- @tparam[opt={}] table args The name. -- @tparam[opt] number args.deprecated_in The version which deprecated this -- class. -- @treturn table A proxy class. diff --git a/lib/gears/filesystem.lua b/lib/gears/filesystem.lua index de58e1a70..64aa43ae0 100644 --- a/lib/gears/filesystem.lua +++ b/lib/gears/filesystem.lua @@ -1,5 +1,8 @@ --------------------------------------------------------------------------- ---- Filesystem module for gears. +--- Various filesystem utility functions. +-- +-- Note that these functions are blocking. If you need to do a large number of +-- I/O operations, it is better to use `lgi.Gio` async functions. -- -- @utillib gears.filesystem --------------------------------------------------------------------------- diff --git a/lib/gears/math.lua b/lib/gears/math.lua index db295f673..38eddaeb4 100644 --- a/lib/gears/math.lua +++ b/lib/gears/math.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Various math related functions. +-- --- Math module for gears. -- -- @utillib gears.math diff --git a/lib/gears/protected_call.lua b/lib/gears/protected_call.lua index fb967d147..7c688ee29 100644 --- a/lib/gears/protected_call.lua +++ b/lib/gears/protected_call.lua @@ -1,4 +1,9 @@ --------------------------------------------------------------------------- +-- Safely call a function and handle errors using `gears.debug`. +-- +-- This is a `pcall`/`xpcall` wrapper. All it does is to integrate into the +-- AwesomeWM-wide error handling and logging. +-- -- @author Uli Schlachter -- @copyright 2016 Uli Schlachter -- @utillib gears.protected_call diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index 4af3d326f..b78c733c1 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -215,7 +215,7 @@ end -- @param cr A cairo content -- @tparam number width The rectangle width -- @tparam number height The rectangle height --- @tparam number radius the corner radius +-- @tparam number radius The corner radius -- @staticfct gears.shape.rounded_rect function module.rounded_rect(cr, width, height, radius) @@ -627,8 +627,8 @@ end -- @tparam[opt=math.min(width height)/2] number thickness The arc thickness -- @tparam[opt=0] number start_angle The start angle (in radian) -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian) --- @tparam[opt=false] boolean start_rounded if the arc start rounded --- @tparam[opt=false] boolean end_rounded if the arc end rounded +-- @tparam[opt=false] boolean start_rounded If the arc start rounded +-- @tparam[opt=false] boolean end_rounded If the arc end rounded -- @staticfct gears.shape.arc function module.arc(cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded) start_angle = start_angle or 0 diff --git a/lib/gears/sort/init.lua b/lib/gears/sort/init.lua index 02c2123f8..2488bd7f0 100644 --- a/lib/gears/sort/init.lua +++ b/lib/gears/sort/init.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Extra sorting algorithms. +--- Utilities to sort and arrange data. -- -- @utillib gears.sort --------------------------------------------------------------------------- diff --git a/lib/gears/string.lua b/lib/gears/string.lua index a4e4db951..229ed810b 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- String module for gears. +--- Various string manipulation and introspection fuctions. -- -- @utillib gears.string --------------------------------------------------------------------------- @@ -10,7 +10,7 @@ local xml_entity_names = { ["'"] = "'", ["\""] = """, ["<"] = "<", --- Escape a string from XML char. -- Useful to set raw text in textbox. --- @param text Text to escape. +-- @tparam string text Text to escape. -- @treturn string Escaped text. -- @staticfct gears.string.xml_escape function gstring.xml_escape(text) @@ -21,7 +21,7 @@ local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = " amp = "&" }; --- Unescape a string from entities. --- @param text Text to unescape. +-- @tparam string text Text to unescape. -- @treturn string Unescaped text. -- @staticfct gears.string.xml_unescape function gstring.xml_unescape(text) diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index a0c2d2b8f..3bf983571 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Utilities to integrate and manipulate Cairo drawing surfaces. +-- -- @author Uli Schlachter -- @copyright 2012 Uli Schlachter -- @module gears.surface @@ -195,10 +197,9 @@ end -- -- If the wibox or client size change, this function need to be called -- again. --- @param draw A wibox or a client --- @param shape or gears.shape function or a custom function with a context, --- width and height as parameter. --- @param[opt] Any additional parameters will be passed to the shape function. +-- @tparam client|wibox draw A wibox or a client. +-- @tparam gears.shape|function shape The shape. +-- @param[opt] ... Any additional parameters will be passed to the shape function. -- @staticfct apply_shape_bounding function surface.apply_shape_bounding(draw, shape, ...) local geo = draw:geometry() diff --git a/lib/gears/table.lua b/lib/gears/table.lua index b98aa66d8..9702c7bc2 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -1,8 +1,8 @@ --------------------------------------------------------------------------- ---- Table module for gears. +--- Various functions to worj with tables. -- -- Examples --- ======= +-- ======== -- -- Using `cycle_value`, you can cycle through values in a table. -- When the end of the table is reached, `cycle_value` loops around to the beginning. diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index b1a9644a4..c27ef6480 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Timer objects and functions. +--- Class to execute code at specific intervals. -- -- @usage -- -- Create a widget and update its content using the output of a shell @@ -134,13 +134,18 @@ function timer:again() end --- The timer is started. --- @property started --- @param boolean +-- +-- For this to be `true` by default, pass `autostart` to the constructor. +-- +-- @property[opt=false] started +-- @tparam boolean started +-- @see start +-- @see stop --- The timer timeout value. --- **Signal:** property::timeout +-- -- @property timeout --- @param number +-- @tparam number timeout -- @propemits true false local timer_instance_mt = { @@ -273,7 +278,7 @@ end --- Call the given function at the end of the current GLib event loop iteration. -- @tparam function callback The function that should be called --- @param ... Arguments to the callback function +--@param ... Arguments to the callback function -- @staticfct gears.timer.delayed_call function timer.delayed_call(callback, ...) assert(type(callback) == "function", "callback must be a function, got: " .. type(callback)) diff --git a/lib/menubar/icon_theme.lua b/lib/menubar/icon_theme.lua index 358f00737..b1946081d 100644 --- a/lib/menubar/icon_theme.lua +++ b/lib/menubar/icon_theme.lua @@ -82,6 +82,7 @@ local index_theme_cache = {} -- @tparam string icon_theme_name Internal name of icon theme -- @tparam table base_directories Paths used for lookup -- @treturn table An instance of the class `icon_theme` +-- @usebeautiful beautiful.icon_theme icon_theme.new = function(icon_theme_name, base_directories) icon_theme_name = icon_theme_name or beautiful.icon_theme or get_default_icon_theme_name() base_directories = base_directories or get_pragmatic_base_directories() diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index 88c8fa5ad..e594fafd1 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -454,6 +454,13 @@ end --- Show the menubar on the given screen. -- @param[opt] scr Screen. -- @staticfct menubar.show +-- @usebeautiful beautiful.menubar_fg_normal +-- @usebeautiful beautiful.menubar_bg_normal +-- @usebeautiful beautiful.menubar_border_width +-- @usebeautiful beautiful.menubar_border_color +-- @usebeautiful beautiful.menubar_fg_focus +-- @usebeautiful beautiful.menubar_bg_focus +-- @usebeautiful beautiful.menubar_font function menubar.show(scr) scr = get_screen(scr or awful.screen.focused() or 1) local fg_color = theme.menubar_fg_normal or theme.menu_fg_normal or theme.fg_normal diff --git a/lib/menubar/utils.lua b/lib/menubar/utils.lua index 9c8f283fd..a3f1e1945 100644 --- a/lib/menubar/utils.lua +++ b/lib/menubar/utils.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Utility module for menubar +--- Utility functions for the `menubar` module. -- -- @author Antonio Terceiro -- @copyright 2009, 2011-2012 Antonio Terceiro, Alexander Yakushev @@ -199,7 +199,7 @@ local function get_icon_lookup_path() end --- Remove CR newline from the end of the string. --- @param s string to trim +-- @tparam string s The string to trim -- @staticfct menubar.utils.rtrim function utils.rtrim(s) if not s then return end diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index 92078d744..a9576c8b3 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -35,12 +35,12 @@ local action = {} -- implement keyboard navigation. -- -- @property selected --- @param boolean +-- @tparam boolean selected -- @propemits true false --- The action position (index). -- @property position --- @param number +-- @tparam number position -- @propemits true false --- The action icon. @@ -53,7 +53,7 @@ local action = {} -- @DOC_wibox_nwidget_actionlist_icon_only_EXAMPLE@ -- -- @property icon_only --- @param[opt=false] boolean +-- @tparam[opt=false] boolean icon_only -- @propemits true false --- When a notification is invoked. diff --git a/lib/naughty/container/background.lua b/lib/naughty/container/background.lua index 535fae5a1..852a6e340 100644 --- a/lib/naughty/container/background.lua +++ b/lib/naughty/container/background.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification background. +--- A notification background widget. -- -- This widget holds the boilerplate code associated with the notification -- background. This includes the color and potentially some other styling @@ -16,6 +16,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2019 Emmanuel Lepage Vallee -- @containermod naughty.widget.background +-- @supermodule wibox.container.background -- @see wibox.container.background ---------------------------------------------------------------------------- local wbg = require("wibox.container.background") diff --git a/lib/naughty/init.lua b/lib/naughty/init.lua index ba23d761d..6b8774073 100644 --- a/lib/naughty/init.lua +++ b/lib/naughty/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Desktop notification handling library. +-- -- @author Uli Schlachter <psychon@znc.in> -- @copyright 2014 Uli Schlachter -- @module naughty diff --git a/lib/naughty/layout/box.lua b/lib/naughty/layout/box.lua index 0c6482471..fae1aeac2 100644 --- a/lib/naughty/layout/box.lua +++ b/lib/naughty/layout/box.lua @@ -208,7 +208,7 @@ end) -- } -- -- @property widget_template --- @param widget +-- @tparam[opt=nil] widget|nil|table widget_template -- @usebeautiful beautiful.notification_max_width The maximum width for the -- resulting widget. diff --git a/lib/naughty/layout/legacy.lua b/lib/naughty/layout/legacy.lua index c5d6c887f..d132d4f65 100644 --- a/lib/naughty/layout/legacy.lua +++ b/lib/naughty/layout/legacy.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification popup widget. +--- A notification popup widget (deprecated implementation). -- -- This is the legacy notification widget. It was the default until Awesome -- v4.3 but is now being deprecated in favor of a more flexible widget. diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 40ff87aae..a2e9e02d1 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A notification object. +--- Notification manipulation class. -- -- This class creates individual notification objects that can be manipulated -- to extend the default behavior. @@ -110,7 +110,7 @@ local notification = {} -- * critical -- -- @property urgency --- @param string +-- @tparam string urgency -- @propemits true false --- The notification category. @@ -167,17 +167,17 @@ local notification = {} -- be updated with a date further in the future. -- -- @property resident --- @param[opt=false] boolean +-- @tparam[opt=false] boolean resident -- @propemits true false --- Delay in seconds after which hovered popup disappears. -- @property hover_timeout --- @param number +-- @tparam[opt=nil] number|nil hover_timeout -- @propemits true false --- Target screen for the notification. -- @property screen --- @param screen +-- @tparam screen screen -- @propemits true false --- Corner of the workarea displaying the popups. @@ -195,34 +195,35 @@ local notification = {} --@DOC_awful_notification_box_corner_EXAMPLE@ -- -- @property position --- @param string +-- @tparam[opt=beautiful.notification_position] string position -- @propemits true false -- @see awful.placement.next_to --- Boolean forcing popups to display on top. -- @property ontop --- @param boolean +-- @tparam[opt=false] boolean ontop --- Popup height. -- --@DOC_awful_notification_geometry_EXAMPLE@ -- -- @property height --- @param number +-- @tparam number height -- @propemits true false -- @see width --- Popup width. -- @property width --- @param number +-- @tparam number width -- @propemits true false -- @see height --- Notification font. --@DOC_naughty_colors_EXAMPLE@ -- @property font --- @param string +-- @tparam string font -- @propemits true false +-- @see wibox.widget.textbox.font --- "All in one" way to access the default image or icon. -- @@ -248,7 +249,7 @@ local notification = {} --- Desired icon size in px. -- @property icon_size --- @param number +-- @tparam[opt=beautiful.notification_icon_size] number icon_size -- @propemits true false --- The icon provided in the `app_icon` field of the DBus notification. @@ -257,7 +258,7 @@ local notification = {} -- icon name to be fetched from the theme. -- -- @property app_icon --- @param string +-- @tparam string app_icon -- @propemits true false --- The notification image. @@ -287,7 +288,7 @@ local notification = {} --@DOC_awful_notification_fg_EXAMPLE@ -- -- @property fg --- @tparam string|color|pattern fg +-- @tparam[beautiful.notification_fg] string|color|pattern fg -- @propemits true false -- @see title -- @see gears.color @@ -297,14 +298,14 @@ local notification = {} --@DOC_awful_notification_bg_EXAMPLE@ -- -- @property bg --- @tparam string|color|pattern bg +-- @tparam[opt=beautiful.notification_bg] string|color|pattern bg -- @propemits true false -- @see title -- @see gears.color --- Border width. -- @property border_width --- @param number +-- @tparam[opt=beautiful.notification_border_width or 0] number border_width -- @propemits true false --- Border color. @@ -312,7 +313,7 @@ local notification = {} --@DOC_awful_notification_border_color_EXAMPLE@ -- -- @property border_color --- @param string +-- @tparam[opt=beautiful.notification_border_color] string border_color -- @propemits true false -- @see gears.color @@ -368,14 +369,14 @@ local notification = {} -- args will override ones defined -- in the preset. -- @property preset --- @param table +-- @tparam table preset -- @propemits true false --- Function that will be called with all arguments. -- The notification will only be displayed if the function returns true. -- Note: this function is only relevant to notifications sent via dbus. -- @property callback --- @param function +-- @tparam function callback -- @propemits true false --- A table containing strings that represents actions to buttons. @@ -383,7 +384,7 @@ local notification = {} -- The table key (a number) is used by DBus to set map the action. -- -- @property actions --- @param table +-- @tparam table actions -- @propemits true false --- Ignore this notification, do not display. @@ -392,19 +393,20 @@ local notification = {} -- handler. -- -- @property ignore --- @param boolean +-- @tparam[opt=false] boolean ignore -- @propemits true false --- Tell if the notification is currently suspended (read only). -- -- This is always equal to `naughty.suspended` ---@property suspended ---@param boolean +-- @property suspended +-- @tparam[opt=false] boolean suspended -- @propemits true false +-- @see naughty.suspended --- If the notification is expired. -- @property is_expired --- @param boolean +-- @tparam boolean is_expired -- @propemits true false -- @see naughty.expiration_paused @@ -436,7 +438,7 @@ local notification = {} -- client. -- -- @property clients --- @param table +-- @tparam table clients --- The maximum popup width. -- @@ -444,8 +446,8 @@ local notification = {} -- this is ignored by `naughty.list.notifications` because it delegate this -- decision to the layout. -- --- @property[opt=500] max_width --- @param number +-- @property max_width +-- @tparam[opt=500] number max_width -- @propemits true false --- The application name specified by the notification. @@ -454,7 +456,7 @@ local notification = {} -- property, but can sometime be specified for remote or headless notifications. -- In these case, it helps to triage and detect the notification from the rules. -- @property app_name --- @param string +-- @tparam string app_name -- @propemits true false --- The widget template used to represent the notification. @@ -463,7 +465,7 @@ local notification = {} -- off with a specialized notification widget. -- -- @property widget_template --- @param table +-- @tparam table|nil widget_template -- @propemits true false --- Destroy notification by notification object. @@ -921,9 +923,9 @@ end -- @tparam[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] string args.bg Background color. -- @tparam[opt=`beautiful.notification_border_width` or 1] integer args.border_width Border width. -- @tparam[opt=`beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'`] gears.color args.border_color Border color. --- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape. --- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity. --- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin. +-- @tparam[opt=beautiful.notification_shape] gears.shape args.shape Widget shape. +-- @tparam[opt=beautiful.notification_opacity] gears.opacity args.opacity Widget opacity. +-- @tparam[opt=beautiful.notification_margin] gears.margin args.margin Widget margin. -- @tparam[opt] function args.run Function to run on left click. The notification -- object will be passed to it as an argument. -- You need to call e.g. diff --git a/lib/naughty/widget/icon.lua b/lib/naughty/widget/icon.lua index f17c5c9d4..00eb59eb6 100644 --- a/lib/naughty/widget/icon.lua +++ b/lib/naughty/widget/icon.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification square icon. +--- A notification square icon widget. -- -- This widget is a specialized `wibox.widget.imagebox` with the following extra -- features: @@ -14,6 +14,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.icon +-- @supermodule wibox.widget.imagebox -- @see wibox.widget.imagebox ---------------------------------------------------------------------------- local imagebox = require("wibox.widget.imagebox") @@ -24,7 +25,7 @@ local dpi = require("beautiful.xresources").apply_dpi local icon = {} --- The default way to resize the icon. +--- The default way to resize the icon. -- @beautiful beautiful.notification_icon_resize_strategy -- @param number @@ -130,6 +131,11 @@ local valid_strategies = { -- there is no specified strategy. -- @usebeautiful beautiful.notification_icon_size The size upper bound. + +--- The default notification icon size. +-- @beautiful beautiful.notification_icon_size +-- @tparam number notification_icon_size The size (in pixels). + function icon:set_resize_strategy(strategy) assert(valid_strategies[strategy], "Invalid strategy") diff --git a/lib/naughty/widget/message.lua b/lib/naughty/widget/message.lua index 9224f1726..6d9a68514 100644 --- a/lib/naughty/widget/message.lua +++ b/lib/naughty/widget/message.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification content message. +--- A notification content message widget. -- -- This widget is a specialized `wibox.widget.textbox` with the following extra -- features: @@ -12,6 +12,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.message +-- @supermodule wibox.widget.textbox -- @see wibox.widget.textbox ---------------------------------------------------------------------------- local textbox = require("wibox.widget.textbox") diff --git a/lib/naughty/widget/title.lua b/lib/naughty/widget/title.lua index dceba4f95..27f1311d6 100644 --- a/lib/naughty/widget/title.lua +++ b/lib/naughty/widget/title.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification title. +--- A notification title widget. -- -- This widget is a specialized `wibox.widget.textbox` with the following extra -- features: @@ -12,6 +12,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.title +-- @supermodule wibox.widget.textbox -- @see wibox.widget.textbox ---------------------------------------------------------------------------- local textbox = require("wibox.widget.textbox") diff --git a/lib/ruled/client.lua b/lib/ruled/client.lua index 54af13a3d..98e0fe0cb 100644 --- a/lib/ruled/client.lua +++ b/lib/ruled/client.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Rules for clients. +--- Apply properties to a new client based on pre-determined rules. -- -- This module applies @{rules} to clients during startup (via @{client.manage}, -- but its functions can be used for client matching in general. diff --git a/lib/ruled/notification.lua b/lib/ruled/notification.lua index de6b306e5..55e8905ea 100644 --- a/lib/ruled/notification.lua +++ b/lib/ruled/notification.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Rules for notifications. +--- Apply properties to a new `naughty.notification` based on pre-determined rules. -- --@DOC_wibox_nwidget_rules_urgency_EXAMPLE@ -- diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index dde2327ee..95b07df86 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -1,6 +1,5 @@ --------------------------------------------------------------------------- --- --- A circular chart (arc chart). +-- A circular chart (arc chart) container. -- -- It can contain a central widget (or not) and display multiple values. -- @@ -43,7 +42,19 @@ local arcchart = { mt = {} } --- The arc thickness. -- @beautiful beautiful.arcchart_thickness --- @param number +-- @tparam number arcchart_thickness + +--- If the chart has rounded edges. +-- @beautiful beautiful.arcchart_rounded_edge +-- @tparam boolean arcchart_rounded_edge + +--- The radial background. +-- @beautiful beautiful.arcchart_bg +-- @tparam gears.color arcchart_bg + +--- The (radiant) angle where the first value start. +-- @beautiful beautiful.arcchart_start_angle +-- @tparam number arcchart_start_angle local function outline_workarea(width, height) local x, y = 0, 0 @@ -102,7 +113,6 @@ function arcchart:after_draw_children(_, cr, width, height) local wa = outline_workarea(width, height) cr:translate(wa.x+border_width/2, wa.y+border_width/2) - -- Get the min and max value --local min_val = self:get_min_value() or 0 --TODO support min_values local max_val = self:get_max_value() @@ -245,9 +255,9 @@ end --- The arcchart values foreground colors. --@DOC_wibox_container_arcchart_color_EXAMPLE@ -- @property colors --- @tparam table values An ordered set of colors for each value in arcchart. +-- @tparam table colors An ordered set of colors for each value in arcchart. -- @propemits true false --- @propbeautiful +-- @usebeautiful beautiful.arcchart_color --- The border width. -- @@ -279,7 +289,7 @@ end --- The value. --@DOC_wibox_container_arcchart_value_EXAMPLE@ -- @property value --- @tparam number value Between min_value and max_value +-- @tparam number value Between `min_value` and `max_value` -- @see values -- @propemits true false @@ -297,18 +307,21 @@ end -- @property rounded_edge -- @tparam[opt=false] boolean rounded_edge -- @propemits true false +-- @propbeautiful --- The arc thickness. --@DOC_wibox_container_arcchart_thickness_EXAMPLE@ -- @property thickness -- @propemits true false -- @tparam number thickness +-- @propbeautiful --- The (radiant) angle where the first value start. ---@DOC_wibox_container_arcchart_start_angle_EXAMPLE@ +-- @DOC_wibox_container_arcchart_start_angle_EXAMPLE@ -- @property start_angle -- @tparam[opt=math.pi] number start_angle A number between 0 and 2*math.pi -- @propemits true false +-- @usebeautiful beautiful.arcchart_start_angle for _, prop in ipairs {"border_width", "border_color", "paddings", "colors", "rounded_edge", "bg", "thickness", "values", "min_value", "max_value", diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index 580c8fd66..384ae7efd 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -349,7 +349,7 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_width --- @tparam[opt=0] number width The border width. +-- @tparam[opt=0] number border_width The border width. -- @propemits true false -- @introducedin 4.4 -- @see border_color @@ -386,7 +386,7 @@ end -- -- @deprecatedproperty shape_border_color -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. --- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient +-- @tparam color fg The border color, pattern or gradient -- @renamedin 4.4 border_color -- @see gears.color -- @see border_color @@ -395,7 +395,7 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_color --- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient +-- @tparam[opt=fg] color border_color The border color, pattern or gradient -- @propemits true false -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. -- @introducedin 4.4 @@ -462,7 +462,7 @@ end -- as arguments. Any other arguments passed to this method will be appended. -- -- @property bgimage --- @tparam string|surface|function image A background image or a function +-- @tparam string|surface|function bgimage A background image or a function -- @see gears.surface function background:set_bgimage(image, ...) diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index 7df9cd9cf..1c8bd90a0 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -94,7 +94,7 @@ end --- Set all the margins to val. -- -- @property margins --- @tparam number|table val The margin value. It can be a number or a table with +-- @tparam number|table margins The margin value. It can be a number or a table with -- the *left*/*right*/*top*/*bottom* keys. -- @propemits false false @@ -126,7 +126,7 @@ end --- Set the margins color to create a border. -- -- @property color --- @param color A color used to fill the margin. +-- @tparam gears.color color A color used to fill the margin. -- @propemits true false function margin:set_color(color) @@ -206,13 +206,13 @@ end --- Returns a new margin container. -- --- @param[opt] widget A widget to use. --- @param[opt] left A margin to use on the left side of the widget. --- @param[opt] right A margin to use on the right side of the widget. --- @param[opt] top A margin to use on the top side of the widget. --- @param[opt] bottom A margin to use on the bottom side of the widget. --- @param[opt] color A color for the margins. --- @param[opt] draw_empty whether or not to draw the margin when the content is empty +-- @tparam[opt] widget widget A widget to use. +-- @tparam[opt] number left A margin to use on the left side of the widget. +-- @tparam[opt] number right A margin to use on the right side of the widget. +-- @tparam[opt] number top A margin to use on the top side of the widget. +-- @tparam[opt] number bottom A margin to use on the bottom side of the widget. +-- @tparam[opt] gears.color color A color for the margins. +-- @tparam[opt] boolean draw_empty Whether or not to draw the margin when the content is empty -- @treturn table A new margin container -- @constructorfct wibox.container.margin local function new(widget, left, right, top, bottom, color, draw_empty) diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index b8ec08055..ac458e9c0 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -178,7 +178,7 @@ end -- --@DOC_wibox_container_radialprogressbar_value_EXAMPLE@ -- @property value --- @tparam number value Between min_value and max_value. +-- @tparam number value Between `min_value` and `max_value`. -- @propemits true false function radialprogressbar:set_value(val) diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index 9da97003f..fedc8e4f9 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -101,7 +101,7 @@ end -- --@DOC_wibox_container_rotate_angle_EXAMPLE@ -- @property direction --- @tparam string dir The direction. +-- @tparam[opt="north"] string direction The direction. -- @propemits true false function rotate:set_direction(dir) diff --git a/lib/wibox/container/tile.lua b/lib/wibox/container/tile.lua index 46fdd391c..e00b8775f 100644 --- a/lib/wibox/container/tile.lua +++ b/lib/wibox/container/tile.lua @@ -110,7 +110,7 @@ end --@DOC_wibox_container_tile_horizontal_crop_EXAMPLE@ -- -- @property horizontal_crop --- @tparam[opt=false] boolean tiled +-- @tparam[opt=false] boolean horizontal_crop -- @see vertical_crop --- Avoid painting incomplete vertical tiles. @@ -118,7 +118,7 @@ end --@DOC_wibox_container_tile_vertical_crop_EXAMPLE@ -- -- @property vertical_crop --- @tparam[opt=false] boolean tiled +-- @tparam[opt=false] boolean vertical_crop -- @see horizontal_crop --- Enable or disable the tiling. @@ -199,9 +199,19 @@ end --- Create a new tile container. -- @tparam table args --- @tparam wibox.widget widget args.widget The widget to tile. +-- @tparam wibox.widget args.widget args.widget The widget to tile. -- @tparam string args.halign Either `left`, `right` or `center`. -- @tparam string args.valign Either `top`, `bottom` or `center`. +-- @tparam number args.horizontal_spacing The horizontal spacing between the tiled. +-- @tparam number args.vertical_spacing The vertical spacing between the tiled. +-- @tparam boolean args.horizontal_crop Avoid painting incomplete horizontal tiles. +-- @tparam boolean args.vertical_crop Avoid painting incomplete vertical tiles. +-- @tparam boolean args.tiled Enable or disable the tiling. +-- @tparam wibox.widget args.widget The widget to be placed. +-- @tparam boolean args.fill_vertical Fill the vertical space. +-- @tparam boolean args.fill_horizontal Fill the horizontal space. +-- @tparam boolean args.content_fill_vertical Stretch the contained widget so it takes all the vertical space. +-- @tparam boolean args.content_fill_horizontal Stretch the contained widget so it takes all the horizontal space. -- @constructorfct wibox.container.tile function module.mt:__call(...) return new(...) diff --git a/lib/wibox/drawable.lua b/lib/wibox/drawable.lua index b8748df77..b79bb3d67 100644 --- a/lib/wibox/drawable.lua +++ b/lib/wibox/drawable.lua @@ -199,7 +199,7 @@ local function find_widgets(self, result, hierarchy, x, y) end end ---- Find a widget by a point. +-- Find a widget by a point. -- The drawable must have drawn itself at least once for this to work. -- @param x X coordinate of the point -- @param y Y coordinate of the point diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index e606864b7..ff458fe78 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Box where widget can be displayed. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @popupmod wibox diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index 58f341794..64d0d948c 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -273,7 +273,7 @@ end -- `"inside"`. -- -- @property expand --- @tparam[opt="inside"] string mode How to use unused space. +-- @tparam[opt="inside"] string expand How to use unused space. function align:set_expand(mode) if mode == "none" or mode == "outside" then diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index bd76c3207..5d4affcbf 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Place many widgets in a column or row, until the available space is used up. +-- -- A `fixed` layout may be initialized with any number of child widgets, and -- during runtime widgets may be added and removed dynamically. -- diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index 9fceef375..153629bae 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -1,4 +1,7 @@ --------------------------------------------------------------------------- +-- Split the space equally between multiple widgets. +-- +-- -- A `flex` layout may be initialized with any number of child widgets, and -- during runtime widgets may be added and removed dynamically. -- @@ -49,7 +52,7 @@ local flex = {} --- Remove a widget from the layout. -- --- @tparam index The widget index to remove. +-- @tparam number index The widget index to remove. -- @treturn boolean index If the operation is successful. -- @method remove -- @interface layout diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index 6ecc04167..dc292ac22 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A grid layout. +--- Place multiple widgets in multiple rows and columns. -- -- Widgets spanning several columns or rows cannot be included using the -- declarative system. @@ -52,7 +52,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- row is filled, creating it if it does not exist. -- --@DOC_wibox_layout_grid_orientation_EXAMPLE@ --- @param[opt="vertical"] string Preferred orientation: "horizontal" or "vertical". +-- @tparam[opt="vertical"] string orientation Preferred orientation: "horizontal" or "vertical". -- @property orientation --- Allow to superpose widgets in the same cell. @@ -60,39 +60,39 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- widget and prevent from adding it. -- --@DOC_wibox_layout_grid_superpose_EXAMPLE@ --- @param[opt=false] boolean +-- @tparam[opt=false] boolean superpose -- @property superpose --- Force the number of rows of the layout. -- @property forced_num_rows --- @tparam[opt=nil] number|nil number Forced number of rows (`nil` for automatic). +-- @tparam[opt=nil] number|nil forced_num_rows Forced number of rows (`nil` for automatic). --- Force the number of columns of the layout. -- @property forced_num_cols --- @tparam[opt=nil] number|nil number Forced number of columns (`nil` for automatic). +-- @tparam[opt=nil] number|nil forced_num_cols Forced number of columns (`nil` for automatic). --- Set the minimum size for the columns. -- --@DOC_wibox_layout_grid_min_size_EXAMPLE@ --- @param[opt=0] number Minimum size of the columns. +-- @tparam[opt=0] number min_cols_size Minimum size of the columns. -- @property min_cols_size --- Set the minimum size for the rows. --- @param[opt=0] number Minimum size of the rows. +-- @tparam[opt=0] number min_rows_size Minimum size of the rows. -- @property min_rows_size --- The spacing between columns. -- -- see `spacing` -- --- @param[opt=0] number The spacing +-- @tparam[opt=0] number horizontal_spacing The spacing -- @property horizontal_spacing --- The spacing between rows. -- -- see `spacing` -- --- @param[opt=0] number The spacing +-- @tparam[opt=0] number vertical_spacing The spacing -- @property vertical_spacing --- The spacing between rows and columns. @@ -101,21 +101,21 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- preferred `orientation`. -- --@DOC_wibox_layout_grid_spacing_EXAMPLE@ --- @param[opt=0] number The spacing +-- @tparam[opt=0] number spacing The spacing -- @property spacing --- Controls if the columns are expanded to use all the available width. -- -- see `expand` -- --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean horizontal_expand Expand the grid into the available space -- @property horizontal_expand --- Controls if the rows are expanded to use all the available height. -- -- see `expand` -- --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean vertical_expand Expand the grid into the available space -- @property vertical_expand --- Controls if the columns/rows are expanded to use all the available space. @@ -124,7 +124,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- preferred `orientation`. -- --@DOC_wibox_layout_grid_expand_EXAMPLE@ --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean expand Expand the grid into the available space -- @property expand --- Controls if the columns all have the same width or if the width of each @@ -132,7 +132,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- -- see `homogeneous` -- --- @param[opt=true] boolean All the columns have the same width. +-- @tparam[opt=true] boolean horizontal_homogeneous All the columns have the same width. -- @property horizontal_homogeneous --- Controls if the rows all have the same height or if the height of each row @@ -140,7 +140,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- -- see `homogeneous` -- --- @param[opt=true] boolean All the rows have the same height. +-- @tparam[opt=true] boolean vertical_homogeneous All the rows have the same height. -- @property vertical_homogeneous --- Controls if the columns/rows all have the same size or if the size depends @@ -150,7 +150,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- by the preferred `orientation`. -- --@DOC_wibox_layout_grid_expand_EXAMPLE@ --- @param[opt=true] boolean All the columns/rows have the same size. +-- @tparam[opt=true] boolean homogeneous All the columns/rows have the same size. -- @property homogeneous --- Child widget position. Return of `get_widget_position`. @@ -305,7 +305,7 @@ end --@DOC_wibox_layout_grid_add_EXAMPLE@ -- -- @method add_widget_at --- @param child Widget that should be added +-- @tparam wibox.widget child Widget that should be added -- @tparam number row Row number for the top left corner of the widget -- @tparam number col Column number for the top left corner of the widget -- @tparam[opt=1] number row_span The number of rows the widget spans. @@ -400,7 +400,7 @@ end --- Return the coordinates of the widget. -- @method get_widget_position --- @param widget The widget +-- @tparam widget widget The widget -- @treturn table The `position` table of the coordinates in the grid, with -- fields `row`, `col`, `row_span` and `col_span`. function grid:get_widget_position(widget) @@ -441,8 +441,8 @@ end --- Replace old widget by new widget, spanning the same columns and rows. -- @method replace_widget --- @param old The widget to remove --- @param new The widget to add +-- @tparam widget old The widget to remove +-- @tparam widget new The widget to add -- @treturn boolean If the operation is successful (widget found) function grid:replace_widget(old, new) -- check if the new object is a widget diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index b570f449d..f89b2c515 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A stacked layout. +-- Place multiple widgets on top of each other. -- -- This layout display widgets on top of each other. It can be used to overlay -- a `wibox.widget.textbox` on top of a `awful.widget.progressbar` or manage @@ -31,7 +31,7 @@ local stack = {mt={}} --- Remove a widget from the layout. -- --- @tparam index The widget index to remove +-- @tparam number index The widget index to remove -- @treturn boolean index If the operation is successful -- @method remove -- @interface layout @@ -115,7 +115,7 @@ end --- Raise a widget at `index` to the top of the stack. -- -- @method raise --- @tparam number index the widget index to raise +-- @tparam number index The widget index to raise function stack:raise(index) if (not index) or (not self._private.widgets[index]) then return end diff --git a/lib/wibox/widget/background.lua b/lib/wibox/widget/background.lua index 0919c2799..7712d5540 100644 --- a/lib/wibox/widget/background.lua +++ b/lib/wibox/widget/background.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- This class has been moved to `wibox.container.background` +-- This class has been moved to `wibox.container.background`. -- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index 26e035231..1cae73bc0 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Base class of every widgets, containers and layouts, +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @classmod wibox.widget.base @@ -31,17 +33,17 @@ local base = {} -- widgets hierarchy. A hierarchy loop is when a widget, or any of its -- children, contain (directly or indirectly) itself. -- @property all_children --- @tparam table children The children. +-- @tparam table all_children The children. -- @baseclass wibox.widget.base --- Force a widget height. -- @property forced_height --- @tparam number|nil height The height (`nil` for automatic) +-- @tparam number|nil forced_height The height (`nil` for automatic) -- @baseclass wibox.widget.base --- Force a widget width. -- @property forced_width --- @tparam number|nil width The width (`nil` for automatic) +-- @tparam number|nil forced_width The width (`nil` for automatic) -- @baseclass wibox.widget.base --- The widget opacity (transparency). @@ -51,14 +53,14 @@ local base = {} --- The widget visibility. -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @baseclass wibox.widget.base --- The widget buttons. -- -- The table contains a list of `awful.button` objects. -- @property buttons --- @param table +-- @tparam table buttons -- @see awful.button -- @baseclass wibox.widget.base @@ -92,7 +94,7 @@ local base = {} -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -123,7 +125,7 @@ local base = {} -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -148,7 +150,7 @@ local base = {} -- @signal mouse::enter -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -173,7 +175,7 @@ local base = {} -- @signal mouse::leave -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. diff --git a/lib/wibox/widget/calendar.lua b/lib/wibox/widget/calendar.lua index b7b21c86a..09bab2b79 100644 --- a/lib/wibox/widget/calendar.lua +++ b/lib/wibox/widget/calendar.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A calendar widget. +-- Display a monthly or yearly calendar. -- -- This module defines two widgets: a month calendar and a year calendar -- @@ -71,7 +71,7 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" -- A table representing the date {day=[number|nil], month=[number|nil], year=[number]}. -- -- E.g.. {day=21, month=2, year=2005}, {month=2, year=2005}, {year=2005} --- @tparam date table Date table. +-- @tparam table date Date table. -- @tparam number date.year Date year -- @tparam number|nil date.month Date month -- @tparam number|nil date.day Date day @@ -80,34 +80,44 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" --- The calendar font. -- -- Choose a monospace font for a better rendering. +-- --@DOC_wibox_widget_calendar_font_EXAMPLE@ --- @param[opt="Monospace 10"] string Font of the calendar +-- +-- @tparam[opt="Monospace 10"] string font Font of the calendar -- @property font +-- @usebeautiful beautiful.calendar_font --- The calendar spacing. -- -- The spacing between cells in the month. -- The spacing between months in a year calendar is twice this value. --- @param[opt=5] number Spacing of the grid +-- @tparam[opt=5] number spacing Spacing of the grid -- @property spacing +-- @usebeautiful beautiful.calendar_spacing --- Display the calendar week numbers. -- --@DOC_wibox_widget_calendar_week_numbers_EXAMPLE@ --- @param[opt=false] boolean Display week numbers +-- +-- @tparam[opt=false] boolean week_numbers Display week numbers -- @property week_numbers +-- @usebeautiful beautiful.calendar_week_numbers --- Start the week on Sunday. -- --@DOC_wibox_widget_calendar_start_sunday_EXAMPLE@ --- @param[opt=false] boolean Start the week on Sunday +-- +-- @tparam[opt=false] boolean start_sunday Start the week on Sunday -- @property start_sunday +-- @usebeautiful beautiful.calendar_start_sunday --- Format the weekdays with three characters instead of two -- --@DOC_wibox_widget_calendar_long_weekdays_EXAMPLE@ --- @param[opt=false] boolean Use three characters for the weekdays instead of two +-- +-- @tparam[opt=false] boolean long_weekdays Use three characters for the weekdays instead of two -- @property long_weekdays +-- @usebeautiful beautiful.calendar_long_weekdays --- The widget encapsulating function. -- @@ -119,15 +129,16 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" -- It is used to add a container to the grid layout and to the cells: -- --@DOC_wibox_widget_calendar_fn_embed_cell_EXAMPLE@ --- @param function Function to embed the widget depending on its flag +-- @tparam function fn_embed Function to embed the widget depending on its flag -- @property fn_embed --- Allow cells to have flexible height -- --@DOC_wibox_widget_calendar_flex_height_EXAMPLE@ -- --- @param[opt=false] boolean Allow flex height. +-- @tparam[opt=false] boolean flex_height Allow flex height. -- @property flex_height +-- @usebeautiful beautiful.flex_height --- Make a textbox -- @tparam string text Text of the textbox @@ -257,7 +268,7 @@ end --- Create a grid layout for the year calendar -- @tparam table props Table of year calendar properties --- @param date Year to display (number or string) +-- @tparam number|string date Year to display. -- @treturn widget Grid layout local function create_year(props, date) -- Create a grid widget with the 12 months diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index f04cf6640..099f32e36 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -137,7 +137,7 @@ local checkbox = {} -- If none is set, then the `shape` property will be used. --@DOC_wibox_widget_checkbox_check_shape_EXAMPLE@ -- @property check_shape --- @tparam gears.shape shape +-- @tparam gears.shape check_shape -- @propbeautiful -- @propemits true false -- @see gears.shape @@ -254,7 +254,7 @@ end --- If the checkbox is checked. -- @property checked --- @param boolean +-- @tparam[opt=false] boolean checked for _, prop in ipairs {"border_width", "bg", "border_color", "check_border_color", "check_border_width", "check_color", "shape", "check_shape", "paddings", diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index 51b5d7545..9d8e1cb7f 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A graph widget. +--- Display multiple values as a stream of bars. -- -- The graph goes from left to right. To change this to right to left, use -- a `wibox.container.mirror` widget. This can also be used to have data @@ -84,7 +84,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_stacked_group_disable_EXAMPLE@ -- -- @property group_colors --- @tparam table colors A table with colors for data groups. +-- @tparam table group_colors A table with colors for data groups. -- @see gears.color --- The maximum value the graph should handle. diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index ace4eed74..946bddc38 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -547,7 +547,7 @@ end -- @DOC_wibox_widget_imagebox_vertical_fit_policy_EXAMPLE@ -- -- @property vertical_fit_policy --- @tparam[opt="auto"] string horizontal_fit_policy +-- @tparam[opt="auto"] string vertical_fit_policy -- @propemits true false -- @see horizontal_fit_policy -- @see resize diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index ccc49c9af..26afbda31 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +--- Utility function for working with widgets. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @module wibox.widget diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 608fdcf6b..1268a6ba0 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -191,7 +191,7 @@ end -- --@DOC_wibox_widget_piechart_label_EXAMPLE@ -- @property display_labels --- @param[opt=true] boolean +-- @tparam[opt=true] boolean display_labels --- The pie elements border width. -- diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index 9e1979849..c541d4ecd 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -54,7 +54,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_border_color_EXAMPLE@ -- -- @property border_color --- @tparam gears.color color The border color to set. +-- @tparam gears.color border_color The border color to set. -- @propemits true false -- @propbeautiful -- @see gears.color @@ -75,7 +75,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_bar_border_color_EXAMPLE@ -- -- @property bar_border_color --- @tparam gears.color color The border color to set. +-- @tparam gears.color bar_border_color The border color to set. -- @propemits true false -- @propbeautiful -- @see gears.color @@ -104,7 +104,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_background_color_EXAMPLE@ -- -- @property background_color --- @tparam gears.color color The progressbar background color. +-- @tparam gears.color background_color The progressbar background color. -- @propemits true false -- @usebeautiful beautiful.progressbar_bg -- @see gears.color @@ -114,7 +114,7 @@ local progressbar = { mt = {} } --@DOC_wibox_widget_progressbar_bar_shape_EXAMPLE@ -- -- @property bar_shape --- @tparam[opt=gears.shape.rectangle] gears.shape shape +-- @tparam[opt=gears.shape.rectangle] gears.shape bar_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -243,7 +243,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_margins1_EXAMPLE@ -- -- @property margins --- @tparam[opt=0] (table|number|nil) margins A table for each side or a number +-- @tparam[opt=0] table|number|nil margins A table for each side or a number -- @tparam[opt=0] number margins.top -- @tparam[opt=0] number margins.bottom -- @tparam[opt=0] number margins.left @@ -268,7 +268,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_paddings1_EXAMPLE@ -- -- @property paddings --- @tparam[opt=0] (table|number|nil) padding A table for each side or a number +-- @tparam[opt=0] (table|number|nil) paddings A table for each side or a number -- @tparam[opt=0] number paddings.top -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left @@ -591,8 +591,24 @@ end -- -- @tparam table args Standard widget() arguments. You should add width and -- height constructor parameters to set progressbar geometry. --- @tparam number args.width The width. --- @tparam number args.height The height. +-- @tparam[opt] number args.width The width. +-- @tparam[opt] number args.height The height. +-- @tparam[opt] gears.color args.border_color The progressbar border color. +-- @tparam[opt] number args.border_width The progressbar border width. +-- @tparam[opt] gears.color args.bar_border_color The progressbar inner border color. +-- @tparam[opt] number args.bar_border_width The progressbar inner border width. +-- @tparam[opt] gears.color args.color The progressbar foreground color. +-- @tparam[opt] gears.color args.background_color The progressbar background color. +-- @tparam[opt] gears.shape args.bar_shape The progressbar inner shape. +-- @tparam[opt] gears.shape args.shape The progressbar shape. +-- @tparam[opt] boolean args.clip Force the inner part (the bar) to fit in the background shape. +-- @tparam[opt] boolean args.ticks The progressbar to draw ticks. +-- @tparam[opt] number args.ticks_gap The progressbar ticks gap. +-- @tparam[opt] number args.ticks_size The progressbar ticks size. +-- @tparam[opt] number args.max_value The maximum value the progressbar should handle. +-- @tparam[opt] table|number args.margins The progressbar margins. +-- @tparam[opt] table|number args.paddings The progressbar padding. +-- @tparam[opt] number args.value Set the progressbar value. -- @treturn wibox.widget.progressbar A progressbar widget. -- @constructorfct wibox.widget.progressbar function progressbar.new(args) diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index 2ae0daa42..d600bcd5c 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -68,7 +68,7 @@ local separator = {} --- The relative percentage covered by the bar. -- -- @property span_ratio --- @tparam[opt=1] number A number between 0 and 1. +-- @tparam[opt=1] number span_ratio A number between 0 and 1. -- @propbeautiful -- @propemits true false @@ -112,7 +112,7 @@ local separator = {} --- The relative percentage covered by the bar. -- @beautiful beautiful.separator_span_ratio --- @tparam[opt=1] number A number between 0 and 1. +-- @tparam[opt=1] number separator_span_ratio A number between 0 and 1. --- The separator's color. -- @beautiful beautiful.separator_color @@ -203,6 +203,13 @@ end --- Create a new separator. -- @constructorfct wibox.widget.separator -- @tparam table args The arguments (all properties are available). +-- @tparam[opt] string args.orientation The separator's orientation. +-- @tparam[opt] number args.thickness The separator's thickness. +-- @tparam[opt] function args.shape The separator's shape. +-- @tparam[opt] number args.span_ratio The relative percentage covered by the bar. +-- @tparam[opt] color args.color The separator's color. +-- @tparam[opt] color args.border_color The separator's border color. +-- @tparam[opt] number args.border_width The separator's border width. local function new(args) local ret = base.make_widget(nil, nil, { diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua index b72577519..4244bdf1b 100644 --- a/lib/wibox/widget/slider.lua +++ b/lib/wibox/widget/slider.lua @@ -30,7 +30,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_shape_EXAMPLE@ -- -- @property handle_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam[opt=gears shape rectangle] gears.shape handle_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -49,7 +49,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_margins_EXAMPLE@ -- -- @property handle_margins --- @tparam[opt={}] table margins +-- @tparam[opt={}] table handle_margins -- @tparam[opt=0] number margins.left -- @tparam[opt=0] number margins.right -- @tparam[opt=0] number margins.top @@ -86,7 +86,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_shape_EXAMPLE@ -- -- @property bar_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam[opt=gears shape rectangle] gears.shape bar_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -124,7 +124,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_margins_EXAMPLE@ -- -- @property bar_margins --- @tparam[opt={}] table margins +-- @tparam[opt={}] table bar_margins -- @tparam[opt=0] number margins.left -- @tparam[opt=0] number margins.right -- @tparam[opt=0] number margins.top @@ -136,6 +136,7 @@ local slider = {mt={}} -- @property bar_border_width -- @tparam[opt=0] number bar_border_width -- @propemits true false +-- @propbeautiful --- The bar (background) border_color. -- @@ -148,8 +149,6 @@ local slider = {mt={}} --- The slider value. -- --- **Signal:** *property::value* notify the value is changed. --- --@DOC_wibox_widget_slider_value_EXAMPLE@ -- -- @property value @@ -521,8 +520,25 @@ local function mouse_press(self, x, y, button_id, _, geo) end --- Create a slider widget. --- @tparam[opt={}] table args +-- -- @constructorfct wibox.widget.slider +-- @tparam[opt={}] table args +-- @tparam[opt] gears.shape args.handle_shape The slider handle shape. +-- @tparam[opt] color args.handle_color The slider handle color. +-- @tparam[opt] table args.handle_margins The slider handle margins. +-- @tparam[opt] number args.handle_width The slider handle width. +-- @tparam[opt] color args.handle_border_color The handle border_color. +-- @tparam[opt] number args.handle_border_width The handle border width. +-- @tparam[opt] gears.shape args.bar_shape The bar (background) shape. +-- @tparam[opt] number args.bar_height The bar (background) height. +-- @tparam[opt] color args.bar_color The bar (background) color. +-- @tparam[opt] color args.bar_active_color The bar (active) color. +-- @tparam[opt] table args.bar_margins The bar (background) margins. +-- @tparam[opt] number args.bar_border_width The bar (background) border width. +-- @tparam[opt] color args.bar_border_color The bar (background) border_color. +-- @tparam[opt] number args.value The slider value. +-- @tparam[opt] number args.minimum The slider minimum value. +-- @tparam[opt] number args.maximum The slider maximum value. local function new(args) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua index f7a20361b..911c768d4 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Container for the various system tray icons. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @widgetmod wibox.widget.systray @@ -27,20 +29,23 @@ local display_on_screen = "primary" --- The systray background color. -- +-- Please note that only solid+opaque colors are supported. It does **not** +-- support gradients, patterns or transparent colors. +-- -- @beautiful beautiful.bg_systray --- @param string The color (string like "#ff0000" only) +-- @tparam string bg_systray The color (string like "#ff0000" only) --- The maximum number of rows for systray icons. Icons will fill the -- current column (orthogonally to the systray direction) before -- filling the next column. -- -- @beautiful beautiful.systray_max_rows --- @tparam[opt=1] integer The positive number of rows +-- @tparam[opt=1] integer systray_max_rows The positive number of rows. --- The systray icon spacing. -- -- @beautiful beautiful.systray_icon_spacing --- @tparam[opt=0] integer The icon spacing +-- @tparam[opt=0] integer systray_icon_spacing The icon spacing local function should_display_on(s) if display_on_screen == "primary" then @@ -143,7 +148,7 @@ end -- available space. Otherwise, any single icon has a size of `size`x`size`. -- -- @property base_size --- @tparam integer|nil size The base size +-- @tparam integer|nil base_size The base size -- @propemits true false function systray:set_base_size(size) @@ -157,7 +162,7 @@ end --- Decide between horizontal or vertical display. -- -- @property horizontal --- @tparam boolean horiz Use horizontal mode? +-- @tparam boolean horizontal Use horizontal mode? -- @propemits true false function systray:set_horizontal(horiz) @@ -171,7 +176,7 @@ end --- Should the systray icons be displayed in reverse order? -- -- @property reverse --- @tparam boolean rev Display in reverse order. +-- @tparam boolean reverse Display in reverse order. -- @propemits true false function systray:set_reverse(rev) @@ -189,7 +194,7 @@ end -- visible on the primary screen. The default value is "primary". -- -- @property screen --- @tparam screen|"primary" s The screen to display on. +-- @tparam screen|"primary" screen The screen to display on. -- @propemits true false function systray:set_screen(s) @@ -204,9 +209,12 @@ end -- -- Note that this widget can only exist once. -- --- @tparam boolean revers Show in the opposite direction +-- @tparam boolean reverse Show in the opposite direction -- @treturn table The new `systray` widget -- @constructorfct wibox.widget.systray +-- @usebeautiful beautiful.bg_systray +-- @usebeautiful beautiful.systray_icon_spacing +-- @usebeautiful beautiful.systray_max_rows local function new(revers) local ret = wbase.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index 3a295a8fe..be8f2d36b 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -21,11 +21,6 @@ local setmetatable = setmetatable local textbox = { mt = {} } ---- The textbox font. --- --- @beautiful beautiful.font --- @param string - --- Set the DPI of a Pango layout local function setup_dpi(box, dpi) assert(dpi, "No DPI provided") @@ -258,7 +253,7 @@ end --@DOC_wibox_widget_textbox_ellipsize_EXAMPLE@ -- -- @property ellipsize --- @tparam[opt="end"] string mode The ellipsize mode. +-- @tparam[opt="end"] string ellipsize The ellipsize mode. -- @propemits true false function textbox:set_ellipsize(mode) @@ -285,7 +280,7 @@ end -- @DOC_wibox_widget_textbox_wrap1_EXAMPLE@ -- -- @property wrap --- @tparam[opt="word_char"] string mode Where to wrap? After "word", "char" or "word_char". +-- @tparam[opt="word_char"] string wrap Where to wrap? After "word", "char" or "word_char". -- @propemits true false function textbox:set_wrap(mode) @@ -315,7 +310,7 @@ end --@DOC_wibox_widget_textbox_valign1_EXAMPLE@ -- -- @property valign --- @tparam[opt="center"] string mode The vertical alignment +-- @tparam[opt="center"] string valign The vertical alignment -- @propemits true false function textbox:set_valign(mode) @@ -345,7 +340,7 @@ end --@DOC_wibox_widget_textbox_align1_EXAMPLE@ -- -- @property align --- @tparam[opt="left"] string mode The horizontal alignment +-- @tparam[opt="left"] string align The horizontal alignment -- @propemits true false function textbox:set_align(mode) diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 2a4c2596e..61a04295d 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Text clock widget. +--- Display the time (and date) in a text box. -- -- The `wibox.widget.textclock` widget is part of the Awesome WM's widget -- system (see @{03-declarative-layout.md}). diff --git a/luaa.c b/luaa.c index 4ebf17d5f..2dbd3ac5f 100644 --- a/luaa.c +++ b/luaa.c @@ -19,7 +19,7 @@ * */ -/** AwesomeWM lifecycle API. +/** AwesomeWM lifecycle and low-level APIs. * * This module contains the functions and signal to manage the lifecycle of the * AwesomeWM process. It allows to execute code at specific point from the early diff --git a/mouse.c b/mouse.c index c7214a595..8bd81aa41 100644 --- a/mouse.c +++ b/mouse.c @@ -19,7 +19,7 @@ * */ -/** awesome mouse API. +/** Manipulate and inspect the mouse cursor. * * The mouse buttons are represented as index. The common ones are: * diff --git a/mousegrabber.c b/mousegrabber.c index 31e0c3457..f048d5d22 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -19,7 +19,7 @@ * */ -/** awesome mousegrabber API. +/** Set a callback to process all mouse events. * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @coreclassmod mousegrabber diff --git a/objects/client.c b/objects/client.c index fbabe7897..74bb0d6fc 100644 --- a/objects/client.c +++ b/objects/client.c @@ -19,7 +19,7 @@ * */ -/** A process window. +/** A process window managed by AwesomeWM. * * Clients are the name used by Awesome (and X11) to refer to a window. * @@ -39,9 +39,6 @@ * client's content. * Finally, each clients can have titlebars (see `awful.titlebar`). * - * Additionally to the classes described here, one can also use signals as - * described in @{signals} and X properties as described in @{xproperties}. - * * Some signal names are starting with a dot. These dots are artefacts from * the documentation generation, you get the real signal name by * removing the starting dot. @@ -273,9 +270,10 @@ lua_class_t client_class; * To implement focus stealing filters see `awful.ewmh.add_activate_filter`. * * @signal request::activate + * @tparam client c The client. * @tparam string context The context where this signal was used. * @tparam[opt] table hints A table with additional hints: - * @tparam[opt=false] boolean hints.raise should the client be raised? + * @tparam[opt=false] boolean hints.raise Should the client be raised? * @request client activate ewmh granted When the client asks to be activated. * @classsignal */ @@ -294,9 +292,10 @@ lua_class_t client_class; * moving the mouse. * * @signal request::autoactivate + * @tparam client c The client. * @tparam string context The context where this signal was used. * @tparam[opt] table hints A table with additional hints: - * @tparam[opt=false] boolean hints.raise should the client be raised? + * @tparam[opt=false] boolean hints.raise Should the client be raised? * @classsignal * */ @@ -307,7 +306,7 @@ lua_class_t client_class; * @tparam client c The client * @tparam string context Why and what to resize. This is used for the * handlers to know if they are capable of applying the new geometry. - * @tparam[opt={}] table Additional arguments. Each context handler may + * @tparam[opt={}] table hints Additional arguments. Each context handler may * interpret this differently. * @request client geometry client_maximize_horizontal granted When a client * (programmatically) asks for the maximization to be changed. @@ -320,6 +319,10 @@ lua_class_t client_class; * * @signal request::tag * @tparam client c The client requesting a new tag. + * @tparam[opt] tag tag A preferred tag. + * @tparam[opt] table hints + * @tparam[opt] string hints.reason + * @tparam[opt] screen hints.screen * @classsignal */ @@ -373,6 +376,8 @@ lua_class_t client_class; /** Emitted when a client gets tagged. * @signal tagged * @tparam tag t The tag object. + * @see tags + * @see untagged */ /** Emitted when a client gets unfocused. @@ -382,6 +387,8 @@ lua_class_t client_class; /** Emitted when a client gets untagged. * @signal untagged * @tparam tag t The tag object. + * @see tags + * @see tagged */ /** @@ -680,7 +687,7 @@ lua_class_t client_class; * } * * @property icon_sizes - * @tparam table sizes + * @tparam table icon_sizes * @propemits false false * @readonly * @see awful.widget.clienticon @@ -1108,7 +1115,7 @@ lua_class_t client_class; * advised to set `size_hints_honor` to `false` in the `ruled.client` rules. * * @property size_hints - * @tparam[opt] table|nil hints The hints. + * @tparam[opt] table|nil size_hints The hints. * @tparam[opt] table|nil hints.user_position A table with `x` and `y` keys. It * contains the preferred position of the client. This is set when the * position has been modified by the user. See `program_position`. @@ -1159,7 +1166,7 @@ lua_class_t client_class; * should be enabled. * * @property motif_wm_hints - * @tparam table hints The hints. + * @tparam table motif_wm_hints The hints. * @tparam[opt] boolean hints.functions.all * @tparam[opt] boolean hints.functions.resize * @tparam[opt] boolean hints.functions.move diff --git a/objects/drawable.c b/objects/drawable.c index 0bf6a21ec..d404b7a46 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -20,10 +20,7 @@ * */ -/** awesome drawable API. - * - * Furthermore to the classes described here, one can also use signals as - * described in @{signals}. +/** Low-level API to allow Cairo to draw on clients and wiboxes. * * @author Uli Schlachter <psychon@znc.in> * @copyright 2012 Uli Schlachter @@ -241,4 +238,6 @@ drawable_class_setup(lua_State *L) NULL); } +/* @DOC_cobject_COMMON@ */ + // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/objects/screen.c b/objects/screen.c index 9eccdc206..9582671e1 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -19,7 +19,7 @@ * */ -/** awesome screen API. +/** A physical or virtual screen object. * * Screen objects can be added and removed over time. To get a callback for all * current and future screens, use `awful.screen.connect_for_each_screen`: @@ -37,9 +37,6 @@ * Most basic Awesome objects also have a screen property, see `mouse.screen` * `client.screen`, `wibox.screen` and `tag.screen`. * - * Furthermore to the classes described here, one can also use signals as - * described in @{signals}. - * * @DOC_uml_nav_tables_screen_EXAMPLE@ * * @author Julien Danjou <julien@danjou.info> @@ -1677,8 +1674,8 @@ luaA_screen_count(lua_State *L) * * @tparam integer x X-coordinate for screen. * @tparam integer y Y-coordinate for screen. - * @tparam integer width width for screen. - * @tparam integer height height for screen. + * @tparam integer width Width for screen. + * @tparam integer height Height for screen. * @treturn screen The new screen. * @constructorfct fake_add */ @@ -1766,6 +1763,8 @@ luaA_screen_fake_remove(lua_State *L) * @tparam integer width The new width for screen. * @tparam integer height The new height for screen. * @method fake_resize + * @see split + * @see geometry */ static int luaA_screen_fake_resize(lua_State *L) diff --git a/objects/tag.c b/objects/tag.c index b76e9ea89..f9ec5cce2 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -19,7 +19,7 @@ * */ - /** awesome tag API. + /** Labelled container where `client` objects can be stored. * * What is a tag? * ============== diff --git a/root.c b/root.c index 4dcca6ad1..a159cc15c 100644 --- a/root.c +++ b/root.c @@ -19,7 +19,16 @@ * */ -/** awesome root window API. +/** APIs to interact with the root window. + * + * X11 windows (clients) are stored in a tree. Each window + * can have children. A common example of this are modal + * dialog windows. + * + * This tree goes beyond a process. The root window is where + * the wallpaper is drawn. It span the combined geometry of + * every screen. It also persist when AwesomeWM is restarted. + * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @coreclassmod root @@ -339,7 +348,7 @@ luaA_root_fake_input(lua_State *L) * (the wallpaper). * * @property keys - * @param table + * @tparam table keys * @see awful.key */ static int @@ -505,7 +514,7 @@ luaA_root_wallpaper(lua_State *L) /** Get the content of the root window as a cairo surface. * * @property content - * @tparam surface A cairo surface with the root window content (aka the whole surface from every screens). + * @tparam surface content A cairo surface with the root window content (aka the whole surface from every screens). * @see gears.surface */ static int diff --git a/xkb.c b/xkb.c index 40b98f8e2..44d1bb8b7 100644 --- a/xkb.c +++ b/xkb.c @@ -37,7 +37,7 @@ * Switch keyboard layout. * * @staticfct xkb_set_layout_group - * @tparam integer num keyboard layout number, integer from 0 to 3 + * @tparam integer num Keyboard layout number, integer from 0 to 3 */ int luaA_xkb_set_layout_group(lua_State *L) From 3510d96d6c8bdc372a134138c22ef2584d19ba71 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 5 Jul 2022 00:07:25 -0700 Subject: [PATCH 050/134] doc: Find and post-process untracked SVG files. Right now the UML template write many files which were not tracked by CMake. This caused them to be missing from the doc since the post-processing was added. --- CMakeLists.txt | 2 +- tests/examples/CMakeLists.txt | 8 ++++- tests/examples/_postprocess.lua | 5 ++- tests/examples/_postprocess_cleanup.lua | 45 +++++++++++++++++++++++++ 4 files changed, 55 insertions(+), 5 deletions(-) create mode 100755 tests/examples/_postprocess_cleanup.lua diff --git a/CMakeLists.txt b/CMakeLists.txt index 370f611d4..c05a7fbc9 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -292,7 +292,7 @@ if(GENERATE_DOC) configure_file(${SOURCE_DIR}/docs/ldoc.ltp ${BUILD_DIR}/docs COPYONLY) add_custom_target(ldoc ALL - DEPENDS ${BUILD_DIR}/doc/index.html + DEPENDS ${BUILD_DIR}/doc/index.html DOC_EXAMPLES_PPOSTPROCESS_CLEANUP ) if (STRICT_TESTS) diff --git a/tests/examples/CMakeLists.txt b/tests/examples/CMakeLists.txt index 2a63c4c43..8fe46ffc3 100644 --- a/tests/examples/CMakeLists.txt +++ b/tests/examples/CMakeLists.txt @@ -309,7 +309,6 @@ function(run_test test_path namespace escaped_content) DEPENDS ${TARGET_NAME}_RAW "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" ) - if(NOT ${OUTPUT_RAW_IMAGE_PATH} STREQUAL "") file(RELATIVE_PATH rel_output "${TOP_SOURCE_DIR}" "${OUTPUT_RAW_IMAGE_PATH}") if(tmp_content MATCHES "--DOC_GEN_OUTPUT") @@ -382,4 +381,11 @@ endforeach() add_custom_target(generate-examples DEPENDS ${EXAMPLE_DOC_GENERATED_FILES}) add_custom_target(check-examples DEPENDS ${EXAMPLE_DOC_TEST_TARGETS}) +# Some tests produce multiple files, find them and post-process them. +add_custom_target(DOC_EXAMPLES_PPOSTPROCESS_CLEANUP + COMMAND "${TOP_SOURCE_DIR}/tests/examples/_postprocess_cleanup.lua" ${RAW_IMAGE_DIR} ${IMAGE_DIR} "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" + VERBATIM + DEPENDS ${BUILD_DIR}/doc/index.html +) + # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker diff --git a/tests/examples/_postprocess.lua b/tests/examples/_postprocess.lua index 7ba00829b..363cc054a 100755 --- a/tests/examples/_postprocess.lua +++ b/tests/examples/_postprocess.lua @@ -23,9 +23,8 @@ local i, o = io.open(input, "r"), io.open(output, "w") if (not i) or (not o) then return end -local line, count = i:read("*line"), 0 - -local add_link = false +local line = i:read("*line") +local count while line do -- Deduplicate and concatenate the classes. diff --git a/tests/examples/_postprocess_cleanup.lua b/tests/examples/_postprocess_cleanup.lua new file mode 100755 index 000000000..90a2fae71 --- /dev/null +++ b/tests/examples/_postprocess_cleanup.lua @@ -0,0 +1,45 @@ +#!/usr/bin/env lua +-- This script locate and post process all "dangling" files CMake +-- didn't track. This allows the `tests/examples/` file to save more +-- than one output artifact. + +pcall(require, "luarocks.loader") + +local gio = require("lgi").Gio + +local name_attr = gio.FILE_ATTRIBUTE_STANDARD_NAME +local type_attr = gio.FILE_ATTRIBUTE_STANDARD_TYPE + +local raw_path, processed_path, script_path = ... + +local function list_svg(path) + local ret = {} + + local enumerator = gio.File.new_for_path(path):enumerate_children( + table.concat({name_attr, type_attr}, ",") , 0, nil, nil + ) + + for file in function() return enumerator:next_file() end do + local file_name = file:get_attribute_as_string(name_attr) + local file_type = file:get_file_type() + local match_ext = file_name:match("[.]svg$") + + if file_type == "REGULAR" and match_ext then + ret[file_name] = true + end + end + + return ret +end + +local raw_files, processed_files = list_svg(raw_path), list_svg(processed_path) + +for file in pairs(raw_files) do + if not processed_files[file] then + os.execute(table.concat({ + script_path, + raw_path .. "/" .. file, + processed_path .. "/" .. file + }, " ")) + end +end From 86d1b1c22ca584640043fc50187ff59a76e488a1 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 5 Jul 2022 01:37:14 -0700 Subject: [PATCH 051/134] doc: Add a mandatory `@noreturn` for functions and methods. The goal is to catch cases where the return value exists, but is forgotten. There was a large enough number of them to turn this into a real check. Initially, I just wanted to implement it to fix the problems, then delete the code. But since this is so common, I think it is worth the annoyance. --- docs/common/cobject.ldoc | 4 +++ docs/common/fixed.ldoc | 1 + docs/common/object.ldoc | 5 ++++ docs/common/signals.ldoc | 2 ++ docs/common/wibox.ldoc | 3 ++- docs/common/widget.ldoc | 3 +++ docs/config.ld | 13 +++++++++ lib/awful/button.lua | 3 ++- lib/awful/client.lua | 23 +++++++++++++++- lib/awful/completion.lua | 1 + lib/awful/hotkeys_popup/init.lua | 1 + lib/awful/hotkeys_popup/widget.lua | 18 +++++++++---- lib/awful/key.lua | 11 ++++---- lib/awful/keyboard.lua | 6 +++++ lib/awful/keygrabber.lua | 5 ++++ lib/awful/layout/init.lua | 15 +++++++---- lib/awful/menu.lua | 7 +++++ lib/awful/mouse/client.lua | 4 +-- lib/awful/mouse/init.lua | 6 +++++ lib/awful/permissions/init.lua | 1 + lib/awful/popup.lua | 2 ++ lib/awful/prompt.lua | 1 + lib/awful/screen.lua | 15 +++++++++-- lib/awful/spawn.lua | 11 ++++++-- lib/awful/tag.lua | 27 ++++++++++++++++--- lib/awful/titlebar.lua | 4 +++ lib/awful/tooltip.lua | 2 ++ lib/awful/wallpaper.lua | 10 +++++++ lib/awful/wibar.lua | 1 + lib/awful/widget/calendar_popup.lua | 2 ++ lib/awful/widget/keyboardlayout.lua | 1 + lib/beautiful/init.lua | 1 + lib/beautiful/theme_assets.lua | 2 ++ lib/beautiful/xresources.lua | 1 + lib/gears/color.lua | 1 + lib/gears/debug.lua | 6 ++++- lib/gears/matcher.lua | 6 +++++ lib/gears/object.lua | 4 +++ lib/gears/shape.lua | 27 +++++++++++++++++-- lib/gears/sort/topological.lua | 4 +++ lib/gears/string.lua | 1 + lib/gears/surface.lua | 1 + lib/gears/timer.lua | 7 ++++- lib/menubar/init.lua | 6 +++-- lib/menubar/menu_gen.lua | 4 +-- lib/menubar/utils.lua | 2 ++ lib/naughty/action.lua | 1 + lib/naughty/notification.lua | 4 +++ lib/ruled/client.lua | 6 +++-- lib/ruled/notification.lua | 8 +++++- lib/wibox/container/arcchart.lua | 1 + lib/wibox/container/background.lua | 1 + lib/wibox/container/constraint.lua | 1 + lib/wibox/container/margin.lua | 1 + lib/wibox/container/mirror.lua | 1 + lib/wibox/container/place.lua | 1 + lib/wibox/container/radialprogressbar.lua | 1 + lib/wibox/container/rotate.lua | 1 + lib/wibox/container/scroll.lua | 11 ++++++++ lib/wibox/hierarchy.lua | 3 +++ lib/wibox/init.lua | 4 +++ lib/wibox/layout/fixed.lua | 1 + lib/wibox/layout/flex.lua | 1 + lib/wibox/layout/grid.lua | 5 +++- lib/wibox/layout/manual.lua | 5 ++++ lib/wibox/layout/ratio.lua | 21 +++++++++------ lib/wibox/layout/stack.lua | 3 +++ lib/wibox/widget/base.lua | 13 +++++++++ lib/wibox/widget/graph.lua | 3 +++ lib/wibox/widget/init.lua | 2 ++ lib/wibox/widget/textclock.lua | 1 + luaa.c | 9 +++++++ mousegrabber.c | 6 +++-- objects/client.c | 5 ++++ objects/drawable.c | 9 ++++--- objects/screen.c | 4 +++ root.c | 2 ++ .../awful/placement/center_vertical.lua | 1 + .../awful/placement/maximize_horizontally.lua | 1 + .../awful/placement/maximize_vertically.lua | 1 + xkb.c | 1 + 81 files changed, 367 insertions(+), 53 deletions(-) diff --git a/docs/common/cobject.ldoc b/docs/common/cobject.ldoc index b8bf3d6f2..f449d4752 100644 --- a/docs/common/cobject.ldoc +++ b/docs/common/cobject.ldoc @@ -1,9 +1,11 @@ */ /** Disconnect from a signal. + * * @tparam string name The name of the signal. * @tparam function func The callback that should be disconnected. * @staticfct disconnect_signal + * @noreturn */ /** Emit a signal. @@ -13,12 +15,14 @@ * function receives the object as first argument and then any extra * arguments that are given to emit_signal(). * @staticfct emit_signal + * @noreturn */ /** Connect to a signal. * @tparam string name The name of the signal. * @tparam function func The callback to call when the signal is emitted. * @staticfct connect_signal + * @noreturn */ /* diff --git a/docs/common/fixed.ldoc b/docs/common/fixed.ldoc index 359fd2ad7..365b161f9 100644 --- a/docs/common/fixed.ldoc +++ b/docs/common/fixed.ldoc @@ -68,6 +68,7 @@ --- Reset the layout. This removes all widgets from the layout. -- @method reset +-- @noreturn -- @emits widget::reset -- @emitstparam widget::reset widget self The layout. -- @interface layout diff --git a/docs/common/object.ldoc b/docs/common/object.ldoc index ed21bedac..8eb477e1c 100644 --- a/docs/common/object.ldoc +++ b/docs/common/object.ldoc @@ -3,6 +3,8 @@ -- @tparam string name The name of the signal. -- @tparam function func The callback that should be disconnected. -- @method disconnect_signal +-- @treturn boolean `true` when the function was disconnected or `false` if it +-- wasn't found. -- @baseclass gears.object --- Emit a signal. @@ -12,12 +14,14 @@ -- function receives the object as first argument and then any extra -- arguments that are given to emit_signal(). -- @method emit_signal +-- @noreturn -- @baseclass gears.object --- Connect to a signal. -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method connect_signal +-- @noreturn -- @baseclass gears.object --- Connect to a signal weakly. @@ -31,4 +35,5 @@ -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method weak_connect_signal +-- @noreturn -- @baseclass gears.object diff --git a/docs/common/signals.ldoc b/docs/common/signals.ldoc index 30499a8ef..b8f1a9439 100644 --- a/docs/common/signals.ldoc +++ b/docs/common/signals.ldoc @@ -10,6 +10,7 @@ -- -- @tparam string name The name of the signal -- @tparam function func The function to attach +-- @noreturn -- @staticfct naughty.connect_signal -- @usage naughty.connect_signal("added", function(notif) -- -- do something @@ -18,6 +19,7 @@ --- Emit a module signal. -- @tparam string name The signal name. -- @param ... The signal callback arguments +-- @noreturn -- @staticfct naughty.emit_signal --- Disconnect a signal from a source. diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc index b12440524..7c1415adc 100644 --- a/docs/common/wibox.ldoc +++ b/docs/common/wibox.ldoc @@ -191,7 +191,7 @@ -- @baseclass wibox -- @tparam[opt=nil] table|nil geo A table with coordinates to modify. If -- nothing is specified, it only returns the current geometry. --- @return A table with wibox coordinates and geometry. +-- @treturn table A table with wibox coordinates and geometry. -- @method geometry -- @emits property::geometry When the geometry change. -- @emitstparam property::geometry table geo The geometry table. @@ -217,6 +217,7 @@ -- @param args An array containing the widgets disposition -- @baseclass wibox -- @method setup +-- @noreturn --- The background of the wibox. -- diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index a08fdc75c..1ef1efb57 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -26,6 +26,7 @@ -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @tparam table args An array containing the widgets disposition -- @method setup +-- @noreturn -- @baseclass wibox.widget --- Force a widget height. @@ -60,6 +61,7 @@ --- Add a new `awful.button` to this widget. -- @tparam awful.button button The button to add. -- @method add_button +-- @noreturn -- @baseclass wibox.widget --- Emit a signal and ensure all parent widgets in the hierarchies also @@ -69,6 +71,7 @@ -- @param ... Other arguments -- @baseclass wibox.widget -- @method emit_signal_recursive +-- @noreturn --- 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 a92528d74..56a3efe3e 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -824,6 +824,14 @@ add_custom_tag { auto_subtags = false } +-- Forces every method and function to have either `@treturn` or `@noreturn`. +-- This avoids the many case where the return value was forgotten. +add_custom_tag { + name = "noreturn", + hidden = true, + auto_subtags = false +} + add_custom_tag { name = "signalhandler", hidden = false, @@ -1342,6 +1350,11 @@ local function sanitize_return_type(item) end item.display_type = item.display_type .. "" + elseif not item.tags["noreturn"] then + print( + "WARNING:", item.name, "from", item.module.name, + "doesn't have a return value or @noreturn" + ) end item.compact_signature = true diff --git a/lib/awful/button.lua b/lib/awful/button.lua index 21c46c7f7..db5ecced3 100644 --- a/lib/awful/button.lua +++ b/lib/awful/button.lua @@ -105,7 +105,8 @@ button.names = { -- @tparam function on_release --- Execute this mousebinding. --- @method :trigger +-- @method trigger +-- @noreturn function button:set_button(b) for _, v in ipairs(self) do diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 28df06d51..dbaf3bfcf 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -178,6 +178,7 @@ end -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client and its first -- tag as arguments. +-- @noreturn -- @request client activate client.jumpto granted When a client is activated -- because `c:jump_to()` is called. -- @see activate @@ -298,6 +299,7 @@ end -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @tparam[opt="focused"] client c The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.global_bydirection @@ -329,6 +331,7 @@ end -- @staticfct awful.client.swap.global_bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @tparam[opt=client.focus] client sel The client. +-- @noreturn -- @request client activate client.swap.global_bydirection granted When a client -- could be activated because `awful.client.swap.global_bydirection` was called. -- @see swap @@ -372,6 +375,7 @@ end -- @staticfct awful.client.swap.byidx -- @tparam integer i The index. Use `1` to get the next, `-1` to get the previous. -- @tparam[opt=client.focus] client c The client, otherwise focused one is used. +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.bydirection @@ -397,6 +401,7 @@ end -- @tparam[opt=false] boolean clockwise True to cycle clients clockwise. -- @tparam[opt=awful.screen.focused()] screen s The screen where to cycle clients. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.bydirection @@ -424,6 +429,7 @@ end -- -- @method append_keybinding -- @tparam awful.key key The key. +-- @noreturn -- @see remove_keybinding -- @see append_mousebinding -- @see remove_mousebinding @@ -431,17 +437,20 @@ end --- Remove a keybinding. -- -- @method remove_keybinding +-- @noreturn -- @tparam awful.key key The key. --- Append a mousebinding. -- -- @method append_mousebinding -- @tparam awful.button button The button. +-- @noreturn --- Remove a mousebinding. -- -- @method remove_mousebinding -- @tparam awful.button button The button. +-- @noreturn --- Get the master window. -- @@ -476,6 +485,7 @@ end -- @DOC_sequences_client_to_primary_EXAMPLE@ -- -- @method to_primary_section +-- @noreturn -- @see swap -- @see to_secondary_section function client.object:to_primary_section() @@ -494,6 +504,7 @@ end -- @DOC_sequences_client_to_secondary_EXAMPLE@ -- -- @method to_secondary_section +-- @noreturn -- @see swap -- @see to_primary_section @@ -527,6 +538,7 @@ end -- @tparam[opt=0] integer y The relative y coordinate. -- @tparam[opt=0] integer w The relative width. -- @tparam[opt=0] integer h The relative height. +-- @noreturn -- @see geometry -- @see x -- @see y @@ -558,6 +570,7 @@ end -- -- @method move_to_tag -- @tparam tag target The tag to move the client to. +-- @noreturn -- @request client activate client.movetotag granted When a client could be -- activated because `c:move_to_tag()` was called. -- @see tags @@ -591,6 +604,7 @@ end -- -- @method toggle_tag -- @tparam tag target The tag to move the client to. +-- @noreturn -- @see tags function client.object.toggle_tag(self, target) -- Check that tag and client screen are identical @@ -631,6 +645,7 @@ end -- -- @method move_to_screen -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1. +-- @noreturn -- @see screen -- @see request::activate -- @request client activate client.movetoscreen granted When a client could be @@ -682,6 +697,7 @@ end -- @DOC_sequences_client_to_selected_tags1_EXAMPLE@ -- -- @method to_selected_tags +-- @noreturn -- @see screen.selected_tags function client.object.to_selected_tags(self) local tags = {} @@ -1444,6 +1460,7 @@ end -- @tparam string prop The property name. -- @tparam string kind The type (used for register_xproperty). -- One of "string", "number" or "boolean". +-- @noreturn function client.property.persist(prop, kind) local xprop = "awful.client.property." .. prop capi.awesome.register_xproperty(xprop, kind) @@ -1466,7 +1483,7 @@ end -- @tparam integer start What index to start iterating from. Defaults to using the -- index of the currently focused client. -- @tparam[opt=nil] screen s Which screen to use. nil means all screens. --- +-- @treturn function A Lua iterator (to use in a `for` loop). -- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances -- local urxvt = function (c) @@ -1666,6 +1683,7 @@ end -- @tparam[opt=false] boolean args.switch_to_tag -- @tparam[opt=false] boolean args.action Once activated, perform an action. -- @tparam[opt=false] boolean args.toggle_minimization +-- @noreturn -- @request client activate args.context granted Will use the context defined in -- `args.context`. -- @see awful.permissions.add_activate_filter @@ -1712,6 +1730,7 @@ end -- @method grant -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions --- Deny a permission for a client. @@ -1719,6 +1738,7 @@ end -- @method deny -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions pcommon.setup_grant(client.object, "client") @@ -1849,6 +1869,7 @@ end) -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client as argument. +-- @noreturn -- Add clients during startup to focus history. -- This used to happen through permissions.activate, but that only handles visible diff --git a/lib/awful/completion.lua b/lib/awful/completion.lua index 45ca4598d..a23590cce 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. -- @tparam string src The bash completion source file, `/etc/bash_completion` by default. +-- @noreturn -- @staticfct awful.completion.bashcomp_load function completion.bashcomp_load(src) if src then bashcomp_src = src end diff --git a/lib/awful/hotkeys_popup/init.lua b/lib/awful/hotkeys_popup/init.lua index 4cb6e4772..058bae128 100644 --- a/lib/awful/hotkeys_popup/init.lua +++ b/lib/awful/hotkeys_popup/init.lua @@ -25,6 +25,7 @@ local hotkeys_popup = { -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. -- @staticfct awful.hotkeys_popup.show_help +-- @noreturn -- @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 e0d5a5613..b6e4ec54b 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -685,11 +685,13 @@ function widget.new(args) --- Show popup with hotkeys help. - -- @tparam[opt] client c Client. - -- @tparam[opt] screen s Screen. - -- @tparam[opt] table show_args Additional arguments. + -- @tparam[opt=client.focus] client c Client. + -- @tparam[opt=c.screen] screen s Screen. + -- @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. + -- @treturn awful.keygrabber The keybrabber used to detect when the key is + -- released. -- @method show_help function widget_instance:show_help(c, s, show_args) show_args = show_args or {} @@ -750,6 +752,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. + -- @noreturn -- @method add_hotkeys function widget_instance:add_hotkeys(hotkeys) for group, bindings in pairs(hotkeys) do @@ -773,6 +776,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. + -- @noreturn -- @method add_group_rules function widget_instance:add_group_rules(group, data) self.group_rules[group] = data @@ -794,6 +798,8 @@ 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. +-- @treturn awful.keygrabber The keybrabber used to detect when the key is +-- released. -- @staticfct awful.hotkeys_popup.widget.show_help function widget.show_help(...) return get_default_widget():show_help(...) @@ -803,9 +809,10 @@ end -- (default widget instance will be used). -- @tparam table hotkeys Table with bindings, -- see `awful.hotkeys_popup.key.vim` as an example. +-- @noreturn -- @staticfct awful.hotkeys_popup.widget.add_hotkeys function widget.add_hotkeys(...) - return get_default_widget():add_hotkeys(...) + get_default_widget():add_hotkeys(...) end --- Add hotkey group rules for third-party applications @@ -813,9 +820,10 @@ end -- @tparam string group Rule group name, -- @tparam table data Rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. +-- @noreturn -- @staticfct awful.hotkeys_popup.widget.add_group_rules function widget.add_group_rules(group, data) - return get_default_widget():add_group_rules(group, data) + get_default_widget():add_group_rules(group, data) end return widget diff --git a/lib/awful/key.lua b/lib/awful/key.lua index efb07a52e..35fff8f61 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -159,7 +159,8 @@ end --- Execute this keybinding. -- --- @method :trigger +-- @method trigger +-- @noreturn function key:trigger() local data = reverse_map[self] @@ -432,10 +433,10 @@ function key.new(args, keycode, press, release, data) end --- Compare a key object with modifiers and key. --- @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 +-- @tparam table pressed_mod The modifiers to compare with. +-- @tparam string pressed_key The key to compare with. +-- @treturn boolean If the key and modifier match. +-- @method match function key.match(self, pressed_mod, pressed_key) -- First, compare key. if pressed_key ~= self.key then return false end diff --git a/lib/awful/keyboard.lua b/lib/awful/keyboard.lua index ea49ba6bb..3ca61dc1f 100644 --- a/lib/awful/keyboard.lua +++ b/lib/awful/keyboard.lua @@ -46,6 +46,7 @@ capi.awesome.connect_signal("xkb::map_changed", function() conversion = nil end) -- @tparam table modifiers A modified table. Valid modifiers are: `Any`, `Mod1`, -- `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. -- @tparam string key The key. +-- @noreturn -- @staticfct awful.keyboard.emulate_key_combination function module.emulate_key_combination(modifiers, key) local modmap = generate_conversion_map() @@ -90,6 +91,7 @@ end -- -- @staticfct awful.keyboard.append_global_keybinding -- @tparam awful.key key The key object. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybindings -- @see awful.keyboard.remove_global_keybinding @@ -107,6 +109,7 @@ end -- @tparam table keys A table of `awful.key` objects. Optionally, it can have -- a `group` entry. If set, the `group` property will be set on all `awful.keys` -- objects. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybinding -- @see awful.keyboard.remove_global_keybinding @@ -131,6 +134,7 @@ end -- -- @staticfct awful.keyboard.remove_global_keybinding -- @tparam awful.key key The key object. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybinding @@ -145,6 +149,7 @@ local default_keys = {} -- -- @staticfct awful.keyboard.append_client_keybinding -- @tparam awful.key key The key. +-- @noreturn -- @emits client_keybinding::added -- @emitstparam client_keybinding::added awful.key key The key. -- @see awful.key @@ -164,6 +169,7 @@ end -- -- @staticfct awful.keyboard.append_client_keybindings -- @tparam table keys A table containing `awful.key` objects. +-- @noreturn -- @emits client_keybinding::added -- @emitstparam client_keybinding::added awful.key key The key. -- @see awful.key diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index f28cce404..ca5211060 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -500,6 +500,7 @@ end -- @method stop -- @tparam string|nil stop_key Override the key passed to `stop_callback` **DEPRECATED** -- @tparam tale|nil Override the modifiers passed to `stop_callback` **DEPRECATED** +-- @noreturn -- @emits stopped -- @emits property::current_instance function keygrabber:stop(stop_key, stop_mods) @@ -535,6 +536,7 @@ end -- @method add_keybinding -- @tparam awful.key key The key. -- @tparam string description.group The keybinding group +-- @noreturn function keygrabber:add_keybinding(key, keycode, callback, description) local mods = not key._is_awful_key and key or nil @@ -852,6 +854,7 @@ local signals = {} -- @staticfct awful.keygrabber.connect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. +-- @noreturn function keygrab.connect_signal(name, callback) signals[name] = signals[name] or {} @@ -865,6 +868,7 @@ end -- @staticfct awful.keygrabber.disconnect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. +-- @noreturn function keygrab.disconnect_signal(name, callback) signals[name] = signals[name] or {} @@ -885,6 +889,7 @@ end -- @staticfct awful.keygrabber.emit_signal -- @tparam string name The signal name. -- @param ... Other arguments for the callbacks. +-- @noreturn function keygrab.emit_signal(name, ...) signals[name] = signals[name] or {} diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua index ba7106234..d66be87bd 100644 --- a/lib/awful/layout/init.lua +++ b/lib/awful/layout/init.lua @@ -109,7 +109,7 @@ local arrange_lock = false local delayed_arrange = {} --- Get the current layout. --- @param screen The screen. +-- @tparam screen screen The screen. -- @return The layout function. -- @staticfct awful.layout.get function layout.get(screen) @@ -122,9 +122,10 @@ function layout.get(screen) end --- Change the layout of the current tag. --- @param i Relative index. --- @param s The screen. --- @param[opt] layouts A table of layouts. +-- @tparam integer i Relative index. +-- @tparam screen s The screen. +-- @tparam[opt=s.selected_tag.layouts] table layouts A table of layouts. +-- @noreturn -- @staticfct awful.layout.inc function layout.inc(i, s, layouts) if type(i) == "table" then @@ -171,6 +172,7 @@ end --- Set the layout function of the current tag. -- @tparam layout|function l Layout object or function. -- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify. +-- @noreturn -- @staticfct awful.layout.set function layout.set(l, t) t = t or capi.mouse.screen.selected_tag @@ -232,7 +234,8 @@ function layout.parameters(t, screen) end --- Arrange a screen using its current layout. --- @param screen The screen to arrange. +-- @tparam screen screen The screen to arrange. +-- @noreturn -- @staticfct awful.layout.arrange function layout.arrange(screen) screen = get_screen(screen) @@ -275,6 +278,7 @@ end -- -- @staticfct awful.layout.append_default_layout -- @tparam layout to_add A valid tag layout. +-- @noreturn -- @see awful.layout.layouts function layout.append_default_layout(to_add) rawset(default_layouts, #default_layouts+1, to_add) @@ -311,6 +315,7 @@ end -- -- @staticfct awful.layout.append_default_layouts -- @tparam table layouts A table of valid tag layout. +-- @noreturn -- @see awful.layout.layouts function layout.append_default_layouts(layouts) for _, l in ipairs(layouts) do diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index 33caa8ceb..474b74320 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -360,6 +360,7 @@ end -- @tparam[opt={}] table args The arguments -- @tparam[opt=mouse.coords] table args.coords The menu position. A table with -- `x` and `y` as keys and position (in pixels) as values. +-- @noreturn -- @method show function menu:show(args) args = args or {} @@ -375,6 +376,7 @@ end --- Hide a menu popup. -- @method hide +-- @noreturn function menu:hide() -- Remove items from screen for i = 1, #self.items do @@ -394,6 +396,7 @@ end -- @tparam table args The arguments. -- @tparam[opt=mouse.coords] table args.coords The menu position. A table with -- `x` and `y` as keys and position (in pixels) as values. +-- @noreturn -- @method toggle function menu:toggle(args) if self.wibox.visible then @@ -405,6 +408,7 @@ end --- Update menu content. -- @method update +-- @noreturn function menu:update() if self.wibox.visible then self:show({ coords = { x = self.x, y = self.y } }) @@ -415,6 +419,7 @@ end --- Get the elder parent so for example when you kill -- it, it will destroy the whole family. -- @method get_root +-- @treturn awful.menu The root menu. function menu:get_root() return self.parent and menu.get_root(self.parent) or self end @@ -425,6 +430,7 @@ end -- @tparam[opt=awful.menu.entry] function args.new The menu entry constructor. -- @tparam[opt] table args.theme The menu entry theme. -- @tparam[opt] number index The index where the new entry will inserted. +-- @treturn table|nil The new item. -- @method add function menu:add(args, index) if not args then return end @@ -482,6 +488,7 @@ end --- Delete menu entry at given position. -- @tparam table|number num The index in the table of the menu entry to be deleted; can be also the menu entry itself. +-- @noreturn -- @method delete function menu:delete(num) if type(num) == "table" then diff --git a/lib/awful/mouse/client.lua b/lib/awful/mouse/client.lua index 5170eb3a1..3a495b86b 100644 --- a/lib/awful/mouse/client.lua +++ b/lib/awful/mouse/client.lua @@ -13,9 +13,9 @@ local module = {} --- Move a client. -- @staticfct awful.mouse.client.move --- @param c The client to move, or the focused one if nil. +-- @tparam client 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. +-- @noreturn -- @request client geometry mouse.move granted When `awful.mouse.client.move` is -- called. function module.move(c, snap, finished_cb) --luacheck: no unused args diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index b4d620360..9648f7ab4 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -201,6 +201,7 @@ end --- Move the wibox under the cursor. -- @staticfct awful.mouse.wibox.move -- @tparam wibox w The wibox to move, or none to use that under the pointer +-- @noreturn -- @request wibox geometry mouse.move granted Requests to move the wibox. function mouse.wibox.move(w) w = w or mouse.current_wibox @@ -248,6 +249,7 @@ end -- -- @staticfct awful.mouse.append_global_mousebinding -- @tparam awful.button button The button object. +-- @noreturn -- @see awful.button function mouse.append_global_mousebinding(button) @@ -264,6 +266,7 @@ end -- @tparam table buttons A table of `awful.button` objects. Optionally, it can have -- a `group` entry. If set, the `group` property will be set on all `awful.buttons` -- objects. +-- @noreturn -- @see awful.button function mouse.append_global_mousebindings(buttons) @@ -286,6 +289,7 @@ end -- -- @staticfct awful.mouse.remove_global_mousebinding -- @tparam awful.button button The button object. +-- @noreturn -- @see awful.button function mouse.remove_global_mousebinding(button) @@ -298,6 +302,7 @@ local default_buttons = {} -- -- @staticfct awful.mouse.append_client_mousebinding -- @tparam awful.button button The button. +-- @noreturn -- @emits client_mousebinding::added -- @emitstparam client_mousebinding::added awful.button button The button. -- @see awful.button @@ -317,6 +322,7 @@ end -- -- @staticfct awful.mouse.append_client_mousebindings -- @tparam table buttons A table containing `awful.button` objects. +-- @noreturn -- @see awful.button -- @see awful.keyboard.append_client_keybinding -- @see awful.mouse.append_client_mousebinding diff --git a/lib/awful/permissions/init.lua b/lib/awful/permissions/init.lua index 5b59b8e1a..9c5be3a79 100644 --- a/lib/awful/permissions/init.lua +++ b/lib/awful/permissions/init.lua @@ -241,6 +241,7 @@ end -- -- @tparam function f The callback -- @tparam[opt] string context The `request::activate` context +-- @noreturn -- @see generic_activate_filters -- @see contextual_activate_filters -- @see remove_activate_filter diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index cde263434..9c5845891 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -264,6 +264,7 @@ end -- @tparam widget widget The widget -- @tparam[opt=1] number button The button index -- @method bind_to_widget +-- @noreturn function popup:bind_to_widget(widget, button) if not self._private.button_for_widget then self._private.button_for_widget = {} @@ -276,6 +277,7 @@ end --- Unbind the popup from a widget button. -- @tparam widget widget The widget -- @method unbind_to_widget +-- @noreturn 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 caf3c57b0..52b4f34e8 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -461,6 +461,7 @@ end -- @tparam[opt] function keypressed_callback The callback function to call -- with mod table, key and command as arguments when a key was pressed. -- [**DEPRECATED**] +-- @noreturn -- @see gears.color -- @staticfct awful.prompt.run function prompt.run(args, textbox, exe_callback, completion_callback, diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index 6d931bda3..e73128624 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -91,6 +91,7 @@ end -- or keeps its position relative to the current focused screen. -- @staticfct awful.screen.focus -- @tparam screen screen Screen number (defaults / falls back to mouse.screen). +-- @treturn screen The newly focused screen. -- @request client activate screen.focus granted The most recent focused client -- for this screen should be re-activated. function screen.focus(_screen) @@ -126,6 +127,8 @@ function screen.focus(_screen) if c then c:emit_signal("request::activate", "screen.focus", {raise=false}) end + + return _screen end --- Get the next screen in a specific direction. @@ -175,6 +178,7 @@ end -- @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. +-- @treturn screen The newly focusd screen. function screen.focus_relative(offset) return screen.focus(gmath.cycle(capi.screen.count(), screen.focused().index + offset)) @@ -542,6 +546,7 @@ end -- @staticfct awful.screen.connect_for_each_screen -- @tparam function func The function to call. -- @tparam screen func.screen The screen. +-- @noreturn function screen.connect_for_each_screen(func) for s in capi.screen do func(s) @@ -552,6 +557,7 @@ end --- Undo the effect of `awful.screen.connect_for_each_screen`. -- @staticfct awful.screen.disconnect_for_each_screen -- @tparam function func The function that should no longer be called. +-- @noreturn function screen.disconnect_for_each_screen(func) capi.screen.disconnect_signal("added", func) end @@ -652,10 +658,14 @@ end -- -- @DOC_awful_screen_split2_EXAMPLE@ -- --- @tparam[opt] table ratios The different ratios to split into. If none is --- provided, it is split in half. +-- @tparam[opt={50﹐50}] table ratios The different ratios to split into. If none +-- is provided, it is split in half. -- @tparam[opt] string mode Either "vertical" or "horizontal". If none is -- specified, it will split along the longest axis. +-- @treturn table A table with the screen objects. The first value is the +-- original screen object (`s`) and the following one(s) are the new screen +-- objects. The values are ordered from left to right or top to bottom depending +-- on the value of `mode`. -- @method split function screen.object.split(s, ratios, mode, _geo) s = get_screen(s) @@ -737,6 +747,7 @@ end -- defaulting to 96. -- -- @tparam boolean enabled Enable or disable automatic DPI support. +-- @noreturn -- @staticfct awful.screen.set_auto_dpi_enabled function screen.set_auto_dpi_enabled(enabled) for s in capi.screen do diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua index beae02d0a..7d3e94508 100644 --- a/lib/awful/spawn.lua +++ b/lib/awful/spawn.lua @@ -364,6 +364,10 @@ end --- Spawn a program using the shell. -- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`). -- @tparam string cmd The command. +-- @treturn[1] integer The forked PID. +-- @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.with_shell function spawn.with_shell(cmd) if cmd and cmd ~= "" then @@ -500,6 +504,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? +-- @noreturn -- @staticfct awful.spawn.read_lines function spawn.read_lines(input_stream, line_callback, done_callback, close) local stream = Gio.DataInputStream.new(input_stream) @@ -649,8 +654,9 @@ end -- @tparam[opt] string unique_id A string to identify the client so it isn't executed -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. --- @see ruled.client +-- @noreturn -- @staticfct awful.spawn.once +-- @see ruled.client 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) @@ -682,8 +688,9 @@ end -- @tparam[opt] string unique_id A string to identify the client so it isn't executed -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. --- @see ruled.client +-- @noreturn -- @staticfct awful.spawn.single_instance +-- @see ruled.client 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) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 958da3937..2ceadb4d4 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -221,6 +221,7 @@ end -- -- @method swap -- @tparam tag tag2 The second tag +-- @noreturn -- @see client.swap function tag.object.swap(self, tag2) local idx1, idx2 = tag.object.get_index(self), tag.object.get_index(tag2) @@ -335,6 +336,7 @@ end -- @staticfct awful.tag.find_fallback -- @tparam[opt=awful.screen.focused()] screen screen The screen to look for a tag on. -- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. +-- @treturn tag|nil Returns a fallback tag if one was found, otherwise `nil`. function tag.find_fallback(screen, invalids) local scr = screen or ascreen.focused() local t = invalids or scr.selected_tags @@ -356,6 +358,7 @@ end -- @tparam table args The arguments. -- @tparam tag args.fallback_tag A fallback tag. -- @tparam[opt=false] boolean args.allow_untagged Allow the untagged clients to remain untagged. +-- @noreturn -- @emits cleared After all clients have been untagged. -- @emits untagged For each currently tagged clients. -- @emitstparam untagged client c The untagged client. @@ -480,6 +483,7 @@ end --- Update the tag history. -- @staticfct awful.tag.history.update -- @tparam screen obj Screen object. +-- @noreturn function tag.history.update(obj) local s = get_screen(obj) local curtags = s.selected_tags @@ -520,6 +524,7 @@ end --- Revert tag history. -- @staticfct awful.tag.history.restore +-- @noreturn -- @tparam screen screen The screen. -- @tparam number 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 @@ -752,6 +757,7 @@ end -- @see master_width_factor -- @tparam number add Value to add to master width factor. -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. +-- @noreturn function tag.incmwfact(add, t) t = t or t or ascreen.focused().selected_tag tag.object.set_master_width_factor(t, tag.object.get_master_width_factor(t) + add) @@ -1128,6 +1134,7 @@ end -- @staticfct awful.tag.incgap -- @tparam number add Value to add to the spacing between clients -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. +-- @noreturn -- @see gap -- @see beautiful.useless_gap function tag.incgap(add, t) @@ -1247,6 +1254,7 @@ end -- "expand" (fill all the available workarea) or -- `master_width_factor` (fill only an area inside the master width factor) -- @tparam[opt=tag.selected()] tag t The tag to modify +-- @noreturn function tag.setmfpol(policy, t) gdebug.deprecate("Use t.master_fill_policy = policy instead of awful.tag.setmfpol", {deprecated_in=4}) @@ -1257,6 +1265,7 @@ end --- Toggle size fill policy for the master client(s) -- between "expand" and `master_width_factor`. -- @staticfct awful.tag.togglemfpol +-- @noreturn -- @see master_fill_policy -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.togglemfpol(t) @@ -1343,6 +1352,7 @@ end -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @tparam[opt=false] boolean sensible Limit nmaster based on the number of -- visible tiled windows? +-- @noreturn function tag.incnmaster(add, t, sensible) t = t or ascreen.focused().selected_tag @@ -1461,6 +1471,7 @@ end -- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @tparam[opt=false] boolean sensible Limit column_count based on the number -- of visible tiled windows? +-- @noreturn function tag.incncol(add, t, sensible) t = t or ascreen.focused().selected_tag @@ -1492,6 +1503,7 @@ end -- -- @staticfct awful.tag.viewnone -- @tparam[opt] int|screen screen The screen. +-- @noreturn function tag.viewnone(screen) screen = screen or ascreen.focused() local tags = screen.tags @@ -1511,6 +1523,7 @@ end -- @see screen.tags -- @tparam number i The **relative** index to see. -- @tparam[opt] screen screen The screen. +-- @noreturn -- @see awful.tag.viewnext -- @see awful.tag.viewprev function tag.viewidx(i, screen) @@ -1552,10 +1565,11 @@ end -- -- @staticfct awful.tag.viewnext -- @tparam screen screen The screen. +-- @noreturn -- @see awful.tag.viewidx -- @see awful.tag.viewprev function tag.viewnext(screen) - return tag.viewidx(1, screen) + tag.viewidx(1, screen) end --- View previous tag. This is the same a `tag.viewidx(-1)`. @@ -1566,10 +1580,11 @@ end -- -- @staticfct awful.tag.viewprev -- @tparam screen screen The screen. +-- @noreturn -- @see awful.tag.viewidx -- @see awful.tag.viewnext function tag.viewprev(screen) - return tag.viewidx(-1, screen) + tag.viewidx(-1, screen) end --- View only a tag. @@ -1577,6 +1592,7 @@ end -- @DOC_sequences_tag_view_only_EXAMPLE@ -- -- @method view_only +-- @noreturn -- @see selected function tag.object.view_only(self) local tags = self.screen.tags @@ -1595,6 +1611,7 @@ end --- View only a tag. -- @deprecated awful.tag.viewonly +-- @noreturn -- @see tag.view_only -- @tparam tag t The tag object. function tag.viewonly(t) @@ -1613,6 +1630,7 @@ end -- @tparam table tags A table with tags to view only. -- @tparam[opt] screen screen The screen of the tags. -- @tparam[opt=#tags] number maximum The maximum number of tags to select. +-- @noreturn function tag.viewmore(tags, screen, maximum) maximum = maximum or #tags local selected = 0 @@ -1643,8 +1661,9 @@ end --- Toggle selection of a tag -- @staticfct awful.tag.viewtoggle --- @see selected -- @tparam tag t Tag to be toggled +-- @noreturn +-- @see selected function tag.viewtoggle(t) t.selected = not t.selected capi.screen[tag.getproperty(t, "screen")]:emit_signal("tag::history::update") @@ -1701,6 +1720,7 @@ end --- Tag a client with the set of current tags. -- @deprecated awful.tag.withcurrent -- @tparam client c The client to tag. +-- @noreturn function tag.withcurrent(c) gdebug.deprecate("Use c:to_selected_tags() instead of awful.tag.selectedlist", {deprecated_in=4}) @@ -1740,6 +1760,7 @@ end -- @tparam screen|nil screen The screen concerned, or all if `nil`. -- @tparam string signal The signal name. -- @tparam function callback +-- @noreturn function tag.attached_connect_signal(screen, ...) if screen then attached_connect_signal_screen(screen, ...) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index db59510c0..99873b216 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -535,6 +535,7 @@ local titlebar = { -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @tparam table args An array containing the widgets disposition -- @method setup +-- @noreturn local all_titlebars = setmetatable({}, { __mode = 'k' }) @@ -713,6 +714,7 @@ end -- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.show -- @request client titlebars show granted Called when `awful.titlebar.show` is -- called. @@ -729,6 +731,7 @@ end -- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.hide function titlebar.hide(c, position) position = position or "top" @@ -739,6 +742,7 @@ end -- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.toggle -- @request client titlebars toggle granted Called when `awful.titlebar.toggle` is -- called. diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index e06ecbeaf..3c6a8a14c 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -575,6 +575,7 @@ end -- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. +-- @noreturn -- @method add_to_object function tooltip:add_to_object(obj) if not obj then return end @@ -588,6 +589,7 @@ end -- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. +-- @noreturn -- @method remove_from_object function tooltip:remove_from_object(obj) obj:disconnect_signal("mouse::enter", self.show) diff --git a/lib/awful/wallpaper.lua b/lib/awful/wallpaper.lua index 19dd08c9f..0a8340558 100644 --- a/lib/awful/wallpaper.lua +++ b/lib/awful/wallpaper.lua @@ -713,6 +713,7 @@ end -- -- @method add_screen -- @tparam screen screen The screen object. +-- @noreturn -- @see remove_screen function module:add_screen(s) s = get_screen(s) @@ -741,6 +742,7 @@ end -- wallpaper will have an overlap. -- -- @method detach +-- @noreturn -- @see remove_screen -- @see add_screen function module:detach() @@ -764,6 +766,7 @@ end -- really need to repaint the wallpaper, call this method. -- -- @method repaint +-- @noreturn function module:repaint() for _, s in ipairs(self._private.screens) do pending_repaint[s] = true @@ -791,21 +794,28 @@ end -- -- @method remove_screen -- @tparam screen screen The screen to remove. +-- @treturn boolean `true` if the screen was removed and `false` if the screen +-- wasn't found. -- @see detach -- @see add_screen -- @see screens function module:remove_screen(s) + local ret = false + s = get_screen(s) for k, s2 in ipairs(self._private.screens) do if s == s2 then table.remove(self._private.screens, k) + ret = true end end backgrounds[s] = nil self:repaint() + + return ret end --- Create a wallpaper. diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index 02377e292..2a35b03a2 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -442,6 +442,7 @@ end --- Remove a wibar. -- @method remove +-- @noreturn function awfulwibar.remove(self) self.visible = false diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 5ec6effa9..ff7dc3c03 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -240,10 +240,12 @@ function calendar_popup:call_calendar(offset, position, screen) end --- Toggle calendar visibility. +-- @treturn boolean The new value of `visible`. -- @method toggle function calendar_popup:toggle() self:call_calendar(0) self.visible = not self.visible + return self.visible end --- Attach the calendar to a widget to display at a specific position. diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index a512d9fdc..781646dfb 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -256,6 +256,7 @@ local function update_layout(self) end --- Select the next layout. +-- @noreturn -- @method next_layout --- Create a keyboard layout widget. diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index 44601324c..d0d0a3d99 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -225,6 +225,7 @@ end --- Get the height of a font. -- -- @tparam string name Name of the font. +-- @treturn number The font height. -- @staticfct beautiful.get_font_height function beautiful.get_font_height(name) return load_font(name).height diff --git a/lib/beautiful/theme_assets.lua b/lib/beautiful/theme_assets.lua index 555a963f8..d4f61de03 100644 --- a/lib/beautiful/theme_assets.lua +++ b/lib/beautiful/theme_assets.lua @@ -86,6 +86,7 @@ end -- @tparam color bg Background color. -- @tparam color fg Main foreground color. -- @tparam color alt_fg Accent foreground color. +-- @noreturn -- @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 @@ -155,6 +156,7 @@ end -- @tparam number height Height. -- @tparam color bg Background color. -- @tparam color fg Foreground color. +-- @noreturn -- @staticfct beautiful.theme_assets.gen_logo function theme_assets.gen_logo(cr, width, height, bg, fg) local ls = math.min(width, height) diff --git a/lib/beautiful/xresources.lua b/lib/beautiful/xresources.lua index 71299cb44..97f51697f 100644 --- a/lib/beautiful/xresources.lua +++ b/lib/beautiful/xresources.lua @@ -119,6 +119,7 @@ end --- Set DPI for a given screen (defaults to global). -- @tparam number dpi DPI value. -- @tparam[opt] integer s Screen. +-- @noreturn -- @staticfct beautiful.xresources.set_dpi function xresources.set_dpi(dpi, s) s = get_screen(s) diff --git a/lib/gears/color.lua b/lib/gears/color.lua index f872221a3..5035da5a5 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -282,6 +282,7 @@ end --- Create a pattern from a given string, same as @{gears.color}. -- @see gears.color +-- @treturn gears.color A cairo pattern object. -- @staticfct gears.color.create_pattern function color.create_pattern(col) if cairo.Pattern:is_type_of(col) then diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua index 835e099fd..4718966a7 100644 --- a/lib/gears/debug.lua +++ b/lib/gears/debug.lua @@ -50,7 +50,7 @@ end -- @param data Value to inspect. -- @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. +-- @treturn 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) @@ -61,6 +61,7 @@ end -- @param tag The name of the table. -- @tparam[opt] int depth Depth of recursion. -- @staticfct gears.debug.dump +-- @noreturn function debug.dump(data, tag, depth) print(debug.dump_return(data, tag, depth)) end @@ -68,6 +69,7 @@ end --- Print an warning message -- @tparam string message The warning message to print. -- @staticfct gears.debug.print_warning +-- @noreturn function debug.print_warning(message) io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n") end @@ -75,6 +77,7 @@ end --- Print an error message -- @tparam string message The error message to print. -- @staticfct gears.debug.print_error +-- @noreturn function debug.print_error(message) io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n") end @@ -93,6 +96,7 @@ local displayed_deprecations = {} -- @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 +-- @noreturn -- @emits debug::deprecation This is usually routed to stdout when the API is -- newly deprecated. -- @emitstparam debug::deprecation string msg The full formatted message. diff --git a/lib/gears/matcher.lua b/lib/gears/matcher.lua index 869147c9d..5b4e3e1b0 100644 --- a/lib/gears/matcher.lua +++ b/lib/gears/matcher.lua @@ -225,6 +225,7 @@ end -- "except" and "except_any" keys. If no rules are provided, all rules -- registered with a source will be matched. -- @method matching_rules +-- @treturn table The matching rules. function matcher:matching_rules(o, rules) -- Match all sources. @@ -290,6 +291,7 @@ end -- @tparam string name The property name. -- @tparam function f The matching function. -- @method add_property_matcher +-- @noreturn -- @usage -- Manually match the screen in various ways. -- matcher:add_property_matcher("screen", function(c, value) -- return c.screen == value @@ -313,6 +315,7 @@ end -- the context of a rule. -- -- @method add_property_setter +-- @noreturn -- @tparam string name The property name. -- @tparam function f The setter function. function matcher:add_property_setter(name, f) @@ -472,6 +475,7 @@ end -- -- @param o The object. -- @method apply +-- @noreturn function matcher:apply(o) local callbacks, props = {}, {} for _, v in ipairs(self._matching_source) do @@ -514,6 +518,7 @@ end -- @tparam string source The source name. -- @tparam table rule A valid rule. -- @method append_rule +-- @noreturn function matcher:append_rule(source, rule) if not self._matching_rules[source] then self:add_matching_rules(source, {}, {}, {}) @@ -526,6 +531,7 @@ end -- @tparam string source The source name. -- @tparam table rules A table with rules. -- @method append_rules +-- @noreturn function matcher:append_rules(source, rules) for _, rule in ipairs(rules) do self:append_rule(source, rule) diff --git a/lib/gears/object.lua b/lib/gears/object.lua index b9b381c5c..35beeb223 100644 --- a/lib/gears/object.lua +++ b/lib/gears/object.lua @@ -52,6 +52,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method connect_signal +-- @noreturn function object:connect_signal(name, func) assert(type(func) == "function", "callback must be a function, got: " .. type(func)) local sig = find_signal(self, name) @@ -105,6 +106,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method weak_connect_signal +-- @noreturn 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) @@ -116,6 +118,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback that should be disconnected. -- @method disconnect_signal +-- @noreturn function object:disconnect_signal(name, func) local sig = find_signal(self, name) sig.weak[func] = nil @@ -129,6 +132,7 @@ end -- function receives the object as first argument and then any extra -- arguments that are given to emit_signal() -- @method emit_signal +-- @noreturn function object:emit_signal(name, ...) local sig = find_signal(self, name) for func in pairs(sig.strong) do diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index b78c733c1..8b7fbea8a 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -74,7 +74,9 @@ local module = {} -- @tparam boolean br If the bottom right corner is rounded -- @tparam boolean bl If the bottom left corner is rounded -- @tparam number rate The "squareness" of the squircle, should be greater than 1 --- @tparam number delta The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not +-- @tparam number delta The "smoothness" of the shape, delta must be greate +-- than 0.01 and will be reset to 0.01 if not +-- @noreturn -- @staticfct gears.shape.partial_squircle function module.partial_squircle(cr, width, height, tl, tr, br, bl, rate, delta) -- rate ~ 2 can be used by icon @@ -167,7 +169,9 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam number rate The "squareness" of the squircle, should be greater than 1 --- @tparam number delta The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not +-- @tparam number delta The "smoothness" of the shape, delta must be greater +-- than 0.01 and will be reset to 0.01 if not +-- @noreturn -- @staticfct gears.shape.squircle function module.squircle(cr, width, height, rate, delta) module.partial_squircle(cr, width, height, true, true, true, true, rate, delta) @@ -182,6 +186,7 @@ end -- @tparam number width The width constraint -- @tparam number height The height constraint -- @tparam number n Number of grams (default n = 5 -> pentagram) +-- @noreturn -- @staticfct gears.shape.star function module.star(cr, width, height, n) -- use the minimum as size @@ -216,6 +221,7 @@ end -- @tparam number width The rectangle width -- @tparam number height The rectangle height -- @tparam number radius The corner radius +-- @noreturn -- @staticfct gears.shape.rounded_rect function module.rounded_rect(cr, width, height, radius) @@ -246,6 +252,7 @@ end -- @param cr A cairo content -- @param width The rectangle width -- @param height The rectangle height. +-- @noreturn -- @staticfct gears.shape.rounded_bar function module.rounded_bar(cr, width, height) module.rounded_rect(cr, width, height, height / 2) @@ -263,6 +270,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 +-- @noreturn -- @staticfct gears.shape.partially_rounded_rect function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad) rad = rad or 10 @@ -319,6 +327,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 +-- @noreturn -- @staticfct gears.shape.infobubble function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position) arrow_size = arrow_size or 10 @@ -353,6 +362,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 +-- @noreturn -- @staticfct gears.shape.rectangular_tag function module.rectangular_tag(cr, width, height, arrow_length) arrow_length = arrow_length or height/2 @@ -383,6 +393,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) +-- @noreturn -- @staticfct gears.shape.arrow function module.arrow(cr, width, height, head_width, shaft_width, shaft_length) shaft_length = shaft_length or height / 2 @@ -408,6 +419,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.hexagon function module.hexagon(cr, width, height) cr:move_to(height/2,0) @@ -428,6 +440,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 +-- @noreturn -- @staticfct gears.shape.powerline function module.powerline(cr, width, height, arrow_depth) arrow_depth = arrow_depth or height/2 @@ -456,6 +469,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.isosceles_triangle function module.isosceles_triangle(cr, width, height) cr:move_to( width/2, 0 ) @@ -472,6 +486,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=width/3] number thickness The cross section thickness +-- @noreturn -- @staticfct gears.shape.cross function module.cross(cr, width, height, thickness) thickness = thickness or width/3 @@ -500,6 +515,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam number corner_radius +-- @noreturn -- @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) @@ -524,6 +540,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 +-- @noreturn -- @staticfct gears.shape.circle function module.circle(cr, width, height, radius) radius = radius or math.min(width, height) / 2 @@ -539,6 +556,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.rectangle function module.rectangle(cr, width, height) cr:rectangle(0, 0, width, height) @@ -553,6 +571,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 +-- @noreturn -- @staticfct gears.shape.parallelogram function module.parallelogram(cr, width, height, base_width) base_width = base_width or width/3 @@ -570,6 +589,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.losange function module.losange(cr, width, height) cr:move_to(width/2 , 0 ) @@ -591,6 +611,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 +-- @noreturn -- @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) @@ -629,6 +650,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 +-- @noreturn -- @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 @@ -752,6 +774,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 +-- @noreturn -- @staticfct gears.shape.radial_progress function module.radial_progress(cr, w, h, percent, hide_left) percent = percent or 1 diff --git a/lib/gears/sort/topological.lua b/lib/gears/sort/topological.lua index 8064e40cb..e11e89e2a 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`. +-- @noreturn -- @method append function tsort:append(node, dependencies) add_node(self, node) @@ -30,6 +31,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`. +-- @noreturn -- @method prepend function tsort:prepend(node, subordinates) for _, dep in ipairs(subordinates) do @@ -65,6 +67,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. +-- @treturn gears.sort.topological The cloned sorter object. -- @method clone function tsort:clone() local new = tsort.topological() @@ -78,6 +81,7 @@ end --- Remove a node from the topological map. -- -- @param node The node +-- @noreturn -- @method remove function tsort:remove(node) self._edges[node] = nil diff --git a/lib/gears/string.lua b/lib/gears/string.lua index 229ed810b..722c66ad5 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -74,6 +74,7 @@ end --- Generate a pattern matching expression that ignores case. -- @tparam string q Original pattern matching expression. +-- @treturn string The pattern. -- @staticfct gears.string.query_to_pattern function gstring.query_to_pattern(q) local s = gstring.quote_pattern(q) diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index 3bf983571..21b4e1531 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -201,6 +201,7 @@ end -- @tparam gears.shape|function shape The shape. -- @param[opt] ... Any additional parameters will be passed to the shape function. -- @staticfct apply_shape_bounding +-- @noreturn function surface.apply_shape_bounding(draw, shape, ...) local geo = draw:geometry() diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index c27ef6480..0c50c954b 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -91,6 +91,7 @@ local timer = { mt = {} } --- Start the timer. -- @method start +-- @noreturn -- @emits start function timer:start() if self.data.source_id ~= nil then @@ -110,6 +111,7 @@ end -- Does nothing if the timer isn't running. -- -- @method stop +-- @noreturn -- @emits stop function timer:stop() if self.data.source_id == nil then @@ -124,6 +126,7 @@ end -- This is equivalent to stopping the timer if it is running and then starting -- it. -- @method again +-- @noreturn -- @emits start -- @emits stop function timer:again() @@ -269,6 +272,7 @@ local delayed_calls = {} -- all, because it means that less batching happens and the delayed calls run -- prematurely. -- @staticfct gears.timer.run_delayed_calls_now +-- @noreturn function timer.run_delayed_calls_now() for _, callback in ipairs(delayed_calls) do protected_call(unpack(callback)) @@ -278,7 +282,8 @@ end --- Call the given function at the end of the current GLib event loop iteration. -- @tparam function callback The function that should be called ---@param ... Arguments to the callback function +-- @param ... Arguments to the callback function +-- @noreturn -- @staticfct gears.timer.delayed_call function timer.delayed_call(callback, ...) assert(type(callback) == "function", "callback must be a function, got: " .. type(callback)) diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index e594fafd1..337483892 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -395,7 +395,8 @@ local function menulist_update(scr) end --- Refresh menubar's cache by reloading .desktop files. --- @tparam[opt] screen scr Screen. +-- @tparam[opt=awful.screen.focused()] screen scr Screen. +-- @noreturn -- @staticfct menubar.refresh function menubar.refresh(scr) scr = get_screen(scr or awful.screen.focused() or 1) @@ -452,7 +453,8 @@ local function prompt_keypressed_callback(mod, key, comm) end --- Show the menubar on the given screen. --- @param[opt] scr Screen. +-- @tparam[opt=awful.screen.focused()] screen scr Screen. +-- @noreturn -- @staticfct menubar.show -- @usebeautiful beautiful.menubar_fg_normal -- @usebeautiful beautiful.menubar_bg_normal diff --git a/lib/menubar/menu_gen.lua b/lib/menubar/menu_gen.lua index 19fb6e735..193eef1c5 100644 --- a/lib/menubar/menu_gen.lua +++ b/lib/menubar/menu_gen.lua @@ -57,8 +57,7 @@ menu_gen.all_categories = { icon_name = "applications-accessories", use = true } } ---- Find icons for category entries. --- @staticfct menubar.menu_gen.lookup_category_icons +-- Find icons for category entries. function menu_gen.lookup_category_icons() for _, v in pairs(menu_gen.all_categories) do v.icon = utils.lookup_icon(v.icon_name) @@ -81,6 +80,7 @@ end -- with the resulting list of menu entries as argument. -- @tparam table callback.entries All menu entries. -- @staticfct menubar.menu_gen.generate +-- @noreturn 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 a3f1e1945..77945a398 100644 --- a/lib/menubar/utils.lua +++ b/lib/menubar/utils.lua @@ -201,6 +201,7 @@ end --- Remove CR newline from the end of the string. -- @tparam string s The string to trim -- @staticfct menubar.utils.rtrim +-- @treturn string The trimmed string. function utils.rtrim(s) if not s then return end if string.byte(s, #s) == 13 then @@ -357,6 +358,7 @@ end -- with the resulting list of menu entries as argument. -- @tparam table callback.programs Paths of found .desktop files. -- @staticfct menubar.utils.parse_dir +-- @noreturn function utils.parse_dir(dir_path, callback) local function get_readable_path(file) diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index a9576c8b3..f88c84869 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -120,6 +120,7 @@ end -- the action was invoked. If a notification is shared by many object (like -- a "mute" or "snooze" action added to all notification), calling `:invoke()` -- without adding the `notif` context will cause unexpected results. +-- @noreturn function action:invoke(notif) self:emit_signal("invoked", notif) end diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index a2e9e02d1..a3da5e5c3 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -498,6 +498,7 @@ end --- Set new notification timeout. -- @method reset_timeout -- @tparam number new_timeout Time in seconds after which notification disappears. +-- @noreturn function notification:reset_timeout(new_timeout) if self.timer then self.timer:stop() end @@ -793,6 +794,7 @@ end --- Add more actions to the notification. -- @method append_actions -- @tparam table new_actions +-- @noreturn function notification:append_actions(new_actions) self._private.actions = self._private.actions or {} @@ -1062,6 +1064,7 @@ end -- @method grant -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions --- Deny a permission for a notification @@ -1069,6 +1072,7 @@ end -- @method deny -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions pcommon.setup_grant(notification, "notification") diff --git a/lib/ruled/client.lua b/lib/ruled/client.lua index 98e0fe0cb..0ac6f049d 100644 --- a/lib/ruled/client.lua +++ b/lib/ruled/client.lua @@ -180,9 +180,10 @@ end --- Apply ruled.client.rules to a client. -- @tparam client c The client. +-- @noreturn -- @staticfct ruled.client.apply function module.apply(c) - return crules:apply(c) + crules:apply(c) end --- Add a new rule to the default set. @@ -527,7 +528,8 @@ end --- Apply properties and callbacks to a client. -- @tparam client c The client. -- @tparam table props Properties to apply. --- @tparam[opt] table callbacks Callbacks to apply. +-- @tparam[opt={}] table callbacks Callbacks to apply. +-- @noreturn -- @staticfct ruled.client.execute -- @request client titlebars rules granted The `titlebars_enabled` is set in the -- rules. diff --git a/lib/ruled/notification.lua b/lib/ruled/notification.lua index 55e8905ea..6203cb3b6 100644 --- a/lib/ruled/notification.lua +++ b/lib/ruled/notification.lua @@ -158,6 +158,7 @@ end -- -- @tparam naughty.notification n The notification. -- @staticfct ruled.notification.apply +-- @noreturn function module.apply(n) local callbacks, props = {}, {} @@ -179,6 +180,7 @@ end --- Add a new rule to the default set. -- @tparam table rule A valid rule. -- @staticfct ruled.notification.append_rule +-- @noreturn function module.append_rule(rule) nrules:append_rule("ruled.notifications", rule) end @@ -186,16 +188,20 @@ end --- Add a new rules to the default set. -- @tparam table rule A table with rules. -- @staticfct ruled.notification.append_rules +-- @noreturn function module.append_rules(rules) nrules:append_rules("ruled.notifications", rules) end --- Remove a new rule to the default set. -- @tparam table rule A valid rule. +-- @treturn boolean `true` if the rule was removed. -- @staticfct ruled.notification.remove_rule function module.remove_rule(rule) - nrules:remove_rule("ruled.notifications", rule) + local ret = nrules:remove_rule("ruled.notifications", rule) module.emit_signal("rule::removed", rule) + + return ret end --- Add a new rule source. diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index 95b07df86..261539237 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -217,6 +217,7 @@ end --- Reset this layout. The widget will be removed and the rotation reset. -- @method reset +-- @noreturn -- @interface container function arcchart:reset() self:set_widget(nil) diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index 384ae7efd..cada81e29 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -316,6 +316,7 @@ end -- -- @method set_shape -- @tparam gears.shape|function shape A function taking a context, width and height as arguments +-- @noreturn -- @propemits true false -- @see gears.shape -- @see shape diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index 62c051f01..7f4661e83 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -135,6 +135,7 @@ end -- and the constraints set to nil. -- -- @method reset +-- @noreturn -- @interface container function constraint:reset() self._private.width = nil diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index 1c8bd90a0..eb8ff267a 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -159,6 +159,7 @@ end --- Reset this layout. The widget will be unreferenced, the margins set to 0 -- and the color erased -- @method reset +-- @noreturn -- @interface container function margin:reset() self:set_widget(nil) diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua index 288308823..d21724f30 100644 --- a/lib/wibox/container/mirror.lua +++ b/lib/wibox/container/mirror.lua @@ -70,6 +70,7 @@ end --- Reset this layout. The widget will be removed and the axes reset. -- -- @method reset +-- @noreturn -- @interface container function mirror:reset() self._private.horizontal = false diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua index 7fd6a8091..352f2c18f 100644 --- a/lib/wibox/container/place.lua +++ b/lib/wibox/container/place.lua @@ -94,6 +94,7 @@ end --- Reset this layout. The widget will be removed and the rotation reset. -- @method reset +-- @noreturn -- @interface container function place:reset() self:set_widget(nil) diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index ac458e9c0..a9effcd78 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -148,6 +148,7 @@ end --- Reset this container. -- -- @method reset +-- @noreturn -- @interface container function radialprogressbar:reset() self:set_widget(nil) diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index fedc8e4f9..c4da7cd0a 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -84,6 +84,7 @@ end -- The widget will be removed and the rotation reset. -- -- @method reset +-- @noreturn -- @interface container function rotate:reset() self._private.direction = nil diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua index 46f928229..c520b443c 100644 --- a/lib/wibox/container/scroll.lua +++ b/lib/wibox/container/scroll.lua @@ -222,6 +222,7 @@ end --- Pause the scrolling animation. -- @method pause +-- @noreturn -- @see continue function scroll:pause() if self._private.paused then @@ -233,6 +234,7 @@ end --- Continue the scrolling animation. -- @method continue +-- @noreturn -- @see pause function scroll:continue() if not self._private.paused then @@ -248,6 +250,7 @@ end -- display the widget without any scrolling applied. -- This function does not undo the effect of @{pause}. -- @method reset_scrolling +-- @noreturn function scroll:reset_scrolling() self._private.timer:start() if self._private.paused then @@ -258,6 +261,7 @@ end --- Set the direction in which this widget scroll. -- @method set_direction -- @param dir Either "h" for horizontal scrolling or "v" for vertical scrolling +-- @noreturn function scroll:set_direction(dir) if dir == self._private.dir then return @@ -306,6 +310,7 @@ end -- @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. +-- @noreturn -- @see set_extra_space function scroll:set_expand(expand) if expand == self._private.expand then @@ -318,6 +323,7 @@ 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 +-- @noreturn function scroll:set_fps(fps) if fps == self._private.fps then return @@ -331,6 +337,7 @@ end -- 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 +-- @noreturn -- @see set_expand function scroll:set_extra_space(extra_space) if extra_space == self._private.extra_space then @@ -345,6 +352,7 @@ end -- in pixels per second. -- @method set_speed -- @tparam number speed The speed for the animation +-- @noreturn function scroll:set_speed(speed) if speed == self._private.speed then return @@ -359,6 +367,7 @@ end -- 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. +-- @noreturn function scroll:set_max_size(max_size) if max_size == self._private.max_size then return @@ -384,6 +393,7 @@ end -- 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. +-- @noreturn -- @see step_functions function scroll:set_step_function(step_function) -- Call the step functions once to see if it works @@ -399,6 +409,7 @@ end -- This restricts the child widget's maximal size. -- @method set_space_for_scrolling -- @tparam number space_for_scrolling The space for scrolling +-- @noreturn function scroll:set_space_for_scrolling(space_for_scrolling) if space_for_scrolling == self._private.space_for_scrolling then return diff --git a/lib/wibox/hierarchy.lua b/lib/wibox/hierarchy.lua index 3472716d1..13ec3e4e3 100644 --- a/lib/wibox/hierarchy.lua +++ b/lib/wibox/hierarchy.lua @@ -23,6 +23,7 @@ local widgets_to_count = setmetatable({}, { __mode = "k" }) -- visible in any hierarchy. -- @param widget The widget that should be counted. -- @staticfct wibox.hierarchy.count_widget +-- @noreturn function hierarchy.count_widget(widget) widgets_to_count[widget] = true end @@ -232,6 +233,7 @@ end --- Get the widget that this hierarchy manages. -- @method get_widget +-- @treturn wibox.widget The widget held by this node. function hierarchy:get_widget() return self._widget end @@ -318,6 +320,7 @@ end -- @param context The context in which widgets are drawn. -- @param cr The cairo context that is used for drawing. -- @method draw +-- @noreturn function hierarchy:draw(context, cr) local widget = self:get_widget() if not widget._private.visible then diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index ff458fe78..9715a93ee 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -103,6 +103,7 @@ end -- @tparam string path The path. -- @tparam[opt=nil] table context A widget context. -- @method save_to_svg +-- @noreturn function wibox:save_to_svg(path, context) wibox.widget.draw_to_svg_file( self:to_widget(), path, self:geometry().width, self:geometry().height, context @@ -404,6 +405,7 @@ end -- automatically called when needed. -- @param wibox -- @method draw +-- @noreturn --- Connect a global signal on the wibox class. -- @@ -416,6 +418,7 @@ end -- @tparam string name The name of the signal -- @tparam function func The function to attach -- @staticfct wibox.connect_signal +-- @noreturn -- @usage wibox.connect_signal("added", function(notif) -- -- do something -- end) @@ -424,6 +427,7 @@ end -- @tparam string name The signal name. -- @param ... The signal callback arguments -- @staticfct wibox.emit_signal +-- @noreturn --- Disconnect a signal from a source. -- @tparam string name The name of the signal diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index 5d4affcbf..e8e94743f 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -136,6 +136,7 @@ end -- -- @method add -- @tparam widget ... Widgets that should be added (must at least be one). +-- @noreturn -- @interface layout function fixed:add(...) -- No table.pack in Lua 5.1 :-( diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index 153629bae..a0c403e6c 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -48,6 +48,7 @@ local flex = {} -- -- @tparam widget ... Widgets that should be added (must at least be one). -- @method add +-- @noreturn -- @interface layout --- Remove a widget from the layout. diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index dc292ac22..e822ec81a 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -288,7 +288,9 @@ end -- The widgets are assumed to span one cell. -- -- @method add --- @param ... Widgets that should be added (must at least be one) +-- @tparam wibox.widget ... Widgets that should be added (must at least be one) +-- @interface layout +-- @noreturn function grid:add(...) local args = { n=select('#', ...), ... } assert(args.n > 0, "need at least one widget to add") @@ -863,6 +865,7 @@ end -- -- **Signal:** widget::reset -- @method reset +-- @noreturn 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 eb2bdbdeb..e98458cd1 100644 --- a/lib/wibox/layout/manual.lua +++ b/lib/wibox/layout/manual.lua @@ -20,6 +20,8 @@ local manual_layout = {} -- -- @method add -- @tparam widget ... Widgets that should be added +-- @interface layout +-- @noreturn --- Remove a widget from the layout. -- @@ -166,6 +168,7 @@ end -- @tparam widget widget The widget. -- @tparam table|function point Either an `{x=x,y=y}` table or a function -- returning the new geometry. +-- @noreturn function manual_layout:add_at(widget, point) assert(not widget.point, "2 points are specified, only one is supported") @@ -189,6 +192,7 @@ end -- @method move -- @tparam number index The widget index. -- @tparam table|function point A new point value. +-- @noreturn -- @see add_at function manual_layout:move(index, point) assert(self._private.pos[index]) @@ -203,6 +207,7 @@ end -- @method move_widget -- @tparam widget widget The widget. -- @tparam table|function point A new point value. +-- @noreturn -- @see add_at function manual_layout:move_widget(widget, point) local idx, l = self:index(widget, false) diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua index ba73b4b22..bfc30d523 100644 --- a/lib/wibox/layout/ratio.lua +++ b/lib/wibox/layout/ratio.lua @@ -215,6 +215,7 @@ end -- @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 +-- @noreturn function ratio:inc_ratio(index, increment) if #self._private.widgets == 1 or (not index) or (not self._private.ratios[index]) or increment < -1 or increment > 1 then @@ -234,6 +235,7 @@ end -- @tparam widget widget The widget to adjust -- @tparam number increment An floating point value between -1 and 1 where the -- end result is within 0 and 1 +-- @noreturn function ratio:inc_widget_ratio(widget, increment) if not widget or not increment then return end @@ -247,6 +249,7 @@ end -- @method set_ratio -- @tparam number index The index of the widget to change -- @tparam number percent An floating point value between 0 and 1 +-- @noreturn function ratio:set_ratio(index, percent) if not percent or #self._private.widgets == 1 or not index or not self._private.widgets[index] or percent < 0 or percent > 1 then @@ -286,6 +289,7 @@ end -- @method set_widget_ratio -- @tparam widget widget The widget to adjust. -- @tparam number percent A floating point value between 0 and 1. +-- @noreturn function ratio:set_widget_ratio(widget, percent) local index = self:index(widget) @@ -302,6 +306,7 @@ end -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:adjust_ratio(index, before, itself, after) if not self._private.widgets[index] or not before or not itself or not after then return @@ -342,19 +347,15 @@ end -- @see wibox.layout.ratio.adjust_ratio -- @deprecated wibox.layout.ratio.ajust_ratio -- @tparam number index The index of the widget to change --- @tparam number index The index of the widget to change --- @tparam number before The sum of the ratio before the widget -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" --- @tparam number itself The ratio for "widget" --- @tparam number after The sum of the ratio after the widget -- @tparam number after The sum of the ratio after the widget function ratio:ajust_ratio(...) require('gears.debug').deprecate( "Use `:adjust_ratio` rather than `:ajust_ratio`", { deprecated_in = 5 } ) - return self:adjust_ratio(...) + self:adjust_ratio(...) end --- Update all widgets to match a set of a ratio. @@ -364,6 +365,7 @@ end -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:adjust_widget_ratio(widget, before, itself, after) local index = self:index(widget) self:adjust_ratio(index, before, itself, after) @@ -375,11 +377,9 @@ end -- @deprecated wibox.layout.ratio.ajust_widget_ratio -- @tparam widget widget The widget to adjust -- @tparam number before The sum of the ratio before the widget --- @tparam number before The sum of the ratio before the widget --- @tparam number itself The ratio for "widget" -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget --- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:ajust_widget_ratio(...) require('gears.debug').deprecate( "Use `:adjust_widget_ratio` rather than `:ajust_widget_ratio`", @@ -392,6 +392,7 @@ end -- -- @method add -- @tparam widget ... Widgets that should be added (must at least be one) +-- @noreturn -- @emits widget::added All new widgets are passed in the parameters. -- @emitstparam widget::added widget self The layout. function ratio:add(...) @@ -439,6 +440,8 @@ end -- @method insert -- @tparam number index The position. -- @tparam widget widget The widget. +-- @treturn boolean `true` if the widget was inserted and `false` if the index +-- is invalid. -- @emits widget::inserted -- @emitstparam widget::inserted widget self The ratio layout. -- @emitstparam widget::inserted widget widget index The inserted widget. @@ -454,6 +457,8 @@ function ratio:insert(index, widget) self:emit_signal("widget::layout_changed") self:emit_signal("widget::inserted", widget, #self._private.widgets) + + return true end --- Set how the space of invisible or `0x0` sized widget is redistributed. diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index f89b2c515..962127f67 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -26,6 +26,7 @@ local stack = {mt={}} --- Add some widgets to the given stack layout. -- -- @tparam widget ... Widgets that should be added (must at least be one) +-- @noreturn -- @method add -- @interface layout @@ -116,6 +117,7 @@ end -- -- @method raise -- @tparam number index The widget index to raise +-- @noreturn function stack:raise(index) if (not index) or (not self._private.widgets[index]) then return end @@ -132,6 +134,7 @@ end -- @tparam widget widget The widget to raise -- @tparam[opt=false] boolean recursive Also look deeper in the hierarchy to -- find the widget +-- @noreturn function stack:raise_widget(widget, recursive) local idx, layout = self:index(widget, recursive) diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index 1cae73bc0..82759442f 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -225,6 +225,7 @@ end --- Add a new `awful.button` to this widget. -- @tparam awful.button button The button to add. -- @method wibox.widget.base:add_button +-- @noreturn function base.widget:add_button(button) if not button then return end @@ -412,6 +413,7 @@ end -- @tparam string signal_name -- @param ... Other arguments -- @method wibox.widget.base:emit_signal_recursive +-- @noreturn function base.widget:emit_signal_recursive(signal_name, ...) -- This is a convenience wrapper, the real implementation is in the -- hierarchy. @@ -500,6 +502,15 @@ end -- This gives only tight bounds if no rotations by non-multiples of 90° are -- used. -- @staticfct wibox.widget.base.rect_to_device_geometry +-- @param cr The cairo context. +-- @tparam number x The `x` value. +-- @tparam number y The `y` value. +-- @tparam number width The `width` value. +-- @tparam number height The `height` value. +-- @treturn number The new `x` value. +-- @treturn number The new `y` value. +-- @treturn number The new `width` value. +-- @treturn number The new `height` value. function base.rect_to_device_geometry(cr, x, y, width, height) return matrix.transform_rectangle(cr.matrix, x, y, width, height) end @@ -585,6 +596,7 @@ end -- -- This is used internally and should not be called directly. -- @staticfct wibox.widget.base.handle_button +-- @noreturn function base.handle_button(event, widget, x, y, button, modifiers, geometry) x = x or y -- luacheck: no unused local function is_any(mod) @@ -997,6 +1009,7 @@ end -- -- This function raises an error if the widget is not valid. -- @staticfct wibox.widget.base.check_widget +-- @noreturn 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/graph.lua b/lib/wibox/widget/graph.lua index 9d8e1cb7f..76795ce3e 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -672,6 +672,7 @@ end -- -- @method compute_drawn_values_num -- @tparam number usable_width +-- @treturn number The number of values. function graph:compute_drawn_values_num(usable_width) if usable_width <= 0 then return 0 @@ -718,6 +719,7 @@ end -- @method add_value -- @tparam[opt=NaN] number value The value to be added to a graph's data group. -- @tparam[opt=1] integer group The index of the data group. +-- @noreturn Note that it actually returns something, but that's better undocumented. function graph:add_value(value, group) value = value or 0/0 -- default to NaN group = group or 1 @@ -762,6 +764,7 @@ end -- Removes all values from all data groups. -- -- @method clear +-- @noreturn Note that it actually returns something, but that's better undocumented. function graph:clear() self._private.values = {} self:emit_signal("widget::redraw_needed") diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index 26afbda31..b96caac7f 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -41,6 +41,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. +-- @noreturn -- @staticfct wibox.widget.draw_to_cairo_context function widget.draw_to_cairo_context(wdg, cr, width, height, context) local function no_op() end @@ -55,6 +56,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. +-- @noreturn -- @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) diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 61a04295d..6d3776831 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -114,6 +114,7 @@ end --- Force a textclock to update now. -- +-- @noreturn -- @method force_update function textclock:force_update() self._timer:emit_signal("timeout") diff --git a/luaa.c b/luaa.c index 2dbd3ac5f..bf1800ce9 100644 --- a/luaa.c +++ b/luaa.c @@ -36,6 +36,7 @@ * * @tparam string name The name of the X11 property. * @tparam string type One of "string", "number" or "boolean". + * @noreturn * @staticfct register_xproperty */ @@ -229,6 +230,7 @@ composite_manager_running(void) /** Quit awesome. * @tparam[opt=0] integer code The exit code to use when exiting. * @staticfct quit + * @noreturn */ static int luaA_quit(lua_State *L) @@ -246,6 +248,7 @@ luaA_quit(lua_State *L) * * @tparam string cmd The command line to execute. * @staticfct exec + * @noreturn */ static int luaA_exec(lua_State *L) @@ -260,6 +263,7 @@ luaA_exec(lua_State *L) /** Restart awesome. * @staticfct restart + * @noreturn */ static int luaA_restart(lua_State *L) @@ -290,6 +294,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. * @staticfct sync + * @noreturn */ static int luaA_sync(lua_State *L) @@ -352,6 +357,7 @@ luaA_load_image(lua_State *L) * * @tparam integer size The size of the icons in pixels. * @staticfct set_preferred_icon_size + * @noreturn */ static int luaA_set_preferred_icon_size(lua_State *L) @@ -808,6 +814,7 @@ luaA_awesome_index(lua_State *L) * @tparam string name A string with the event name. * @tparam function func The function to call. * @staticfct connect_signal + * @noreturn */ static int luaA_awesome_connect_signal(lua_State *L) @@ -823,6 +830,7 @@ luaA_awesome_connect_signal(lua_State *L) * @tparam string name A string with the event name. * @tparam function func The function to call. * @staticfct disconnect_signal + * @noreturn */ static int luaA_awesome_disconnect_signal(lua_State *L) @@ -840,6 +848,7 @@ luaA_awesome_disconnect_signal(lua_State *L) * @tparam function name A string with the event name. * @param ... The signal arguments. * @staticfct emit_signal + * @noreturn */ static int luaA_awesome_emit_signal(lua_State *L) diff --git a/mousegrabber.c b/mousegrabber.c index f048d5d22..35bbeb520 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -87,8 +87,9 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask) *@DOC_cursor_c_COMMON@ * * - * @param func A callback function as described above. - * @param cursor The name of a X cursor to use while grabbing. + * @tparam function func A callback function as described above. + * @tparam string cursor The name of a X cursor to use while grabbing. + * @noreturn * @staticfct run */ static int @@ -120,6 +121,7 @@ luaA_mousegrabber_run(lua_State *L) /** Stop grabbing the mouse pointer. * * @staticfct stop + * @noreturn */ int luaA_mousegrabber_stop(lua_State *L) diff --git a/objects/client.c b/objects/client.c index 74bb0d6fc..8b35b7d97 100644 --- a/objects/client.c +++ b/objects/client.c @@ -3191,6 +3191,7 @@ out: * @DOC_sequences_client_kill1_EXAMPLE@ * * @method kill + * @noreturn * @see awesome.kill */ static int @@ -3206,6 +3207,7 @@ luaA_client_kill(lua_State *L) * @DOC_sequences_client_swap1_EXAMPLE@ * * @tparam client c A client to swap with. + * @noreturn * @method swap * @emits swapped * @emitstparam swapped client other The other client. @@ -3338,6 +3340,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. * * @method raise + * @noreturn * @emits raised * @see above * @see below @@ -3364,6 +3367,7 @@ luaA_client_raise(lua_State *L) /** Lower a client on bottom of others which are on the same layer. * * @method lower + * @noreturn * @emits lowered * @see above * @see below @@ -3396,6 +3400,7 @@ luaA_client_lower(lua_State *L) /** Stop managing a client. * * @method unmanage + * @noreturn */ static int luaA_client_unmanage(lua_State *L) diff --git a/objects/drawable.c b/objects/drawable.c index d404b7a46..a26abedd5 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -35,8 +35,8 @@ /** Drawable object. * - * @field surface The drawable's cairo surface. - * @staticfct drawable + * @property surface The drawable's cairo surface. + * @tparam gears.surface surface */ /** @@ -89,12 +89,12 @@ * @staticfct instances */ -/** Set a __index metamethod for all drawable instances. +/* Set a __index metamethod for all drawable instances. * @tparam function cb The meta-method * @staticfct set_index_miss_handler */ -/** Set a __newindex metamethod for all drawable instances. +/* Set a __newindex metamethod for all drawable instances. * @tparam function cb The meta-method * @staticfct set_newindex_miss_handler */ @@ -186,6 +186,7 @@ luaA_drawable_get_surface(lua_State *L, drawable_t *drawable) * the drawable's surface has been done and should become visible. * * @method refresh + * @noreturn */ static int luaA_drawable_refresh(lua_State *L) diff --git a/objects/screen.c b/objects/screen.c index 9582671e1..b72aab97e 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -1564,6 +1564,7 @@ luaA_screen_module_newindex(lua_State *L) * for s in screen do * print("Oh, wow, we have screen " .. tostring(s)) * end + * @treturn function A lua iterator function. * @staticfct screen */ static int @@ -1725,6 +1726,7 @@ luaA_screen_fake_add(lua_State *L) * @DOC_sequences_screen_fake_remove_EXAMPLE@ * * @method fake_remove + * @noreturn */ static int luaA_screen_fake_remove(lua_State *L) @@ -1763,6 +1765,7 @@ luaA_screen_fake_remove(lua_State *L) * @tparam integer width The new width for screen. * @tparam integer height The new height for screen. * @method fake_resize + * @noreturn * @see split * @see geometry */ @@ -1800,6 +1803,7 @@ luaA_screen_fake_resize(lua_State *L) * * @tparam client s A screen to swap with. * @method swap + * @noreturn */ static int luaA_screen_swap(lua_State *L) diff --git a/root.c b/root.c index a159cc15c..94f04977b 100644 --- a/root.c +++ b/root.c @@ -280,6 +280,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. + * @noreturn * @staticfct fake_input */ static int @@ -437,6 +438,7 @@ luaA_root_buttons(lua_State *L) *@DOC_cursor_c_COMMON@ * * @tparam string cursor_name A X cursor name. + * @noreturn * @staticfct cursor */ static int diff --git a/tests/examples/awful/placement/center_vertical.lua b/tests/examples/awful/placement/center_vertical.lua index 0817921df..23658e9f7 100644 --- a/tests/examples/awful/placement/center_vertical.lua +++ b/tests/examples/awful/placement/center_vertical.lua @@ -2,6 +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 +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.center_vertical --DOC_HEADER require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_horizontally.lua b/tests/examples/awful/placement/maximize_horizontally.lua index 7fad3db57..4b7698c8d 100644 --- a/tests/examples/awful/placement/maximize_horizontally.lua +++ b/tests/examples/awful/placement/maximize_horizontally.lua @@ -2,6 +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 +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.maximize_horizontally --DOC_HEADER require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_vertically.lua b/tests/examples/awful/placement/maximize_vertically.lua index e5011b56a..9bdef475f 100644 --- a/tests/examples/awful/placement/maximize_vertically.lua +++ b/tests/examples/awful/placement/maximize_vertically.lua @@ -2,6 +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 +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.maximize_vertically --DOC_HEADER require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE diff --git a/xkb.c b/xkb.c index 44d1bb8b7..0ab49a541 100644 --- a/xkb.c +++ b/xkb.c @@ -38,6 +38,7 @@ * * @staticfct xkb_set_layout_group * @tparam integer num Keyboard layout number, integer from 0 to 3 + * @noreturn */ int luaA_xkb_set_layout_group(lua_State *L) From 4fa957b75dfabe63d3eb4636b5e409038318b461 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 10 Jul 2022 00:29:33 -0700 Subject: [PATCH 052/134] doc: Force all properties to document their default value. --- docs/config.ld | 31 +++++++++++++++++++++++++++++++ lib/wibox/widget/imagebox.lua | 18 +++++++++--------- lib/wibox/widget/piechart.lua | 2 +- lib/wibox/widget/progressbar.lua | 2 +- lib/wibox/widget/separator.lua | 2 +- lib/wibox/widget/systray.lua | 8 ++++---- lib/wibox/widget/textbox.lua | 4 ++-- lib/wibox/widget/textclock.lua | 6 +++--- 8 files changed, 52 insertions(+), 21 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 56a3efe3e..7b6d684af 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -234,6 +234,37 @@ create_type { " doesn't match the property name. For linting purpose, please fix this." ) end + + -- Properties should have a default value. If they don't or if the + -- default depends on the context, then `opt=nil` should be used to + -- mute this warning. + if not item:default_of_param(item.params[1]) then + local auto_opt = nil + + -- Extract the default value from other metadata. + if item.tags["propbeautiful"] and item.tags["propbeautiful"][1] then + auto_opt = "beautiful."..(item.module.name.."_"..item.name):gsub("[.]", "_") + elseif item.tags["usebeautiful"] and item.tags["usebeautiful"][1] then + auto_opt = item.tags["usebeautiful"][1]:match("[^ ]+") + end + + -- This adds a default value. It works for LDoc 1.4.5, but is a + -- private API and might break in the future. + if auto_opt then + local mods = item.modifiers[item.parameter] + + if mods then + mods[item.params[1]].opt = auto_opt + end + else + -- The default could not be determined automatically, it requires + -- an explicit `opt=`. + print( + "WARNING: Property", item.name .." from "..item.module.name --, + --"doesn't have a default value. Add `[opt=value]` to the @tparam" + ) + end + end end } diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index 946bddc38..6473ef9c9 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -304,7 +304,7 @@ end -- * `nil`: Unset the image. -- -- @property image --- @tparam image image The image to render. +-- @tparam[opt=nil] image image The image to render. -- @propemits false false --- Set the `imagebox` image. @@ -370,7 +370,7 @@ end -- @DOC_wibox_widget_imagebox_clip_shape_EXAMPLE@ -- -- @property clip_shape --- @tparam function|gears.shape clip_shape A `gears.shape` compatible shape function. +-- @tparam[opt=nil] function|gears.shape clip_shape A `gears.shape` compatible shape function. -- @propemits true false -- @see gears.shape @@ -402,7 +402,7 @@ end -- @DOC_wibox_widget_imagebox_resize_EXAMPLE@ -- @property resize -- @propemits true false --- @tparam boolean resize +-- @tparam[opt=true] boolean resize --- Allow the image to be upscaled (made bigger). -- @@ -412,7 +412,7 @@ end -- -- @DOC_wibox_widget_imagebox_upscale_EXAMPLE@ -- @property upscale --- @tparam boolean upscale +-- @tparam[opt=self.resize] boolean upscale -- @see downscale -- @see resize @@ -424,7 +424,7 @@ end -- -- @DOC_wibox_widget_imagebox_downscale_EXAMPLE@ -- @property downscale --- @tparam boolean downscale +-- @tparam[opt=self.resize] boolean downscale -- @see upscale -- @see resize @@ -439,7 +439,7 @@ end --@DOC_wibox_widget_imagebox_stylesheet_EXAMPLE@ -- -- @property stylesheet --- @tparam string stylesheet +-- @tparam[opt=""] string stylesheet -- @propemits true false --- Set the SVG DPI (dot per inch). @@ -455,7 +455,7 @@ end --@DOC_wibox_widget_imagebox_dpi_EXAMPLE@ -- -- @property dpi --- @tparam number|table dpi +-- @tparam[opt=96] number|table dpi -- @propemits true false -- @see auto_dpi @@ -597,7 +597,7 @@ end -- @DOC_wibox_widget_imagebox_max_scaling_factor_EXAMPLE@ -- -- @property max_scaling_factor --- @tparam number max_scaling_factor +-- @tparam[opt=0] number max_scaling_factor Use `0` for "no limit". -- @propemits true false -- @see valign -- @see halign @@ -629,7 +629,7 @@ end -- @DOC_wibox_widget_imagebox_scaling_quality_EXAMPLE@ -- -- @property scaling_quality --- @tparam string scaling_quality Either `"fast"`, `"good"`, `"best"`, +-- @tparam[op="fast"] string scaling_quality Either `"fast"`, `"good"`, `"best"`, -- `"nearest"` or `"bilinear"`. -- @propemits true false -- @see resize diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 1268a6ba0..0642ead31 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -140,7 +140,7 @@ end --- The pie chart data list. -- -- @property data_list --- @tparam table data_list Sorted table where each entry has a label as its +-- @tparam[opt={}] table data_list Sorted table where each entry has a label as its -- first value and a number as its second value. -- @propemits false false diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index c541d4ecd..be64eabd1 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -519,7 +519,7 @@ end -- @DOC_wibox_widget_progressbar_value_EXAMPLE@ -- -- @property value --- @tparam number value The progress bar value. +-- @tparam[opt=0] number value The progress bar value. -- @propemits true false -- @see max_value diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index d600bcd5c..aff0c99f9 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -43,7 +43,7 @@ local separator = {} --@DOC_wibox_widget_separator_orientation_EXAMPLE@ -- -- @property orientation --- @tparam string orientation +-- @tparam[opt="auto"] string orientation -- @propemits true false --- The separator's thickness. diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua index 911c768d4..37d7596c1 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -148,7 +148,7 @@ end -- available space. Otherwise, any single icon has a size of `size`x`size`. -- -- @property base_size --- @tparam integer|nil base_size The base size +-- @tparam[opt=nil] integer|nil base_size The base size -- @propemits true false function systray:set_base_size(size) @@ -162,7 +162,7 @@ end --- Decide between horizontal or vertical display. -- -- @property horizontal --- @tparam boolean horizontal Use horizontal mode? +-- @tparam[opt=true] boolean horizontal Use horizontal mode? -- @propemits true false function systray:set_horizontal(horiz) @@ -176,7 +176,7 @@ end --- Should the systray icons be displayed in reverse order? -- -- @property reverse --- @tparam boolean reverse Display in reverse order. +-- @tparam[opt=false] boolean reverse Display in reverse order. -- @propemits true false function systray:set_reverse(rev) @@ -194,7 +194,7 @@ end -- visible on the primary screen. The default value is "primary". -- -- @property screen --- @tparam screen|"primary" screen The screen to display on. +-- @tparam[opt=nil] screen|"primary" screen The screen to display on. -- @propemits true false function systray:set_screen(s) diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index be8f2d36b..8996b21c4 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -189,7 +189,7 @@ end -- @DOC_wibox_widget_textbox_markup2_EXAMPLE@ -- -- @property markup --- @tparam string markup The text to set. This can contain pango markup (e.g. +-- @tparam[opt=self.text] string markup The text to set. This can contain pango markup (e.g. -- `bold`). You can use `gears.string.escape` to escape -- parts of it. -- @propemits true false @@ -217,7 +217,7 @@ end -- @DOC_wibox_widget_textbox_text2_EXAMPLE@ -- -- @property text --- @tparam string text The text to display. Pango markup is ignored and shown +-- @tparam[opt=""] string text The text to display. Pango markup is ignored and shown -- as-is. -- @propemits true false -- @see markup diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 6d3776831..13fe21fa9 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -70,7 +70,7 @@ end -- For information about the format specifiers, see -- [the GLib docs](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format). -- @property format --- @tparam string format The new time format. This can contain pango markup. +-- @tparam[opt=" %a %b %d %H:%M"] string format The new time format. This can contain pango markup. function textclock:set_format(format) self._private.format = format @@ -86,7 +86,7 @@ end -- e.g. "Z" for UTC, "±hh:mm" or "Europe/Amsterdam". See -- [GTimeZone](https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new). -- @property timezone --- @tparam string timezone +-- @tparam[opt=TimeZone.new()] string timezone function textclock:set_timezone(tzid) self._private.tzid = tzid @@ -101,7 +101,7 @@ end --- Set the clock's refresh rate. -- -- @property refresh --- @tparam number refresh How often the clock is updated, in seconds +-- @tparam[opt=60] number refresh How often the clock is updated, in seconds function textclock:set_refresh(refresh) self._private.refresh = refresh or self._private.refresh From 31061cb2e64aea71eed3d062d2d8d3b9ddb0700a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 10 Jul 2022 22:56:54 -0700 Subject: [PATCH 053/134] doc: Add @range_stop, @range_start, @property_value and @property_unit. This will be used in the next commit to describe properties in a more consistent way. --- docs/config.ld | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 7b6d684af..c402b0041 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -863,6 +863,34 @@ add_custom_tag { auto_subtags = false } +-- When properties are integers, the value usually has a meaning, like the PID, +-- apoint or a pixel. +add_custom_tag { + name = "propertyunit", + hidden = true, + auto_subtags = false +} + +-- Some string properties are de-facto enums. Only a small set of value is valid. +-- This tag provides a consistent rendering for such properties. +add_custom_tag { + name = "propertyvalue", + hidden = true, + auto_subtags = false +} + +-- Some values, mostly bytes, have a minimum and maximum value. +add_custom_tag { + name = "rangestart", + hidden = true, + auto_subtags = false +} +add_custom_tag { + name = "rangestop", + hidden = true, + auto_subtags = false +} + add_custom_tag { name = "signalhandler", hidden = false, @@ -935,14 +963,6 @@ add_custom_tag { end } --- @rangestart --- @rangeend --- @minimumvalue --- @maximumvalue --- @tenumvalue --- @increments --- @tablekey or not? - -- More fitting section names kind_names={topic='Documentation', module='Libraries', script='Sample files'} From 19e586f969e11187848be367c825cd6dbd438fc0 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 10 Jul 2022 01:19:38 -0700 Subject: [PATCH 054/134] doc: Replace the rendering for the @property default values. --- docs/ldoc.css | 10 ++++++++-- docs/ldoc.ltp | 14 +++++++++++++- 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/ldoc.css b/docs/ldoc.css index 4c1397014..54d150540 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -70,7 +70,8 @@ dd > code, td code, span.default_value, .see_also_description code, -.important_box code +.important_box code, +.property_type code { background-color: #eaedf587; padding-left: 3px; @@ -523,7 +524,7 @@ dl.function dd { margin-bottom: 15px; } -#content dl.function dd h3 { +#content dl.function dd h3, .property_type i { margin-top: 0px; margin-left: 0px; padding-left: 0px; @@ -747,3 +748,8 @@ pre .url { color: #272fc2; text-decoration: underline; } .copy-link--failure { background-color: red; } + +.property_type { + display: inline-block; + margin-left: 15px; +} diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index a054d99cd..a22d344fe 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -377,7 +377,19 @@
        $(M(ldoc.descript(item),item)) -# if show_parms and item.params and #item.params > 0 and not item.hide_params then +# if kind == "Object properties" and item.params[1] then +
        + +
        +# if item:default_of_param(item.params[1]) then + Default value: $(item:default_of_param(item.params[1]))
        +# end +# if item.params[1] then + Type constraint: $(M(item.params.map[item.params[1]],item))
        +# end +         +
        +# elseif 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 a698d20e810a8e79ec247e60135058f4a3087722 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 12 Jul 2022 21:59:19 -0700 Subject: [PATCH 055/134] doc: Add more property warnings. The goal is to fix these issues so the new rendering can become stable. --- docs/config.ld | 42 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index c402b0041..99d59e224 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -224,6 +224,13 @@ create_type { ) end + if type == "bool" then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " type is `bool`, please use `boolean`." + ) + end + -- One of the repeated problem we have is the first word of the -- description being removed because it is used as the property name. -- This "rule" might be stupid, but it prevents it from accidentally @@ -235,10 +242,37 @@ create_type { ) end - -- Properties should have a default value. If they don't or if the - -- default depends on the context, then `opt=nil` should be used to - -- mute this warning. - if not item:default_of_param(item.params[1]) then + local def = item:default_of_param(item.params[1]) + + -- Check the default value for obvious mistakes. + if def then + -- Detect the blatant missing quote marks for string. This is important + -- to differentiate variables from string literals. + if type == "string" and def:sub(1,1) ~= '"' and not def:find(".") then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " is a string, but the default value is not quoted." + ) + end + + -- If the default value is `nil`, then the property must be nullable. + if def == "nil" and not type:find("nil") then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " default value is `nil`, but the type doesn't allow it" + ) + end + + if type == "boolean" and (not (def == "true" or def == "false")) and (not def:find(".")) then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " is a boolean, but is neither `true`, `false` or an alias" + ) + end + else + -- Properties should have a default value. If they don't or if the + -- default depends on the context, then `opt=nil` should be used to + -- mute this warning. local auto_opt = nil -- Extract the default value from other metadata. From 27f329a22914e59d6312f68149c06ff39f4a38f5 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 12 Jul 2022 23:17:53 -0700 Subject: [PATCH 056/134] doc: Add a standard way to add metadata to the property documentation. --- docs/config.ld | 27 ++++++++++++++++++++++++++- docs/ldoc.css | 10 ++-------- docs/ldoc.ltp | 18 ++++++++++++------ 3 files changed, 40 insertions(+), 15 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 99d59e224..9942446ff 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -299,6 +299,16 @@ create_type { ) end end + + -- Allow the template to be shorter by using a for-loop. + for _, mt in ipairs {"propertyunit", "rangestart", "rangestop" } do + local tag_desc = named_tags[mt] + + if item.tags[mt] and item.tags[mt][1] then + local title = tag_desc.title or mt + item:add_metadata(title, item.tags[mt][1]) + end + end end } @@ -901,6 +911,7 @@ add_custom_tag { -- apoint or a pixel. add_custom_tag { name = "propertyunit", + title = "Unit", hidden = true, auto_subtags = false } @@ -916,11 +927,13 @@ add_custom_tag { -- Some values, mostly bytes, have a minimum and maximum value. add_custom_tag { name = "rangestart", + title = "Range starts", hidden = true, auto_subtags = false } add_custom_tag { name = "rangestop", + title = "Range stops", hidden = true, auto_subtags = false } @@ -1204,7 +1217,7 @@ local function init_custom_types(item) -- Give each item an unique identifier so the JavaScript can locate them. item.uid, item_id = item_id, item_id + 1 - item.delims, item.auto_usage, item.auto_params = {}, {}, {} + item.delims, item.auto_usage, item.auto_params, item.metadata = {}, {}, {}, {} local to_rm = {} @@ -1278,6 +1291,18 @@ local function init_custom_types(item) return nil, nil, extra end + -- Recursive way to annotate property-like objects. + local amt + amt = function(self, title, value, children) + self.metadata[#self.metadata+1] = { + title = title, + value = value, + children = children or {}, + add_metadata = amt + } + end + item.add_metadata = amt + item.is_init = true end diff --git a/docs/ldoc.css b/docs/ldoc.css index 54d150540..eda56fa4d 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -70,8 +70,7 @@ dd > code, td code, span.default_value, .see_also_description code, -.important_box code, -.property_type code +.important_box code { background-color: #eaedf587; padding-left: 3px; @@ -524,7 +523,7 @@ dl.function dd { margin-bottom: 15px; } -#content dl.function dd h3, .property_type i { +#content dl.function dd h3, .see_also i { margin-top: 0px; margin-left: 0px; padding-left: 0px; @@ -748,8 +747,3 @@ pre .url { color: #272fc2; text-decoration: underline; } .copy-link--failure { background-color: red; } - -.property_type { - display: inline-block; - margin-left: 15px; -} diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index a22d344fe..f6a74af5c 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -378,17 +378,23 @@ $(M(ldoc.descript(item),item)) # if kind == "Object properties" and item.params[1] then -
        +

        Constraints:

        -
        + # if item:default_of_param(item.params[1]) then - Default value: $(item:default_of_param(item.params[1]))
        +         # end -# if item.params[1] then - Type constraint: $(M(item.params.map[item.params[1]],item))
        +# for _, metadata in ldoc.ipairs(item.metadata or {}) do +         +# for _, child in ldoc.ipairs(metadata.children) do + +# end # end +# if item.params.map[item.params[1]] and item.params.map[item.params[1]] ~= "" then + +# end +
        Default value: $(item:default_of_param(item.params[1]))
        $(metadata.title): $(metadata.value)
        $(child.title): $(child.value)
        Valid values: $(M(item.params.map[item.params[1]],item))
         -
        # elseif 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 From 9c6ac7ec35a6c595e934a098a67699655d5ee699 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 17 Jul 2022 01:26:11 -0700 Subject: [PATCH 057/134] doc: Enforce a strict schema for all @property entries. It now requires some extra tags to be added. With the new constraints, the rendering is much more detailed. --- docs/common/widget.ldoc | 18 +- docs/config.ld | 677 ++++++++++++++++++++++++++++++++++++++-- docs/ldoc.css | 6 + docs/ldoc.ltp | 34 +- 4 files changed, 687 insertions(+), 48 deletions(-) diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index 1ef1efb57..66f4a635e 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -13,6 +13,7 @@ -- @property children -- @tparam table children The children. -- @baseclass wibox.widget +-- @see all_children --- Get all direct and indirect children widgets. -- This will scan all containers recursively to find widgets @@ -21,6 +22,7 @@ -- @property all_children -- @tparam table all_children The children. -- @baseclass wibox.widget +-- @see children --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) @@ -32,16 +34,30 @@ --- Force a widget height. -- @property forced_height -- @tparam number|nil forced_height The height (`nil` for automatic) +-- @propertytype nil Let the layout decide the height. Usually using the widget +-- native height. +-- @propertytype number Enforce a number of pixels. +-- @rangestart 0 +-- @rangestop 65534 -- @baseclass wibox.widget +-- @see forced_width --- Force a widget width. -- @property forced_width -- @tparam number|nil forced_width The width (`nil` for automatic) +-- @propertytype nil Let the layout decide the width. Usually using the widget +-- native width. +-- @propertytype number Enforce a number of pixels. +-- @rangestart 0 +-- @rangestop 65534 -- @baseclass wibox.widget +-- @see forced_height --- The widget opacity (transparency). -- @property opacity --- @tparam[opt=1] number opacity The opacity (between 0 and 1) +-- @tparam[opt=1] number opacity. +-- @rangestart 0.0 +-- @rangestop 1.0 -- @baseclass wibox.widget --- The widget visibility. diff --git a/docs/config.ld b/docs/config.ld index 9942446ff..fc3a5be61 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -95,6 +95,82 @@ topics={ '89-NEWS.md', } +-- Rather han copy paste this hundreds of time, unify these special type +-- descriptions. +local type_fallback_description = { + image = { + "string Interpreted as a path to an image file." , + "string A valid SVG content." , + "cairo A cairo image surface: Directly used as-is." , + "librsvg A librsvg handle object: Directly used as-is." , + "nil Unset the image." , + }, + color = { + "string An hexadecimal color code, such as `\"#ff0000\"` for red." , + "string A color name, such as `\"red\"`." , + "table A [gradient table](../theme_related_libraries/gears.color.html)." , + "cairo.pattern Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html)." , + "cairo.pattern A texture build from an image by [gears.color.create\\_png\\_pattern](../theme_related_libraries/gears.color.html#create_png_pattern)" , + }, + shape = { + "gears.shape Like `gears.shape.circle`", + "function This can be used for custom shapes or to set parameters of existing shapes.", + }, + screen = { + "screen A valid screen object such as retured by `awful.screen.focused()` or `mouse.screen`.", + "integer A screen global id. Avoid using this since they are unsorted.", + "string The `\"primary\"` value is also valid.", + }, + font = { + "string A Pango [font description](../widgets/wibox.widget.textbox.html#font).", + "string An [XFT string](https://wiki.archlinux.org/title/X_Logical_Font_Description), such as `\"-*-dejavu sans mono-medium-r-normal--*-80-*-*-*-*-iso10646-1\"`.", + + }, + template = { + "table A table containing a widget tree definition. WARNING: This is really a table".. + " and **NOT** a widget object. Use the `widget = come.class.here` to define the ".. + " topmost class rather than construct an instance." + }, + placement = { + "function A custom callback to generate *and set* the geometry.", + "placement Any of the `awful.placement` function or constructs." + } +} + +-- Document the "common" function prototypes. Some common types, such as +-- the client layouts, the shapes and placements are just glorified functions. +local callback_fallback_description = { + shape = { + {"functionparam", "cairo.context", "cr", "A [Cairo context](https://cairographics.org/manual/cairo-cairo-t.html)"}, + {"functionparam", "number", "width", "The area width."}, + {"functionparam", "number", "height", "The area height."}, + }, + placement = { + {"functionreturn", "table", "A table with an `x`, `y`, `width` and `height` keys."}, + {"functionparam", "object", "obj", "Any object with a `geometry` property or method."}, + {"functionparam", "table", "args", "The `placement` arguments. See `awful.placement` for a complete list."}, + }, +} + +-- Try to use a single name for common types. For example, mixing `color` and +-- `gears.color` (which is *not* a type) is confusing. It also allows the +-- type description to be auto-generated from `type_fallback_description`. +local type_name_linting = { + ["gears.color"] = "color", + ["gears.shape"] = "shape", + ["wibox.widget"] = "widget", + ["gears.surface"] = "image", + ["surface"] = "image", + ["awful.placement"] = "placement", + ["double"] = "number", + ["float"] = "number", + ["bool"] = "boolean", +} + +local metadata_tags = { + "propertyunit", "rangestart", "rangestop", "negativeallowed", +} + local databases, named_tags, item_id, is_init = {}, {}, 1, false local all_theme_vars, delayed_collect = nil, {} @@ -135,29 +211,76 @@ end -- Add the @usebeautiful from the optional/default value. local function auto_add_usebeautiful(item) - local vars, var_names = {}, {} + local vars, var_names = {}, {} - -- Datamine the default values to autogenerate the @usebeautiful. - for parm in ldoc.modules.iter(item.params) do - for p in ldoc.modules.iter(item:subparam(parm)) do - local def = item:default_of_param(p) + -- Datamine the default values to autogenerate the @usebeautiful. + for parm in ldoc.modules.iter(item.params) do + for p in ldoc.modules.iter(item:subparam(parm)) do + local def = item:default_of_param(p) - if def and def ~= true then - for var in def:gmatch("beautiful[.][a-z_]+") do - if not var_names[var] then - vars[#vars+1] = var - end - var_names[var] = true + if def and def ~= true then + for var in def:gmatch("beautiful[.][a-z_]+") do + if not var_names[var] then + vars[#vars+1] = var end + var_names[var] = true end end end + end - for _, var in ipairs(vars) do - named_tags.usebeautiful:add_to_item(item, var) + for _, var in ipairs(vars) do + named_tags.usebeautiful:add_to_item(item, var) + end +end + +-- Handle both manually specified callback prototypes and common ones. +local function parse_properties_function_metadata(item, types) + local raw_input = item.tags["functionnoparam"] and {} or item.tags["functionparam"] + local raw_output = item.tags["functionnoreturn"] and {} or item.tags["functionreturn"] + local fallback, input, output = true, {}, {} + + for _, arg in ipairs(raw_input or {}) do + input[#input+1] = item.parsed_tags["functionparam"][arg] + fallback = false + end + + for _, ret in ipairs(raw_output or {}) do + output[#output+1] = item.parsed_tags["functionreturn"][ret] + fallback = false + end + + local has_in = #input > 0 or item.tags["functionnoparam"] ~= nil + local has_out = #output > 0 or item.tags["functionnoreturn"] ~= nil + + if fallback then + for type in pairs(types) do + if callback_fallback_description[type] then + for _, row in ipairs(callback_fallback_description[type]) do + local dest = row[1] == "functionparam" and input or output + + dest[#dest+1] = { + description = row[#row], + type = row[2] and {value = row[2]}, + name = row[3] and {value = row[3]}, + } + end + + -- Assume the fallback is correct. + has_out, has_in = true, true + break + end end end + return { + input = input, + output = output, + has_input = has_in, + has_output = has_out, + } +end + -- The first stereotype are the constructors. create_type { name = "constructorfct", @@ -211,8 +334,8 @@ create_type { return end - local param = item:subparam(item.params[1]) - local type = item:type_of_param(param[1]) + local param, sublist = item:subparam(item.params[1]) + local type = item:type_of_param(item.params[1]) -- Force people to use @tparam because it is easier to lint and allows -- multiple types. @@ -269,6 +392,8 @@ create_type { " is a boolean, but is neither `true`, `false` or an alias" ) end + + item:add_metadata("Default value", ("%s"):format(def)) else -- Properties should have a default value. If they don't or if the -- default depends on the context, then `opt=nil` should be used to @@ -284,31 +409,361 @@ create_type { -- This adds a default value. It works for LDoc 1.4.5, but is a -- private API and might break in the future. - if auto_opt then + if item.tags["propertydefault"] and item.tags["propertydefault"][1] then + item:add_metadata( + "Default value", + ldoc.markup(item.tags["propertydefault"][1]) + ) + elseif auto_opt then local mods = item.modifiers[item.parameter] if mods then mods[item.params[1]].opt = auto_opt end - else + + item:add_metadata("Default value", ("%s"):format(auto_opt)) + elseif not sublist then -- The default could not be determined automatically, it requires -- an explicit `opt=`. print( - "WARNING: Property", item.name .." from "..item.module.name --, - --"doesn't have a default value. Add `[opt=value]` to the @tparam" + "WARNING: Property", item.name .." from "..item.module.name, + "doesn't have a default value. Add `[opt=value]` to the @tparam" ) end end + local prop_types, prop_type_names, fallback_callback = {}, {}, false + + -- Type validation. + do + -- Handle the case where a property has multiple types. + local metatypes, table_args = {}, {} + local prop_has_nil, prop_has_obj = false, false + + -- Make a copy of the table to avoid recursion. + for _, t in ipairs(item.tags["propertytype"] or {}) do + metatypes[#metatypes+1] = t + end + + for t in item:type_of_param(item.params[1]):gmatch('[^|]+') do + if type_name_linting[t] then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " type is '"..t.."'. Please use `"..type_name_linting[t].."'" + ) + end + + if not prop_type_names[t] then + prop_types[#prop_types+1] = t + end + prop_type_names[t] = true + fallback_callback = fallback_callback or callback_fallback_description[t] + prop_has_nil = prop_has_nil or t == "nil" + prop_has_obj = prop_has_obj or (t:find('.') and not t:sub(1,5) == "gears") + end + + if item.tags["propbeautiful"] + and item.tags["propbeautiful"][1] + and not prop_type_names["nil"] then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " uses `@propbeautiful`, yet, doesn't have `nil` as a type." + ) + end + + if #item.params == 0 then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " is missing it's `@tparam` section. Please add it." + ) + elseif #item.params > 1 then + for i=2, #item.params do + local splitted = {} + + for part in item.params[i]:gmatch("[^.]+") do + splitted[#splitted+1] = part + end + + if #splitted == 1 then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has a `@tparam` named \""..item.params[i].."\". The only".. + " valid name is \"..item.name\"" + ) + else + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has a `@tparam` named \""..item.params[i].."\". This is".. + " not valid. It should be `@tparam[opt=...] "..item.name.. + ". " + ) + end + end + end + + -- Some properties are table with fixed keys. + local param,sublist = item:subparam(item.params[1]) + if sublist then + for _, sub_param in pairs(param) do + local splitted = {} + + for part in sub_param:gmatch("[^.]+") do + splitted[#splitted+1] = part + end + + -- The first part should match the property name. If it doesn't, + -- then it's unclear what it is. + if splitted[1] ~= item.name then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has additional @tparams with unclear meaning. Please".. + " use `@tparam[opt=...] type property_name.subparam Desc...`" + ) + else + local rebuilt_name = "" + + for i=2, #splitted do + rebuilt_name = rebuilt_name .. ((#rebuilt_name > 0) and "." or "") .. splitted[i] + end + + table_args[#table_args+1] = { + name = rebuilt_name, + default = item:default_of_param(sub_param), + type = item:type_of_param(sub_param), + description = item.params.map[sub_param], + } + end + end + end + + if prop_has_obj and not prop_has_nil then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has an object type, however it doesn't define the behavior".. + " or `nil` (or lack `@nonnullable`)" + ) + end + + local type_map = {} + + for _, typeinfo in ipairs(metatypes) do + local parsed = item.parsed_tags["propertytype"][typeinfo] + type_map[parsed.typename.value] = type_map[parsed.typename.value] or {} + type_map[parsed.typename.value][#type_map[parsed.typename.value]+1] = parsed + end + + local warnings = {} + + -- Check if every possible type is described. + for _, t in ipairs(prop_types) do + if not type_map[t] then + -- Auto add description for common types. + if type_fallback_description[t] then + for _, entry in ipairs(type_fallback_description[t]) do + metatypes[#metatypes+1] = entry + named_tags.propertytype:add_to_item(item, entry) + type_map[t] = type_map[t] or {} + type_map[t][#type_map[t]+1] = entry + end + elseif #prop_types > 1 then + local warn = "WARNING: Property", item.name .." from "..item.module.name.. + " has the undescribed object type \""..t.."\", please add".. + " one (or more) `@propertytype "..t.." ` tag." + warnings[t] = warnings[t] or {} + warnings[t][#warnings[t]+1] = warn + end + end + end + + -- Autofill the meaning of `nil` when there is a fallback `beautiful` + -- variable. + if prop_type_names["nil"] + and (not type_map["nil"]) + and item.tags["propbeautiful"] + and item.tags["propbeautiful"][1] then + local modname = item.module.name:gmatch("[^.]+$")() + local fallback = "beautiful."..(modname.."_"..item.name):gsub("[.]", "_") + local entry = "nil Fallback to the current value of `"..fallback.."`." + named_tags.propertytype:add_to_item(item, entry) + metatypes[#metatypes+1] = entry + + warnings["nil"] = nil + end + + for _, warn in ipairs(warnings) do + print(warn) + end + + local mt_by_type = {} + + -- Add the metatype section + if #metatypes > 0 then + local mt = item:add_metadata("Type description") + + for _, typeinfo in ipairs(metatypes) do + local parsed = item.parsed_tags["propertytype"][typeinfo] + local tmt = mt:add_metadata( + ""..parsed.typename.value.."", + ldoc.markup(parsed.description) + ) + mt_by_type[parsed.typename.value] = mt_by_type[parsed.typename.value] or {} + mt_by_type[parsed.typename.value][#mt_by_type[parsed.typename.value]+1] = tmt + end + end + + if #table_args > 0 then + local mt = mt_by_type["table"] and mt_by_type["table"][1] or item:add_metadata("Table keys") + for _, key in ipairs(table_args) do + mt:add_metadata( + key.name, + ldoc.markup(key.description), + key.type + ) + end + end + + -- Add the function callback parameters section. + if prop_type_names["function"] or fallback_callback then + local fp = (mt_by_type["function"] and mt_by_type["function"][1] or item):add_metadata("Function prototype") + + local prototype = parse_properties_function_metadata(item, prop_type_names) + + if not prototype.has_input then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " needs either `@functionparam` or `@functionnoparam` if there".. + " is none." + ) + elseif #prototype.input == 0 then + fp:add_metadata("Parameters:", "The function has no parameters") + else + local fparams = fp:add_metadata("Parameters") + for _, parsed in ipairs(prototype.input) do + if (not parsed.name) or (not parsed.type) then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " has a `@functionparam` improperly formatted. The format is ".. + "` [description]`." + ) + else + fparams:add_metadata( + parsed.name.value, + ldoc.markup(parsed.description), + parsed.type.value + ) + end + end + end + + args = item.tags["functionnoreturn"] and {} or item.tags["functionreturn"] + + if not prototype.has_output then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " needs either `@functionreturn` or `@functionnoreturn` if there".. + " is none." + ) + elseif #prototype.output == 0 then + fp:add_metadata("Return", "The function returns nothing.") + elseif #prototype.output == 1 then + fp:add_metadata("Return", ldoc.markup(prototype.output[1].description), prototype.output[1].type.value) + else + local md = fp:add_metadata("Return") + for _, parsed in ipairs(prototype.output) do + md:add_metadata( + "", + ldoc.markup(parsed.description), + parsed.type.value + ) + end + end + end + + -- Handle the case where the table is a list. + if #prop_types == 1 and prop_types[1] == "table" + and #(item.tags["tablerowtype"] or {}) == 0 + and #table_args == 0 then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " needs either `@tablerowtype` or additional `@tparam`." + ) + elseif #(item.tags["tablerowtype"] or {}) > 0 then + local mt = item:add_metadata("Table content", ldoc.markup(item.tags["tablerowtype"][1])) + + for _, key in ipairs(item.tags["tablerowkey"] or {}) do + local parsed = item.parsed_tags["tablerowkey"][key] + local type, val, desc = parsed.type.value, parsed.name.value, parsed.description + mt:add_metadata(""..val.."", ldoc.markup(desc), type) + end + end + end + -- Allow the template to be shorter by using a for-loop. - for _, mt in ipairs {"propertyunit", "rangestart", "rangestop" } do + local has_start, has_allow_negative = false, false + for _, mt in ipairs(metadata_tags) do local tag_desc = named_tags[mt] if item.tags[mt] and item.tags[mt][1] then + has_start = has_start or mt == "rangestart" + has_allow_negative = has_allow_negative or mt == "negativeallowed" local title = tag_desc.title or mt - item:add_metadata(title, item.tags[mt][1]) + item:add_metadata(title, ldoc.markup(item.tags[mt][1])) end end + + if (prop_type_names["number"] or prop_type_names["integer"]) and not (has_start or has_allow_negative) then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has numeric type, please add either `@rangestart` or `@negativeallowed false`." + ) + end + + local tdesc = item.params.map[item.params[1]] and item.params.map[item.params[1]] or "" + + -- Auto add the description for "simple" boolean. + if #prop_types == 1 and prop_types[1] == "boolean" and tdesc == "" then + tdesc = "`true` or `false`." + end + + -- Handle custom type description and string "enum". + if #(item.tags["propertyvalue"] or {}) > 0 or tdesc ~= "" then + + local mt = item:add_metadata("Valid values", ldoc.markup(tdesc)) + + local values, found_default = item.tags["propertyvalue"] or {}, false + + for _, enum_val in ipairs(values) do + local parsed = item.parsed_tags["propertyvalue"][enum_val] + local val, desc = parsed.value.value, parsed.description + + if val:sub(1,1) ~= '"' or val:sub(#val,#val) ~= '"' then + print( + "WARNING: Value `"..val.."` from property ".. item.name + .." from module "..item.module.name.. "should be a quoted string." + ) + end + + found_default = found_default or val == def + + mt:add_metadata(""..val.."", ldoc.markup(desc)) + end + + if def and #values > 0 and def:sub(1,9) ~= "beautiful" and not found_default then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " has some `@propertyvalue`, but the default value is not among them." + ) + end + end + + -- @return is not displayed for properties, something important + -- might have been written there, so it's better to block it + if item.tags["return"] or item.tags["treturn"] then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " has a `@return`, it is not rendered. Remove it." + ) + end end } @@ -405,12 +860,58 @@ all_theme_vars = create_type { end end, finish_callback = function(item) - if item.tags["beautiful_used_by"] then return end + if not item.tags["beautiful_used_by"] then + -- Every variable should be consumed by something. Better "park" some + -- variable in the constructors than leave them disconnected from the + -- global model. + print("WARNING: ", item.name, "is not used by anything, add @usebeautiful or @propbeautiful") + else + local prop, mn = nil, item.module.name:match("[.]?([^.]+)$") + -- If there is a property with the corresponding name and it doesn't + -- mention the `beautiful` variable, that's nearly always a bug. + for kind, items in item.module.kinds() do + if kind == "Object properties" then + for k in items do + for k2,v2 in k do + if item.name:match("[.]"..mn.."_"..k2.name.."$") then + prop = k2 + break + end + if prop then break end + end + break + end + end + end - -- Every variable should be consumed by something. Better "park" some - -- variable in the constructors than leave them disconnected from the - -- global model. - print("WARNING: ", item.name, "is not used by anything, add @usebeautiful or @propbeautiful") + if prop then + local mention = false + + if prop.tags.propbeautiful then mention = true end + + if (not mention) and prop:default_of_param(prop.params[1]) == item.name then + mention = true + end + + for _, v in ipairs((not mention) and prop.tags.usebeautiful or {}) do + local parsed = prop.parsed_tags.usebeautiful[v] + if parsed.name.value == item.name then + mention = true + break + end + end + + if not mention then + print( + "WARNING: `"..item.name.. "` from `"..item.module.name.."` ".. + "seems to match a property called `"..prop.name.."`. However, ".. + "there is no mention of this `beautiful` ".. + "variable in its documentation. Please add `@propbeautiful` or ".. + "`[opt="..item.module.name.."]" + ) + end + end + end end } @@ -624,6 +1125,8 @@ add_custom_tag = function(args) end item.has_show_more = item.has_show_more or (not args.hidden) + + return parsed end custom_tags[#custom_tags+1] = args @@ -907,6 +1410,13 @@ add_custom_tag { auto_subtags = false } +-- When a property cannot be `nil` or a function/method cannot return `nil`. +add_custom_tag { + name = "nonnullable", + hidden = true, + auto_subtags = false +} + -- When properties are integers, the value usually has a meaning, like the PID, -- apoint or a pixel. add_custom_tag { @@ -921,22 +1431,109 @@ add_custom_tag { add_custom_tag { name = "propertyvalue", hidden = true, - auto_subtags = false + auto_subtags = false, + params = { + { name = "value" }, + }, +} + +-- Some defaults are not values. They are either algorithms, chains od fallbacks +-- or somehow inherited. `ldoc` `opt` can only parse single "words", thus a new +-- tag is needed for textual description of the default value. +add_custom_tag { + name = "propertydefault", + hidden = true, + auto_subtags = false, +} + +-- Some properties have multiple possible types. Some also might support multiple +-- "logical type" for the same datatype. For example `string` can be a path or +-- some CSS/SVG or an integer have different meaning for positive vs. +-- negative/zeroed. +-- +-- This tag helps document those nuances. +add_custom_tag { + name = "propertytype", + hidden = true, + auto_subtags = false, + params = { + { name = "typename" }, + }, } -- Some values, mostly bytes, have a minimum and maximum value. add_custom_tag { name = "rangestart", - title = "Range starts", + title = "Minimum value", hidden = true, auto_subtags = false } add_custom_tag { name = "rangestop", - title = "Range stops", + title = "Maximum value", hidden = true, auto_subtags = false } +add_custom_tag { + name = "negativeallowed", + title = "Negative allowed", + hidden = true, + auto_subtags = false, + params = { + { name = "allowed" }, + }, +} + +-- A lot of properties have the `table` value. Lua tables can be anything from +-- "struct" to list to objects. For lists, then the type of the row needs to +-- be specified. +add_custom_tag { + name = "tablerowtype", + title = "Table content", + hidden = true, + auto_subtags = false, +} +add_custom_tag { + name = "tablerowkey", + title = "Row keys", + hidden = true, + auto_subtags = false, + params = { + { name = "type" }, + { name = "name" }, + }, +} + +-- When a `@property` takes a `function` value, then the function arguments +-- much be provided. If there is none, then `@functionnoparam` must be explicitly +-- specified. Same for the return value(s). +add_custom_tag { + name = "functionnoparam", + hidden = true, + auto_subtags = false, +} +add_custom_tag { + name = "functionparam", + hidden = true, + auto_subtags = false, + params = { + { name = "type" }, + { name = "name" }, + }, +} +add_custom_tag { + name = "functionnoreturn", + hidden = true, + auto_subtags = false, +} +add_custom_tag { + name = "functionreturn", + hidden = true, + auto_subtags = false, + params = { + { name = "type" }, + }, +} add_custom_tag { name = "signalhandler", @@ -1115,9 +1712,19 @@ local named_args = { [ '(args)' ] = true, } +-- Some values come from external sources, we can't enforce the naming conventions +-- on them. So far, they are all keyboard related. local param_name_whitelist = { - Mod2 = true, - Lock = true, + Mod2 = true, Lock = true, Control = true, Mod1 = true, ISO_Level3_Shift = true, + Mod4 = true, Insert = true, Delete = true, Next = true, Prior = true, Left = true, + Up = true, Right = true, Down = true, KP_End = true, KP_Down = true, + KP_Next = true, KP_Left = true, KP_Begin = true, KP_Right = true, + KP_Home = true, KP_Up = true, KP_Prior = true, KP_Insert = true, KP_Delete = true, + KP_Divide = true, KP_Multiply = true, KP_Subtract = true, KP_Add = true, + KP_Enter = true, Escape = true, Tab = true, space = true, Return = true, + XF86MonBrightnessUp = true, XF86MonBrightnessDown = true, + XF86AudioRaiseVolume = true, XF86AudioLowerVolume = true, XF86AudioMute = true, + XF86AudioPlay = true, XF86AudioPrev = true, XF86AudioNext = true, XF86AudioStop = true, } -- Sections which are hidden by default, but visible when clicked. @@ -1293,13 +1900,15 @@ local function init_custom_types(item) -- Recursive way to annotate property-like objects. local amt - amt = function(self, title, value, children) + amt = function(self, title, description, datatype) self.metadata[#self.metadata+1] = { title = title, - value = value, - children = children or {}, + datatype = datatype, + description = description, + metadata = {}, add_metadata = amt } + return self.metadata[#self.metadata] end item.add_metadata = amt diff --git a/docs/ldoc.css b/docs/ldoc.css index eda56fa4d..c86acc14e 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -47,6 +47,12 @@ td span.types { width: 100%; } +td span.inline_types { + color: #a4c7ff; + flex-flow: nowrap; + width: 100%; +} + .type { flex-basis: auto; font-weight: bold; diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index f6a74af5c..e7cf8b4ec 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -257,7 +257,7 @@

        See also:

        <$(list_or_p)> # for see in iter(module.see) do - $(li)$(see.label) BOB$(il) + $(li)$(see.label)$(il) # end -- for @@ -377,22 +377,30 @@
        $(M(ldoc.descript(item),item)) -# if kind == "Object properties" and item.params[1] then +# if kind == "Object properties" and item.params[1] and #item.metadata > 0 then

        Constraints:

        -# if item:default_of_param(item.params[1]) then - -# end -# for _, metadata in ldoc.ipairs(item.metadata or {}) do - -# for _, child in ldoc.ipairs(metadata.children) do - +# local current_level +# current_level = function(metadata, level) +# for _, metadata in ldoc.ipairs(metadata, level) do + + +# if metadata.description and not metadata.description:match("^[\t\n ]*$") then + +# end + +# current_level(metadata.metadata, level + 1) # end -# end -# if item.params.map[item.params[1]] and item.params.map[item.params[1]] ~= "" then - -# end +# end --current_level +# current_level(item.metadata or {}, 0)
        Default value: $(item:default_of_param(item.params[1]))
        $(metadata.title): $(metadata.value)
        $(child.title): $(child.value)
        + + $(metadata.title)$(#(metadata.metadata or {}) > 0 and ":" or "") + +# if metadata.datatype then + ($(metadata.datatype)) +# end + : $(metadata.description)
        Valid values: $(M(item.params.map[item.params[1]],item))
         # elseif show_parms and item.params and #item.params > 0 and not item.hide_params then From a722a67679486ba45a12dcaf662b000767d49689 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 17 Jul 2022 01:26:15 -0700 Subject: [PATCH 058/134] doc: Fix a CSS regression from a recent commit. --- docs/ldoc.css | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ldoc.css b/docs/ldoc.css index c86acc14e..9576dc0f9 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -650,6 +650,8 @@ pre .url { color: #272fc2; text-decoration: underline; } /* Inheritance diagram */ .inheritance .inheritance__level { list-style: none; + padding-top: 0px; + padding-left: 30px; } .inheritance .inheritance__level--root { From 7091b2720c8c9c2f1967b895c8ba60f22531c00e Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 30 Jul 2022 21:16:54 -0700 Subject: [PATCH 059/134] test: Enforce the maximum size for the `wibox` test example templte. So far, it worked fine if both `w`/`h` were enforced or neither. If one was, then there was a chance one axis would end up 9999 pixel wide or tall. This worked fine when the `.svg` was inserted using ``, but now that it's using ``, it now scales down to zero. --- tests/examples/wibox/template.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/examples/wibox/template.lua b/tests/examples/wibox/template.lua index 409e0ee6e..08c1af988 100644 --- a/tests/examples/wibox/template.lua +++ b/tests/examples/wibox/template.lua @@ -52,7 +52,7 @@ for _ = 1, 10 do end -- Get the example fallback size (the tests can return a size if the want) -local f_w, f_h = container:fit({dpi=96}, 9999, 9999) +local f_w, f_h = container:fit({dpi=96}, w or 9999, h or 9999) -- There is an overhead that cause testbox "...", add 10 until someone -- figures out the real equation From 0f948c145f71f84071a38078a14fe82a64cac75c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 7 Aug 2022 17:43:18 -0700 Subject: [PATCH 060/134] tests: Fix a missing --DOC_HIDE in the notification examples. --- tests/examples/awful/notification/bg.lua | 2 +- tests/examples/awful/notification/border_color.lua | 2 +- tests/examples/awful/notification/fg.lua | 2 +- tests/examples/awful/notification/margin.lua | 2 +- tests/examples/awful/notification/shape.lua | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/examples/awful/notification/bg.lua b/tests/examples/awful/notification/bg.lua index 8762be5a7..591ff625f 100644 --- a/tests/examples/awful/notification/bg.lua +++ b/tests/examples/awful/notification/bg.lua @@ -28,4 +28,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/notification/border_color.lua b/tests/examples/awful/notification/border_color.lua index d89affe11..28ef20f39 100644 --- a/tests/examples/awful/notification/border_color.lua +++ b/tests/examples/awful/notification/border_color.lua @@ -29,4 +29,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/notification/fg.lua b/tests/examples/awful/notification/fg.lua index b3f461e85..ef521d7ce 100644 --- a/tests/examples/awful/notification/fg.lua +++ b/tests/examples/awful/notification/fg.lua @@ -29,4 +29,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/notification/margin.lua b/tests/examples/awful/notification/margin.lua index ac0da4eac..49d2b54ea 100644 --- a/tests/examples/awful/notification/margin.lua +++ b/tests/examples/awful/notification/margin.lua @@ -37,4 +37,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/notification/shape.lua b/tests/examples/awful/notification/shape.lua index 8b48110e2..f5b07d5ac 100644 --- a/tests/examples/awful/notification/shape.lua +++ b/tests/examples/awful/notification/shape.lua @@ -39,4 +39,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE From 50c98059b8a6be8505924f4041d4965ffc3e9e5d Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 21:56:10 -0700 Subject: [PATCH 061/134] doc: Fix a rendering problem. Beause the HTML was indented with more than 3 spaces, it was converted to mardown when using the fallback (not discount) markdown rendered. --- docs/config.ld | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index fc3a5be61..6d3a4f9df 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -35,24 +35,24 @@ should be useful for you. ### Default configuration components name:
        - +
        ### Guides
        -
        - @{07-my-first-awesome.md|Getting started} - @{90-FAQ.md|FAQ} - @{01-readme.md|Read Me} - @{89-NEWS.md|NEWS} -
        -
        - @{03-declarative-layout.md|The widget system} - @{09-options.md|Startup options} - @{05-awesomerc.md|The default rc.lua} - @{08-client-layout-system.md|Window management} -
        +
        + @{07-my-first-awesome.md|Getting started} + @{90-FAQ.md|FAQ} + @{01-readme.md|Read Me} + @{89-NEWS.md|NEWS} +
        +
        + @{03-declarative-layout.md|The widget system} + @{09-options.md|Startup options} + @{05-awesomerc.md|The default rc.lua} + @{08-client-layout-system.md|Window management} +
        ## Major libraries From 0cf97e007d35587ca52d664920a9a9724469d4ff Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 062/134] docs.common.wibox.ldoc: Update the property documentation. --- docs/common/wibox.ldoc | 49 ++++++++++++++++++++++++++++++------------ 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc index 7c1415adc..ea9d40f7c 100644 --- a/docs/common/wibox.ldoc +++ b/docs/common/wibox.ldoc @@ -3,6 +3,8 @@ -- @baseclass wibox -- @property border_width -- @tparam[opt=0] integer border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits false false --- Border color. @@ -39,7 +41,8 @@ -- -- @baseclass wibox -- @property cursor --- @tparam string cursor +-- @tparam[opt=nil] string|nil cursor +-- @propertytype nil Do not change the mouse cursor. -- @see mouse -- @propemits false false @@ -47,21 +50,23 @@ -- -- @baseclass wibox -- @property visible --- @tparam boolean visible +-- @tparam[opt=false] boolean visible -- @propemits false false --- The opacity of the wibox, between 0 and 1. -- -- @baseclass wibox -- @property opacity --- @tparam number opacity (between 0 and 1) +-- @tparam[opt=true] number opacity +-- @rangestart 0.0 +-- @rangestop 1.0 -- @propemits false false --- The window type (desktop, normal, dock, ...). -- -- @baseclass wibox -- @property type --- @tparam string type +-- @tparam[opt=""] string type -- @see client.type -- @propemits false false @@ -69,28 +74,38 @@ -- -- @baseclass wibox -- @property x --- @tparam integer x +-- @tparam[opt=0] integer x +-- @propertyunit pixel +-- @negativeallowed true -- @propemits false false --- The y coordinates. -- -- @baseclass wibox -- @property y --- @tparam integer y +-- @tparam[opt=0] integer y +-- @propertyunit pixel +-- @negativeallowed true -- @propemits false false --- The width of the wibox. -- -- @baseclass wibox -- @property width --- @tparam integer width +-- @tparam[opt=1] integer width +-- @propertyunit pixel +-- @rangestart 1 +-- @negativeallowed false -- @propemits false false --- The height of the wibox. -- -- @baseclass wibox -- @property height --- @tparam integer height +-- @tparam[opt=1] integer height +-- @propertyunit pixel +-- @rangestart 1 +-- @negativeallowed false -- @propemits false false --- The wibox screen. @@ -98,9 +113,10 @@ -- @baseclass wibox -- @property screen -- @tparam screen screen +-- @propertydefault The screen which contains `0x0`. -- @propemits true false ---- The wibox's `drawable`. +-- The wibox's `drawable`. -- -- @baseclass wibox -- @property drawable @@ -110,7 +126,7 @@ --- The widget that the `wibox` displays. -- @baseclass wibox -- @property widget --- @tparam[opt=nil] wibox.widget widget +-- @tparam[opt=nil] widget|nil widget -- @propemits true false --- The X window id. @@ -118,6 +134,7 @@ -- @baseclass wibox -- @property window -- @tparam string window +-- @propertydefault Autogenerated. -- @see client.window -- @propemits false false @@ -130,6 +147,7 @@ -- @baseclass wibox -- @property shape_bounding -- @tparam surface._native shape_bounding +-- @propertydefault Fill all pixels. -- @propemits false false -- @see shape @@ -141,6 +159,7 @@ -- @baseclass wibox -- @property shape_clip -- @tparam surface._native shape_clip +-- @propertydefault Fill all pixels. -- @propemits false false -- @see shape @@ -153,6 +172,7 @@ -- @baseclass wibox -- @property shape_input -- @tparam surface._native shape_input +-- @propertydefault Fill all pixels. -- @propemits false false -- @see input_passthrough @@ -160,7 +180,7 @@ -- -- @baseclass wibox -- @property shape --- @tparam gears.shape shape +-- @tparam[opt=gears.shape.rectangle] shape shape -- @propemits true false -- @see gears.shape @@ -182,7 +202,8 @@ -- -- @baseclass wibox -- @property buttons --- @tparam table buttons A table of buttons objects, or nothing. +-- @tparam[opt={}] table buttons A table of buttons objects, or nothing. +-- @tablerowtype A list of `awful.button`s. -- @propemits false false --- Get or set wibox geometry. That's the same as accessing or setting the x, @@ -242,7 +263,7 @@ -- -- @baseclass wibox -- @property bgimage --- @tparam gears.suface|string|function bgimage A background image or a function. +-- @tparam[opt=nil] image|nil bgimage -- @see gears.surface -- @propemits true false @@ -250,7 +271,7 @@ -- -- @baseclass wibox -- @property fg --- @tparam[opt=beautiful.fg_normal] gears.color fg +-- @tparam[opt=beautiful.fg_normal] color fg -- @see gears.color -- @propemits true false -- @usebeautiful beautiful.fg_normal The default (fallback) fg color. From f6370c45c33959d1fd67152e5a9743eeb732b9cc Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 063/134] docs.common.widget.ldoc: Update the property documentation. --- docs/common/widget.ldoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index 66f4a635e..1d4c21ff9 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -11,7 +11,8 @@ --- Get or set the children elements. -- @property children --- @tparam table children The children. +-- @tparam table children +-- @tablerowtype A list of `widget`s. -- @baseclass wibox.widget -- @see all_children @@ -20,7 +21,8 @@ -- Warning: This method it prone to stack overflow id the widget, or any of its -- children, contain (directly or indirectly) itself. -- @property all_children --- @tparam table all_children The children. +-- @tparam table all_children +-- @tablerowtype A list of `widget`s. -- @baseclass wibox.widget -- @see children @@ -33,7 +35,7 @@ --- Force a widget height. -- @property forced_height --- @tparam number|nil forced_height The height (`nil` for automatic) +-- @tparam number|nil forced_height -- @propertytype nil Let the layout decide the height. Usually using the widget -- native height. -- @propertytype number Enforce a number of pixels. @@ -44,7 +46,7 @@ --- Force a widget width. -- @property forced_width --- @tparam number|nil forced_width The width (`nil` for automatic) +-- @tparam number|nil forced_width -- @propertytype nil Let the layout decide the width. Usually using the widget -- native width. -- @propertytype number Enforce a number of pixels. From 6e546bcb6a087f612741aadc29a5a7702f119110 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 064/134] awful.button: Update the property documentation. --- lib/awful/button.lua | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/lib/awful/button.lua b/lib/awful/button.lua index db5ecced3..b9d506359 100644 --- a/lib/awful/button.lua +++ b/lib/awful/button.lua @@ -70,7 +70,8 @@ button.names = { -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock). -- -- @property modifiers --- @tparam table modifiers +-- @tparam[opt={}] table modifiers +-- @tablerowtype A list of modifier names in no specific order. --- The mouse button identifier. -- @@ -78,31 +79,38 @@ button.names = { -- -- @property button -- @tparam integer button +-- @propertydefault Set in the constructor. +-- @propertyunit X11 mouse button codes. +-- @negativeallowed false --- The button description. -- -- @property description --- @tparam string description +-- @tparam[opt=""] string description --- The button name. -- -- @property name --- @tparam string name +-- @tparam[opt=""] string name --- The button group. -- -- @property group --- @tparam string group +-- @tparam[opt=""] string group --- The callback when this button is pressed. -- -- @property on_press --- @tparam function on_press +-- @tparam[opt=nil] function|nil on_press +-- @functionnoparam +-- @functionnoreturn --- The callback when this button is released. -- -- @property on_release --- @tparam function on_release +-- @tparam[opt=nil] function|nil on_release +-- @functionnoparam +-- @functionnoreturn --- Execute this mousebinding. -- @method trigger @@ -239,7 +247,7 @@ local obj_mt = { -- -- @constructorfct awful.button -- @tparam table mod A list of modifier keys. Valid modifiers are: --- `Any`, `Mod1`, Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. +-- `Any`, `Mod1`, `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. -- This argument is (**mandatory**). -- @tparam number button The mouse button (it is recommended to use the -- `awful.button.names` constants. @@ -252,7 +260,7 @@ local obj_mt = { -- @constructorfct2 awful.button -- @tparam table args -- @tparam table args.modifiers A list of modifier keys. Valid modifiers are: --- `Any`, `Mod1`, Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. +-- `Any`, `Mod1`, `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. -- This argument is (**mandatory**). -- @tparam number args.button The mouse button (it is recommended to use the -- `awful.button.names` constants. From 418bf92858fe9f5502bf93728ce5c78c85a3ba1f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 065/134] awful.client: Update the property documentation. --- lib/awful/client.lua | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/lib/awful/client.lua b/lib/awful/client.lua index dbaf3bfcf..b1d5478b5 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -731,7 +731,7 @@ end --- If a client is marked or not. -- -- @property marked --- @tparam boolean marked +-- @tparam[opt=false] boolean marked -- @emits marked (for legacy reasons, use `property::marked`) -- @emits unmarker (for legacy reasons, use `property::marked`) -- @emits property::marked @@ -883,8 +883,10 @@ end --- Return if a client has a fixed size or not. -- +-- Fixed size means it cannot be resized. +-- -- @property is_fixed --- @tparam[opt=false] boolean is_fixed The fixed size state. +-- @tparam[opt=false] boolean is_fixed -- @propemits false false -- @readonly -- @see size_hints @@ -910,7 +912,7 @@ end -- `fullscreen`, `maximized`, or `maximized_horizontal`? -- -- @property immobilized_horizontal --- @tparam[opt=false] boolean immobilized_horizontal The immobilized state. +-- @tparam[opt=false] boolean immobilized_horizontal -- @readonly -- @see maximized -- @see maximized_horizontal @@ -926,7 +928,7 @@ end -- fullscreen, maximized, or vertically maximized? -- -- @property immobilized_vertical --- @tparam[opt=false] boolean immobilized_vertical The immobilized state +-- @tparam[opt=false] boolean immobilized_vertical -- @readonly -- @see maximized -- @see maximized_vertical @@ -959,7 +961,7 @@ end -- @DOC_sequences_client_floating1_EXAMPLE@ -- -- @property floating --- @tparam boolean floating The floating state. +-- @tparam[opt=false] boolean floating -- @request client border floating granted When a border update is required -- because the client focus status changed. -- @request client border active granted When a client becomes active and is not @@ -1047,7 +1049,8 @@ end -- @DOC_sequences_client_x1_EXAMPLE@ -- -- @property x --- @tparam integer x +-- @tparam[opt=c:geometry().x] integer x +-- @negativeallowed true -- @emits property::geometry -- @emitstparam property::geometry table geo The -- geometry (with `x`, `y`, `width`, `height`). @@ -1065,7 +1068,8 @@ end -- @DOC_sequences_client_y1_EXAMPLE@ -- -- @property y --- @tparam integer y +-- @tparam[opt=c:geometry().y] integer y +-- @negativeallowed true -- @emits property::geometry -- @emitstparam property::geometry table geo The -- geometry (with `x`, `y`, `width`, `height`). @@ -1079,7 +1083,8 @@ end -- @DOC_sequences_client_width1_EXAMPLE@ -- -- @property width --- @tparam integer width +-- @tparam[opt=c:geometry().width] integer width +-- @rangestart 1 -- @emits property::geometry -- @emitstparam property::geometry table geo The -- geometry (with `x`, `y`, `width`, `height`). @@ -1093,7 +1098,8 @@ end -- @DOC_sequences_client_height1_EXAMPLE@ -- -- @property height --- @tparam integer height +-- @tparam[opt=c:geometry().height] integer height +-- @rangestart 1 -- @emits property::geometry -- @emitstparam property::geometry table geo The -- geometry (with `x`, `y`, `width`, `height`). @@ -1347,7 +1353,7 @@ end -- default. -- -- @property dockable --- @tparam boolean dockable The dockable state +-- @tparam[opt=false] boolean dockable -- @propemits false false -- @see struts @@ -1386,7 +1392,7 @@ end -- interprets it as the client (not) wanting a titlebar. -- -- @property requests_no_titlebar --- @tparam boolean requests_no_titlebar Whether the client +-- @tparam[opt=false] boolean requests_no_titlebar Whether the client -- requests not to get a titlebar. -- @propemits false false @@ -1628,7 +1634,7 @@ end, true, true, "keybinding") -- @DOC_awful_client_shape1_EXAMPLE@ -- -- @property shape --- @tparam gears.shape shape A gears.shape compatible function. +-- @tparam[opt=gears.shape.rectangle] shape shape A gears.shape compatible function. -- @propemits true false -- @see gears.shape function client.object.set_shape(self, shape) @@ -1794,7 +1800,7 @@ pcommon.setup_grant(client.object, "client") -- end) -- -- @property active --- @tparam boolean active +-- @tparam[opt=true] boolean active -- @request client border active granted When a client becomes active. -- @request client border inactive granted When a client stop being active. -- @readonly From 0b902c1d693b97f0bb0ff258d41065f428f97719 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 066/134] awful.hotkeys_popup.widget: Update the property documentation. --- lib/awful/hotkeys_popup/widget.lua | 47 ++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index b6e4ec54b..20fb3d77b 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -125,8 +125,51 @@ widget.hide_without_description = true widget.merge_duplicates = true --- Labels used for displaying human-readable keynames. --- @tfield table widget.labels --- @param table +-- @tfield table awful.hotkeys_popup.widget.labels +-- @tfield[opt="Ctrl"] string Control +-- @tfield[opt="Alt"] string Mod1 +-- @tfield[opt="Alt Gr"] string ISO_Level3_Shift +-- @tfield[opt="Super"] string Mod4 +-- @tfield[opt="Ins"] string Insert +-- @tfield[opt="Del"] string Delete +-- @tfield[opt="PgDn"] string Next +-- @tfield[opt="PgUp"] string Prior +-- @tfield[opt="←"] string Left +-- @tfield[opt="↑"] string Up +-- @tfield[opt="→"] string Right +-- @tfield[opt="↓"] string Down +-- @tfield[opt="Num1"] string KP_End +-- @tfield[opt="Num2"] string KP_Down +-- @tfield[opt="Num3"] string KP_Next +-- @tfield[opt="Num4"] string KP_Left +-- @tfield[opt="Num5"] string KP_Begin +-- @tfield[opt="Num6"] string KP_Right +-- @tfield[opt="Num7"] string KP_Home +-- @tfield[opt="Num8"] string KP_Up +-- @tfield[opt="Num9"] string KP_Prior +-- @tfield[opt="Num0"] string KP_Insert +-- @tfield[opt="Num."] string KP_Delete +-- @tfield[opt="Num/"] string KP_Divide +-- @tfield[opt="Num*"] string KP_Multiply +-- @tfield[opt="Num-"] string KP_Subtract +-- @tfield[opt="Num+"] string KP_Add +-- @tfield[opt="NumEnter"] string KP_Enter +-- @tfield[opt="Esc"] string Escape +-- @tfield[opt="Tab"] string Tab +-- @tfield[opt="Space"] string space +-- @tfield[opt="Enter"] string Return +-- @tfield[opt="´"] string dead_acute +-- @tfield[opt="^"] string dead_circumflex +-- @tfield[opt="`"] string dead_grave +-- @tfield[opt="🔆+"] string XF86MonBrightnessUp +-- @tfield[opt="🔅-"] string XF86MonBrightnessDown +-- @tfield[opt="🕩+"] string XF86AudioRaiseVolume +-- @tfield[opt="🕩-"] string XF86AudioLowerVolume +-- @tfield[opt="🔇"] string XF86AudioMute +-- @tfield[opt="⏯"] string XF86AudioPlay +-- @tfield[opt="⏮"] string XF86AudioPrev +-- @tfield[opt="⏭"] string XF86AudioNext +-- @tfield[opt="⏹"] string XF86AudioStop widget.labels = { Control = "Ctrl", Mod1 = "Alt", From 530055f0240a3923da65a6b1260fbad170569a8b Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 067/134] awful.key: Update the property documentation. --- lib/awful/key.lua | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/lib/awful/key.lua b/lib/awful/key.lua index 35fff8f61..1fc4b17cc 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -44,6 +44,7 @@ local gobject = require("gears.object") -- -- @property key -- @tparam string key +-- @propertydefault Set in the constructor. --- The table of modifier keys. -- @@ -68,38 +69,43 @@ local gobject = require("gears.object") -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock). -- -- @property modifiers --- @tparam table modifiers +-- @tparam[opt={}] table modifiers +-- @tablerowtype A list of modifier names in no specific order. --- The description of the function run from a key binding. -- -- This is used, for example, by `awful.hotkeys_popup`. -- -- @property description --- @tparam string description +-- @tparam[opt=""] string description --- The key name. -- -- This can be useful when searching for keybindings by keywords. -- -- @property name --- @tparam string name +-- @tparam[opt=""] string name --- The key group bound to a function in a key binding. -- -- This is used, for example, by `awful.hotkeys_popup`. -- -- @property group --- @tparam string group +-- @tparam[opt=""] string group --- The callback when this key is pressed. -- -- @property on_press --- @tparam function on_press +-- @tparam[opt=nil] function|nil on_press +-- @functionnoparam +-- @functionnoreturn --- The callback when this key is released. -- -- @property on_release --- @tparam function on_release +-- @tparam[opt=nil] function|nil on_release +-- @functionnoparam +-- @functionnoreturn local key = { mt = {}, hotkeys = {} } From deaeb4dab84d870a828a2eaac9f3b25ffd7d7970 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 068/134] awful.keygrabber: Update the property documentation. --- lib/awful/keygrabber.lua | 43 ++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index ca5211060..f7e04e00d 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -296,7 +296,10 @@ end -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@ -- -- @property timeout --- @tparam number timeout +-- @tparam[opt=nil] number|nil timeout +-- @propertyunit second +-- @negativeallowed false +-- @propertytype nil No timeout. -- @see gears.timer -- @see timeout_callback @@ -313,26 +316,23 @@ end -- -- It can also be a table containing many keys (as values). -- --- @DOC_text_awful_keygrabber_stop_keys_EXAMPLE@ --- --- @DOC_text_awful_keygrabber_stop_key_EXAMPLE@ --- -- Please note that modkeys are not accepted as `stop_key`s. You have to use -- their corresponding key names such as `Control_L`. -- -- @property stop_key --- @tparam[opt=nil] string|table stop_key +-- @tparam[opt=nil] string|table|nil stop_key +-- @propertyunit nil No stop key. +-- @propertyunit string A single stop key. +-- @propertyunit table One or more stop key(s). +-- @tablerowtype A list of key names, such as `"Control"` or `"a"`. -- @see stop_event --- The event on which the keygrabbing will be terminated. -- --- the valid values are: --- --- * "press" (default) --- * "release" --- -- @property stop_event --- @tparam string stop_event +-- @tparam[opt="press"] string stop_event +-- @propertyvalue "press" When the keyboard key is first pressed. +-- @propertyvalue "release" When the keyboard key is released. -- @see stop_key --- Whether or not to execute the key press/release callbacks when keybindings are called. @@ -376,7 +376,8 @@ end -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@ -- -- @property root_keybindings --- @tparam table root_keybindings +-- @tparam[opt={}] table root_keybindings +-- @tablerowtype A list of `awful.key` objects. -- @see export_keybindings -- @see keybindings @@ -385,7 +386,8 @@ end -- This property contains a table of `awful.key` objects. -- -- @property keybindings --- @tparam table keybindings +-- @tparam[opt={}] table keybindings +-- @tablerowtype A list of `awful.key` objects. -- @see export_keybindings -- @see root_keybindings -- @see awful.key @@ -402,7 +404,10 @@ end -- @DOC_text_awful_keygrabber_allowed_keys_EXAMPLE@ -- -- @property allowed_keys --- @tparam[opt=nil] table|nil allowed_keys The list of keys. +-- @tparam[opt=nil] table|nil allowed_keys +-- @propertytype nil All keys are allowed. +-- @propertytype table Only some keys are allowed. +-- @tablerowtype A list of key names, such as `"Control"` or `"a"`. --- The sequence of keys recorded since the start of the keygrabber. -- @@ -415,7 +420,7 @@ end -- @DOC_text_awful_keygrabber_autostart_EXAMPLE@ -- -- @property sequence --- @tparam string sequence +-- @tparam[opt=""] string sequence -- --- The current (running) instance of this keygrabber. @@ -654,7 +659,7 @@ end -- -- @callback keypressed_callback -- @tparam table self The current transaction object. --- @tparam table mod The current modifiers (like "Control" or "Shift"). +-- @tparam table mod The current modifiers (like `"Control"` or `"Shift"`). -- @tparam string key The key name. -- @tparam string event The event ("press" or "release"). -- @usage local function my_keypressed_cb(self, mod, key, command) @@ -668,7 +673,7 @@ end -- end -- @callback keyreleased_callback -- @tparam table self The current transaction object. --- @tparam table mod The current modifiers (like "Control" or "Shift"). +-- @tparam table mod The current modifiers (like `"Control"` or `"Shift"`). -- @tparam string key The key name. -- @tparam string event The event ("press" or "release") @@ -700,7 +705,7 @@ end -- @tparam[opt=false] boolean args.export_keybindings Create root (global) keybindings. -- @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. +-- modifier keys (like `"Control"` or `"Mod4"`) events. -- @constructorfct awful.keygrabber function keygrab.run_with_keybindings(args) args = args or {} From e8a505273a382b0101551276fb0c56c47adb250a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 069/134] awful.mouse.init: Update the property documentation. --- lib/awful/mouse/init.lua | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index 9648f7ab4..b67d1f8eb 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -116,7 +116,8 @@ end, "mouse.resize") --- Get the client currently under the mouse cursor. -- @property current_client --- @tparam client|nil current_client The client +-- @tparam[opt=nil] client|nil current_client +-- @propertytype nil When the mouse cursor is not over a client. function mouse.object.get_current_client() local obj = capi.mouse.object_under_pointer() @@ -127,7 +128,8 @@ end --- Get the wibox currently under the mouse cursor. -- @property current_wibox --- @tparam wibox|nil current_wibox The wibox +-- @tparam[opt=nil] wibox|nil current_wibox +-- @propertytype nil When the mouse cursor is not over a wibox. function mouse.object.get_current_wibox() local obj = capi.mouse.object_under_pointer() @@ -139,10 +141,10 @@ end --- Get the widgets currently under the mouse cursor. -- -- @property current_widgets --- @tparam nil|table current_widgets The widget list --- @treturn table The list of widgets.The first element is the biggest --- container while the last is the topmost widget. The table contains *x*, *y*, --- *width*, *height* and *widget*. +-- @tparam[opt=nil] nil|table current_widgets +-- @tablerowtype table The list of `wibox.widget`s. The first element is the biggest +-- container while the last is the topmost widget. +-- @propertytype nil When the mouse cursor is not over any widget. function mouse.object.get_current_widgets() local w = mouse.object.get_current_wibox() @@ -164,8 +166,8 @@ end --- Get the topmost widget currently under the mouse cursor. -- @property current_widget --- @tparam widget|nil current_widget The widget --- @treturn ?widget The widget +-- @tparam[opt=nil] widget|nil current_widget +-- @propertytype nil When the mouse cursor is not over a widget. -- @see current_widget_geometry function mouse.object.get_current_widget() @@ -178,7 +180,13 @@ end --- Get the current widget geometry. -- @property current_widget_geometry --- @tparam ?table current_widget_geometry The geometry. +-- @tparam[opt=nil] table|nil current_widget_geometry +-- @tparam number current_widget_geometry.x +-- @tparam number current_widget_geometry.y +-- @tparam number current_widget_geometry.width +-- @tparam number current_widget_geometry.height +-- @propertytype nil When there is no current widgets. +-- @propertytype table -- @see current_widget function mouse.object.get_current_widget_geometry() @@ -189,7 +197,13 @@ end --- Get the current widget geometries. -- @property current_widget_geometries --- @tparam ?table current_widget_geometries A list of geometry tables. +-- @tparam[opt=nil] table|nil current_widget_geometries A list of geometry tables. +-- @propertytype nil When there is no widgets. +-- @propertytype table A list of geometry tables. +-- @tablerowkey x integer +-- @tablerowkey y integer +-- @tablerowkey width integer +-- @tablerowkey height integer -- @see current_widgets function mouse.object.get_current_widget_geometries() @@ -231,15 +245,15 @@ end --- True if the left mouse button is pressed. -- @property is_left_mouse_button_pressed --- @tparam boolean is_left_mouse_button_pressed +-- @tparam[opt=false] boolean is_left_mouse_button_pressed --- True if the right mouse button is pressed. -- @property is_right_mouse_button_pressed --- @tparam boolean is_right_mouse_button_pressed +-- @tparam[opt=false] boolean is_right_mouse_button_pressed --- True if the middle mouse button is pressed. -- @property is_middle_mouse_button_pressed --- @tparam boolean is_middle_mouse_button_pressed +-- @tparam[opt=false] boolean is_middle_mouse_button_pressed --- Add an `awful.button` based mousebinding to the global set. -- From 5909d2f155984e39431e57e6211249bd76a5196b Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 070/134] awful.popup: Update the property documentation. --- lib/awful/popup.lua | 89 ++++++++++++++++++++++++++++----------------- 1 file changed, 56 insertions(+), 33 deletions(-) diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index 9c5845891..71ca6a6a1 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -145,13 +145,6 @@ local popup = {} -- parent menu. If there is no space on the right, it tries on the left and so -- on. -- --- Valid directions are: --- --- * left --- * right --- * top --- * bottom --- -- The basic use case for this method is to give it a parent wibox: -- -- @DOC_awful_popup_position1_EXAMPLE@ @@ -162,8 +155,16 @@ local popup = {} -- @DOC_awful_popup_position2_EXAMPLE@ -- -- @property preferred_positions --- @tparam table|string preferred_positions A position name or an ordered --- table of positions +-- @tparam table|string preferred_positions +-- @propertydefault `{ "right", "left", "top", "bottom" }` +-- @propertytype string A single position with no fallback. It will be used +-- even if it doesn't fit. +-- @propertytype table A list of possible positions. The first one to fit will be +-- used. +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "top" +-- @propertyvalue "bottom" -- @see awful.placement.next_to -- @see awful.popup.preferred_anchors -- @propemits true false @@ -176,12 +177,6 @@ end --- Set the preferred popup anchors relative to the parent. -- --- The possible values are: --- --- * front --- * middle --- * back --- -- For details information, see the `awful.placement.next_to` documentation. -- -- In this example, it is possible to see the effect of having a fallback @@ -190,8 +185,14 @@ end -- @DOC_awful_popup_anchors_EXAMPLE@ -- -- @property preferred_anchors --- @tparam table|string preferred_anchors Either a single anchor name or a table +-- @tparam[opt="back"] table|string preferred_anchors -- ordered by priority. +-- @propertytype string A single anchor value with no fallback. +-- @propertytype table A list of possible anchor, the first one has the higher +-- priority, but will fallback if it doesn't fit. +-- @propertyvalue "front" +-- @propertyvalue "middle" +-- @propertyvalue "back" -- @propemits true false -- @see awful.placement.next_to -- @see awful.popup.preferred_positions @@ -210,7 +211,14 @@ end -- isn't enough space, it can also be one of the fallback. -- -- @property current_position --- @tparam string current_position Either "left", "right", "top" or "bottom" +-- @tparam string current_position +-- @propertydefault This depends on where the popup was displayed. +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "top" +-- @propertyvalue "bottom" +-- @readonly +-- @see awful.popup.preferred_positions function popup:get_current_position() return self._private.current_position @@ -224,7 +232,13 @@ end -- opposite direction from the anchor. -- -- @property current_anchor --- @tparam string current_anchor Either "front", "middle", "back" +-- @tparam string current_anchor +-- @propertydefault This depends on where the popup was displayed. +-- @propertyvalue "front" +-- @propertyvalue "middle" +-- @propertyvalue "back" +-- @readonly +-- @see awful.popup.preferred_anchors function popup:get_current_anchor() return self._private.current_anchor @@ -275,7 +289,8 @@ function popup:bind_to_widget(widget, button) end --- Unbind the popup from a widget button. --- @tparam widget widget The widget +-- @tparam widget widget +-- @propertytype widget A widget or declarative widget construct. -- @method unbind_to_widget -- @noreturn function popup:unbind_to_widget(widget) @@ -298,25 +313,33 @@ end --- The popup minimum width. -- -- @property minimum_width --- @tparam[opt=1] number minimum_width The minimum width. +-- @tparam[opt=1] integer minimum_width +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup minimum height. -- -- @property minimum_height --- @tparam[opt=1] number minimum_height The minimum height. +-- @tparam[opt=1] integer minimum_height +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup maximum width. -- -- @property maximum_width --- @tparam[opt=1] number maximum_width The maximum width. +-- @tparam[opt=1] integer maximum_width +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup maximum height. -- -- @property maximum_height --- @tparam[opt=1] number maximum_height The maximum height. +-- @tparam[opt=1] integer maximum_height +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false for _, orientation in ipairs {"_width", "_height"} do @@ -340,9 +363,13 @@ end -- -- @DOC_awful_popup_position3_EXAMPLE@ -- @property offset --- @tparam table|integer offset An integer value or a `{x=, y=}` table. --- @tparam[opt=offset] integer offset.x The horizontal distance. --- @tparam[opt=offset] integer offset.y The vertical distance. +-- @tparam[opt=0] table|integer offset +-- @tparam[opt=0] integer offset.x The horizontal offset. +-- @tparam[opt=0] integer offset.y The vertical offset. +-- @propertytype integer A value for both `x` and `y` simultaneously. +-- @propertytype table Specify values for `x` and `y` individually. +-- @negativeallowed true +-- @propertyunit pixel -- @propemits true false function popup:set_offset(offset) @@ -369,10 +396,10 @@ end --- Set the placement function. -- --- (or false to disable placement) --- -- @property placement --- @tparam[opt=awful.placement.next_to] function|string|boolean placement The placement function or name +-- @tparam[opt=awful.placement.next_to] placement|string|boolean placement +-- @propertytype boolean Use `false` to disable automatic placement. +-- @propertytype string The name of an `awful.placement` function, like `"next_to"`. -- @propemits true false -- @see awful.placement @@ -496,8 +523,4 @@ local function create_popup(_, args) return w end ---@DOC_wibox_COMMON@ - ---@DOC_object_COMMON@ - return setmetatable(module, {__call = create_popup}) From 6d31e783dfa1dcc1135700f2c2c833ee817c0b28 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 071/134] awful.screen: Update the property documentation. --- lib/awful/screen.lua | 99 +++++++++++++++++++++++++++++--------------- 1 file changed, 66 insertions(+), 33 deletions(-) diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index e73128624..e846cda61 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -198,6 +198,8 @@ end -- @tparam number tiling_area.y -- @tparam number tiling_area.width -- @tparam number tiling_area.height +-- @propertydefault This is the `workarea` substracted with the `padding` area. +-- @propertyunit pixel -- @readonly -- @see padding -- @see get_bounding_geometry @@ -214,8 +216,13 @@ end -- Reading this property returns a screenshot of the physical -- (Xinerama) screen as a cairo surface. -- +-- Use `gears.surface(c.content)` to convert the raw content into a static image. +-- -- @property content --- @tparam gears.surface content +-- @tparam raw_surface content +-- @propertydefault The client raw pixels at the time the property is called. +-- If there is no compositing manager running, it might be black. +-- @see gears.surface -- @readonly function screen.object.get_content(s) @@ -251,18 +258,19 @@ end -- -- This adds a "buffer" section on each side of the screen. -- --- **Signal:** --- --- * *property::padding* --- -- @DOC_screen_padding_EXAMPLE@ -- -- @property padding --- @tparam table padding --- @tfield integer table.left The padding on the left. --- @tfield integer table.right The padding on the right. --- @tfield integer table.top The padding on the top. --- @tfield integer table.bottom The padding on the bottom. +-- @tparam[opt=0] table|number padding +-- @tparam[opt=0] integer padding.left The padding on the left. +-- @tparam[opt=0] integer padding.right The padding on the right. +-- @tparam[opt=0] integer padding.top The padding on the top. +-- @tparam[opt=0] integer padding.bottom The padding on the bottom. +-- @negativeallowed false +-- @propertyunit pixel +-- @propertytype number A single value for each sides. +-- @propertytype table A different value for each sides. +-- @propemits true false -- @usebeautiful beautiful.maximized_honor_padding Honor the screen padding when maximizing. function screen.object.get_padding(self) @@ -304,18 +312,18 @@ end -- -- do something -- end -- --- **Signal:** --- --- * *property::outputs* --- -- @property outputs -- @tparam table outputs --- @tfield table table.name A table with the screen name as key (like `eDP1` on a laptop) --- @tfield integer table.mm_width The screen physical width. --- @tfield integer table.mm_height The screen physical height. --- @tfield integer table.name The output name. --- @tfield integer table.viewport_id The identifier of the viewport this output +-- @tablerowtype A key-value table with the output name as key and a table of +-- metadata as value. +-- @tablerowkey integer mm_width The screen physical width. +-- @tablerowkey integer mm_height The screen physical height. +-- @tablerowkey string name The output name. +-- @tablerowkey string viewport_id The identifier of the viewport this output -- corresponds to. +-- @propertydefault This may or may not be populated if the screen are based on +-- an actual physical screen. For fake screen, this property content is undefined. +-- @propemits true false -- @readonly function screen.object.get_outputs(s) @@ -444,7 +452,8 @@ end -- default. -- -- @property clients --- @tparam table clients The clients list, ordered from top to bottom. +-- @tparam[opt={}] table clients The clients list, ordered from top to bottom. +-- @tablerowtype A list of `client` objects. -- @see all_clients -- @see hidden_clients -- @see client.get @@ -472,7 +481,8 @@ end -- This includes minimized clients and clients on hidden tags. -- -- @property hidden_clients --- @tparam table hidden_clients The clients list, ordered from top to bottom. +-- @tparam[opt={}] table hidden_clients The clients list, ordered from top to bottom. +-- @tablerowtype A list of `client` objects. -- @see clients -- @see all_clients -- @see client.get @@ -491,7 +501,8 @@ end --- All clients assigned to the screen. -- -- @property all_clients --- @tparam table all_clients The clients list, ordered from top to bottom. +-- @tparam[opt={}] table all_clients The clients list, ordered from top to bottom. +-- @tablerowtype A list of `client` objects. -- @see clients -- @see hidden_clients -- @see client.get @@ -518,7 +529,8 @@ end -- @DOC_screen_tiled_clients_EXAMPLE@ -- -- @property tiled_clients --- @tparam table tiled_clients The clients list, ordered from top to bottom. +-- @tparam[opt={}] table tiled_clients The clients list, ordered from top to bottom. +-- @tablerowtype A list of `client` objects. --- Get tiled clients for the screen. -- @@ -568,8 +580,8 @@ end -- `awful.tag.new` or `t:delete()` to alter this list. -- -- @property tags --- @tparam table tags --- @treturn table A table with all available tags. +-- @tparam[opt={}] table tags +-- @tablerowtype A table with all available tags. -- @readonly function screen.object.get_tags(s, unordered) @@ -592,8 +604,8 @@ end --- A list of all selected tags on the screen. -- @property selected_tags --- @tparam table selected_tags --- @treturn table A table with all selected tags. +-- @tparam[opt={}] table selected_tags +-- @tablerowtype A table with all selected tags. -- @readonly -- @see tag.selected -- @see client.to_selected_tags @@ -612,8 +624,7 @@ end --- The first selected tag. -- @property selected_tag --- @tparam tag selected_tag --- @treturn ?tag The first selected tag or nil. +-- @tparam[opt=nil] tag|nil selected_tag -- @readonly -- @see tag.selected -- @see selected_tags @@ -765,16 +776,24 @@ end -- screen is duplicated on a projector). -- -- @property dpi --- @tparam number dpi The DPI value. +-- @tparam[opt=96] number dpi +-- @propertyunit pixel\_per\_inch +-- @negativeallowed false --- The lowest density DPI from all of the (physical) outputs. -- @property minimum_dpi --- @tparam number minimum_dpi The DPI value. +-- @tparam number minimum_dpi +-- @propertyunit pixel\_per\_inch +-- @propertydefault This is extracted from `outputs`. +-- @negativeallowed false -- @readonly --- The highest density DPI from all of the (physical) outputs. -- @property maximum_dpi --- @tparam number maximum_dpi The DPI value. +-- @tparam number maximum_dpi +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit pixel\_per\_inch +-- @negativeallowed false -- @readonly --- The preferred DPI from all of the (physical) outputs. @@ -783,28 +802,42 @@ end -- the lowest of the resulting virtual DPIs. -- -- @property preferred_dpi --- @tparam number preferred_dpi The DPI value. +-- @tparam number preferred_dpi +-- @propertydefault This is extracted from `outputs`. +-- @negativeallowed false -- @readonly --- The maximum diagonal size in millimeters. -- -- @property mm_maximum_size -- @tparam number mm_maximum_size +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit millimeter +-- @negativeallowed false --- The minimum diagonal size in millimeters. -- -- @property mm_minimum_size -- @tparam number mm_minimum_size +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit millimeter +-- @negativeallowed false --- The maximum diagonal size in inches. -- -- @property inch_maximum_size -- @tparam number inch_maximum_size +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit inch +-- @negativeallowed false --- The minimum diagonal size in inches. -- -- @property inch_minimum_size -- @tparam number inch_minimum_size +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit inch +-- @negativeallowed false --- Emitted when a new screen is added. -- From 91de26870341a49cba9517827637cda88d6da89f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 072/134] awful.tag: Update the property documentation. --- lib/awful/tag.lua | 68 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 14 deletions(-) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 2ceadb4d4..662ecfacd 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -149,6 +149,8 @@ end -- -- @property index -- @tparam integer index +-- @propertydefault This is based on the current list of `t.screen:tags()`. +-- @negativeallowed false -- @propemits false false function tag.object.set_index(self, idx) @@ -598,7 +600,7 @@ end --- The tag screen. -- -- @property screen --- @tparam screen screen +-- @tparam[opt=awful.screen.focused()] screen screen -- @propemits false false -- @see screen @@ -718,7 +720,9 @@ end -- @DOC_screen_mwfact2_EXAMPLE@ -- -- @property master_width_factor --- @tparam[opt=beautiful.master_width_factor] number master_width_factor Between 0 and 1 +-- @tparam[opt=beautiful.master_width_factor] number master_width_factor +-- @rangestart 0.0 +-- @rangestop 1.0 -- @emits property::mwfact When the value changes (deprecated). -- @emits property::master_width_factor When the value changes. -- @see master_count @@ -827,6 +831,34 @@ end -- placed. The only parameter is a table or arguments returned by -- `awful.layout.parameters` -- +-- The parameter table contains: +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +--
        Parameter TypeDescription
        `workarea` table +-- A table with `x`,`y`, `width` and `height` keys.
        +-- All clients must be placed within this area. +--
        `geometry` table A table with the screen geometry.
        `clients` table A list of the clients to place.
        `screen` screen The screen.
        `padding` table +-- A table with `left`, `right`, `top` and `bottom` keys. +--
        `useless_gap` integer The space that will be removed from the clients.
        `geometries` table +-- Empty. Place the client as key and preferred geometry
        +-- as value. Do not call `:geometry()` directly. +--
        +-- -- **Stateful layouts:** -- -- The stateful layouts API is the same as stateless, but they are a function @@ -843,9 +875,13 @@ end -- -- @property layout -- @tparam layout|function layout A layout table or a constructor function +-- @propertydefault The first non-nil value of either `self.layouts[1]` or +-- `awful.layout.layouts[1]` or `awful.layout.suit.floating`. +-- @functionparam table params A table containing the state of the layout (see the table above). +-- @functionnoreturn -- @propemits false false -- @see awful.tag.layouts --- @return The layout +-- @see awful.layout.parameters --- The (proposed) list of available layouts for this tag. -- @@ -859,10 +895,13 @@ end -- front of the list. -- -- @property layouts --- @tparam table layouts +-- @tparam[opt=nil] table|nil layouts +-- @propertytype nil Use the current value of `awful.layout.layouts`. -- @request tag layouts awful granted When the `layouts` property is first called -- and there is no layouts, then that signal is called. -- @see awful.layout.layouts +-- @see screen.workarea +-- @see screen.padding -- @see layout function tag.object.set_layout(t, layout) @@ -1053,7 +1092,7 @@ end -- the "Non-volatile" tag is still there (but with zero clients). -- -- @property volatile --- @tparam boolean volatile +-- @tparam[opt=false] boolean volatile -- @propemits false false -- @see delete @@ -1102,7 +1141,9 @@ end -- @DOC_screen_gaps2_EXAMPLE@ -- -- @property gap --- @tparam[opt=beautiful.useless_gap] number gap The value has to be greater than zero. +-- @tparam[opt=beautiful.useless_gap] integer gap The value has to be greater than zero. +-- @propertyunit pixel +-- @negativeallowed false -- @emits property::useless_gap When the gap changes. -- @see gap_single_client -- @see awful.tag.incgap @@ -1219,12 +1260,6 @@ end -- Some multi-column layouts can be configured so that the space is -- redistributed when there is not enough clients to fill all columns. -- --- ** Possible values**: --- --- * *expand*: Take all the space --- * *master\_width\_factor*: Only take the ratio defined by the --- `master_width_factor` --- -- This is the default behavior of the `tile.left` layout (*expand*): -- -- @DOC_screen_mfpol2_EXAMPLE@ @@ -1237,7 +1272,10 @@ end -- redistributed on both side. -- -- @property master_fill_policy --- @tparam[opt=beautiful.master_fill_policy] string master_fill_policy "expand" or "master\_width\_factor" +-- @tparam[opt=beautiful.master_fill_policy] string master_fill_policy +-- @propertyvalue "expand" Take all the space +-- @propertyvalue "master_width_factor" Only take the ratio defined by the +-- `master_width_factor` -- @propemits false false -- @see awful.tag.togglemfpol @@ -1306,6 +1344,7 @@ end -- -- @property master_count -- @tparam[opt=beautiful.master_count] integer master_count Only positive values are accepted +-- @rangestart 1 -- @emits property::nmaster Deprecated. -- @emits property::master_count When the value changes. -- @see awful.tag.incnmaster @@ -1380,7 +1419,7 @@ end -- @DOC_wibox_awidget_taglist_icon_EXAMPLE@ -- -- @property icon --- @tparam path|surface icon The icon +-- @tparam[opt=nil] image|nil icon -- @propemits false false -- @see awful.widget.taglist -- @see gears.surface @@ -1422,6 +1461,7 @@ end -- -- @property column_count -- @tparam[opt=beautiful.column_count or 1] integer column_count Has to be greater than 1 +-- @rangestart 1 -- @emits property::ncol Deprecated. -- @emits property::column_count When the value changes. -- @see awful.tag.incncol From 9d04ba72f970e239af1cf76bbcb5f3f781dc20ca Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 073/134] awful.tooltip: Update the property documentation. --- lib/awful/tooltip.lua | 106 ++++++++++++++++++++++++------------------ 1 file changed, 62 insertions(+), 44 deletions(-) diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index 3c6a8a14c..2dfe67d35 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -207,6 +207,7 @@ end --- The wibox containing the tooltip widgets. -- @property wibox -- @tparam wibox wibox +-- @propertydefault Autogenerated. function tooltip:get_wibox() if self._private.wibox then @@ -257,23 +258,20 @@ end -- -- @DOC_awful_tooltip_align2_EXAMPLE@ -- --- The following values are valid: --- --- * top_left --- * left --- * bottom_left --- * right --- * top_right --- * bottom_right --- * bottom --- * top --- -- @property align --- @tparam string align --- @see mode --- @see preferred_positions +-- @tparam[opt="right"] string|nil align +-- @propertyvalue "top_left" +-- @propertyvalue "left" +-- @propertyvalue "bottom_left" +-- @propertyvalue "right" +-- @propertyvalue "top_right" +-- @propertyvalue "bottom_right" +-- @propertyvalue "bottom" +-- @propertyvalue "top" -- @propemits true false -- @propbeautiful +-- @see mode +-- @see preferred_positions --- The default tooltip alignment. -- @beautiful beautiful.tooltip_align @@ -300,7 +298,7 @@ end -- @DOC_awful_tooltip_shape_EXAMPLE@ -- -- @property shape --- @tparam gears.shape shape +-- @tparam[opt=gears.shape.rectangle] shap|nil shape -- @see gears.shape -- @propemits true false -- @propbeautiful @@ -324,13 +322,10 @@ end -- -- @DOC_awful_tooltip_mode2_EXAMPLE@ -- --- Valid modes are: --- --- * "mouse": Next to the mouse cursor --- * "outside": Outside of the widget --- -- @property mode --- @tparam string mode +-- @tparam[opt="mouse"] string mode +-- @propertyvalue "mouse" Next to the mouse cursor. +-- @propertyvalue "outside" Outside of the widget. -- @propemits true false function tooltip:set_mode(mode) @@ -358,12 +353,10 @@ end -- * "left" -- * "bottom" -- --- The default is: --- --- {"top", "right", "left", "bottom"} --- -- @property preferred_positions -- @tparam table preferred_positions The position, ordered by priorities +-- @propertydefault `{"top", "right", "left", "bottom"}` +-- @tablerowtype A list of strings. -- @propemits true false -- @see align -- @see mode @@ -401,16 +394,14 @@ end -- -- The valid table values are: -- --- * front --- * middle --- * back --- --- The default is: --- --- {"front", "back", "middle"} +-- * "front" +-- * "middle" +-- * "back" -- -- @property preferred_alignments --- @tparam string preferred_alignments +-- @tparam table preferred_alignments +-- @tablerowtype A list of strings. +-- @propertydefault `{"front", "back", "middle"}` -- @propemits true false -- @see preferred_positions @@ -430,7 +421,7 @@ end --- Change displayed text. -- -- @property text --- @tparam string text New tooltip text, passed to +-- @tparam[opt=""] string text New tooltip text, passed to -- `wibox.widget.textbox.set_text`. -- @propemits true false -- @see wibox.widget.textbox @@ -447,7 +438,7 @@ end --- Change displayed markup. -- -- @property markup --- @tparam string markup New tooltip markup, passed to +-- @tparam[opt=""] string markup New tooltip markup, passed to -- `wibox.widget.textbox.set_markup`. -- @propemits true false -- @see wibox.widget.textbox @@ -464,7 +455,9 @@ end --- Change the tooltip's update interval. -- -- @property timeout --- @tparam number timeout The timeout value. +-- @tparam[opt=1] number timeout +-- @negativeallowed false +-- @propertyunit second -- @propemits true false function tooltip:set_timeout(timeout) @@ -479,7 +472,15 @@ end -- @DOC_awful_tooltip_margins_EXAMPLE@ -- -- @property margins --- @tparam number|table margins New margins value. +-- @tparam[opt=0] number|table margins +-- @tparam[opt=0] number margins.top +-- @tparam[opt=0] number margins.bottom +-- @tparam[opt=0] number margins.left +-- @tparam[opt=0] number margins.right +-- @negativeallowed true +-- @propertyunit pixel +-- @propertytype number A single value for each sides. +-- @propertytype table A different value for each side. -- @propemits true false function tooltip:set_margins(val) @@ -492,7 +493,9 @@ end -- @DOC_awful_tooltip_border_width_EXAMPLE@ -- -- @property border_width --- @tparam[opt=0] number border_width +-- @tparam[opt=0] number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @propbeautiful @@ -507,7 +510,7 @@ end -- -- @property border_color -- @tparam[opt=beautiful.tooltip_border_color or beautiful.border_color_normal or beautiful.fg_normal] --- gears.color border_color +-- color|nil border_color -- @propemits true false -- @propbeautiful @@ -521,8 +524,12 @@ end -- @DOC_awful_tooltip_margins_leftright_EXAMPLE@ -- -- @property margins_leftright --- @tparam number margins_leftright New margins value. +-- @tparam[opt=0] number margins_leftright +-- @negativeallowed true +-- @propertyunit pixel -- @propemits true false +-- @see margins +-- @see margins_topbottom function tooltip:set_margin_leftright(val) self.marginbox:set_left(val) @@ -540,8 +547,12 @@ end -- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@ -- -- @property margins_topbottom --- @tparam number margins_topbottom New margins value. +-- @tparam[opt=0] number margins_topbottom +-- @negativeallowed true +-- @propertyunit pixel -- @propemits true false +-- @see margins +-- @see margins_leftright function tooltip:set_margin_topbottom(val) self.marginbox:set_top(val) @@ -559,8 +570,17 @@ end -- @DOC_awful_tooltip_gaps_EXAMPLE@ -- -- @property gaps --- @tparam number|table gaps New margins value. +-- @tparam[opt=0] number|table|nil gaps +-- @tparam[opt=0] number gaps.top +-- @tparam[opt=0] number gaps.bottom +-- @tparam[opt=0] number gaps.left +-- @tparam[opt=0] number gaps.right +-- @negativeallowed true +-- @propertytype number A single value for each sides. +-- @propertytype table A different value for each side. +-- @propertyunit pixel -- @propemits true false +-- @propbeautiful function tooltip:set_gaps(val) self._private.gaps = val @@ -572,7 +592,6 @@ end --- Add tooltip to an object. -- --- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. -- @noreturn @@ -586,7 +605,6 @@ end --- Remove tooltip from an object. -- --- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. -- @noreturn From b5a9250a58323e29a42554fe33efa298294683ee Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 074/134] awful.wallpaper: Update the property documentation. --- lib/awful/wallpaper.lua | 42 ++++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/lib/awful/wallpaper.lua b/lib/awful/wallpaper.lua index 0a8340558..285bc8c01 100644 --- a/lib/awful/wallpaper.lua +++ b/lib/awful/wallpaper.lua @@ -329,7 +329,6 @@ local function paint() cr:rectangle(area.x, area.y, area.width, area.height) cr:fill() end - end if not wall._private.container then @@ -413,7 +412,7 @@ end) -- wallpaper will be defined as a normal `wibox` widget tree. -- -- @property widget --- @tparam wibox.widget widget +-- @tparam[opt=nil] widget|nil widget -- @see wibox.widget.imagebox -- @see wibox.container.tile @@ -434,7 +433,9 @@ end) -- @DOC_awful_wallpaper_dpi1_EXAMPLE@ -- -- @property dpi --- @tparam[opt=screen.dpi] number dpi +-- @tparam[opt=self.screen.dpi] number dpi +-- @propertyunit pixel\_per\_inch +-- @negativeallowed false -- @see screen -- @see screen.dpi @@ -445,6 +446,7 @@ end) -- -- @property screen -- @tparam screen screen +-- @propertydefault Obtained from the constructor. -- @see screens -- @see add_screen -- @see remove_screen @@ -455,7 +457,8 @@ end) -- -- Some large wallpaper are made to span multiple screens. -- @property screens --- @tparam table screens +-- @tparam[opt={self.screen}] table screens +-- @tablerowtype A list of `screen` objects. -- @see screen -- @see add_screen -- @see remove_screen @@ -464,12 +467,12 @@ end) --- The background color. -- -- It will be used as the "fill" color if the `image` doesn't take all the --- screen space. It will also be the default background for the `widget. +-- screen space. It will also be the default background for the `widget`. -- -- As usual with colors in `AwesomeWM`, it can also be a gradient or a pattern. -- -- @property bg --- @tparam gears.color bg +-- @tparam[opt=beautiful.wallpaper_bg] color bg -- @usebeautiful beautiful.wallpaper_bg -- @see gears.color @@ -480,12 +483,12 @@ end) -- As usual with colors in `AwesomeWM`, it can also be a gradient or a pattern. -- -- @property fg --- @tparam gears.color fg +-- @tparam[opt=beautiful.wallpaper_fg] color fg -- @see gears.color --- The default wallpaper background color. -- @beautiful beautiful.wallpaper_bg --- @tparam gears.color wallpaper_bg +-- @tparam color wallpaper_bg -- @usebeautiful beautiful.wallpaper_fg -- @see bg @@ -521,18 +524,23 @@ end) -- @DOC_awful_wallpaper_padding1_EXAMPLE@ -- -- @property honor_padding --- @tparam boolean honor_padding +-- @tparam[opt=false] boolean honor_padding -- @see honor_workarea -- @see uncovered_areas --- Returns the list of screen(s) area which won't be covered by the wallpaper. -- -- When `honor_workarea`, `honor_padding` or panning are used, some section of --- the screen won't have a wallpaper. This returns a list of areas tables. Each --- table has a `x`, `y`, `width` and `height` key. +-- the screen won't have a wallpaper. -- -- @property uncovered_areas -- @tparam table uncovered_areas +-- @propertydefault This depends on the `honor_workarea` and `honor_padding` values. +-- @tablerowtype A list of area tables with the following keys: +-- @tablerowkey number x +-- @tablerowkey number y +-- @tablerowkey number width +-- @tablerowkey number height -- @see honor_workarea -- @see honor_padding -- @see uncovered_areas_color @@ -547,7 +555,7 @@ end) -- color or a gradient. -- -- @property uncovered_areas_color --- @tparam gears.color uncovered_areas_color +-- @tparam[opt="transparent"] color uncovered_areas_color -- @see uncovered_areas --- Defines where the wallpaper is placed when there is multiple screens. @@ -592,7 +600,15 @@ end) -- @DOC_awful_wallpaper_panning_custom_EXAMPLE@ -- -- @property panning_area --- @tparam function|string panning_area +-- @tparam[opt="outer"] function|string panning_area +-- @propertytype string A panning algorithm +-- @propertyvalue "outer" +-- @propertyvalue "inner" +-- @propertyvalue "inner_horizontal" +-- @propertyvalue "inner_vertical" +-- @propertytype function Custom panning function. +-- @functionparam awful.wallpaper wallpaper The wallpaper object. +-- @functionreturn A table with `x`, `y`, `width` and `height` keys, -- @see uncovered_areas function module:set_panning_area(value) From bd07d49197940106c933267994901ce14eeb48b3 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 075/134] awful.wibar: Update the property documentation. --- lib/awful/wibar.lua | 45 ++++++++++++++++++++++----------------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index 2a35b03a2..470868d9b 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -62,25 +62,22 @@ local align_map = { -- @DOC_awful_wibar_stretch_EXAMPLE@ -- -- @property stretch --- @tparam boolean stretch +-- @tparam[opt=true] boolean|nil stretch -- @propbeautiful -- @propemits true false -- @see align --- How to align non-stretched wibars. -- --- Values are: --- --- * `"top"` --- * `"bottom"` --- * `"left"` --- * `"right"` --- * `"centered"` --- -- @DOC_awful_wibar_align_EXAMPLE@ -- -- @property align --- @tparam string align +-- @tparam[opt="centered"] string|nil align +-- @propertyvalue "top" +-- @propertyvalue "bottom" +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "centered" -- @propbeautiful -- @propemits true false -- @see stretch @@ -93,7 +90,16 @@ local align_map = { -- @DOC_awful_wibar_margins_EXAMPLE@ -- -- @property margins --- @tparam number|table margins +-- @tparam[opt=0] number|table|nil margins +-- @tparam[opt=0] number margins.left +-- @tparam[opt=0] number margins.right +-- @tparam[opt=0] number margins.top +-- @tparam[opt=0] number margins.bottom +-- @negativeallowed true +-- @propertytype number A single value for each side. +-- @propertytype table A different value for each side. +-- @propertytype nil Fallback to `beautiful.wibar_margins`. +-- @propertyunit pixel -- @propbeautiful -- @propemits true false @@ -281,17 +287,14 @@ end --- The wibox position. -- --- The valid values are: --- --- * left --- * right --- * top --- * bottom --- -- @DOC_awful_wibar_position_EXAMPLE@ -- -- @property position --- @tparam string position Either "left", right", "top" or "bottom" +-- @tparam[opt="top"] string position +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "top" +-- @propertyvalue "bottom" -- @propemits true false function awfulwibar.get_position(wb) @@ -672,10 +675,6 @@ function awfulwibar.mt:__index(_, k) end end ---@DOC_wibox_COMMON@ - ---@DOC_object_COMMON@ - return setmetatable(awfulwibar, awfulwibar.mt) -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 From 176526a8d21ea2988e2c6c4ae70c62e58e11aea4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 076/134] awful.widget.clienticon: Update the property documentation. --- lib/awful/widget/clienticon.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/awful/widget/clienticon.lua b/lib/awful/widget/clienticon.lua index a3151899b..3076256fa 100644 --- a/lib/awful/widget/clienticon.lua +++ b/lib/awful/widget/clienticon.lua @@ -86,7 +86,7 @@ end --- The widget's @{client}. -- -- @property client --- @tparam client client +-- @tparam[opt=nil] client|nil client -- @propemits true false function clienticon:get_client() From 72041d63a4d86b38715174d6ab6fb3e73d474174 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 077/134] awful.widget.keyboardlayout: Update the property documentation. --- lib/awful/widget/keyboardlayout.lua | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index 781646dfb..486259901 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -5,6 +5,7 @@ -- @author Aleksey Fedotov <lexa@cfotr.com> -- @copyright 2015 Aleksey Fedotov -- @widgetmod awful.widget.keyboardlayout +-- @supermodule wibox.widget.base --------------------------------------------------------------------------- local capi = {awesome = awesome} @@ -317,9 +318,6 @@ function keyboardlayout.mt:__call(...) return _instance end ---@DOC_widget_COMMON@ - ---@DOC_object_COMMON@ return setmetatable(keyboardlayout, keyboardlayout.mt) From 0e5a62950ebe3661c29323d9197bfe2115dcc21d Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 078/134] awful.widget.layoutbox: Update the property documentation. --- lib/awful/widget/layoutbox.lua | 4 ---- 1 file changed, 4 deletions(-) diff --git a/lib/awful/widget/layoutbox.lua b/lib/awful/widget/layoutbox.lua index b6a68d319..a25a74c46 100644 --- a/lib/awful/widget/layoutbox.lua +++ b/lib/awful/widget/layoutbox.lua @@ -115,10 +115,6 @@ function layoutbox.mt:__call(...) return layoutbox.new(...) end ---@DOC_widget_COMMON@ - ---@DOC_object_COMMON@ - return setmetatable(layoutbox, layoutbox.mt) -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 From 4c4d833a694582ed96f06e5af2acf546a4b69ccd Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 079/134] awful.widget.layoutlist: Update the property documentation. --- lib/awful/widget/layoutlist.lua | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index ba44437b9..c3abbb618 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -190,23 +190,22 @@ local layoutlist = {} --- The delegate widget template. -- -- @property widget_template --- @tparam[opt=nil] table widget_template +-- @tparam[opt=nil] template|nil widget_template -- @propemits true false --- The layoutlist screen. -- -- @property screen -- @tparam screen screen +-- @propertydefault Obtained from the constructor. --- A function that returns the list of layout to display. -- -- @property source -- @tparam[opt=awful.widget.layoutlist.source.for_screen] function source - ---- The layoutlist filter function. --- --- @property filter --- @tparam[opt=awful.widget.layoutlist.source.for_screen] function filter +-- @functionparam screen s The layoutlist screen. +-- @functionparam table metadata Various metadata. +-- @functionreturn table The list of layouts. --- The default foreground (text) color. -- @@ -281,17 +280,21 @@ local layoutlist = {} --- The currenly displayed layouts. -- @property layouts --- @tparam table layouts +-- @tparam[opt={}] table layouts +-- @tablerowtype A list of `awful.layout.suit`. --- The currently selected layout. -- @property current_layout --- @tparam layout current_layout +-- @tparam[opt=nil] layout|nil current_layout +-- @readonly --- The current number of layouts. -- -- @property count -- @readonly -- @tparam number count The number of layouts. +-- @propertydefault This current number of layouts. +-- @negativeallowed false -- @propemits true false function layoutlist:get_layouts() From 60b52ab4c3828b22b115ac7c0e1c11fe3bdf1c75 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 080/134] awful.widget.only_on_screen: Update the property documentation. --- lib/awful/widget/only_on_screen.lua | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua index 3dfa0519a..0cbabfde0 100644 --- a/lib/awful/widget/only_on_screen.lua +++ b/lib/awful/widget/only_on_screen.lua @@ -50,7 +50,7 @@ end --- The widget to be displayed -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget only_on_screen.set_widget = base.set_widget_common @@ -66,10 +66,11 @@ function only_on_screen:set_children(children) self:set_widget(children[1]) end ---- The screen to display on. Can be a screen object, a screen index, a screen +--- The screen to display on. +-- Can be a screen object, a screen index, a screen -- name ("VGA1") or the string "primary" for the primary screen. -- @property screen --- @tparam screen|string|integer screen The screen. +-- @tparam[opt="primary"] screen screen function only_on_screen:set_screen(s) self._private.screen = s @@ -83,8 +84,8 @@ end --- Returns a new `awful.widget.only_on_screen` container. -- This widget makes some other widget visible on just some screens. Use -- `:set_widget()` to set the widget and `:set_screen()` to set the screen. --- @param[opt] widget The widget to display. --- @param[opt] s The screen to display on. +-- @tparam[opt=nil] widget widget The widget to display. +-- @tparam[opt="primary"] screen s The screen to display on. -- @treturn table A new only_on_screen container -- @constructorfct awful.widget.only_on_screen local function new(widget, s) From a96ad1b76627516729ea4986a1a1fa6f770915e4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 081/134] awful.widget.taglist: Update the property documentation. --- lib/awful/widget/taglist.lua | 44 ++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index 9894c35b9..aeb6513ec 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -35,6 +35,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou -- @widgetmod awful.widget.taglist +-- @supermodule wibox.widget.base --------------------------------------------------------------------------- -- Grab environment we need @@ -419,6 +420,7 @@ end --- The taglist screen. -- -- @property screen +-- @propertydefault Obtained from the constructor. -- @tparam screen screen --- Set the taglist layout. @@ -429,9 +431,15 @@ end --- The current number of tags. -- +-- Note that the `tasklist` is usually lazy-loaded. Reading this property +-- may cause the widgets to be created. Depending on where the property is called +-- from, it might, in theory, cause an infinite loop. +-- -- @property count -- @readonly -- @tparam number count The number of tags. +-- @propertydefault This current number of tags. +-- @negativeallowed false -- @propemits true false function taglist:set_base_layout(layout) @@ -483,11 +491,21 @@ end -- -- @property update_function -- @tparam function update_function +-- @propertydefault The default function delegate everything to the `widget_template`. +-- @functionparam widget layout The base layout object. +-- @functionparam table buttons The buttons for this tag entry (see below). +-- @functionparam string label The tag name. +-- @functionparam table data Arbitrary metadate. +-- @functionparam table tags The list of tags (ordered). +-- @functionparam table metadata Other values. +-- @functionnoreturn --- A function to restrict the content of the taglist. -- -- @property filter --- @tparam function filter +-- @tparam[opt=nil] function|nil filter +-- @functionparam tag t The tag to accept or reject. +-- @functionreturn boolean `true` if the tag is accepter or `false` if it is rejected. -- @see source -- @see awful.widget.taglist.filter.noempty -- @see awful.widget.taglist.filter.selected @@ -497,14 +515,17 @@ end --- The function used to gather the group of tags. -- -- @property source --- @tparam function source +-- @tparam[opt=awful.widget.taglist.source.for_screen] function source +-- @functionparam screen s The taglist screen. +-- @functionparam table metadata Various metadata. +-- @functionreturn table The list of tags -- @see filter -- @see awful.widget.taglist.source.for_screen --- A templete used to genetate the individual tag widgets. -- -- @property widget_template --- @tparam table widget_template +-- @tparam[opt=nil] template|nil widget_template for _, prop in ipairs { "filter", "update_function", "widget_template", "source", "screen" } do taglist["set_"..prop] = function(self, value) @@ -560,11 +581,16 @@ end -- @tparam[opt=beautiful.taglist_disable_icon] string args.style.disable_icon -- @tparam[opt=beautiful.taglist_font] string args.style.font -- @tparam[opt=beautiful.taglist_spacing] number args.style.spacing The spacing between tags. --- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel A user provided image for selected squares. --- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel A user provided image for unselected squares. --- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty A user provided image for selected squares for empty tags. --- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags. --- @tparam[opt=beautiful.taglist_squares_resize] boolean args.style.squares_resize True or false to resize squares. +-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel A user +-- provided image for selected squares. +-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel A +-- user provided image for unselected squares. +-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty A +-- user provided image for selected squares for empty tags. +-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty A +-- user provided image for unselected squares for empty tags. +-- @tparam[opt=beautiful.taglist_squares_resize] boolean args.style.squares_resize `true` +-- or `false` to resize squares. -- @tparam[opt=beautiful.taglist_font] string args.style.font The font. -- @tparam[opt=beautiful.taglist_shape] gears.shape|function args.style.shape -- @tparam[opt=beautiful.taglist_shape_border_width] number args.style.shape_border_width @@ -746,8 +772,6 @@ function taglist.mt:__call(...) return taglist.new(...) end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(taglist, taglist.mt) From d45bd3a9d918886e294718ba69c36075ae0422c5 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 082/134] awful.widget.tasklist: Update the property documentation. --- lib/awful/widget/tasklist.lua | 47 +++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 11 deletions(-) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index d352ff104..a0b29688c 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -71,6 +71,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou -- @widgetmod awful.widget.tasklist +-- @supermodule wibox.widget.base --------------------------------------------------------------------------- -- Grab environment we need @@ -435,7 +436,8 @@ local function tasklist_label(c, args, tb) local bg_image_focus = args.bg_image_focus or theme.tasklist_bg_image_focus or theme.bg_image_focus local bg_image_urgent = args.bg_image_urgent or theme.tasklist_bg_image_urgent or theme.bg_image_urgent local bg_image_minimize = args.bg_image_minimize or theme.tasklist_bg_image_minimize or theme.bg_image_minimize - local tasklist_disable_icon = args.disable_icon or args.tasklist_disable_icon or theme.tasklist_disable_icon or false + local tasklist_disable_icon = args.disable_icon or args.tasklist_disable_icon + or theme.tasklist_disable_icon or false local disable_task_name = args.disable_task_name or theme.tasklist_disable_task_name or false local font = args.font or theme.tasklist_font or theme.font local font_focus = args.font_focus or theme.tasklist_font_focus or theme.font_focus or font @@ -607,9 +609,15 @@ end --- The current number of clients. -- +-- Note that the `tasklist` is usually lazy-loaded. Reading this property +-- may cause the widgets to be created. Depending on where the property is called +-- from, it might, in theory, cause an infinite loop. +-- -- @property count -- @readonly --- @tparam number count The number of client. +-- @tparam number count +-- @propertydefault The current number of client. +-- @negativeallowed false -- @propemits true false --- Set the tasklist layout. @@ -629,6 +637,7 @@ end -- -- @property screen -- @tparam screen screen +-- @propertydefault Obtained from the constructor. -- @propemits true false --- A function to narrow down the list of clients. @@ -636,7 +645,10 @@ end -- @DOC_sequences_client_tasklist_custom_filter1_EXAMPLE@ -- -- @property filter --- @tparam function filter +-- @tparam[opt=awful.widget.tasklist.filter.alltags] function filter +-- @functionparam client c The client to accept or reject. +-- @functionparam screen s The value of the tasklist `screen` property. +-- @functionreturn boolean `true` if the client is accepter or `false` if it is rejected. -- @propemits true false -- @see awful.widget.tasklist.filter.allscreen -- @see awful.widget.tasklist.filter.alltags @@ -650,7 +662,15 @@ end -- you can. -- -- @property update_function --- @tparam function update_function +-- @tparam function|nil update_function +-- @propertydefault The default function delegate everything to the `widget_template`. +-- @functionparam widget layout The base layout object. +-- @functionparam table buttons The buttons for this client entry (see below). +-- @functionparam string label The client name. +-- @functionparam table data Arbitrary metadate. +-- @functionparam table clients The list of clients (ordered). +-- @functionparam table metadata Other values. +-- @functionnoreturn -- @propemits true false --- A template for creating the client widgets. @@ -658,7 +678,7 @@ end -- @DOC_sequences_client_tasklist_widget_template1_EXAMPLE@ -- -- @property widget_template --- @tparam table widget_template +-- @tparam[opt=nil] template|nil widget_template -- @propemits true false --- A function to gather the clients to display. @@ -666,7 +686,10 @@ end -- @DOC_sequences_client_tasklist_custom_source1_EXAMPLE@ -- -- @property source --- @tparam function source +-- @tparam[opt=awful.widget.tasklist.source.all_clients] function source +-- @functionparam screen s The tasklist screen. +-- @functionparam table metadata Various metadata. +-- @functionreturn table The list of clients. -- @propemits true false -- @see awful.widget.tasklist.source.all_clients @@ -822,9 +845,12 @@ end -- @tparam[opt=beautiful.tasklist_above or '▴'] string args.style.above Extra icon when client is above -- @tparam[opt=beautiful.tasklist_below or '▾'] string args.style.below Extra icon when client is below -- @tparam[opt=beautiful.tasklist_floating or '✈'] string args.style.floating Extra icon when client is floating --- @tparam[opt=beautiful.tasklist_maximized or '+'] string args.style.maximized Extra icon when client is maximized --- @tparam[opt=beautiful.tasklist_maximized_horizontal or '⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal --- @tparam[opt=beautiful.tasklist_maximized_vertical or '⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical +-- @tparam[opt=beautiful.tasklist_maximized or '+'] string args.style.maximized Extra +-- icon when client is maximized +-- @tparam[opt=beautiful.tasklist_maximized_horizontal or '⬌'] string args.style.maximized_horizontal Extra +-- icon when client is maximized_horizontal +-- @tparam[opt=beautiful.tasklist_maximized_vertical or '⬍'] string args.style.maximized_vertical Extra +-- icon when client is maximized_vertical -- @tparam[opt=beautiful.tasklist_disable_task_name or false] boolean args.style.disable_task_name -- @tparam[opt=beautiful.tasklist_font] string args.style.font -- @tparam[opt=beautiful.tasklist_align or "left"] string args.style.align *left*, *right* or *center* @@ -844,6 +870,7 @@ end -- @tparam[opt=beautiful.tasklist_shape_urgent] gears.shape args.style.shape_urgent -- @tparam[opt=beautiful.tasklist_shape_border_width_urgent] number args.style.shape_border_width_urgent -- @tparam[opt=beautiful.tasklist_shape_border_color_urgent] string|color args.style.shape_border_color_urgent +-- @tparam[opt=beautiful.tasklist_minimized ] string|color args.style.minimized -- @param filter **DEPRECATED** use args.filter -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style @@ -1101,8 +1128,6 @@ function tasklist.mt:__call(...) return tasklist.new(...) end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(tasklist, tasklist.mt) From 8f1a29b15fdb7723e49314605f4e75da17b9ec68 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 083/134] awful.widget.watch: Update the property documentation. --- lib/awful/widget/watch.lua | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/awful/widget/watch.lua b/lib/awful/widget/watch.lua index 9dfca6f16..21d094124 100644 --- a/lib/awful/widget/watch.lua +++ b/lib/awful/widget/watch.lua @@ -31,6 +31,7 @@ -- @author Yauheni Kirylau -- @copyright 2015, 2016 Benjamin Petrenko, Yauheni Kirylau -- @widgetmod awful.widget.watch +-- @supermodule wibox.widget.base --------------------------------------------------------------------------- local setmetatable = setmetatable @@ -91,8 +92,6 @@ function watch.mt.__call(_, ...) return watch.new(...) end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(watch, watch.mt) From 52c481babc47bc2bde70c1b32f3b024aa0abe4f6 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 084/134] gears.color: Update the property documentation. --- lib/gears/color.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/gears/color.lua b/lib/gears/color.lua index 5035da5a5..e982eb102 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -361,7 +361,7 @@ end -- @staticfct gears.color.change_opacity -- @tparam string|pattern input The input color. -- @tparam number opacity A floating point number between 0 and 1. --- @treturn The new color if successful or `input` if invalid. +-- @treturn color The new color if successful or `input` if invalid. function color.change_opacity(input, opacity) input = color.create_pattern(input) From 11ce8fd77c8e0c6f4e3bc16502a1057ce7bc69ea Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 085/134] gears.timer: Update the property documentation. --- lib/gears/timer.lua | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index 0c50c954b..b8ab26fb8 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -140,15 +140,17 @@ end -- -- For this to be `true` by default, pass `autostart` to the constructor. -- --- @property[opt=false] started --- @tparam boolean started +-- @property started +-- @tparam[opt=false] boolean started -- @see start -- @see stop --- The timer timeout value. -- -- @property timeout --- @tparam number timeout +-- @tparam[opt=0] number timeout +-- @propertyunit second +-- @negativeallowed false -- @propemits true false local timer_instance_mt = { From 05ecb513c5cd06b31005113d44e6b2e636411446 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 086/134] menubar.init: Update the property documentation. --- lib/menubar/init.lua | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index 337483892..142054f29 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -542,6 +542,7 @@ end --- Hide the menubar. -- @staticfct menubar.hide +-- @noreturn function menubar.hide() if instance then instance.wibox.visible = false From 6b382148a8fa030e9a785946073106b6f1d70257 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 087/134] naughty.action: Update the property documentation. --- lib/naughty/action.lua | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index f88c84869..0a4e66b50 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -27,6 +27,7 @@ local action = {} -- The action name. -- @property name -- @tparam string name The name. +-- @propertydefault This is provided by DBus. -- @propemits true false -- If the action is selected. @@ -35,17 +36,19 @@ local action = {} -- implement keyboard navigation. -- -- @property selected --- @tparam boolean selected +-- @tparam[opt=false] boolean selected -- @propemits true false --- The action position (index). -- @property position --- @tparam number position +-- @tparam integer position +-- @propertydefault This is provided by DBus. -- @propemits true false +-- @negativeallowed false --- The action icon. -- @property icon --- @tparam gears.surface|string icon +-- @tparam[opt=nil] image|string|nil icon -- @propemits true false --- If the action should hide the label and only display the icon. From 85eb759bd89a706c6aa451e53f191ad5c92383a7 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 088/134] naughty.container.background: Update the property documentation. --- lib/naughty/container/background.lua | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/naughty/container/background.lua b/lib/naughty/container/background.lua index 852a6e340..5a24f0607 100644 --- a/lib/naughty/container/background.lua +++ b/lib/naughty/container/background.lua @@ -44,6 +44,7 @@ end --- The attached notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false function background:set_notification(notif) @@ -101,8 +102,6 @@ local function new(args) return bg end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(background, {__call = function(_, ...) return new(...) end}) From c3a73cab536399df177d69b8f67e1ea19db6294c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 089/134] naughty.core: Update the property documentation. --- lib/naughty/core.lua | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/lib/naughty/core.lua b/lib/naughty/core.lua index 98106ef33..8f4b7f366 100644 --- a/lib/naughty/core.lua +++ b/lib/naughty/core.lua @@ -120,7 +120,7 @@ gtable.crush(naughty, require("naughty.constants")) -- useful when watching movies or doing presentations. -- -- @property suspended --- @tparam boolean suspended +-- @tparam[opt=false] boolean suspended -- @emits added -- @propemits true false @@ -138,17 +138,19 @@ gtable.crush(naughty, require("naughty.constants")) -- -- Please note that this list is kept up-to-date even in suspended mode. -- --- **Signal:** --- --- * property::active --- -- @property active --- @tparam table active +-- @tparam[opt={}] table active +-- @tablerowtype A list of `naughty.notification` objects. -- @propemits false false --- True when there is a handler connected to `request::display`. +-- +-- Note that using the legacy notifications is deprecated. +-- -- @property has_display_handler -- @tparam boolean has_display_handler +-- @propertydefault If `rc.lua` has a `request::display` section, this will +-- be `true`. Otherwise it is `false` and the legacy notification will be used. --- If the timeout needs to be reset when a property changes. -- From eb21c24acb93f6fff59d36a755eccfca1c955707 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 090/134] naughty.layout.box: Update the property documentation. --- lib/naughty/layout/box.lua | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/naughty/layout/box.lua b/lib/naughty/layout/box.lua index fae1aeac2..dd7fe8f3f 100644 --- a/lib/naughty/layout/box.lua +++ b/lib/naughty/layout/box.lua @@ -167,6 +167,7 @@ end) -- -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This must be provided by the constructor. -- @propemits true false --- The widget template to construct the box content. @@ -208,7 +209,7 @@ end) -- } -- -- @property widget_template --- @tparam[opt=nil] widget|nil|table widget_template +-- @tparam[opt=nil] template|nil widget_template -- @usebeautiful beautiful.notification_max_width The maximum width for the -- resulting widget. @@ -396,6 +397,4 @@ local function new(args) return ret end ---@DOC_wibox_COMMON@ - return setmetatable(box, {__call = function(_, args) return new(args) end}) From 51a1d387e5ec2b0fff1e9f924ee30e4624956319 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 091/134] naughty.list.actions: Update the property documentation. --- lib/naughty/list/actions.lua | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/lib/naughty/list/actions.lua b/lib/naughty/list/actions.lua index 46a66337d..eb51557da 100644 --- a/lib/naughty/list/actions.lua +++ b/lib/naughty/list/actions.lua @@ -24,6 +24,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.list.actions +-- @supermodule wibox.widget.base -- @see awful.widget.common ---------------------------------------------------------------------------- @@ -188,7 +189,7 @@ local actionlist = {} --- The actionlist parent notification. -- @property notification --- @tparam naughty.notification notification +-- @tparam[opt=nil] naughty.notification|nil notification -- @propemits true false -- @see naughty.notification @@ -196,18 +197,33 @@ local actionlist = {} -- If no layout is specified, a `wibox.layout.fixed.horizontal` will be created -- automatically. -- @property base_layout --- @tparam widget base_layout +-- @tparam[opt=wibox.layout.fixed.horizontal] widget base_layout -- @propemits true false -- @see wibox.layout.fixed.horizontal --- The actionlist parent notification. -- @property widget_template --- @tparam table widget_template +-- @tparam[opt=nil] template|nil widget_template -- @propemits true false --- A table with values to override each `beautiful.notification_action` values. -- @property style --- @tparam table style +-- @tparam[opt={}] table|nil style +-- @tparam boolean|nil style.underline_normal +-- @tparam boolean|nil style.underline_selected +-- @tparam shape|nil style.shape_normal +-- @tparam shape|nil style.shape_selected +-- @tparam gears.color|string|nil style.shape_border_color_normal +-- @tparam gears.color|string|nil style.shape_border_color_selected +-- @tparam number|nil style.shape_border_width_normal +-- @tparam number|nil style.shape_border_width_selected +-- @tparam number|nil style.icon_size +-- @tparam color|string|nil style.bg_normal +-- @tparam color|string|nil style.bg_selected +-- @tparam color|string|nil style.fg_normal +-- @tparam color|string|nil style.fg_selected +-- @tparam surface|string|nil style.bgimage_normal +-- @tparam surface|string|nil style.bgimage_selected -- @propemits true false -- @usebeautiful beautiful.font Fallback when the `font` property isn't set. -- @usebeautiful beautiful.notification_action_underline_normal Fallback. @@ -349,8 +365,6 @@ local function new(_, args) return wdg end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(module, {__call = new}) From e4d88e556652a954dbd23823d35efdae3e3769e5 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 092/134] naughty.list.notifications: Update the property documentation. --- lib/naughty/list/notifications.lua | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/lib/naughty/list/notifications.lua b/lib/naughty/list/notifications.lua index d5561fcaa..9fb5afbb8 100644 --- a/lib/naughty/list/notifications.lua +++ b/lib/naughty/list/notifications.lua @@ -6,6 +6,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.list.notifications +-- @supermodule wibox.widget.base -- @see awful.widget.common ---------------------------------------------------------------------------- @@ -160,16 +161,17 @@ local notificationlist = {} --- The notificationlist parent notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false -- @see naughty.notification --- A `wibox.layout` to be used to place the entries. -- --- If no layout is specified, a `wibox.layout.fixed.vertical` will be created +-- If no layout is specified, a `wibox.layout.flex.horizontal` will be created -- automatically. -- -- @property base_layout --- @tparam widget base_layout +-- @tparam[opt=wibox.layout.flex.horizontal] widget base_layout -- @propemits true false -- @usebeautiful beautiful.notification_spacing -- @see wibox.layout.fixed.horizontal @@ -180,12 +182,15 @@ local notificationlist = {} --- The notificationlist parent notification. -- @property widget_template --- @tparam table widget_template +-- @tparam[opt=nil] template|nil widget_template +-- @propertydefault The default template displays the icon, title, message and +-- actions. -- @propemits true false --- A table with values to override each `beautiful.notification_action` values. -- @property style --- @tparam table style +-- @tparam[opt=nil] table|nil style +-- @propertytype nil Use the values from `beautiful` rather than hardcoded ones. -- @propemits true false -- @usebeautiful beautiful.notification_shape_normal Fallback. -- @usebeautiful beautiful.notification_shape_selected Fallback. @@ -242,7 +247,11 @@ end --- A function to prevent some notifications from being added to the list. -- @property filter --- @tparam function filter +-- @tparam[opt=nil] function|nil filter +-- @functionparam naughty.notification n The notification object. +-- @functionparam number count The number of notifications in the list. +-- @functionreturn boolean `true` if the notification is allowed and `false` if +-- it is rejected. -- @propemits true false for _, prop in ipairs { "filter", "base_layout" } do @@ -367,8 +376,6 @@ function module.filter.most_recent(n, count) return false end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(module, {__call = new}) From a7fd2e2278c3055777bb1960c0bc8df1c6e43fcd Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 093/134] naughty.notification: Update the property documentation. --- lib/naughty/notification.lua | 138 ++++++++++++++++++++++++----------- 1 file changed, 94 insertions(+), 44 deletions(-) diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index a3da5e5c3..a1c745333 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -27,6 +27,8 @@ local pcommon = require("awful.permissions._common") local notification = {} +--luacheck: no max line length + --- Notifications font. -- @beautiful beautiful.notification_font -- @tparam string|lgi.Pango.FontDescription notification_font @@ -78,6 +80,8 @@ local notification = {} -- notifications. -- @property id -- @tparam number id +-- @propertydefault This is autogenerated. +-- @readonly -- @propemits true false --- Text of the notification. @@ -92,25 +96,26 @@ local notification = {} --- Title of the notification. --@DOC_naughty_helloworld_EXAMPLE@ -- @property title --- @tparam string title +-- @tparam[opt=""] string title -- @propemits true false --- Time in seconds after which popup expires. -- Set 0 for no timeout. -- @property timeout -- @tparam number timeout +-- @propertydefault If unspecified, it can come from either the notification +-- itself, the presets or the `ruled.notification` rules. +-- @negativeallowed false +-- @propertyunit second -- @propemits true false --- The notification urgency level. -- --- The default urgency levels are: --- --- * low --- * normal --- * critical --- -- @property urgency --- @tparam string urgency +-- @tparam[opt="normal"] string urgency +-- @propertyvalue "low" +-- @propertyvalue "normal" +-- @propertyvalue "critical" -- @propemits true false --- The notification category. @@ -157,7 +162,7 @@ local notification = {} -- -- -- @property category --- @tparam string|nil category +-- @tparam[opt=nil] string|nil category -- @propemits true false --- True if the notification should be kept when an action is pressed. @@ -173,29 +178,28 @@ local notification = {} --- Delay in seconds after which hovered popup disappears. -- @property hover_timeout -- @tparam[opt=nil] number|nil hover_timeout +-- @negativeallowed false +-- @propertyunit second -- @propemits true false --- Target screen for the notification. -- @property screen --- @tparam screen screen +-- @tparam[opt=awful.screen.preferred()] screen screen -- @propemits true false --- Corner of the workarea displaying the popups. -- --- The possible values are: --- --- * *top_right* --- * *top_left* --- * *bottom_left* --- * *bottom_right* --- * *top_middle* --- * *bottom_middle* --- * *middle* --- --@DOC_awful_notification_box_corner_EXAMPLE@ -- -- @property position --- @tparam[opt=beautiful.notification_position] string position +-- @tparam[opt=beautiful.notification_position] string|nil position +-- @propertyvalue "top_right" +-- @propertyvalue "top_left" +-- @propertyvalue "bottom_left" +-- @propertyvalue "bottom_right" +-- @propertyvalue "top_middle" +-- @propertyvalue "bottom_middle" +-- @propertyvalue "middle" -- @propemits true false -- @see awful.placement.next_to @@ -208,20 +212,26 @@ local notification = {} --@DOC_awful_notification_geometry_EXAMPLE@ -- -- @property height --- @tparam number height +-- @tparam number|nil height -- @propemits true false +-- @propertyunit pixel +-- @negativeallowed false +-- @propbeautiful -- @see width --- Popup width. -- @property width --- @tparam number width +-- @tparam number|nil width -- @propemits true false +-- @propertyunit pixel +-- @negativeallowed false +-- @propbeautiful -- @see height --- Notification font. --@DOC_naughty_colors_EXAMPLE@ -- @property font --- @tparam string font +-- @tparam[opt=beautiful.notification_font] font|nil font -- @propemits true false -- @see wibox.widget.textbox.font @@ -242,14 +252,16 @@ local notification = {} -- * The `icon` of a client with `dialog` type. -- -- @property icon --- @tparam string|surface icon +-- @tparam[opt=nil] image|nil icon -- @propemits true false -- @see app_icon -- @see image --- Desired icon size in px. -- @property icon_size --- @tparam[opt=beautiful.notification_icon_size] number icon_size +-- @tparam[opt=beautiful.notification_icon_size] integer|nil icon_size +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- The icon provided in the `app_icon` field of the DBus notification. @@ -258,7 +270,7 @@ local notification = {} -- icon name to be fetched from the theme. -- -- @property app_icon --- @tparam string app_icon +-- @tparam[opt=nil] string|nil app_icon -- @propemits true false --- The notification image. @@ -268,7 +280,7 @@ local notification = {} -- or stored elsewhere than the filesystem (databases, web, Android phones, etc). -- -- @property image --- @tparam string|surface image +-- @tparam[opt=nil] image|nil image -- @propemits true false --- The notification (animated) images. @@ -279,8 +291,11 @@ local notification = {} -- Also note that there is *zero* support for this anywhere else in `naughty` -- and very, very few applications support this. -- +-- This exists purely to comply with the specification. +-- -- @property images --- @tparam nil|table images +-- @tparam[opt=nil] nil|table images +-- @tablerowtype A list of `image`s. -- @propemits true false --- Foreground color. @@ -288,7 +303,8 @@ local notification = {} --@DOC_awful_notification_fg_EXAMPLE@ -- -- @property fg --- @tparam[beautiful.notification_fg] string|color|pattern fg +-- @tparam[beautiful.notification_fg] color|nil fg +-- @propbeautiful -- @propemits true false -- @see title -- @see gears.color @@ -298,22 +314,27 @@ local notification = {} --@DOC_awful_notification_bg_EXAMPLE@ -- -- @property bg --- @tparam[opt=beautiful.notification_bg] string|color|pattern bg +-- @tparam[opt=beautiful.notification_bg] color|nil bg -- @propemits true false -- @see title -- @see gears.color --- Border width. -- @property border_width --- @tparam[opt=beautiful.notification_border_width or 0] number border_width +-- @tparam[opt=beautiful.notification_border_width or 0] number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel +-- @propbeautiful -- @propemits true false --- Border color. -- --@DOC_awful_notification_border_color_EXAMPLE@ -- +-- Please note that only string (like `#ff0000`) are supported. +-- -- @property border_color --- @tparam[opt=beautiful.notification_border_color] string border_color +-- @tparam[opt=beautiful.notification_border_color] string|nil border_color -- @propemits true false -- @see gears.color @@ -332,12 +353,15 @@ local notification = {} --@DOC_naughty_shape_EXAMPLE@ -- -- @property shape --- @tparam gears.shape shape +-- @tparam[opt=beautiful.notification_shape] shape|nil shape -- @propemits true false --- Widget opacity. -- @property opacity --- @tparam number opacity Between 0 to 1. +-- @tparam[opt=beautiful.notification_opacity] number|nil opacity +-- @rangestart 0.0 +-- @rangestop 1.0 +-- @propertyunit Gradient beween 0.0 (transparent) and 1.0 (opaque). -- @propemits true false --- Widget margin. @@ -345,7 +369,15 @@ local notification = {} --@DOC_awful_notification_margin_EXAMPLE@ -- -- @property margin --- @tparam number|table margin +-- @tparam[opt=beautiful.notification_margin] number|table|nil margin +-- @tparam[opt=0] number margin.top +-- @tparam[opt=0] number margin.bottom +-- @tparam[opt=0] number margin.left +-- @tparam[opt=0] number margin.right +-- @propertytype number A single value for all sides. +-- @propertytype table A different value for all sides. +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @see shape @@ -369,14 +401,24 @@ local notification = {} -- args will override ones defined -- in the preset. -- @property preset --- @tparam table preset +-- @tparam[opt=nil] table|nil preset -- @propemits true false --- Function that will be called with all arguments. -- The notification will only be displayed if the function returns true. -- Note: this function is only relevant to notifications sent via dbus. -- @property callback --- @tparam function callback +-- @tparam[opt=nil] function|nil callback +-- @functionparam table legacy_data +-- @functionparam string appname +-- @functionparam number replaces_id +-- @functionparam string app_icon +-- @functionparam string title +-- @functionparam string message +-- @functionparam table actions +-- @functionparam table hints +-- @functionparam number expire +-- @functionnoreturn -- @propemits true false --- A table containing strings that represents actions to buttons. @@ -384,7 +426,8 @@ local notification = {} -- The table key (a number) is used by DBus to set map the action. -- -- @property actions --- @tparam table actions +-- @tparam[opt={}] table actions +-- @tablerowtype A list of `naughty.action` objects. -- @propemits true false --- Ignore this notification, do not display. @@ -408,6 +451,8 @@ local notification = {} -- @property is_expired -- @tparam boolean is_expired -- @propemits true false +-- @propertydefault This becomes `true` either then `:destroy()` is called or +-- if the `timeout` expires. -- @see naughty.expiration_paused --- If the timeout needs to be reset when a property changes. @@ -438,7 +483,8 @@ local notification = {} -- client. -- -- @property clients --- @tparam table clients +-- @tparam[opt={}] table clients +-- @tablerowtype A list of `client` objects. --- The maximum popup width. -- @@ -447,8 +493,11 @@ local notification = {} -- decision to the layout. -- -- @property max_width --- @tparam[opt=500] number max_width +-- @tparam[opt=500] number|nil max_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false +-- @propbeautiful --- The application name specified by the notification. -- @@ -456,7 +505,7 @@ local notification = {} -- property, but can sometime be specified for remote or headless notifications. -- In these case, it helps to triage and detect the notification from the rules. -- @property app_name --- @tparam string app_name +-- @tparam[opt=nil] string|nil app_name -- @propemits true false --- The widget template used to represent the notification. @@ -465,7 +514,8 @@ local notification = {} -- off with a specialized notification widget. -- -- @property widget_template --- @tparam table|nil widget_template +-- @tparam[opt=nil] template|nil widget_template +-- @propertydefault The default template as the icon, title, message and actions. -- @propemits true false --- Destroy notification by notification object. @@ -919,7 +969,7 @@ end -- @tparam[opt=`beautiful.notification_height` or auto] integer args.height Popup height. -- @tparam[opt=`beautiful.notification_width` or auto] integer args.width Popup width. -- @tparam[opt=`beautiful.notification_font` or `beautiful.font` or `awesome.font`] string|lgi.Pango.FontDescription args.font Notification font. --- @tparam[opt] gears.surface args.icon Path to icon. +-- @tparam[opt] image args.icon Path to icon. -- @tparam[opt] integer args.icon_size Desired icon size in px. -- @tparam[opt=`beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`] string args.fg Foreground color. -- @tparam[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] string args.bg Background color. From 7149b93abb9b299177f7800eaa2f387508c0c504 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 094/134] naughty.widget.icon: Update the property documentation. --- lib/naughty/widget/icon.lua | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/lib/naughty/widget/icon.lua b/lib/naughty/widget/icon.lua index 00eb59eb6..d44025a2b 100644 --- a/lib/naughty/widget/icon.lua +++ b/lib/naughty/widget/icon.lua @@ -81,6 +81,7 @@ end --- The attached notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false function icon:set_notification(notif) @@ -113,12 +114,6 @@ local valid_strategies = { --- How small icons are handled. -- --- Valid values are: --- --- * **scale**: Scale the icon up to the optimal size. --- * **center**: Keep the icon size and draw it in the center --- * **resize**: Change the size of the widget itself (*default*). --- -- Note that the size upper bound is defined by -- `beautiful.notification_icon_size`. -- @@ -127,6 +122,9 @@ local valid_strategies = { -- @property resize_strategy -- @tparam string resize_strategy -- @propemits true false +-- @propertyvalue "scale" Scale the icon up to the optimal size. +-- @propertyvalue "center" Keep the icon size and draw it in the center +-- @propertyvalue "resize" Change the size of the widget itself (*default*). -- @usebeautiful beautiful.notification_icon_resize_strategy The fallback when -- there is no specified strategy. -- @usebeautiful beautiful.notification_icon_size The size upper bound. @@ -183,8 +181,6 @@ local function new(args) return tb end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(icon, {__call = function(_, ...) return new(...) end}) From 0014785c851456dc7c6ef0905b734cc769a8370f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 095/134] naughty.widget.message: Update the property documentation. --- lib/naughty/widget/message.lua | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/naughty/widget/message.lua b/lib/naughty/widget/message.lua index 6d9a68514..f0834d135 100644 --- a/lib/naughty/widget/message.lua +++ b/lib/naughty/widget/message.lua @@ -25,6 +25,7 @@ local message = {} --- The attached notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false function message:set_notification(notif) @@ -86,8 +87,6 @@ local function new(args) return tb end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(message, {__call = function(_, ...) return new(...) end}) From 2c14e90a898f048ba360af528bf9a8ea294247d4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 096/134] naughty.widget.title: Update the property documentation. --- lib/naughty/widget/title.lua | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/naughty/widget/title.lua b/lib/naughty/widget/title.lua index 27f1311d6..8b58448a8 100644 --- a/lib/naughty/widget/title.lua +++ b/lib/naughty/widget/title.lua @@ -25,6 +25,7 @@ local title = {} --- The attached notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false function title:set_notification(notif) @@ -87,8 +88,6 @@ local function new(args) return tb end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(title, {__call = function(_, ...) return new(...) end}) From 73ec4162878cca003fad984063524fd063dd78aa Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 097/134] wibox.container.arcchart: Update the property documentation. --- lib/wibox/container/arcchart.lua | 40 +++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index 261539237..d7138685f 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -201,7 +201,7 @@ end --- The widget to wrap in a radial proggressbar. -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container arcchart.set_widget = base.set_widget_common @@ -240,6 +240,10 @@ end -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left -- @tparam[opt=0] number paddings.right +-- @propertytype number A single padding value for each side. +-- @propertytype table A different padding value for each side. +-- @propertyunit pixel +-- @negativeallowed false -- @emits [opt=bob] property::paddings When the `paddings` changes. -- @emitstparam property::paddings widget self The object being modified. -- @emitstparam property::paddings table paddings The new paddings. @@ -249,14 +253,15 @@ end --- The border background color. --@DOC_wibox_container_arcchart_border_color_EXAMPLE@ -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propemits true false -- @propbeautiful --- The arcchart values foreground colors. --@DOC_wibox_container_arcchart_color_EXAMPLE@ -- @property colors --- @tparam table colors An ordered set of colors for each value in arcchart. +-- @tparam table colors +-- @tablerowtype An ordered list of colors for each value in arcchart. -- @propemits true false -- @usebeautiful beautiful.arcchart_color @@ -265,24 +270,29 @@ end --@DOC_wibox_container_arcchart_border_width_EXAMPLE@ -- -- @property border_width --- @tparam[opt=3] number border_width +-- @tparam[opt=0] number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @propbeautiful --- The minimum value. -- @property min_value --- @tparam number min_value +-- @tparam[opt=0] number min_value +-- @negativeallowed true -- @propemits true false --- The maximum value. -- @property max_value -- @tparam number max_value +-- @propertydefault The sum of all `values`. +-- @negativeallowed true -- @propemits true false --- The radial background. --@DOC_wibox_container_arcchart_bg_EXAMPLE@ -- @property bg --- @tparam color bg +-- @tparam color|nil bg -- @see gears.color -- @propemits true false -- @propbeautiful @@ -290,7 +300,10 @@ end --- The value. --@DOC_wibox_container_arcchart_value_EXAMPLE@ -- @property value --- @tparam number value Between `min_value` and `max_value` +-- @tparam[opt=0] number value +-- @rangestart `min_value` +-- @rangestop `max_value` +-- @negativeallowed true -- @see values -- @propemits true false @@ -299,14 +312,15 @@ end -- shown in table order. --@DOC_wibox_container_arcchart_values_EXAMPLE@ -- @property values --- @tparam table values An ordered set of values. +-- @tparam[opt={}] table values An ordered set of values. +-- @tablerowtype A list of numbers. -- @propemits true false -- @see value --- If the chart has rounded edges. --@DOC_wibox_container_arcchart_rounded_edge_EXAMPLE@ -- @property rounded_edge --- @tparam[opt=false] boolean rounded_edge +-- @tparam[opt=false] boolean|nil rounded_edge -- @propemits true false -- @propbeautiful @@ -314,13 +328,17 @@ end --@DOC_wibox_container_arcchart_thickness_EXAMPLE@ -- @property thickness -- @propemits true false --- @tparam number thickness +-- @tparam number|nil thickness +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful --- The (radiant) angle where the first value start. -- @DOC_wibox_container_arcchart_start_angle_EXAMPLE@ -- @property start_angle --- @tparam[opt=math.pi] number start_angle A number between 0 and 2*math.pi +-- @tparam[opt=math.pi] number start_angle +-- @rangestart 0 +-- @rangestop 2*math.pi -- @propemits true false -- @usebeautiful beautiful.arcchart_start_angle From d147899f86c7b5bf8b3844a5d33b3e4d033bb1a0 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 098/134] wibox.container.background: Update the property documentation. --- lib/wibox/container/background.lua | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index cada81e29..8262d6a7e 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -235,8 +235,8 @@ end --- The widget displayed in the background widget. -- @property widget --- @tparam widget widget The widget to be disaplayed inside of the background --- area. +-- @tparam[opt=nil] widget|nil widget The widget to be disaplayed inside of +-- the background area. -- @interface container background.set_widget = base.set_widget_common @@ -258,7 +258,9 @@ end --@DOC_wibox_container_background_bg_EXAMPLE@ -- -- @property bg --- @tparam color bg A color string, pattern or gradient +-- @tparam color bg +-- @propertydefault When unspecified, it will inherit the value from an higher +-- level `wibox.container.background` or directly from the `wibox.bg` property. -- @see gears.color -- @propemits true false @@ -282,6 +284,8 @@ end -- -- @property fg -- @tparam color fg A color string, pattern or gradient +-- @propertydefault When unspecified, it will inherit the value from an higher +-- level `wibox.container.background` or directly from the `wibox.fg` property. -- @propemits true false -- @see gears.color @@ -306,7 +310,7 @@ end --@DOC_wibox_container_background_shape_EXAMPLE@ -- -- @property shape --- @tparam gears.shape|function shape A function taking a context, width and height as arguments +-- @tparam[opt=gears.shape.rectangle] shape shape -- @see gears.shape -- @see set_shape @@ -350,7 +354,9 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_width --- @tparam[opt=0] number border_width The border width. +-- @tparam[opt=0] number border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @introducedin 4.4 -- @see border_color @@ -396,7 +402,8 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_color --- @tparam[opt=fg] color border_color The border color, pattern or gradient +-- @tparam color border_color +-- @propertydefault `wibox.container.background.fg` if set, otherwise `beautiful.fg_normal`. -- @propemits true false -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. -- @introducedin 4.4 @@ -443,13 +450,10 @@ end --- How the border width affects the contained widget. -- --- The valid values are: --- --- * *none*: Just apply the border, do not affect the content size (default). --- * *inner*: Squeeze the size of the content by the border width. --- -- @property border_strategy -- @tparam[opt="none"] string border_strategy +-- @propertyvalue "none" Just apply the border, do not affect the content size (default). +-- @propertyvalue "inner" Squeeze the size of the content by the border width. function background:set_border_strategy(value) self._private.border_strategy = value @@ -463,7 +467,7 @@ end -- as arguments. Any other arguments passed to this method will be appended. -- -- @property bgimage --- @tparam string|surface|function bgimage A background image or a function +-- @tparam[opt=nil] image|nil bgimage -- @see gears.surface function background:set_bgimage(image, ...) From 268c66584e2b9559c6d11a93db0a5ed11b335c7e Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 099/134] wibox.container.constraint: Update the property documentation. --- lib/wibox/container/constraint.lua | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index 7f4661e83..a1c36bcfd 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -43,7 +43,7 @@ end --- The widget to be constrained. -- -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container constraint.set_widget = base.set_widget_common @@ -61,14 +61,12 @@ function constraint:set_children(children) end --- Set the strategy to use for the constraining. --- Valid values are: --- --- * **max**: Never allow the size to be larger than the limit. --- * **min**: Never allow the size to tbe below the limit. --- * **exact**: Force the widget size. -- -- @property strategy --- @tparam string strategy Either 'max', 'min' or 'exact'. +-- @tparam[opt="max"] string strategy +-- @propertyvalue "max" Never allow the size to be larger than the limit. +-- @propertyvalue "min" Never allow the size to tbe below the limit. +-- @propertyvalue "exact" Force the widget size. -- @propemits true false function constraint:set_strategy(val) @@ -100,7 +98,11 @@ end --- Set the maximum width to val. nil for no width limit. -- -- @property width --- @tparam number width +-- @tparam[opt=nil] number|nil width +-- @negativeallowed false +-- @propertyunit pixel +-- @propertytype nil Do not set a width limit. +-- @propertytype number Set a width limit. -- @propemits true false function constraint:set_width(val) @@ -116,7 +118,11 @@ end --- Set the maximum height to val. nil for no height limit. -- -- @property height --- @tparam number height +-- @tparam[opt=nil] number|nil height +-- @negativeallowed false +-- @propertyunit pixel +-- @propertytype nil Do not set a height limit. +-- @propertytype number Set a height limit. -- @propemits true false function constraint:set_height(val) From 534c2324aef7b82ba58156743e4bce13bf1e4a9f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 100/134] wibox.container.margin: Update the property documentation. --- lib/wibox/container/margin.lua | 37 +++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index eb8ff267a..eb28eb576 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -74,7 +74,7 @@ end --- The widget to be wrapped the the margins. -- -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container margin.set_widget = base.set_widget_common @@ -94,8 +94,15 @@ end --- Set all the margins to val. -- -- @property margins --- @tparam number|table margins The margin value. It can be a number or a table with --- the *left*/*right*/*top*/*bottom* keys. +-- @tparam[opt=0] number|table margins +-- @tparam[opt=0] number margins.left +-- @tparam[opt=0] number margins.right +-- @tparam[opt=0] number margins.top +-- @tparam[opt=0] number margins.bottom +-- @propertytype number A single value for all margins. +-- @propertytype table A different value for each side. +-- @propertyunit pixel +-- @negativeallowed false -- @propemits false false function margin:set_margins(val) @@ -126,7 +133,8 @@ end --- Set the margins color to create a border. -- -- @property color --- @tparam gears.color color A color used to fill the margin. +-- @tparam[opt=nil] color|nil color A color used to fill the margin. +-- @propertytype nil Transparent margins. -- @propemits true false function margin:set_color(color) @@ -142,7 +150,7 @@ end --- Draw the margin even if the content size is 0x0. -- -- @property draw_empty --- @tparam[opt=true] boolean draw_empty Draw nothing is content is 0x0 or draw +-- @tparam[opt=true] boolean draw_empty Draw nothing is content is `0x0` or draw -- the margin anyway. -- @propemits true false @@ -156,7 +164,8 @@ function margin:get_draw_empty() return self._private.draw_empty end ---- Reset this layout. The widget will be unreferenced, the margins set to 0 +--- Reset this layout. +-- The widget will be unreferenced, the margins set to 0 -- and the color erased -- @method reset -- @noreturn @@ -170,25 +179,33 @@ end --- Set the left margin that this layout adds to its widget. -- -- @property left --- @tparam number left The new margin to use. +-- @tparam[opt=0] number left +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- Set the right margin that this layout adds to its widget. -- -- @property right --- @tparam number right The new margin to use. +-- @tparam[opt=0] number right +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- Set the top margin that this layout adds to its widget. -- -- @property top --- @tparam number top The new margin to use. +-- @tparam[opt=0] number top +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- Set the bottom margin that this layout adds to its widget. -- -- @property bottom --- @tparam number bottom The new margin to use. +-- @tparam[opt=0] number bottom +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- Create setters for each direction From bdec7eb5164ad38c84281707052bed3f14b54f1a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 101/134] wibox.container.mirror: Update the property documentation. --- lib/wibox/container/mirror.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua index d21724f30..49b59538d 100644 --- a/lib/wibox/container/mirror.lua +++ b/lib/wibox/container/mirror.lua @@ -50,7 +50,7 @@ end --- The widget to be reflected. -- -- @property widget --- @tparam widget widget The widget. +-- @tparam[opt=nil] widget|nil widget -- @interface container mirror.set_widget = base.set_widget_common @@ -96,8 +96,8 @@ end -- -- @property reflection -- @tparam table reflection A table of booleans with the keys "horizontal", "vertical". --- @tparam boolean reflection.horizontal --- @tparam boolean reflection.vertical +-- @tparam[opt=false] boolean reflection.horizontal +-- @tparam[opt=false] boolean reflection.vertical -- @propemits true false function mirror:get_reflection() From f0482485fae70273291f82b697bfb40694a2aaf4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 102/134] wibox.container.place: Update the property documentation. --- lib/wibox/container/place.lua | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua index 352f2c18f..66d198662 100644 --- a/lib/wibox/container/place.lua +++ b/lib/wibox/container/place.lua @@ -75,7 +75,7 @@ end --- The widget to be placed. -- -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container place.set_widget = base.set_widget_common @@ -102,30 +102,24 @@ end --- The vertical alignment. -- --- Possible values are: --- --- * *top* --- * *center* (default) --- * *bottom* --- --@DOC_wibox_container_place_valign_EXAMPLE@ -- -- @property valign -- @tparam[opt="center"] string valign +-- @propertyvalue "top" +-- @propertyvalue "center" +-- @propertyvalue "bottom" -- @propemits true false --- The horizontal alignment. -- --- Possible values are: --- --- * *left* --- * *center* (default) --- * *right* --- --@DOC_wibox_container_place_halign_EXAMPLE@ -- -- @property halign -- @tparam[opt="center"] string halign +-- @propertyvalue "left" +-- @propertyvalue "center" +-- @propertyvalue "right" -- @propemits true false function place:set_valign(value) From 6c84e83ccf28f72928d82a5ffd31b9bcdc3f4fb2 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 103/134] wibox.container.radialprogressbar: Update the property documentation. --- lib/wibox/container/radialprogressbar.lua | 27 ++++++++++++++++------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index a9effcd78..11c676787 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -131,7 +131,7 @@ end --- The widget to wrap in a radial proggressbar. -- -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container radialprogressbar.set_widget = base.set_widget_common @@ -167,11 +167,15 @@ end -- --@DOC_wibox_container_radialprogressbar_padding_EXAMPLE@ -- @property paddings --- @tparam[opt=0] table|number paddings A number or a table +-- @tparam[opt=0] table|number|nil paddings A number or a table -- @tparam[opt=0] number paddings.top -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left -- @tparam[opt=0] number paddings.right +-- @propertytype number A single value for each sides. +-- @propertytype table A different value for each side. +-- @negativeallowed false +-- @propertyunit pixel -- @propbeautiful -- @propemits false false @@ -179,7 +183,10 @@ end -- --@DOC_wibox_container_radialprogressbar_value_EXAMPLE@ -- @property value --- @tparam number value Between `min_value` and `max_value`. +-- @tparam[opt=0] number value +-- @rangestart `min_value` +-- @rangestop `max_value` +-- @negativeallowed true -- @propemits true false function radialprogressbar:set_value(val) @@ -202,7 +209,7 @@ end -- --@DOC_wibox_container_radialprogressbar_border_color_EXAMPLE@ -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propbeautiful -- @propemits true false @@ -210,7 +217,7 @@ end -- --@DOC_wibox_container_radialprogressbar_color_EXAMPLE@ -- @property color --- @tparam color color +-- @tparam color|nil color -- @propbeautiful -- @propemits true false @@ -218,20 +225,24 @@ end -- --@DOC_wibox_container_radialprogressbar_border_width_EXAMPLE@ -- @property border_width --- @tparam[opt=3] number border_width +-- @tparam[opt=2] number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel -- @propbeautiful -- @propemits true false --- The minimum value. -- -- @property min_value --- @tparam number min_value +-- @tparam[opt=0] number min_value +-- @negativeallowed true -- @propemits true false --- The maximum value. -- -- @property max_value --- @tparam number max_value +-- @tparam[opt=1] number max_value +-- @negativeallowed true -- @propemits true false for _, prop in ipairs {"max_value", "min_value", "border_color", "color", From 1dafd25d932ca548cb538d7c87682167098af9d3 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 104/134] wibox.container.rotate: Update the property documentation. --- lib/wibox/container/rotate.lua | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index c4da7cd0a..571854008 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -62,7 +62,7 @@ end --- The widget to be rotated. -- -- @property widget --- @tparam widget widget The widget. +-- @tparam[opt=nil] widget|nil widget -- @interface container rotate.set_widget = base.set_widget_common @@ -93,16 +93,13 @@ end --- The direction of this rotating container. -- --- Valid values are: --- --- * *north* --- * *east* --- * *south* --- * *north* --- --@DOC_wibox_container_rotate_angle_EXAMPLE@ -- @property direction --- @tparam[opt="north"] string direction The direction. +-- @tparam[opt="north"] string direction +-- @propertyvalue "north" +-- @propertyvalue "east" +-- @propertyvalue "south" +-- @propertyvalue "north" -- @propemits true false function rotate:set_direction(dir) From 4c06aaab4fce7bd9b4de954e485ae581f94b2e67 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 105/134] wibox.container.scroll: Update the property documentation. --- lib/wibox/container/scroll.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua index c520b443c..85c706dc6 100644 --- a/lib/wibox/container/scroll.lua +++ b/lib/wibox/container/scroll.lua @@ -276,7 +276,7 @@ end --- The widget to be scrolled. -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget function scroll:set_widget(widget) if widget == self._private.widget then From 2e41211772fc198e82838d8ee399240e241f4c40 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 106/134] wibox.container.tile: Update the property documentation. --- lib/wibox/container/tile.lua | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/lib/wibox/container/tile.lua b/lib/wibox/container/tile.lua index e00b8775f..15c264dd1 100644 --- a/lib/wibox/container/tile.lua +++ b/lib/wibox/container/tile.lua @@ -92,8 +92,10 @@ end --@DOC_wibox_container_tile_horizontal_spacing_EXAMPLE@ -- -- @property horizontal_spacing --- @tparam number horizontal_spacing +-- @tparam[opt=0] number horizontal_spacing -- @propemits true false +-- @propertyunit pixel +-- @negativeallowed false -- @see vertical_spacing --- The vertical spacing between the tiled. @@ -101,7 +103,9 @@ end --@DOC_wibox_container_tile_vertical_spacing_EXAMPLE@ -- -- @property vertical_spacing --- @tparam number vertical_spacing +-- @tparam[opt=0] number vertical_spacing +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @see horizontal_spacing From 1fa30c31956140b8e8d44d566028ea212cfacd99 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 107/134] wibox.layout.align: Update the property documentation. --- lib/wibox/layout/align.lua | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index 64d0d948c..93ee8a7f7 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -164,7 +164,10 @@ end -- This is the widget that is at the left/top. -- -- @property first --- @tparam widget first +-- @tparam[opt=nil] widget|nil first +-- @propertytype nil This spot will be empty. Depending on how large the second +-- widget is an and the value of `expand`, it might mean it will leave an empty +-- area. -- @propemits true false function align:set_first(widget) @@ -181,7 +184,9 @@ end -- This is the centered one. -- -- @property second --- @tparam widget second +-- @tparam[opt=nil] widget|nil second +-- @propertytype nil When this property is `nil`, then there will be an empty +-- area. -- @propemits true false function align:set_second(widget) @@ -198,7 +203,10 @@ end -- This is the widget that is at the right/bottom. -- -- @property third --- @tparam widget third +-- @tparam[opt=nil] widget|nil third +-- @propertytype nil This spot will be empty. Depending on how large the second +-- widget is an and the value of `expand`, it might mean it will leave an empty +-- area. -- @propemits true false function align:set_third(widget) @@ -256,24 +264,21 @@ end --- Set the expand mode, which determines how child widgets expand to take up -- unused space. -- --- The following values are valid: --- --- * `"inside"`: The widgets in slot one and three are set to their minimal --- required size. The widget in slot two is then given the remaining space. --- This is the default behaviour. --- * `"outside"`: The widget in slot two is set to its minimal required size and --- placed in the center of the space available to the layout. The other --- widgets are then given the remaining space on either side. --- If the center widget requires all available space, the outer widgets are --- not drawn at all. --- * `"none"`: All widgets are given their minimal required size or the --- remaining space, whichever is smaller. The center widget gets priority. --- -- Attempting to set any other value than one of those three will fall back to -- `"inside"`. -- -- @property expand -- @tparam[opt="inside"] string expand How to use unused space. +-- @propertyvalue "inside" The widgets in slot one and three are set to their minimal +-- required size. The widget in slot two is then given the remaining space. +-- This is the default behaviour. +-- @propertyvalue "outside" The widget in slot two is set to its minimal required size and +-- placed in the center of the space available to the layout. The other +-- widgets are then given the remaining space on either side. +-- If the center widget requires all available space, the outer widgets are +-- not drawn at all. +-- @propertyvalue "none" All widgets are given their minimal required size or the +-- remaining space, whichever is smaller. The center widget gets priority. function align:set_expand(mode) if mode == "none" or mode == "outside" then From 285a8b23ffdce8e726c0b47e0a4f190484ace50c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 108/134] wibox.layout.fixed: Update the property documentation. --- lib/wibox/layout/fixed.lua | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index e8e94743f..d40c160d1 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -299,7 +299,7 @@ end --@DOC_wibox_layout_fixed_spacing_widget_EXAMPLE@ -- -- @property spacing_widget --- @tparam widget spacing_widget +-- @tparam[opt=nil] widget|nil spacing_widget -- @propemits true false -- @interface layout @@ -404,7 +404,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 --- @tparam boolean fill_space +-- @tparam[opt=false] boolean fill_space -- @propemits true false function fixed:fill_space(val) @@ -455,7 +455,8 @@ end --@DOC_wibox_layout_fixed_spacing_EXAMPLE@ -- -- @property spacing --- @tparam number spacing Spacing between widgets. +-- @tparam[opt=0] number spacing Spacing between widgets. +-- @negativeallowed true -- @propemits true false -- @interface layout From 13b792e42eb9b37e2d9eab3d3293392c61087388 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 109/134] wibox.layout.flex: Update the property documentation. --- lib/wibox/layout/flex.lua | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index a0c403e6c..08335bcab 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -38,7 +38,7 @@ local flex = {} --- From `wibox.layout.fixed`. -- @property fill_space --- @tparam boolean fill_space +-- @tparam[opt=true] boolean fill_space -- @propemits true false -- @hidden @@ -91,7 +91,7 @@ local flex = {} --@DOC_wibox_layout_flex_spacing_widget_EXAMPLE@ -- -- @property spacing_widget --- @tparam widget spacing_widget +-- @tparam[opt=nil] widget|nil spacing_widget -- @propemits true false -- @interface layout @@ -102,7 +102,9 @@ local flex = {} --@DOC_wibox_layout_flex_spacing_EXAMPLE@ -- -- @property spacing --- @tparam number spacing Spacing between widgets. +-- @tparam[opt=0] number spacing Spacing between widgets. +-- @propertyunit pixel +-- @negativeallowed true -- @propemits true false -- @interface layout @@ -200,7 +202,9 @@ end --That is, maximum width for horizontal and maximum height for vertical. -- -- @property max_widget_size --- @tparam number max_widget_size +-- @tparam[opt=nil] number|nil max_widget_size +-- @propertytype nil No size limit. +-- @negativeallowed false -- @propemits true false function flex:set_max_widget_size(val) From c963b16f90d5e9bf56c1e977f9cf1bacaa70120c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 110/134] wibox.layout.grid: Update the property documentation. --- lib/wibox/layout/grid.lua | 81 ++++++++++++++++++++++++++------------- 1 file changed, 54 insertions(+), 27 deletions(-) diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index e822ec81a..9ef13ffd9 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -40,19 +40,16 @@ local dir_properties = { "spacing", "homogeneous", "expand" } --- Set the preferred orientation of the grid layout. -- --- Allowed values are "horizontal" and "vertical". --- When calling `get_next_empty`, empty cells are browsed differently: --- --- * for "horizontal", the grid can be extended horizontally. The current --- column is filled first; if no empty cell is found up to `forced_num_rows`, --- the next column is filled, creating it if it does not exist. --- --- * for "vertical", the grid can be extended vertically. The current row is --- filled first; if no empty cell is found up to `forced_num_cols`, the next --- row is filled, creating it if it does not exist. +-- When calling `get_next_empty`, empty cells are browsed differently. -- --@DOC_wibox_layout_grid_orientation_EXAMPLE@ --- @tparam[opt="vertical"] string orientation Preferred orientation: "horizontal" or "vertical". +-- @tparam[opt="vertical"] string orientation Preferred orientation. +-- @propertyvalue "horizontal" The grid can be extended horizontally. The current +-- column is filled first; if no empty cell is found up to `forced_num_rows`, +-- the next column is filled, creating it if it does not exist. +-- @propertyvalue "vertical" The grid can be extended vertically. The current row is +-- filled first; if no empty cell is found up to `forced_num_cols`, the next +-- row is filled, creating it if it does not exist. -- @property orientation --- Allow to superpose widgets in the same cell. @@ -65,67 +62,90 @@ local dir_properties = { "spacing", "homogeneous", "expand" } --- Force the number of rows of the layout. -- @property forced_num_rows --- @tparam[opt=nil] number|nil forced_num_rows Forced number of rows (`nil` for automatic). +-- @tparam[opt=nil] number|nil forced_num_rows +-- @propertytype nil Automatically determine the number of rows. +-- @propertyunit rows +-- @negativeallowed false +-- @see forced_num_cols --- Force the number of columns of the layout. -- @property forced_num_cols --- @tparam[opt=nil] number|nil forced_num_cols Forced number of columns (`nil` for automatic). +-- @tparam[opt=nil] number|nil forced_num_cols +-- @propertytype nil Automatically determine the number of columns.' +-- @propertyunit columns +-- @negativeallowed false +-- @see forced_num_rows --- Set the minimum size for the columns. -- --@DOC_wibox_layout_grid_min_size_EXAMPLE@ -- @tparam[opt=0] number min_cols_size Minimum size of the columns. -- @property min_cols_size +-- @propertyunit pixel +-- @negativeallowed false +-- @see min_rows_size --- Set the minimum size for the rows. -- @tparam[opt=0] number min_rows_size Minimum size of the rows. -- @property min_rows_size +-- @propertyunit pixel +-- @negativeallowed false +-- @see min_cols_size --- The spacing between columns. -- --- see `spacing` --- --- @tparam[opt=0] number horizontal_spacing The spacing +-- @tparam[opt=0] number horizontal_spacing -- @property horizontal_spacing +-- @propertyunit pixel +-- @negativeallowed false +-- @see spacing +-- @see vertical_spacing --- The spacing between rows. -- --- see `spacing` --- --- @tparam[opt=0] number vertical_spacing The spacing +-- @tparam[opt=0] number vertical_spacing -- @property vertical_spacing +-- @propertyunit pixel +-- @negativeallowed false +-- @see spacing +-- @see horizontal_spacing --- The spacing between rows and columns. --- Set both `horizontal_spacing` and `vertical_spacing` to the same value. +-- -- Get the value `horizontal_spacing` or `vertical_spacing` defined by the -- preferred `orientation`. -- --@DOC_wibox_layout_grid_spacing_EXAMPLE@ --- @tparam[opt=0] number spacing The spacing +-- @tparam[opt=0] number spacing -- @property spacing +-- @negativeallowed false +-- @see vertical_spacing +-- @see horizontal_spacing --- Controls if the columns are expanded to use all the available width. -- --- see `expand` --- -- @tparam[opt=false] boolean horizontal_expand Expand the grid into the available space -- @property horizontal_expand +-- @see expand +-- @see vertical_expand --- Controls if the rows are expanded to use all the available height. -- --- see `expand` --- -- @tparam[opt=false] boolean vertical_expand Expand the grid into the available space -- @property vertical_expand +-- @see expand +-- @see horizontal_expand --- Controls if the columns/rows are expanded to use all the available space. --- Set both `horizontal_expand` and `vertical_expand` to the same value. +-- -- Get the value `horizontal_expand` or `vertical_expand` defined by the -- preferred `orientation`. -- --@DOC_wibox_layout_grid_expand_EXAMPLE@ -- @tparam[opt=false] boolean expand Expand the grid into the available space -- @property expand +-- @see horizontal_expand +-- @see vertical_expand --- Controls if the columns all have the same width or if the width of each -- column depends on the content. @@ -134,6 +154,8 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- -- @tparam[opt=true] boolean horizontal_homogeneous All the columns have the same width. -- @property horizontal_homogeneous +-- @see vertical_homogeneous +-- @see homogeneous --- Controls if the rows all have the same height or if the height of each row -- depends on the content. @@ -142,6 +164,8 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- -- @tparam[opt=true] boolean vertical_homogeneous All the rows have the same height. -- @property vertical_homogeneous +-- @see homogeneous +-- @see horizontal_homogeneous --- Controls if the columns/rows all have the same size or if the size depends -- on the content. @@ -152,6 +176,9 @@ local dir_properties = { "spacing", "homogeneous", "expand" } --@DOC_wibox_layout_grid_expand_EXAMPLE@ -- @tparam[opt=true] boolean homogeneous All the columns/rows have the same size. -- @property homogeneous +-- @see vertical_homogeneous +-- @see horizontal_homogeneous + --- Child widget position. Return of `get_widget_position`. -- @field row Top row index @@ -863,8 +890,8 @@ end --- Reset the grid layout. -- Remove all widgets and reset row and column counts -- --- **Signal:** widget::reset -- @method reset +-- @emits reset -- @noreturn function grid:reset() self._private.widgets = {} From d05fc5dc8ff98fe2e93032adf4be14b5798a42ea Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 111/134] wibox.layout.ratio: Update the property documentation. --- lib/wibox/layout/ratio.lua | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua index bfc30d523..d960490f8 100644 --- a/lib/wibox/layout/ratio.lua +++ b/lib/wibox/layout/ratio.lua @@ -29,7 +29,7 @@ local ratio = {} --@DOC_wibox_layout_ratio_spacing_widget_EXAMPLE@ -- -- @property spacing_widget --- @tparam widget spacing_widget +-- @tparam[opt=nil] widget|nil spacing_widget -- @propemits true false -- @interface layout @@ -38,7 +38,8 @@ local ratio = {} --@DOC_wibox_layout_ratio_spacing_EXAMPLE@ -- -- @property spacing --- @tparam number spacing Spacing between widgets. +-- @tparam[opt=0] number spacing +-- @negativeallowed true -- @propemits true false -- @interface layout @@ -463,20 +464,17 @@ end --- Set how the space of invisible or `0x0` sized widget is redistributed. -- --- Possible values: --- --- * "default": Honor the ratio and do not redistribute the space. --- * "justify": Distribute the space among remaining widgets. --- * "center": Squash remaining widgets and leave equal space on both side. --- * "inner_spacing": Add equal spacing between all widgets. --- * "spacing": Add equal spacing between all widgets and on the outside. --- * "left": Squash remaining widgets and leave empty space on the left. --- * "right": Squash remaining widgets and leave empty space on the right. --- --@DOC_wibox_layout_ratio_strategy_EXAMPLE@ -- -- @property inner_fill_strategy --- @tparam string inner_fill_strategy One of the value listed above. +-- @tparam[opt="default"] string inner_fill_strategy One of the value listed above. +-- @propertyvalue "default" Honor the ratio and do not redistribute the space. +-- @propertyvalue "justify" Distribute the space among remaining widgets. +-- @propertyvalue "center" Squash remaining widgets and leave equal space on both side. +-- @propertyvalue "inner_spacing" Add equal spacing between all widgets. +-- @propertyvalue "spacing" Add equal spacing between all widgets and on the outside. +-- @propertyvalue "left" Squash remaining widgets and leave empty space on the left. +-- @propertyvalue "right" Squash remaining widgets and leave empty space on the right. -- @propemits true false function ratio:get_inner_fill_strategy() From 926f0ff22f2fc5a0ecc70d84cc3f60d8e3b2fb91 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 112/134] wibox.layout.stack: Update the property documentation. --- lib/wibox/layout/stack.lua | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index 962127f67..82d13c2a8 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -63,7 +63,9 @@ local stack = {mt={}} -- --@DOC_wibox_layout_stack_spacing_EXAMPLE@ -- @property spacing --- @tparam number spacing Spacing between widgets. +-- @tparam[opt=0] number spacing Spacing between widgets. +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @interface layout @@ -100,7 +102,7 @@ end --- If only the first stack widget is drawn. -- -- @property top_only --- @tparam boolean top_only +-- @tparam[opt=false] boolean top_only -- @propemits true false function stack:get_top_only() @@ -158,17 +160,21 @@ end --@DOC_wibox_layout_stack_offset_EXAMPLE@ -- -- @property horizontal_offset --- @tparam number horizontal_offset +-- @tparam[opt=0] number horizontal_offset +-- @propertyunit pixel +-- @negativeallowed true -- @propemits true false --- @see vertial_offset +-- @see vertical_offset --- Add an vertical offset to each layers. -- -- Note that this reduces the overall size of each widgets by the sum of all -- layers offsets. -- --- @property vertial_offset --- @tparam number vertial_offset +-- @property vertical_offset +-- @tparam[opt=0] number vertical_offset +-- @propertyunit pixel +-- @negativeallowed true -- @propemits true false -- @see horizontal_offset From 1259c3ccc6c622b98992dc14c5666efbd5e8fa74 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 113/134] wibox.widget.base: Update the property documentation. --- lib/wibox/widget/base.lua | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index 82759442f..b71b78b86 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -24,8 +24,10 @@ local base = {} --- Get or set the children elements. -- @property children --- @tparam table children The children. +-- @tparam[opt={}] table children +-- @tablerowtype A list of `wibox.widget`. -- @baseclass wibox.widget.base +-- @see all_children --- Get all direct and indirect children widgets. -- This will scan all containers recursively to find widgets @@ -33,34 +35,56 @@ local base = {} -- widgets hierarchy. A hierarchy loop is when a widget, or any of its -- children, contain (directly or indirectly) itself. -- @property all_children --- @tparam table all_children The children. +-- @tparam[opt={}] table all_children +-- @tablerowtype A list of `wibox.widget`. -- @baseclass wibox.widget.base +-- @see children --- Force a widget height. -- @property forced_height --- @tparam number|nil forced_height The height (`nil` for automatic) +-- @tparam[opt=nil] number|nil forced_height +-- @propertyunit pixel +-- @propertytype nil Let the layout decide the height. Usually using the widget +-- native height. +-- @propertytype number Enforce a number of pixels. +-- @rangestart 0 +-- @rangestop 65534 -- @baseclass wibox.widget.base +-- @see forced_width --- Force a widget width. -- @property forced_width --- @tparam number|nil forced_width The width (`nil` for automatic) +-- @tparam[opt=nil] number|nil forced_width +-- @propertyunit pixel +-- @propertytype nil Let the layout decide the width. Usually using the widget +-- native width. +-- @propertytype number Enforce a number of pixels. +-- @rangestart 0 +-- @rangestop 65534 -- @baseclass wibox.widget.base +-- @see forced_height --- The widget opacity (transparency). -- @property opacity --- @tparam[opt=1] number opacity The opacity (between 0 and 1) +-- @tparam[opt=1.0] number opacity +-- @rangestart 0.0 +-- @rangestop 1.0 +-- @propertyunit A gradient between transparent (`0.0`) and opaque (`1.0`). -- @baseclass wibox.widget.base +-- @see visible --- The widget visibility. -- @property visible -- @tparam[opt=true] boolean visible -- @baseclass wibox.widget.base +-- @see opacity --- The widget buttons. -- -- The table contains a list of `awful.button` objects. -- @property buttons --- @tparam table buttons +-- @tparam[opt={}] table buttons +-- @tablerowtype A list of `awful.button`. -- @see awful.button -- @baseclass wibox.widget.base From 1b726985de756569c85f5a72c0ca2958d065efd3 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 114/134] wibox.widget.calendar: Update the property documentation. --- lib/wibox/widget/calendar.lua | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/lib/wibox/widget/calendar.lua b/lib/wibox/widget/calendar.lua index 09bab2b79..c4b541032 100644 --- a/lib/wibox/widget/calendar.lua +++ b/lib/wibox/widget/calendar.lua @@ -4,12 +4,12 @@ -- This module defines two widgets: a month calendar and a year calendar -- -- The two widgets have a `date` property, in the form of --- a table {day=[number|nil], month=[number|nil], year=[number]}. +-- a table `{day=[number|nil], month=[number|nil], year=[number]}`. -- --- The `year` widget displays the whole specified year, e.g. {year=2006}. +-- The `year` widget displays the whole specified year, e.g. `{year=2006}`. -- --- The `month` widget displays the calendar for the specified month, e.g. {month=12, year=2006}, --- highlighting the specified day if the day is provided in the date, e.g. {day=22, month=12, year=2006}. +-- The `month` widget displays the calendar for the specified month, e.g. `{month=12, year=2006}`, +-- highlighting the specified day if the day is provided in the date, e.g. `{day=22, month=12, year=2006}`. -- -- Cell and container styles can be overridden using the `fn_embed` callback function -- which is called before adding the widgets to the layouts. The `fn_embed` function @@ -68,13 +68,12 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" --- The calendar date. -- --- A table representing the date {day=[number|nil], month=[number|nil], year=[number]}. --- --- E.g.. {day=21, month=2, year=2005}, {month=2, year=2005}, {year=2005} --- @tparam table date Date table. +-- E.g.. `{day=21, month=2, year=2005}`, `{month=2, year=2005}, {year=2005}` +-- @tparam[opt=nil] table|nil date -- @tparam number date.year Date year -- @tparam number|nil date.month Date month -- @tparam number|nil date.day Date day +-- @propertytype nil The current date. -- @property date --- The calendar font. @@ -83,7 +82,7 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" -- --@DOC_wibox_widget_calendar_font_EXAMPLE@ -- --- @tparam[opt="Monospace 10"] string font Font of the calendar +-- @tparam[opt="Monospace 10"] font font Font of the calendar -- @property font -- @usebeautiful beautiful.calendar_font @@ -93,6 +92,8 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" -- The spacing between months in a year calendar is twice this value. -- @tparam[opt=5] number spacing Spacing of the grid -- @property spacing +-- @negativeallowed false +-- @propertyunit pixel -- @usebeautiful beautiful.calendar_spacing --- Display the calendar week numbers. @@ -129,7 +130,13 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" -- It is used to add a container to the grid layout and to the cells: -- --@DOC_wibox_widget_calendar_fn_embed_cell_EXAMPLE@ --- @tparam function fn_embed Function to embed the widget depending on its flag +-- @tparam[opt=nil] function|nil fn_embed Function to embed the widget depending on its flag. +-- @functionparam widget widget +-- @functionparam string flag The type of widget. It is one of `"header"`, `"monthheader"`, +-- `"weeknumber"` `"weekday"`, `"focus"`, `"month"` or `"normal"`. +-- @functionparam table date A table with `day`, `month` and `year` keys. +-- @functionreturn widget A new widget to insert into the calendar. +-- @propertytype nil Use an uncustomized `wibox.widget.textbox`. -- @property fn_embed --- Allow cells to have flexible height From ff9c89d005bedf0045e4f7e265d6a66f8e7a29b8 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH 115/134] wibox.widget.checkbox: Update the property documentation. --- lib/wibox/widget/checkbox.lua | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index 099f32e36..0577eb296 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -83,7 +83,9 @@ local checkbox = {} --- The outer (unchecked area) border width. -- -- @property border_width --- @tparam number border_width +-- @tparam number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel -- @propbeautiful -- @propemits true false @@ -91,35 +93,37 @@ local checkbox = {} -- --@DOC_wibox_widget_checkbox_bg_EXAMPLE@ -- @property bg --- @tparam color bg +-- @tparam color|nil bg -- @propbeautiful -- @propemits true false --- The outer (unchecked area) border color. -- -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propbeautiful -- @propemits true false --- The checked part border color. -- -- @property check_border_color --- @tparam color check_border_color +-- @tparam color|nil check_border_color -- @propbeautiful -- @propemits true false --- The checked part border width. -- -- @property check_border_width --- @tparam number check_border_width +-- @tparam number|nil check_border_width -- @propbeautiful +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- The checked part filling color. -- -- @property check_color --- @tparam color check_color +-- @tparam color|nil check_color -- @propbeautiful -- @propemits true false @@ -127,7 +131,7 @@ local checkbox = {} -- --@DOC_wibox_widget_checkbox_shape_EXAMPLE@ -- @property shape --- @tparam gears.shape shape +-- @tparam shape|nil shape -- @propbeautiful -- @propemits true false -- @see gears.shape @@ -137,7 +141,7 @@ local checkbox = {} -- If none is set, then the `shape` property will be used. --@DOC_wibox_widget_checkbox_check_shape_EXAMPLE@ -- @property check_shape --- @tparam gears.shape check_shape +-- @tparam shape|nil check_shape -- @propbeautiful -- @propemits true false -- @see gears.shape @@ -145,11 +149,15 @@ local checkbox = {} --- The padding between the outline and the progressbar. -- -- @property paddings --- @tparam[opt=0] table|number paddings A number or a table +-- @tparam[opt=0] table|number|nil paddings A number or a table -- @tparam[opt=0] number paddings.top -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left -- @tparam[opt=0] number paddings.right +-- @propertyunit pixel +-- @negativeallowed true +-- @propertytype number A single number for all sides. +-- @propertytype table A different value for each sides: -- @propbeautiful -- @propemits false false @@ -159,7 +167,7 @@ local checkbox = {} -- filling color. Note that `check_color` and `border_color` have priority -- over this property. -- @property color --- @tparam color color +-- @tparam color|nil color -- @propbeautiful -- @propemits true false From 8e16dc4412d7fad68731517a25655ef96d53bbf4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 116/134] wibox.widget.graph: Update the property documentation. --- lib/wibox/widget/graph.lua | 44 ++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index 76795ce3e..96fa3d2e5 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -36,7 +36,9 @@ local graph = { mt = {} } --@DOC_wibox_widget_graph_border_width_EXAMPLE@ -- -- @property border_width --- @tparam number border_width +-- @tparam[opt=0] number border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @see border_color @@ -45,7 +47,7 @@ local graph = { mt = {} } --@DOC_wibox_widget_graph_border_color_EXAMPLE@ -- -- @property border_color --- @tparam gears.color border_color The border color to set. +-- @tparam color|nil border_color The border color to set. -- @propbeautiful -- @propemits true false -- @see gears.color @@ -67,7 +69,7 @@ local graph = { mt = {} } --@DOC_wibox_widget_graph_background_color_EXAMPLE@ -- -- @property background_color --- @tparam gears.color background_color The graph background color. +-- @tparam color background_color The graph background color. -- @usebeautiful beautiful.graph_bg -- @propemits true false -- @see gears.color @@ -84,7 +86,8 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_stacked_group_disable_EXAMPLE@ -- -- @property group_colors --- @tparam table group_colors A table with colors for data groups. +-- @tparam[opt=self.color] table group_colors A table with colors for data groups. +-- @tablerowtype List of color values. -- @see gears.color --- The maximum value the graph should handle. @@ -97,7 +100,8 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_max_value_EXAMPLE@ -- -- @property max_value --- @tparam number max_value +-- @tparam[opt=1] number max_value +-- @negativeallowed true -- @propemits true false --- The minimum value the graph should handle. @@ -110,10 +114,11 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_min_value_EXAMPLE@ -- -- @property min_value --- @tparam number min_value +-- @tparam[opt=0] number min_value +-- @negativeallowed true -- @propemits true false ---- Set the graph to automatically scale its values. Default is false. +--- Set the graph to automatically scale its values. -- -- If this property is set to true, the graph calculates -- effective `min_value` and `max_value` based on the displayed data, @@ -126,7 +131,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_scale1_EXAMPLE@ -- -- @property scale --- @tparam boolean scale +-- @tparam[opt=false] boolean scale -- @propemits true false --- Clamp graph bars to keep them inside the widget for out-of-range values. @@ -144,15 +149,16 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_clamp_bars_EXAMPLE@ -- -- @property clamp_bars --- @tparam boolean clamp_bars +-- @tparam[opt=false] boolean clamp_bars -- @propemits true false ---- The value corresponding to the starting point of graph bars. Default is 0. +--- The value corresponding to the starting point of graph bars. -- -- @DOC_wibox_widget_graph_baseline_value_EXAMPLE@ -- -- @property baseline_value --- @tparam number baseline_value +-- @tparam[opt=0] number baseline_value +-- @negativeallowed true -- @propemits true false --- Set the width or the individual steps. @@ -161,6 +167,8 @@ local graph = { mt = {} } -- -- @property step_width -- @tparam[opt=1] number step_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false --- Set the spacing between the steps. @@ -169,6 +177,8 @@ local graph = { mt = {} } -- -- @property step_spacing -- @tparam[opt=0] number step_spacing +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false --- The step shape. @@ -176,7 +186,7 @@ local graph = { mt = {} } --@DOC_wibox_widget_graph_step_shape_EXAMPLE@ -- -- @property step_shape --- @tparam[opt=rectangle] gears.shape|function step_shape +-- @tparam[opt=gears.rect.rectangle] shape step_shape -- @propemits true false -- @see gears.shape @@ -190,7 +200,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_normal_vs_stacked_EXAMPLE@ -- -- @property stack --- @tparam boolean stack +-- @tparam[opt=false] boolean stack -- @propemits true false --- Display NaN indication. Default is true. @@ -205,7 +215,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_nan_color_EXAMPLE@ -- -- @property nan_indication --- @tparam boolean nan_indication +-- @tparam[opt=true] boolean nan_indication -- @propemits true false --- The color of NaN indication. @@ -216,7 +226,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_stacked_nan_EXAMPLE@ -- -- @property nan_color --- @tparam gears.color nan_color The color of NaN indication. +-- @tparam[opt="#ffff00"] color nan_color The color of NaN indication. -- @propemits true false -- @see gears.color @@ -377,7 +387,7 @@ end -- -- @method pick_data_group_color -- @tparam number group_idx The index of the data group. --- @treturn gears.color The color to paint the data group's values with. +-- @treturn color The color to paint the data group's values with. function graph:pick_data_group_color(group_idx) -- Use an individual group color, if there's one local data_group_colors = self._private.group_colors @@ -787,6 +797,8 @@ end -- @property capacity -- @tparam[opt=nil] integer|nil capacity The maximum number of values to keep -- per data group (`nil` for automatic guess). +-- @negativeallowed false +-- @propertyunit Number of value. -- @propemits true false function graph:set_capacity(capacity) -- Property override to avoid emitting the "redraw_needed" signal, From 95cd45942ae75dd1762281f9d69614f08047d9df Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 117/134] wibox.widget.imagebox: Update the property documentation. --- lib/wibox/widget/imagebox.lua | 59 +++++++++++++---------------------- 1 file changed, 22 insertions(+), 37 deletions(-) diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index 6473ef9c9..79b6f710b 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -296,15 +296,8 @@ end --- The image rendered by the `imagebox`. -- --- It can can be any of the following: --- --- * A `string`: Interpreted as a path to an image file --- * A cairo image surface: Directly used as-is --- * A librsvg handle object: Directly used as-is --- * `nil`: Unset the image. --- -- @property image --- @tparam[opt=nil] image image The image to render. +-- @tparam[opt=nil] image|nil image -- @propemits false false --- Set the `imagebox` image. @@ -370,7 +363,7 @@ end -- @DOC_wibox_widget_imagebox_clip_shape_EXAMPLE@ -- -- @property clip_shape --- @tparam[opt=nil] function|gears.shape clip_shape A `gears.shape` compatible shape function. +-- @tparam[opt=gears.shape.rectangle] shape clip_shape A `gears.shape` compatible shape function. -- @propemits true false -- @see gears.shape @@ -456,6 +449,7 @@ end -- -- @property dpi -- @tparam[opt=96] number|table dpi +-- @negativeallowed false -- @propemits true false -- @see auto_dpi @@ -516,38 +510,30 @@ end --- Set the horizontal fit policy. -- --- Valid values are: --- --- * `"auto"`: Honor the `resize` variable and preserve the aspect ratio. --- This is the default behaviour. --- * `"none"`: Do not resize at all. --- * `"fit"`: Resize to the widget width. --- -- Here is the result for a 22x32 image: -- -- @DOC_wibox_widget_imagebox_horizontal_fit_policy_EXAMPLE@ -- -- @property horizontal_fit_policy -- @tparam[opt="auto"] string horizontal_fit_policy +-- @propertyvalue "auto" Honor the `resize` variable and preserve the aspect ratio. +-- @propertyvalue "none" Do not resize at all. +-- @propertyvalue "fit" Resize to the widget width. -- @propemits true false -- @see vertical_fit_policy -- @see resize --- Set the vertical fit policy. -- --- Valid values are: --- --- * `"auto"`: Honor the `resize` varible and preserve the aspect ratio. --- This is the default behaviour. --- * `"none"`: Do not resize at all. --- * `"fit"`: Resize to the widget height. --- -- Here is the result for a 32x22 image: -- -- @DOC_wibox_widget_imagebox_vertical_fit_policy_EXAMPLE@ -- -- @property vertical_fit_policy -- @tparam[opt="auto"] string vertical_fit_policy +-- @propertyvalue "auto" Honor the `resize` variable and preserve the aspect ratio. +-- @propertyvalue "none" Do not resize at all. +-- @propertyvalue "fit" Resize to the widget height. -- @propemits true false -- @see horizontal_fit_policy -- @see resize @@ -555,32 +541,26 @@ end --- The vertical alignment. -- --- Possible values are: --- --- * `"top"` --- * `"center"` (default) --- * `"bottom"` --- -- @DOC_wibox_widget_imagebox_valign_EXAMPLE@ -- -- @property valign -- @tparam[opt="center"] string valign +-- @propertyvalue "top" +-- @propertyvalue "center" +-- @propertyvalue "bottom" -- @propemits true false -- @see wibox.container.place -- @see halign --- The horizontal alignment. -- --- Possible values are: --- --- * `"left"` --- * `"center"` (default) --- * `"right"` --- -- @DOC_wibox_widget_imagebox_halign_EXAMPLE@ -- -- @property halign -- @tparam[opt="center"] string halign +-- @propertyvalue "left" +-- @propertyvalue "center" +-- @propertyvalue "right" -- @propemits true false -- @see wibox.container.place -- @see valign @@ -598,6 +578,7 @@ end -- -- @property max_scaling_factor -- @tparam[opt=0] number max_scaling_factor Use `0` for "no limit". +-- @negativeallowed false -- @propemits true false -- @see valign -- @see halign @@ -629,8 +610,12 @@ end -- @DOC_wibox_widget_imagebox_scaling_quality_EXAMPLE@ -- -- @property scaling_quality --- @tparam[op="fast"] string scaling_quality Either `"fast"`, `"good"`, `"best"`, --- `"nearest"` or `"bilinear"`. +-- @tparam[opt="good"] string scaling_quality +-- @propertyvalue "fast" A high-performance filter. +-- @propertyvalue "good" A reasonable-performance filter. +-- @propertyvalue "best" The highest-quality available. +-- @propertyvalue "nearest" Nearest-neighbor filtering (blocky). +-- @propertyvalue "bilinear" Linear interpolation in two dimensions. -- @propemits true false -- @see resize -- @see horizontal_fit_policy From e63d8675237532fa0084a6031da536e3ac513a6c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 118/134] wibox.widget.piechart: Update the property documentation. --- lib/wibox/widget/piechart.lua | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 0642ead31..79140ff67 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -140,15 +140,22 @@ end --- The pie chart data list. -- -- @property data_list --- @tparam[opt={}] table data_list Sorted table where each entry has a label as its +-- @tparam[opt={}] table data_list +-- @tablerowtype Sorted list where each entry has a label as its -- first value and a number as its second value. +-- @tablerowkey string 1 The label. +-- @tablerowkey number 2 The value. -- @propemits false false --- The pie chart data. -- -- @property data --- @tparam table data Labels as keys and number as value. +-- @tparam[opt={}] table data +-- @tablerowtype Key/value pair. +-- @tablerowkey string key The label. +-- @tablerowkey number value The value. -- @propemits false false +-- @see data_list --- The border color. -- @@ -156,7 +163,7 @@ end -- --@DOC_wibox_widget_piechart_border_color_EXAMPLE@ -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propemits true false -- @propbeautiful -- @see gears.color @@ -165,7 +172,9 @@ end -- --@DOC_wibox_widget_piechart_border_width_EXAMPLE@ -- @property border_width --- @tparam[opt=1] number border_width +-- @tparam[opt=1] number|nil border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @propbeautiful @@ -175,7 +184,8 @@ end -- required are set, colors will be re-used in order. -- -- @property colors --- @tparam table colors A table of colors, one for each elements. +-- @tparam table|nil colors A table of colors, one for each elements. +-- @propertytype table List of colors (numerical keys). -- @propemits true false -- @propbeautiful -- @see gears.color @@ -192,6 +202,7 @@ end --@DOC_wibox_widget_piechart_label_EXAMPLE@ -- @property display_labels -- @tparam[opt=true] boolean display_labels +-- @propemits true false --- The pie elements border width. -- From f9f04866b8f7a5f29a883c4e052d387aaa2702e9 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 119/134] wibox.widget.progressbar: Update the property documentation. --- lib/wibox/widget/progressbar.lua | 57 +++++++++++++++++++++++++------- 1 file changed, 45 insertions(+), 12 deletions(-) diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index be64eabd1..c34ce3801 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -54,7 +54,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_border_color_EXAMPLE@ -- -- @property border_color --- @tparam gears.color border_color The border color to set. +-- @tparam color|nil border_color The border color to set. -- @propemits true false -- @propbeautiful -- @see gears.color @@ -64,7 +64,12 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_border_width_EXAMPLE@ -- -- @property border_width --- @tparam number border_width +-- @tparam number|nil border_width +-- @propertytype nil Defaults to `beautiful.progressbar_border_width`. +-- @propertytype number The number of pixels +-- @propertyunit pixel +-- @negativeallowed false +-- @propbeautiful -- @propemits true false -- @propbeautiful @@ -75,7 +80,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_bar_border_color_EXAMPLE@ -- -- @property bar_border_color --- @tparam gears.color bar_border_color The border color to set. +-- @tparam color|nil bar_border_color The border color to set. -- @propemits true false -- @propbeautiful -- @see gears.color @@ -85,8 +90,12 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_bar_border_width_EXAMPLE@ -- -- @property bar_border_width --- @tparam number bar_border_width +-- @tparam number|nil bar_border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful +-- @usebeautiful beautiful.progressbar_border_width Fallback when +-- `beautiful.progressbar_bar_border_width` isn't set. -- @propemits true false --- The progressbar foreground color. @@ -94,7 +103,8 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_color_EXAMPLE@ -- -- @property color --- @tparam gears.color color The progressbar color. +-- @tparam color|nil color The progressbar color. +-- @propertytype nil Fallback to the current value of `beautiful.progressbar_fg`. -- @propemits true false -- @usebeautiful beautiful.progressbar_fg -- @see gears.color @@ -104,7 +114,8 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_background_color_EXAMPLE@ -- -- @property background_color --- @tparam gears.color background_color The progressbar background color. +-- @tparam color|nil background_color The progressbar background color. +-- @propertytype nil Fallback to the current value of `beautiful.progressbar_bg`. -- @propemits true false -- @usebeautiful beautiful.progressbar_bg -- @see gears.color @@ -114,7 +125,7 @@ local progressbar = { mt = {} } --@DOC_wibox_widget_progressbar_bar_shape_EXAMPLE@ -- -- @property bar_shape --- @tparam[opt=gears.shape.rectangle] gears.shape bar_shape +-- @tparam shape|nil bar_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -124,7 +135,7 @@ local progressbar = { mt = {} } --@DOC_wibox_widget_progressbar_shape_EXAMPLE@ -- -- @property shape --- @tparam[opt=gears.shape.rectangle] gears.shape shape +-- @tparam shape|nil shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -147,11 +158,15 @@ local progressbar = { mt = {} } --- The progressbar to draw ticks. -- +-- The add a little bar in between the values. +-- -- @DOC_wibox_widget_progressbar_ticks_EXAMPLE@ -- -- @property ticks -- @tparam[opt=false] boolean ticks -- @propemits true false +-- @see ticks_gap +-- @see ticks_size --- The progressbar ticks gap. -- @@ -159,7 +174,11 @@ local progressbar = { mt = {} } -- -- @property ticks_gap -- @tparam[opt=1] number ticks_gap +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false +-- @see ticks_size +-- @see ticks --- The progressbar ticks size. -- @@ -171,7 +190,11 @@ local progressbar = { mt = {} } -- -- @property ticks_size -- @tparam[opt=4] number ticks_size +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false +-- @see ticks_gap +-- @see ticks --- The maximum value the progressbar should handle. -- @@ -182,6 +205,7 @@ local progressbar = { mt = {} } -- -- @property max_value -- @tparam[opt=1] number max_value +-- @negativeallowed true -- @propemits true false -- @see value @@ -198,7 +222,7 @@ local progressbar = { mt = {} } --- The progressbar shape. -- -- @beautiful beautiful.progressbar_shape --- @tparam gears.shape shape +-- @tparam[opt=gears.shape.rectangle] shape shape -- @see gears.shape --- The progressbar border color. @@ -214,7 +238,7 @@ local progressbar = { mt = {} } --- The progressbar inner shape. -- -- @beautiful beautiful.progressbar_bar_shape --- @tparam gears.shape shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The progressbar bar border width. @@ -248,6 +272,10 @@ local progressbar = { mt = {} } -- @tparam[opt=0] number margins.bottom -- @tparam[opt=0] number margins.left -- @tparam[opt=0] number margins.right +-- @propertyunit pixel +-- @negativeallowed true +-- @propertytype number Use the same value for each side. +-- @propertytype table Use a different value for each side: -- @propemits false false -- @propbeautiful -- @see clip @@ -268,11 +296,15 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_paddings1_EXAMPLE@ -- -- @property paddings --- @tparam[opt=0] (table|number|nil) paddings A table for each side or a number +-- @tparam[opt=0] table|number|nil paddings A table for each side or a number -- @tparam[opt=0] number paddings.top -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left -- @tparam[opt=0] number paddings.right +-- @propertyunit pixel +-- @negativeallowed true +-- @propertytype number Use the same value for each side. +-- @propertytype table Use a different value for each side: -- @propemits false false -- @propbeautiful -- @see clip @@ -519,7 +551,8 @@ end -- @DOC_wibox_widget_progressbar_value_EXAMPLE@ -- -- @property value --- @tparam[opt=0] number value The progress bar value. +-- @tparam[opt=0] number value +-- @negativeallowed true -- @propemits true false -- @see max_value From 79496e9accd6b71bcba1dd7fcd6646bd13b96656 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 120/134] wibox.widget.separator: Update the property documentation. --- lib/wibox/widget/separator.lua | 36 +++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index aff0c99f9..3d13cb881 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -31,12 +31,6 @@ local separator = {} --- The separator's orientation. -- --- Valid values are: --- --- * *vertical*: From top to bottom --- * *horizontal*: From left to right --- * *auto*: Decide depending on the widget geometry (default) --- -- The default value is selected automatically. If the widget is taller than -- large, it will use vertical and vice versa. -- @@ -44,6 +38,9 @@ local separator = {} -- -- @property orientation -- @tparam[opt="auto"] string orientation +-- @propertyvalue "vertical" From top to bottom. +-- @propertyvalue "horizontal" From left to right. +-- @propertyvalue "auto" Decide depending on the widget geometry. -- @propemits true false --- The separator's thickness. @@ -51,7 +48,9 @@ local separator = {} -- This is used by the default line separator, but ignored when a shape is used. -- -- @property thickness --- @tparam number thickness +-- @tparam number|nil thickness +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful -- @propemits true false @@ -60,7 +59,7 @@ local separator = {} --@DOC_wibox_widget_separator_shape_EXAMPLE@ -- -- @property shape --- @tparam function shape A valid shape function +-- @tparam shape|nil shape A valid shape function -- @propbeautiful -- @propemits true false -- @see gears.shape @@ -68,13 +67,16 @@ local separator = {} --- The relative percentage covered by the bar. -- -- @property span_ratio --- @tparam[opt=1] number span_ratio A number between 0 and 1. +-- @tparam[opt=1] number|nil span_ratio +-- @rangestart 0.0 +-- @rangestop 1.0 +-- @propertyunit A gradient between "small" (0.0) and "full width/height" (1.0). -- @propbeautiful -- @propemits true false --- The separator's color. -- @property color --- @tparam color color +-- @tparam color|nil color -- @propbeautiful -- @propemits true false -- @see gears.color @@ -84,20 +86,22 @@ local separator = {} --@DOC_wibox_widget_separator_border_color_EXAMPLE@ -- -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propbeautiful -- @propemits true false -- @see gears.color --- The separator's border width. -- @property border_width --- @tparam number border_width +-- @tparam number|nil border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful -- @propemits true false --- The separator thickness. -- @beautiful beautiful.separator_thickness --- @param number +-- @tparam[opt=1] number separator_thickness -- @see thickness --- The separator border color. @@ -107,7 +111,7 @@ local separator = {} --- The separator border width. -- @beautiful beautiful.separator_border_width --- @param number +-- @tparam[opt=0] number separator_border_width -- @see border_width --- The relative percentage covered by the bar. @@ -116,13 +120,13 @@ local separator = {} --- The separator's color. -- @beautiful beautiful.separator_color --- @param string +-- @param color -- @see gears.color --- The separator's shape. -- -- @beautiful beautiful.separator_shape --- @tparam function shape A valid shape function +-- @tparam[opt=gears.shape.rectangle] shape shape A valid shape function -- @see gears.shape local function draw_shape(self, _, cr, width, height, shape) From 53675136098f82a0f80b8f44cd571ad094ef1ec6 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 121/134] wibox.widget.slider: Update the property documentation. --- lib/wibox/widget/slider.lua | 65 ++++++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 23 deletions(-) diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua index 4244bdf1b..e397f45c7 100644 --- a/lib/wibox/widget/slider.lua +++ b/lib/wibox/widget/slider.lua @@ -30,7 +30,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_shape_EXAMPLE@ -- -- @property handle_shape --- @tparam[opt=gears shape rectangle] gears.shape handle_shape +-- @tparam shape|nil handle_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -41,7 +41,7 @@ local slider = {mt={}} -- -- @property handle_color -- @propbeautiful --- @tparam color handle_color +-- @tparam color|nil handle_color -- @propemits true false --- The slider handle margins. @@ -49,11 +49,15 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_margins_EXAMPLE@ -- -- @property handle_margins --- @tparam[opt={}] table handle_margins --- @tparam[opt=0] number margins.left --- @tparam[opt=0] number margins.right --- @tparam[opt=0] number margins.top --- @tparam[opt=0] number margins.bottom +-- @tparam[opt={}] table|number|nil handle_margins +-- @tparam[opt=0] number handle_margins.left +-- @tparam[opt=0] number handle_margins.right +-- @tparam[opt=0] number handle_margins.top +-- @tparam[opt=0] number handle_margins.bottom +-- @propertyunit pixel +-- @propertytype number A single value used for all sides. +-- @propertytype table A different value for each side. The side names are: +-- @negativeallowed true -- @propemits true false -- @propbeautiful @@ -62,7 +66,9 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_width_EXAMPLE@ -- -- @property handle_width --- @tparam number handle_width +-- @tparam number|nil handle_width +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @propbeautiful @@ -71,13 +77,15 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_border_EXAMPLE@ -- -- @property handle_border_color --- @tparam color handle_border_color +-- @tparam color|nil handle_border_color -- @propemits true false -- @propbeautiful --- The handle border width. -- @property handle_border_width --- @tparam[opt=0] number handle_border_width +-- @tparam[opt=0] number|nil handle_border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @propbeautiful @@ -86,7 +94,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_shape_EXAMPLE@ -- -- @property bar_shape --- @tparam[opt=gears shape rectangle] gears.shape bar_shape +-- @tparam shape|nil bar_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -96,7 +104,9 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_height_EXAMPLE@ -- -- @property bar_height --- @tparam number bar_height +-- @tparam number|nil bar_height +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful -- @propemits true false @@ -105,7 +115,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_color_EXAMPLE@ -- -- @property bar_color --- @tparam color bar_color +-- @tparam color|nil bar_color -- @propbeautiful -- @propemits true false @@ -115,7 +125,7 @@ local slider = {mt={}} -- -- Only works when both `bar_active_color` and `bar_color` are passed as hex color string -- @property bar_active_color --- @tparam color bar_active_color +-- @tparam color|nil bar_active_color -- @propbeautiful -- @propemits true false @@ -124,17 +134,23 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_margins_EXAMPLE@ -- -- @property bar_margins --- @tparam[opt={}] table bar_margins --- @tparam[opt=0] number margins.left --- @tparam[opt=0] number margins.right --- @tparam[opt=0] number margins.top --- @tparam[opt=0] number margins.bottom +-- @tparam[opt={}] table|number|nil bar_margins +-- @tparam[opt=0] number bar_margins.left +-- @tparam[opt=0] number bar_margins.right +-- @tparam[opt=0] number bar_margins.top +-- @tparam[opt=0] number bar_margins.bottom +-- @propertyunit pixel +-- @propertytype number A single value used for all sides. +-- @propertytype table A different value for each side. The side names are: +-- @negativeallowed true -- @propbeautiful -- @propemits true false --- The bar (background) border width. -- @property bar_border_width --- @tparam[opt=0] number bar_border_width +-- @tparam[opt=0] number|nil bar_border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @propbeautiful @@ -143,7 +159,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_border_EXAMPLE@ -- -- @property bar_border_color --- @tparam color bar_border_color +-- @tparam color|nil bar_border_color -- @propbeautiful -- @propemits true false @@ -153,18 +169,21 @@ local slider = {mt={}} -- -- @property value -- @tparam[opt=0] number value +-- @negativeallowed true -- @propemits true false --- The slider minimum value. -- -- @property minimum -- @tparam[opt=0] number minimum +-- @negativeallowed true -- @propemits true false --- The slider maximum value. -- -- @property maximum -- @tparam[opt=100] number maximum +-- @negativeallowed true -- @propemits true false --- The bar (background) border width. @@ -200,13 +219,13 @@ local slider = {mt={}} --- The handle shape. -- -- @beautiful beautiful.slider_handle_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The bar (background) shape. -- -- @beautiful beautiful.slider_bar_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The bar (background) height. From 642fa3b66bb801b8815fbc1e517fde0f95627033 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 122/134] wibox.widget.systray: Update the property documentation. --- lib/wibox/widget/systray.lua | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua index 37d7596c1..e41e7b2c6 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -148,7 +148,11 @@ end -- available space. Otherwise, any single icon has a size of `size`x`size`. -- -- @property base_size --- @tparam[opt=nil] integer|nil base_size The base size +-- @tparam[opt=nil] integer|nil base_size +-- @propertytype integer The size. +-- @propertytype nil Select the size based on the availible space. +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false function systray:set_base_size(size) @@ -162,7 +166,7 @@ end --- Decide between horizontal or vertical display. -- -- @property horizontal --- @tparam[opt=true] boolean horizontal Use horizontal mode? +-- @tparam[opt=true] boolean horizontal -- @propemits true false function systray:set_horizontal(horiz) @@ -176,7 +180,7 @@ end --- Should the systray icons be displayed in reverse order? -- -- @property reverse --- @tparam[opt=false] boolean reverse Display in reverse order. +-- @tparam[opt=false] boolean reverse -- @propemits true false function systray:set_reverse(rev) @@ -194,7 +198,9 @@ end -- visible on the primary screen. The default value is "primary". -- -- @property screen --- @tparam[opt=nil] screen|"primary" screen The screen to display on. +-- @tparam[opt=nil] screen|nil screen +-- @propertytype nil Valid as long as the `systray` widget is only being displayed +-- on a single screen. -- @propemits true false function systray:set_screen(s) From 1eda8cdf9305f0e50c4cc98f78f98dd163545859 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 123/134] wibox.widget.textbox: Update the property documentation. --- lib/wibox/widget/textbox.lua | 46 +++++++++++++----------------------- 1 file changed, 17 insertions(+), 29 deletions(-) diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index 8996b21c4..41a76e053 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -240,20 +240,17 @@ end --- Set the text ellipsize mode. -- --- Valid values are: --- --- * `"start"` --- * `"middle"` --- * `"end"` --- * `"none"` --- -- See Pango for additional details: -- [Layout.set_ellipsize](https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html) -- --@DOC_wibox_widget_textbox_ellipsize_EXAMPLE@ -- -- @property ellipsize --- @tparam[opt="end"] string ellipsize The ellipsize mode. +-- @tparam[opt="end"] string ellipsize +-- @propertyvalue "start" +-- @propertyvalue "middle" +-- @propertyvalue "end" +-- @propertyvalue "none" -- @propemits true false function textbox:set_ellipsize(mode) @@ -271,16 +268,13 @@ end --- Set a textbox wrap mode. -- --- Valid values are: --- --- * **word** --- * **char** --- * **word_char** --- -- @DOC_wibox_widget_textbox_wrap1_EXAMPLE@ -- -- @property wrap -- @tparam[opt="word_char"] string wrap Where to wrap? After "word", "char" or "word_char". +-- @propertyvalue "word" +-- @propertyvalue "char" +-- @propertyvalue "word_char" -- @propemits true false function textbox:set_wrap(mode) @@ -301,16 +295,13 @@ end -- This aligns the text within the widget's bounds. In some situations this may -- differ from aligning the widget with `wibox.container.place`. -- --- Valid values are: --- --- * `"top"` --- * `"center"` --- * `"bottom"` --- --@DOC_wibox_widget_textbox_valign1_EXAMPLE@ -- -- @property valign --- @tparam[opt="center"] string valign The vertical alignment +-- @tparam[opt="center"] string valign +-- @propertyvalue "top" +-- @propertyvalue "center" +-- @propertyvalue "bottom" -- @propemits true false function textbox:set_valign(mode) @@ -331,16 +322,13 @@ end -- This aligns the text within the widget's bounds. In some situations this may -- differ from aligning the widget with `wibox.container.place`. -- --- Valid values are: --- --- * `"left"` --- * `"center"` --- * `"right"` --- --@DOC_wibox_widget_textbox_align1_EXAMPLE@ -- -- @property align --- @tparam[opt="left"] string align The horizontal alignment +-- @tparam[opt="left"] string align +-- @propertyvalue "left" +-- @propertyvalue "center" +-- @propertyvalue "right" -- @propemits true false function textbox:set_align(mode) @@ -398,7 +386,7 @@ end --@DOC_wibox_widget_textbox_font2_EXAMPLE@ -- -- @property font --- @tparam[opt=beautiful.font] string font The font description as string. +-- @tparam[opt=beautiful.font] font font -- @propemits true false -- @usebeautiful beautiful.font The default font. From a18b40e12b4b8f9de78da885894052cce6c6d903 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 124/134] wibox.widget.textclock: Update the property documentation. --- lib/wibox/widget/textclock.lua | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 13fe21fa9..94c27f9fe 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -102,6 +102,8 @@ end -- -- @property refresh -- @tparam[opt=60] number refresh How often the clock is updated, in seconds +-- @propertyunit second +-- @negativeallowed false function textclock:set_refresh(refresh) self._private.refresh = refresh or self._private.refresh From b662bf772f0bba3d465e5edab4302534ee3b4807 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 125/134] mouse: Update the property documentation. --- mouse.c | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/mouse.c b/mouse.c index 8bd81aa41..bce3d33a4 100644 --- a/mouse.c +++ b/mouse.c @@ -76,7 +76,15 @@ static int miss_newindex_handler = LUA_REFNIL; /** * The `screen` under the cursor * @property screen - * @tparam screen screen + * @tparam screen|nil screen + * @propertytype nil This will only happen if `screen` is set to `off` in the + * modeline or command line options. It happens very early in the initialization + * before the screens are created. If you check the screen from a signal, then + * you should never have to worry about this. Another corner case where this + * *might* happen is if you use `fake_resize` to have a smaller area than the + * physical screen. + * @propertydefault It checks where the cursor is and match it to one of the + * screen `geometry`. */ /** Get the pointer position. From 34f936b646623a2a7262839d5d2b247a429fc07a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 126/134] objects.client: Update the property documentation. --- objects/client.c | 174 +++++++++++++++++++++++++++++------------------ 1 file changed, 109 insertions(+), 65 deletions(-) diff --git a/objects/client.c b/objects/client.c index 8b35b7d97..6bd8df267 100644 --- a/objects/client.c +++ b/objects/client.c @@ -455,6 +455,8 @@ lua_class_t client_class; * * @property window * @tparam integer window + * @propertydefault This is generated by X11. + * @negativeallowed false * @propemits false false * @readonly */ @@ -467,6 +469,7 @@ lua_class_t client_class; * * @property name * @tparam string name + * @propertydefault This is provided by the application. * @propemits false false * @see awful.titlebar * @see awful.widget.tasklist @@ -530,6 +533,7 @@ lua_class_t client_class; * @property type * @tparam string type * @propemits false false + * @propertydefault This is provided by the application. * @readonly * @see ruled.client */ @@ -559,6 +563,7 @@ lua_class_t client_class; * @property class * @tparam string class * @propemits false false + * @propertydefault This is provided by the application. * @readonly * @see instance * @see ruled.client @@ -585,6 +590,7 @@ lua_class_t client_class; * * @property instance * @tparam string instance + * @propertydefault This is provided by the application. * @propemits false false * @readonly * @see class @@ -598,6 +604,8 @@ lua_class_t client_class; * * @property pid * @tparam integer pid + * @negativeallowed false + * @propertydefault This is randomly assigned by the kernel. * @propemits false false * @readonly */ @@ -607,6 +615,7 @@ lua_class_t client_class; * * @property role * @tparam string role + * @propertydefault This is provided by the application. * @propemits false false * @readonly * @see instance @@ -628,6 +637,8 @@ lua_class_t client_class; * * @property machine * @tparam string machine + * @propertydefault This is the hostname unless the client is from an + * SSH session or using the rarely used direct X11 network socket. * @propemits false false * @readonly */ @@ -637,6 +648,7 @@ lua_class_t client_class; * * @property icon_name * @tparam string icon_name + * @propertydefault This is provided by the application. * @propemits false false * @readonly */ @@ -668,7 +680,8 @@ lua_class_t client_class; * smallest available) * * @property icon - * @tparam surface icon + * @tparam image icon + * @propertydefault This is provided by the application. * @propemits false false * @usage local ib = wibox.widget.imagebox(c.icon) * @see awful.widget.clienticon @@ -688,6 +701,10 @@ lua_class_t client_class; * * @property icon_sizes * @tparam table icon_sizes + * @tablerowtype A list of tables. Each table has the following rows: + * @tablerowkey integer 1 The width value. + * @tablerowkey integer 2 The height value. + * @propertydefault This is provided by the application. * @propemits false false * @readonly * @see awful.widget.clienticon @@ -709,6 +726,8 @@ lua_class_t client_class; * * @property screen * @tparam screen screen + * @propertydefault This usually correspond to where the top-left (or other + * gravities) is placed. Then it is mapped to the screen `geometry`. * @propemits false false * @see move_to_screen */ @@ -717,7 +736,7 @@ lua_class_t client_class; * Define if the client must be hidden (Never mapped, invisible in taskbar). * * @property hidden - * @tparam boolean hidden + * @tparam[opt=false] boolean hidden * @propemits false false * @see minimized * @see skip_taskbar @@ -736,7 +755,7 @@ lua_class_t client_class; * @DOC_sequences_client_minimize1_EXAMPLE@ * * @property minimized - * @tparam boolean minimized + * @tparam[opt=false] boolean minimized * @propemits false false * @see hidden * @see isvisible @@ -753,7 +772,7 @@ lua_class_t client_class; * This is enabled by default. To disable it by default, see `ruled.client`. * * @property size_hints_honor - * @tparam boolean size_hints_honor + * @tparam[opt=true] boolean size_hints_honor * @propemits false false * @see size_hints */ @@ -771,7 +790,10 @@ lua_class_t client_class; * @DOC_awful_client_border_width_EXAMPLE@ * * @property border_width - * @tparam integer border_width + * @tparam[opt=nil] integer|nil border_width + * @propertytype nil Let AwesomeWM manage it based on the client state. + * @negativeallowed false + * @propertyunit pixel * @propemits false false * @usebeautiful beautiful.border_width_active * @usebeautiful beautiful.border_width_normal @@ -812,8 +834,9 @@ lua_class_t client_class; * specifically. Other RGB colors with an alpha of `0` won't work. * * @property border_color - * @tparam color border_color Any string, gradient or pattern definition that - * can be converted to a cairo pattern. + * @tparam[opt=nil] color|nil border_color + * @propertytype nil Let AwesomeWM manage it based on the client state. + * @propertydefault * @propemits false false * @usebeautiful beautiful.border_color_marked The fallback color when the * client is marked. @@ -872,7 +895,7 @@ lua_class_t client_class; * @DOC_awful_client_urgent1_EXAMPLE@ * * @property urgent - * @tparam boolean urgent + * @tparam[opt=false] boolean urgent * @propemits false false * @request client border active granted When a client becomes active and is no * longer urgent. @@ -929,7 +952,9 @@ lua_class_t client_class; * This property has no signals when the content changes. * * @property content - * @tparam surface content + * @tparam raw_curface content + * @propertydefault This is a live surface. Always use `gears.surface` to take + * a snapshot. * @readonly * @see gears.surface */ @@ -944,7 +969,9 @@ lua_class_t client_class; * @DOC_awful_client_opacity1_EXAMPLE@ * * @property opacity - * @tparam number opacity Between 0 (transparent) to 1 (opaque). + * @tparam[opt=1.0] number opacity + * @rangestart 0.0 Transparent. + * @rangestop 1.0 Opaque. * @propemits false false * @see request::border * @see awesome.composite_manager_running @@ -954,7 +981,7 @@ lua_class_t client_class; * The client is on top of every other windows. * * @property ontop - * @tparam boolean ontop + * @tparam[opt=false] boolean ontop * @propemits false false * @see below * @see above @@ -964,7 +991,7 @@ lua_class_t client_class; * The client is above normal windows. * * @property above - * @tparam boolean above + * @tparam[opt=false] boolean above * @propemits false false * @see below * @see ontop @@ -974,7 +1001,7 @@ lua_class_t client_class; * The client is below normal windows. * * @property below - * @tparam boolean below + * @tparam[opt=false] boolean below * @propemits false false * @see above * @see ontop @@ -986,7 +1013,7 @@ lua_class_t client_class; * @DOC_sequences_client_fullscreen_EXAMPLE@ * * @property fullscreen - * @tparam boolean fullscreen + * @tparam[opt=false] boolean fullscreen * @propemits false false * @request client geometry fullscreen granted When the client must be resized * because it became (or stop being) fullscreen. @@ -1004,7 +1031,7 @@ lua_class_t client_class; * @DOC_sequences_client_maximized_EXAMPLE@ * * @property maximized - * @tparam boolean maximized + * @tparam[opt=false] boolean maximized * @propemits false false * @request client geometry maximized granted When the client must be resized * because it became (or stop being) maximized. @@ -1022,7 +1049,7 @@ lua_class_t client_class; * @DOC_sequences_client_maximized_horizontal_EXAMPLE@ * * @property maximized_horizontal - * @tparam boolean maximized_horizontal + * @tparam[opt=false] boolean maximized_horizontal * @propemits false false * @request client geometry maximized_horizontal granted When the client must be resized * because it became (or stop being) maximized horizontally. @@ -1039,7 +1066,7 @@ lua_class_t client_class; * @DOC_sequences_client_maximized_vertical_EXAMPLE@ * * @property maximized_vertical - * @tparam boolean maximized_vertical + * @tparam[opt=false] boolean maximized_vertical * @propemits false false * @request client geometry maximized_vertical granted When the client must be resized * because it became (or stop being) maximized vertically. @@ -1065,7 +1092,7 @@ lua_class_t client_class; * applications can belong to each other without being modal. * * @property transient_for - * @tparam client transient_for + * @tparam[opt=nil] client|nil transient_for * @propemits false false * @readonly * @see modal @@ -1083,6 +1110,8 @@ lua_class_t client_class; * * @property group_window * @tparam integer group_window + * @propertydefault This is auto-generated by X11. + * @negativeallowed false * @propemits false false * @readonly * @see leader_window @@ -1094,7 +1123,9 @@ lua_class_t client_class; * This is the ID of the group window, not a client object. * * @property leader_window - * @tparam number leader_window + * @tparam integer leader_window + * @propertydefault This is auto-generated by X11. + * @negativeallowed false * @propemits false false * @readonly * @see transient_for @@ -1115,39 +1146,39 @@ lua_class_t client_class; * advised to set `size_hints_honor` to `false` in the `ruled.client` rules. * * @property size_hints - * @tparam[opt] table|nil size_hints The hints. - * @tparam[opt] table|nil hints.user_position A table with `x` and `y` keys. It + * @tparam[opt=nil] table|nil size_hints + * @tparam[opt] table|nil size_hints.user_position A table with `x` and `y` keys. It * contains the preferred position of the client. This is set when the * position has been modified by the user. See `program_position`. - * @tparam[opt] table|nil hints.program_position A table with `x` and `y` keys. It + * @tparam[opt] table|nil size_hints.program_position A table with `x` and `y` keys. It * contains the preferred position of the client. This is set when the * application itself requests a specific position. See `user_position`. - * @tparam[opt] table|nil hints.user_size A table with `width` and `height`. This + * @tparam[opt] table|nil size_hints.user_size A table with `width` and `height`. This * contains the client preferred size when it has previously been set by * the user. See `program_size` for the equivalent when the applications * itself wants to specify its preferred size. - * @tparam[opt] table|nil hints.program_size A table with `width` and `height`. This + * @tparam[opt] table|nil size_hints.program_size A table with `width` and `height`. This * contains the client preferred size as specified by the application. - * @tparam[opt] integer|nil hints.max_width The maximum width (in pixels). - * @tparam[opt] integer|nil hints.max_height The maximum height (in pixels). - * @tparam[opt] integer|nil hints.min_width The minimum width (in pixels). - * @tparam[opt] integer|nil hints.min_height The minimum height (in pixels). - * @tparam[opt] integer|nil hints.width_inc The number of pixels by which the + * @tparam[opt] integer|nil size_hints.max_width The maximum width (in pixels). + * @tparam[opt] integer|nil size_hints.max_height The maximum height (in pixels). + * @tparam[opt] integer|nil size_hints.min_width The minimum width (in pixels). + * @tparam[opt] integer|nil size_hints.min_height The minimum height (in pixels). + * @tparam[opt] integer|nil size_hints.width_inc The number of pixels by which the * client width may be increased or decreased. For example, for terminals, * the size has to be proportional with the monospace font size. - * @tparam[opt] integer|nil hints.height_inc The number of pixels by which the + * @tparam[opt] integer|nil size_hints.height_inc The number of pixels by which the * client height may be increased or decreased. For example, for terminals, * the size has to be proportional with the monospace font size. - * @tparam[opt] string|nil hints.win_gravity The client `gravity` defines the corder + * @tparam[opt] string|nil size_hints.win_gravity The client `gravity` defines the corder * from which the size is computed. For most clients, it is `north_west`, which * corresponds to the top-left of the window. This will affect how the client * is resized and other size related operations. - * @tparam[opt] integer|nil hints.min_aspect_num - * @tparam[opt] integer|nil hints.min_aspect_den - * @tparam[opt] integer|nil hints.max_aspect_num - * @tparam[opt] integer|nil hints.max_aspect_den - * @tparam[opt] integer|nil hints.base_width - * @tparam[opt] integer|nil hints.base_height + * @tparam[opt] integer|nil size_hints.min_aspect_num + * @tparam[opt] integer|nil size_hints.min_aspect_den + * @tparam[opt] integer|nil size_hints.max_aspect_num + * @tparam[opt] integer|nil size_hints.max_aspect_den + * @tparam[opt] integer|nil size_hints.base_width + * @tparam[opt] integer|nil size_hints.base_height * @propemits false false * @readonly * @see size_hints_honor @@ -1166,24 +1197,24 @@ lua_class_t client_class; * should be enabled. * * @property motif_wm_hints - * @tparam table motif_wm_hints The hints. - * @tparam[opt] boolean hints.functions.all - * @tparam[opt] boolean hints.functions.resize - * @tparam[opt] boolean hints.functions.move - * @tparam[opt] boolean hints.functions.minimize - * @tparam[opt] boolean hints.functions.maximize - * @tparam[opt] boolean hints.functions.close - * @tparam[opt] boolean hints.decorations.all - * @tparam[opt] boolean hints.decorations.border - * @tparam[opt] boolean hints.decorations.resizeh - * @tparam[opt] boolean hints.decorations.title - * @tparam[opt] boolean hints.decorations.menu - * @tparam[opt] boolean hints.decorations.minimize - * @tparam[opt] boolean hints.decorations.maximize - * @tparam[opt] string hints.input_mode This is either `modeless`, + * @tparam[opt={}] table motif_wm_hints + * @tparam[opt] boolean motif_wm_hints.functions.all + * @tparam[opt] boolean motif_wm_hints.functions.resize + * @tparam[opt] boolean motif_wm_hints.functions.move + * @tparam[opt] boolean motif_wm_hints.functions.minimize + * @tparam[opt] boolean motif_wm_hints.functions.maximize + * @tparam[opt] boolean motif_wm_hints.functions.close + * @tparam[opt] boolean motif_wm_hints.decorations.all + * @tparam[opt] boolean motif_wm_hints.decorations.border + * @tparam[opt] boolean motif_wm_hints.decorations.resizeh + * @tparam[opt] boolean motif_wm_hints.decorations.title + * @tparam[opt] boolean motif_wm_hints.decorations.menu + * @tparam[opt] boolean motif_wm_hints.decorations.minimize + * @tparam[opt] boolean motif_wm_hints.decorations.maximize + * @tparam[opt] string motif_wm_hints.input_mode This is either `modeless`, * `primary_application_modal`, `system_modal`, * `full_application_modal` or `unknown`. - * @tparam[opt] boolean hints.status.tearoff_window + * @tparam[opt] boolean motif_wm_hints.status.tearoff_window * @propemits false false * @readonly */ @@ -1198,7 +1229,7 @@ lua_class_t client_class; * @DOC_sequences_client_sticky_EXAMPLE@ * * @property sticky - * @tparam boolean sticky + * @tparam[opt=false] boolean sticky * @propemits false false * @see skip_taskbar */ @@ -1220,6 +1251,7 @@ lua_class_t client_class; * * @property modal * @tparam boolean modal + * @propertydefault This is provided by the application. * @propemits false false * @see transient_for */ @@ -1231,7 +1263,7 @@ lua_class_t client_class; * click on it. * * @property focusable - * @tparam boolean focusable + * @tparam[opt=true] boolean focusable * @propemits false false * @see shape_input * @see client.focus @@ -1251,7 +1283,8 @@ lua_class_t client_class; * cases, use the `shape` property. * * @property shape_bounding - * @tparam surface shape_bounding + * @tparam image shape_bounding + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @see shape * @see gears.surface.apply_shape_bounding @@ -1270,7 +1303,8 @@ lua_class_t client_class; * border. * * @property shape_clip - * @tparam surface shape_clip + * @tparam image shape_clip + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @see shape_bounding * @see shape_input @@ -1289,7 +1323,8 @@ lua_class_t client_class; * client rather than propagated below it. * * @property shape_input - * @tparam surface shape_input + * @tparam image shape_input + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @see shape_bounding * @see shape_clip @@ -1305,7 +1340,8 @@ lua_class_t client_class; * The client's bounding shape as set by the program as a (native) cairo surface. * * @property client_shape_bounding - * @tparam surface client_shape_bounding + * @tparam image client_shape_bounding + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @readonly * @see shape_bounding @@ -1322,7 +1358,8 @@ lua_class_t client_class; * The client's clip shape as set by the program as a (native) cairo surface. * * @property client_shape_clip - * @tparam surface client_shape_clip + * @tparam image client_shape_clip + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @readonly * @see shape_bounding @@ -1391,6 +1428,7 @@ lua_class_t client_class; * * @property startup_id * @tparam string startup_id + * @propertydefault This is optionally provided by the application. * @propemits false false * @see awful.spawn */ @@ -1403,7 +1441,7 @@ lua_class_t client_class; * local is_valid = pcall(function() return c.valid end) and c.valid * * @property valid - * @tparam boolean valid + * @tparam[opt=true] boolean valid * @propemits false false * @readonly * @see kill @@ -1417,7 +1455,7 @@ lua_class_t client_class; * to only get the first tag and ignore everything else. * * @property first_tag - * @tparam tag first_tag + * @tparam[opt=nil] tag|nil first_tag * @propemits false false * @readonly * @see tags @@ -1438,7 +1476,11 @@ lua_class_t client_class; * * @DOC_screen_struts_EXAMPLE@ * - * @tparam table struts A table with new strut values, or none. + * @tparam table|nil struts A table with new strut values, or none. + * @tparam[opt=0] integer struts.left + * @tparam[opt=0] integer struts.right + * @tparam[opt=0] integer struts.top + * @tparam[opt=0] integer struts.bottom * @treturn table A table with strut values. * @method struts * @see geometry @@ -1449,7 +1491,8 @@ lua_class_t client_class; /** Get or set mouse buttons bindings for a client. * * @property buttons - * @tparam table buttons + * @tparam[opt={}] table buttons + * @tablerowtype A list of `awful.button`s objects. * @propemits false false * @see awful.button * @see append_mousebinding @@ -4302,7 +4345,8 @@ luaA_client_set_shape_input(lua_State *L, client_t *c) /** Get or set keys bindings for a client. * * @property keys - * @tparam table keys + * @tparam[opt={}] table keys + * @tablerowtype A list of `awful.key`s objects. * @propemits false false * @see awful.key * @see append_keybinding From c60e7002e05001b70d423ad2ea127ac5e037c00c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 127/134] objects.drawable: Update the property documentation. --- objects/drawable.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/objects/drawable.c b/objects/drawable.c index a26abedd5..56449c0e8 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -35,8 +35,9 @@ /** Drawable object. * - * @property surface The drawable's cairo surface. - * @tparam gears.surface surface + * @property image + * @tparam image image + * @propertydefault Autogenerated. */ /** From f30800ec4ed6da5113e3ce74c11c20dabc75fa51 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 128/134] objects.screen: Update the property documentation. --- objects/screen.c | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/objects/screen.c b/objects/screen.c index b72aab97e..f6425c43e 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -170,10 +170,12 @@ * * @property geometry * @tparam table geometry - * @tfield integer table.x The horizontal position. - * @tfield integer table.y The vertical position. - * @tfield integer table.width The width. - * @tfield integer table.height The height. + * @tparam integer geometry.x The horizontal position. + * @tparam integer geometry.y The vertical position. + * @tparam integer geometry.width The width. + * @tparam integer geometry.height The height. + * @propertydefault Either from `xrandr` or from `fake_resize`. + * @propertyunit pixel * @propemits false false * @readonly */ @@ -205,6 +207,9 @@ * * @property index * @tparam integer index + * @propertydefault The index is not derived from the geometry. It may or may + * not be from `xrandr`. It isn't a good idea to rely on indices. + * @negativeallowed false * @see screen * @readonly */ @@ -222,10 +227,13 @@ * * @property workarea * @tparam table workarea - * @tfield integer table.x The horizontal position - * @tfield integer table.y The vertical position - * @tfield integer table.width The width - * @tfield integer table.height The height + * @tparam integer workarea.x The horizontal position + * @tparam integer workarea.y The vertical position + * @tparam integer workarea.width The width + * @tparam integer workarea.height The height + * @propertyunit pixel + * @propertydefault Based on `geometry` with the `awful.wibar` and docks area + * substracted. * @propemits false false * @see client.struts * @readonly From 1998fe860918919aa6fbeafae5b3b7ad3df9e058 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 129/134] objects.tag: Update the property documentation. --- objects/tag.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/objects/tag.c b/objects/tag.c index f9ec5cce2..87bff22a0 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -262,7 +262,7 @@ lua_class_t tag_class; * @DOC_sequences_tag_name_EXAMPLE@ * * @property name - * @tparam string name + * @tparam[opt=""] string name * @propemits false false */ @@ -272,7 +272,7 @@ lua_class_t tag_class; * @DOC_sequences_tag_selected_EXAMPLE@ * * @property selected - * @tparam boolean selected + * @tparam[opt=false] boolean selected * @propemits false false */ @@ -280,7 +280,7 @@ lua_class_t tag_class; * True if the tag is active and can be used. * * @property activated - * @tparam boolean activated + * @tparam[opt=true] boolean activated * @propemits false false */ From 4ff17396b68f0960039a66c9719dcc16c0069667 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:27 -0700 Subject: [PATCH 130/134] root: Update the property documentation. --- root.c | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/root.c b/root.c index 94f04977b..ef6aa2684 100644 --- a/root.c +++ b/root.c @@ -349,7 +349,8 @@ luaA_root_fake_input(lua_State *L) * (the wallpaper). * * @property keys - * @tparam table keys + * @tparam[opt={}] table keys + * @tablerowtype A list of `awful.key` objects. * @see awful.key */ static int @@ -390,7 +391,8 @@ luaA_root_keys(lua_State *L) * known as root window). * * @property buttons - * @tparam[opt={}] table buttons The list of buttons. + * @tparam[opt={}] table buttons + * @tablerowtype A list of `awful.button` objects. * @see awful.button * * @usage @@ -516,7 +518,9 @@ luaA_root_wallpaper(lua_State *L) /** Get the content of the root window as a cairo surface. * * @property content - * @tparam surface content A cairo surface with the root window content (aka the whole surface from every screens). + * @tparam raw_surface content A cairo surface with the root window content (aka the whole surface from every screens). + * @propertydefault This is the live content. Use `gears.surface(root.content)` to + * take a screenshot. * @see gears.surface */ static int From fc95f43bde686e4f62d3d1b464f9f98ef4fbe2f7 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 27 Aug 2022 17:08:03 -0700 Subject: [PATCH 131/134] doc: Add logging to _postprocess.lua. Try to find why it works locally, but not on GitHub. --- tests/examples/_postprocess.lua | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tests/examples/_postprocess.lua b/tests/examples/_postprocess.lua index 363cc054a..009e19a4a 100755 --- a/tests/examples/_postprocess.lua +++ b/tests/examples/_postprocess.lua @@ -7,6 +7,13 @@ local input, output = ... +if (not input) or (not output) then + io.stderr:write("_postprocess.lua require and \n") + io.stderr:write("Got input: "..tostring(input).."\n") + io.stderr:write("Got output: "..tostring(output).."\n") + os.exit(0) +end + -- The second 24bit is just the 32 bit converted to #010001 and back. local FOREGROUNDS = { "rgb[(]0[.]5%%,0%%,0[.]5%%[)];", From 3c0d5b606ffafd62ab1ec51b7283c6e9b2940dac Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 28 Aug 2022 00:17:17 -0700 Subject: [PATCH 132/134] doc: Fix issues found by @aire-one. --- docs/common/widget.ldoc | 3 ++- docs/config.ld | 8 ++++---- lib/awful/widget/calendar_popup.lua | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index 1d4c21ff9..632be1869 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -72,8 +72,9 @@ -- The table contains a list of `awful.button` objects. -- -- @property buttons --- @tparam table buttons +-- @tparam[opt={}] table buttons -- @see awful.button +-- @tablerowtype A list of `awful.button`. -- @baseclass wibox.widget --- Add a new `awful.button` to this widget. diff --git a/docs/config.ld b/docs/config.ld index 6d3a4f9df..8ab55afe1 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -334,7 +334,7 @@ create_type { return end - local param, sublist = item:subparam(item.params[1]) + local _, sublist = item:subparam(item.params[1]) local type = item:type_of_param(item.params[1]) -- Force people to use @tparam because it is easier to lint and allows @@ -347,10 +347,10 @@ create_type { ) end - if type == "bool" then + if type_name_linting[type] then print( "WARNING: Property ".. item.name .." from "..item.module.name.. - " type is `bool`, please use `boolean`." + " type is `"..type.."`, please use `"..type_name_linting[type].."`." ) end @@ -371,7 +371,7 @@ create_type { if def then -- Detect the blatant missing quote marks for string. This is important -- to differentiate variables from string literals. - if type == "string" and def:sub(1,1) ~= '"' and not def:find(".") then + if type == "string" and def:sub(1,1) ~= '"' and def:sub(-1) ~= '"' and not def:find(".") then print( "WARNING: Property ".. item.name .." from "..item.module.name.. " is a string, but the default value is not quoted." diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index ff7dc3c03..19f96a373 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A popup wibox containing a `wibox.widget,calendar` widget. +-- A popup wibox containing a `wibox.widget.calendar` widget. -- -- Display a month or year calendar popup using `calendar_popup.month` or `calendar_popup.year`. -- The calendar style can be tweaked by providing tables of style properties at creation: From 328551d479c982e6609bcabfb661c09daffd7089 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 28 Aug 2022 00:43:17 -0700 Subject: [PATCH 133/134] doc: Fix the UML template luacheck issues --- .../examples/uml/nav_tables/client.output.txt | 2 +- .../examples/uml/nav_tables/screen.output.txt | 2 +- tests/examples/uml/nav_tables/tag.output.txt | 2 +- tests/examples/uml/template.lua | 25 ++++++++++++++----- 4 files changed, 22 insertions(+), 9 deletions(-) diff --git a/tests/examples/uml/nav_tables/client.output.txt b/tests/examples/uml/nav_tables/client.output.txt index b4802f4b8..2b6312e52 100644 --- a/tests/examples/uml/nav_tables/client.output.txt +++ b/tests/examples/uml/nav_tables/client.output.txt @@ -17,4 +17,4 @@ Core components relationship screens.tiled_clients mousemouse.current_client -
        Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object, n: a naughty.notification object
        +
        Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object,n: a naughty.notification object
        diff --git a/tests/examples/uml/nav_tables/screen.output.txt b/tests/examples/uml/nav_tables/screen.output.txt index a60e8acdb..d575afd98 100644 --- a/tests/examples/uml/nav_tables/screen.output.txt +++ b/tests/examples/uml/nav_tables/screen.output.txt @@ -17,4 +17,4 @@ Core components relationship clientc.screen naughty.notificationn.screen -
        Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object, n: a naughty.notification object
        +
        Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object,n: a naughty.notification object
        diff --git a/tests/examples/uml/nav_tables/tag.output.txt b/tests/examples/uml/nav_tables/tag.output.txt index 2f25497dd..8b4cbe46b 100644 --- a/tests/examples/uml/nav_tables/tag.output.txt +++ b/tests/examples/uml/nav_tables/tag.output.txt @@ -14,4 +14,4 @@ Core components relationship screens.selected_tag screens.selected_tags -
        Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object, n: a naughty.notification object
        +
        Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object,n: a naughty.notification object
        diff --git a/tests/examples/uml/template.lua b/tests/examples/uml/template.lua index da46a298f..20a2750d5 100644 --- a/tests/examples/uml/template.lua +++ b/tests/examples/uml/template.lua @@ -166,12 +166,20 @@ local map = { } local function gen_table_header(title, o) - print([[
        ]]) + print(table.concat({[[
        ]], + [[
        ]]..map[title](o)..[[
        ClassProperty
        ]], + [[]], + [[]], + [[]], + [[]], + [[]] + })) end -local function get_table_row(path, class, prop) - print([[]]) +local function get_table_row(rel_path, class, prop) + print([[]]) end local function get_table_footer() @@ -197,11 +205,11 @@ function module.generate_nav_table(t) assert(entry.class) assert(entry.left.msg and entry.left.card) assert(entry.right.msg and entry.right.card) - local path = relative_image_path..counter..".svg" + local rel_path = relative_image_path..counter..".svg" local fpath = image_path..counter..".svg" local widget = gen_table_uml(entry, t.class, entry.class, false) wibox.widget.draw_to_svg_file(widget, fpath, 320, 50) - get_table_row(path, entry.class, entry[tab.."_property"]) + get_table_row(rel_path, entry.class, entry[tab.."_property"]) counter = counter + 1 end end @@ -209,7 +217,12 @@ function module.generate_nav_table(t) end -- End the last section and add a footer - print([[
        Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object, n: a naughty.notification object
        ]]) + print(table.concat({[[
        ]], + [[Legend: c: a client object, t: a tag object, s]], + [[: a screen object, k: an awful.key object, b: a awful.button object,]], + [[n: a naughty.notification object
        ]], + [[]] + })) end loadfile(file_path)(module) From 82a5fb60304815ca120b3dbecb17a2d7a859eb32 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 29 Aug 2022 22:54:09 -0700 Subject: [PATCH 134/134] doc: Do not document the 16bit max widget size. As pointed out by @aire-one, it does not provide much value. --- docs/common/widget.ldoc | 6 ++---- lib/wibox/widget/base.lua | 6 ++---- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index 632be1869..7330059b6 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -39,8 +39,7 @@ -- @propertytype nil Let the layout decide the height. Usually using the widget -- native height. -- @propertytype number Enforce a number of pixels. --- @rangestart 0 --- @rangestop 65534 +-- @negativeallowed false -- @baseclass wibox.widget -- @see forced_width @@ -50,8 +49,7 @@ -- @propertytype nil Let the layout decide the width. Usually using the widget -- native width. -- @propertytype number Enforce a number of pixels. --- @rangestart 0 --- @rangestop 65534 +-- @negativeallowed false -- @baseclass wibox.widget -- @see forced_height diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index b71b78b86..13a85d722 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -47,8 +47,7 @@ local base = {} -- @propertytype nil Let the layout decide the height. Usually using the widget -- native height. -- @propertytype number Enforce a number of pixels. --- @rangestart 0 --- @rangestop 65534 +-- @negativeallowed false -- @baseclass wibox.widget.base -- @see forced_width @@ -59,8 +58,7 @@ local base = {} -- @propertytype nil Let the layout decide the width. Usually using the widget -- native width. -- @propertytype number Enforce a number of pixels. --- @rangestart 0 --- @rangestop 65534 +-- @negativeallowed false -- @baseclass wibox.widget.base -- @see forced_height
        ]]..map[title](o)..[[
        ClassProperty
        ]].. class ..[[]].. prop ..[[
        ]].. class ..[[]].. prop ..[[