diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua
index c8a7c6dda..e9aeb0097 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 ea265f982..b17964a4d 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 d423ef482..5c6a2c0f1 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 c9d13f6a0..dddcafe70 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 709300252..3e3479d8d 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 b2be8684c..d3182a474 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 9a14556c9..7d2150c87 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 a555130d2..42f94ec71 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 2bacf6bbf..61c19d004 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 ff551883a..a5c2eec09 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 45095e091..db038c2bc 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 c76b58a6f..b604dd26a 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 681f21551..9a9e88715 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 3aef7c33c..2cf02e196 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/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua
index 5764e1382..18e0aaf50 100644
--- a/lib/wibox/widget/imagebox.lua
+++ b/lib/wibox/widget/imagebox.lua
@@ -1,6 +1,23 @@
 ---------------------------------------------------------------------------
+-- A widget to display image.
+--
+-- 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@
+--
+-- 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
@@ -125,11 +142,29 @@ 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` : Unset the 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.
+--
+-- 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
 
@@ -169,23 +204,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, ...)
@@ -195,24 +230,39 @@ 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
--- @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.
+--
+-- 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
+--   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 function new(image, resize_allowed, clip_shape, ...)
     local ret = base.make_widget(nil, nil, {enable_properties = true})
 
     gtable.crush(ret, imagebox, true)
@@ -225,7 +275,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
diff --git a/mousegrabber.c b/mousegrabber.c
index abb6b6c81..cc7be5857 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 bd6c78926..0bf6a21ec 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 b0c394148..fc3417c89 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 9c1b14655..ae683756f 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
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 000000000..60a0613ed
--- /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 33eec9f19..8cd14f223 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
diff --git a/tests/examples/wibox/widget/imagebox/resize.lua b/tests/examples/wibox/widget/imagebox/resize.lua
new file mode 100644
index 000000000..2b4124ef5
--- /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