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

@@ -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

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

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 {
+parent:add(my_imagebox) --DOC_HIDE
-    image  = beautiful.awesome_icon,
-    resize = false,
-    widget = wibox.widget.imagebox
-}
 
-) --DOC_HIDE
 --DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80