From 82a2769e046dc49e21165cb872ae1bf03e31b094 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Thu, 21 Nov 2019 15:43:15 +0100 Subject: [PATCH 1/6] Fix ldoc modules summaries missing the final `.`. --- lib/awful/layout/init.lua | 2 +- lib/awful/menu.lua | 2 +- lib/awful/screen.lua | 2 +- lib/awful/util.lua | 2 +- lib/awful/widget/calendar_popup.lua | 2 +- lib/awful/widget/layoutbox.lua | 2 +- lib/awful/widget/taglist.lua | 2 +- lib/gears/filesystem.lua | 2 +- lib/gears/math.lua | 2 +- lib/gears/string.lua | 2 +- lib/gears/table.lua | 2 +- lib/menubar/init.lua | 2 +- lib/wibox/layout/init.lua | 2 +- lib/wibox/widget/calendar.lua | 2 +- mousegrabber.c | 2 +- objects/drawable.c | 2 +- objects/screen.c | 2 +- root.c | 2 +- 18 files changed, 18 insertions(+), 18 deletions(-) diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua index c8a7c6dd..e9aeb009 100644 --- a/lib/awful/layout/init.lua +++ b/lib/awful/layout/init.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Layout module for awful +--- Layout module for awful. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index ea265f98..b17964a4 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -1,5 +1,5 @@ -------------------------------------------------------------------------------- ---- A menu for awful +--- A menu for awful. -- -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index 2684a231..1c2177db 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Screen module for awful +--- Screen module for awful. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou diff --git a/lib/awful/util.lua b/lib/awful/util.lua index c9d13f6a..dddcafe7 100644 --- a/lib/awful/util.lua +++ b/lib/awful/util.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Utility module for awful +--- Utility module for awful. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 70930025..3e3479d8 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A calendar popup wibox +-- A calendar popup wibox. -- -- 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: diff --git a/lib/awful/widget/layoutbox.lua b/lib/awful/widget/layoutbox.lua index b2be8684..d3182a47 100644 --- a/lib/awful/widget/layoutbox.lua +++ b/lib/awful/widget/layoutbox.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Display the current client layout (`awful.layout`) icon or name +--- Display the current client layout (`awful.layout`) icon or name. -- -- -- @author Julien Danjou <julien@danjou.info> diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index 9a14556c..7d2150c8 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Taglist widget module for awful +--- Taglist widget module for awful. -- -- Here is a more advanced example of how to extent the `taglist`. It provides: -- diff --git a/lib/gears/filesystem.lua b/lib/gears/filesystem.lua index a555130d..42f94ec7 100644 --- a/lib/gears/filesystem.lua +++ b/lib/gears/filesystem.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Filesystem module for gears +--- Filesystem module for gears. -- -- @utillib gears.filesystem --------------------------------------------------------------------------- diff --git a/lib/gears/math.lua b/lib/gears/math.lua index 2bacf6bb..61c19d00 100644 --- a/lib/gears/math.lua +++ b/lib/gears/math.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Math module for gears +--- Math module for gears. -- -- @utillib gears.math --------------------------------------------------------------------------- diff --git a/lib/gears/string.lua b/lib/gears/string.lua index ff551883..a5c2eec0 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- String module for gears +--- String module for gears. -- -- @utillib gears.string --------------------------------------------------------------------------- diff --git a/lib/gears/table.lua b/lib/gears/table.lua index 45095e09..db038c2b 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Table module for gears +--- Table module for gears. -- -- @utillib gears.table --------------------------------------------------------------------------- diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index c76b58a6..b604dd26 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Menubar module, which aims to provide a freedesktop menu alternative +--- Menubar module, which aims to provide a freedesktop menu alternative. -- -- List of menubar keybindings: -- --- diff --git a/lib/wibox/layout/init.lua b/lib/wibox/layout/init.lua index 681f2155..9a9e8871 100644 --- a/lib/wibox/layout/init.lua +++ b/lib/wibox/layout/init.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Collection of layouts that can be used in widget boxes +--- Collection of layouts that can be used in widget boxes. -- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter diff --git a/lib/wibox/widget/calendar.lua b/lib/wibox/widget/calendar.lua index 3aef7c33..2cf02e19 100644 --- a/lib/wibox/widget/calendar.lua +++ b/lib/wibox/widget/calendar.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A calendar widget +-- A calendar widget. -- -- This module defines two widgets: a month calendar and a year calendar -- diff --git a/mousegrabber.c b/mousegrabber.c index abb6b6c8..cc7be585 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -19,7 +19,7 @@ * */ -/** awesome mousegrabber API +/** awesome mousegrabber API. * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @coreclassmod mousegrabber diff --git a/objects/drawable.c b/objects/drawable.c index bd6c7892..0bf6a21e 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -20,7 +20,7 @@ * */ -/** awesome drawable API +/** awesome drawable API. * * Furthermore to the classes described here, one can also use signals as * described in @{signals}. diff --git a/objects/screen.c b/objects/screen.c index b0c39414..fc3417c8 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -19,7 +19,7 @@ * */ -/** awesome screen API +/** awesome screen API. * * 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`: diff --git a/root.c b/root.c index 9c1b1465..ae683756 100644 --- a/root.c +++ b/root.c @@ -19,7 +19,7 @@ * */ -/** awesome root window API +/** awesome root window API. * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @coreclassmod root From 86a9bbfd712dbfc267f341de5c40a644bbd4ce13 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Thu, 21 Nov 2019 16:14:59 +0100 Subject: [PATCH 2/6] Improve the `wibox.widget.imagebox` descrition. * Add a better descrition for the `imagebox` role in the wiboxes system ; * Improve image + code render and integration into the descrition ; * Add a second code exemple to show both coding style (imperative and declarative). I think the user can now have a better overview of what's a `wibox.widget.imagebox` and how to use it. --- lib/wibox/widget/imagebox.lua | 12 +++++++++++- .../wibox/widget/declarative-pattern/imagebox.lua | 14 ++++++++++++++ tests/examples/wibox/widget/defaults/imagebox.lua | 12 ++++-------- 3 files changed, 29 insertions(+), 9 deletions(-) create mode 100644 tests/examples/wibox/widget/declarative-pattern/imagebox.lua diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index 5764e138..09472991 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -1,6 +1,16 @@ --------------------------------------------------------------------------- +-- A widget to render image(s). +-- +-- The `wibox.widget.imagebox` is part of the Awesome WM's wiboxes system. +-- It renders image in a box widget. +-- +-- @DOC_wibox_widget_defaults_imagebox_EXAMPLE@ +-- +-- Alternatively, you can declare the `imagebox` widget using the +-- declarative pattern (Both codes are strictly equivalent): +-- +-- @DOC_wibox_widget_declarative-pattern_imagebox_EXAMPLE@ -- ---@DOC_wibox_widget_defaults_imagebox_EXAMPLE@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @widgetmod wibox.widget.imagebox diff --git a/tests/examples/wibox/widget/declarative-pattern/imagebox.lua b/tests/examples/wibox/widget/declarative-pattern/imagebox.lua new file mode 100644 index 00000000..60a0613e --- /dev/null +++ b/tests/examples/wibox/widget/declarative-pattern/imagebox.lua @@ -0,0 +1,14 @@ +--DOC_NO_USAGE +local parent = ... --DOC_HIDE +local wibox = require( "wibox" ) --DOC_HIDE +local beautiful = require( "beautiful" ) --DOC_HIDE + + local my_imagebox = wibox.widget { + image = beautiful.awesome_icon, + resize = false, + widget = wibox.widget.imagebox + } + +parent:add(my_imagebox) --DOC_HIDE + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/widget/defaults/imagebox.lua b/tests/examples/wibox/widget/defaults/imagebox.lua index 33eec9f1..8cd14f22 100644 --- a/tests/examples/wibox/widget/defaults/imagebox.lua +++ b/tests/examples/wibox/widget/defaults/imagebox.lua @@ -1,15 +1,11 @@ ---DOC_GEN_IMAGE --DOC_HIDE +--DOC_GEN_IMAGE +--DOC_NO_USAGE local parent = ... --DOC_HIDE local wibox = require( "wibox" ) --DOC_HIDE local beautiful = require( "beautiful" ) --DOC_HIDE -parent:add( --DOC_HIDE + local my_imagebox = wibox.widget.imagebox(beautiful.awesome_icon, false) -wibox.widget { - image = beautiful.awesome_icon, - resize = false, - widget = wibox.widget.imagebox -} +parent:add(my_imagebox) --DOC_HIDE -) --DOC_HIDE --DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 From 5bf703416c2bb1c63058f2887a886c8dfceb1bdd Mon Sep 17 00:00:00 2001 From: Aire-One Date: Thu, 21 Nov 2019 17:34:28 +0100 Subject: [PATCH 3/6] Improve `wibox.widget.imagebox` documentation. * Add the ldoc stop marker `.` to each functions, properties and methods definition ; * Improve a little summaries ; * Improve properties vs access methods documentation ; * Change all documented parameters and return values to typed values. --- lib/wibox/widget/imagebox.lua | 55 +++++++++++++++++++++++------------ 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index 09472991..bf677703 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -135,11 +135,24 @@ local function load_and_apply(ib, file, image_loader, image_setter) return image_applied end ---- Set an imagebox' image +--- The image rendered by the `imagebox`. +--
It can can be any of the following: +-- +-- * A `string` : Interpreted as the path to an image file ; +-- * A cairo image surface : Directly used as is ; +-- * An rsvg handle object : Directly used as is ; +-- * `nil` : Deny previously setted image. +-- -- @property image --- @param image This can can be string, cairo image surface, rsvg handle object or nil. A string is --- interpreted as the path to an image file. Nil will deny previously set image. --- @return true on success, false if the image cannot be used +-- @tparam image image The image to render. +-- @see set_image + +--- Set the `imagebox` image. +-- @method imagebox:set_image +-- @tparam image image The image to render. +-- @treturn boolean `true` on success, `false` if the image cannot be used. +-- @usage my_imagebox:set_image(beautiful.awesome_icon) +-- @usage my_imagebox:set_image('/usr/share/icons/theme/my_icon.png') function imagebox:set_image(image) local setup_succeed @@ -179,23 +192,23 @@ function imagebox:set_image(image) return true end ---- Set a clip shape for this imagebox +--- Set a clip shape for this imagebox. -- A clip shape define an area where the content is displayed and one where it -- is trimmed. -- -- @property clip_shape --- @tparam gears.shape clip_shape A `gears_shape` compatible shape function +-- @tparam function|gears.shape clip_shape A `gears.shape` compatible shape function. -- @see gears.shape -- @see set_clip_shape ---- Set a clip shape for this imagebox +--- Set a clip shape for this imagebox. -- A clip shape define an area where the content is displayed and one where it -- is trimmed. -- --- Any other parameters will be passed to the clip shape function +-- Any other parameters will be passed to the clip shape function. -- --- @tparam function clip_shape A `gears_shape` compatible shape function. --- @method set_clip_shape +-- @tparam function|gears.shape clip_shape A `gears_shape` compatible shape function. +-- @method imagebox:set_clip_shape -- @see gears.shape -- @see clip_shape function imagebox:set_clip_shape(clip_shape, ...) @@ -206,21 +219,25 @@ end --- Should the image be resized to fit into the available space? -- @property resize --- @param allowed If false, the image will be clipped, else it will be resized --- to fit into the available space. +-- @tparam boolean resize + +--- Should the image be resized to fit into the available space? +-- @tparam boolean allowed If `false`, the image will be clipped, else it will +-- be resized to fit into the available space. +-- @method imagebox:set_resize function imagebox:set_resize(allowed) self._private.resize_forbidden = not allowed self:emit_signal("widget::redraw_needed") self:emit_signal("widget::layout_changed") end ---- Returns a new imagebox. --- Any other arguments will be passed to the clip shape function --- @param image the image to display, may be nil --- @param resize_allowed If false, the image will be clipped, else it will be resized --- to fit into the available space. --- @param clip_shape A `gears.shape` compatible function --- @treturn table A new `imagebox` +--- Returns a new `wibox.widget.imagebox` instance. +-- Any additional arguments will be passed to the clip shape function. +-- @tparam[opt] image image The image to display (may be `nil`). +-- @tparam[opt] boolean resize_allowed If `false`, the image will be +-- clipped, else it will be resized to fit into the available space. +-- @tparam[opt] function clip_shape A `gears.shape` compatible function. +-- @treturn wibox.widget.imagebox A new `wibox.widget.imagebox` widget instance. -- @constructorfct wibox.widget.imagebox local function new(image, resize_allowed, clip_shape) local ret = base.make_widget(nil, nil, {enable_properties = true}) From 90f89432d247fa996b9c8e78bb09f3d54aeaf7f0 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Fri, 22 Nov 2019 19:06:37 +0100 Subject: [PATCH 4/6] Improvement following the @psychon review. --- lib/wibox/widget/imagebox.lua | 38 +++++++++++++++++++++++++++-------- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index bf677703..2426f401 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -1,8 +1,15 @@ --------------------------------------------------------------------------- --- A widget to render image(s). +-- A widget to display image. -- --- The `wibox.widget.imagebox` is part of the Awesome WM's wiboxes system. --- It renders image in a box widget. +-- The `wibox.widget.imagebox` is part of the Awesome WM's wiboxes system +-- (see @{03-declarative-layout.md}). +-- +-- This widget displays an image. The image can be a file, +-- a cairo image surface, or an rsvg handle object (see the +-- [image property](#image)). +-- +-- Use a `wibox.widget.imagebox` +-- --- -- -- @DOC_wibox_widget_defaults_imagebox_EXAMPLE@ -- @@ -136,23 +143,28 @@ local function load_and_apply(ib, file, image_loader, image_setter) end --- The image rendered by the `imagebox`. ---
It can can be any of the following: -- --- * A `string` : Interpreted as the path to an image file ; --- * A cairo image surface : Directly used as is ; --- * An rsvg handle object : Directly used as is ; --- * `nil` : Deny previously setted image. +-- It can can be any of the following: +-- +-- * A `string` : Interpreted as the path to an image file, +-- * A cairo image surface : Directly used as is, +-- * An rsvg handle object : Directly used as is, +-- * `nil` : Unset the image. -- -- @property image -- @tparam image image The image to render. -- @see set_image --- Set the `imagebox` image. +-- +-- The image can be a file, a cairo image surface, or an rsvg handle object +-- (see the [image property](#image)). -- @method imagebox:set_image -- @tparam image image The image to render. -- @treturn boolean `true` on success, `false` if the image cannot be used. -- @usage my_imagebox:set_image(beautiful.awesome_icon) -- @usage my_imagebox:set_image('/usr/share/icons/theme/my_icon.png') +-- @see image function imagebox:set_image(image) local setup_succeed @@ -232,6 +244,16 @@ function imagebox:set_resize(allowed) end --- Returns a new `wibox.widget.imagebox` instance. +-- +-- This is the constructor of `wibox.widget.imagebox`. It creates a new +-- instance of imagebox widget. +-- +-- Alternatively, the declarative layout syntax can handle +-- `wibox.widget.imagebox` instanciation. +-- +-- The image can be a file, a cairo image surface, or an rsvg handle object +-- (see the [image property](#image)). +-- -- Any additional arguments will be passed to the clip shape function. -- @tparam[opt] image image The image to display (may be `nil`). -- @tparam[opt] boolean resize_allowed If `false`, the image will be From 15209b305c229e130cdc9c6d823e56c3fae8f104 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Thu, 28 Nov 2019 12:02:18 +0100 Subject: [PATCH 5/6] Fix imagebox constructor missing argument. --- lib/wibox/widget/imagebox.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index 2426f401..f5d4d9c6 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -261,7 +261,7 @@ end -- @tparam[opt] function clip_shape A `gears.shape` compatible function. -- @treturn wibox.widget.imagebox A new `wibox.widget.imagebox` widget instance. -- @constructorfct wibox.widget.imagebox -local function new(image, resize_allowed, clip_shape) +local function new(image, resize_allowed, clip_shape, ...) local ret = base.make_widget(nil, nil, {enable_properties = true}) gtable.crush(ret, imagebox, true) @@ -274,7 +274,7 @@ local function new(image, resize_allowed, clip_shape) end ret._private.clip_shape = clip_shape - ret._private.clip_args = {} + ret._private.clip_args = {...} return ret end From 3e6c33af64584194e023d8f067d97938c744f426 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Thu, 28 Nov 2019 12:42:29 +0100 Subject: [PATCH 6/6] Add imagebox doc example for `resize` property. --- lib/wibox/widget/imagebox.lua | 1 + .../examples/wibox/widget/imagebox/resize.lua | 46 +++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 tests/examples/wibox/widget/imagebox/resize.lua diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index f5d4d9c6..18e0aaf5 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -230,6 +230,7 @@ function imagebox:set_clip_shape(clip_shape, ...) end --- Should the image be resized to fit into the available space? +-- @DOC_wibox_widget_imagebox_resize_EXAMPLE@ -- @property resize -- @tparam boolean resize diff --git a/tests/examples/wibox/widget/imagebox/resize.lua b/tests/examples/wibox/widget/imagebox/resize.lua new file mode 100644 index 00000000..2b4124ef --- /dev/null +++ b/tests/examples/wibox/widget/imagebox/resize.lua @@ -0,0 +1,46 @@ +--DOC_HIDE_ALL +--DOC_GEN_IMAGE +local parent = ... +local wibox = require( "wibox" ) +local beautiful = require( "beautiful" ) + +local function cell_centered_widget(widget) + return wibox.widget { + widget, + valign = 'center', + halign = 'center', + content_fill_vertical = false, + content_fill_horizontal = false, + widget = wibox.container.place + } +end + +local function build_ib(size, resize) + return cell_centered_widget({ + resize = resize, + forced_width = size, + forced_height = size, + image = beautiful.awesome_icon, + widget = wibox.widget.imagebox + }) +end + + +local l = wibox.widget { + homogeneous = false, + spacing = 5, + layout = wibox.layout.grid, +} +parent:add(l) + +l:add_widget_at(cell_centered_widget(wibox.widget.textbox('resize = true')), 1, 1) +l:add_widget_at(cell_centered_widget(wibox.widget.textbox('resize = false')), 2, 1) +l:add_widget_at(cell_centered_widget(wibox.widget.textbox('imagebox size')), 3, 1) + +for i,size in ipairs({16, 32, 64}) do + l:add_widget_at(build_ib(size, true), 1, i + 1) + l:add_widget_at(build_ib(size, false), 2, i + 1) + l:add_widget_at(cell_centered_widget(wibox.widget.textbox(size..'x'..size)), 3, i + 1) +end + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80