From 86a9bbfd712dbfc267f341de5c40a644bbd4ce13 Mon Sep 17 00:00:00 2001
From: Aire-One <erwan.maugere@gmail.com>
Date: Thu, 21 Nov 2019 16:14:59 +0100
Subject: [PATCH] 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