diff --git a/lib/awful/widget/button.lua b/lib/awful/widget/button.lua
index eaaafb288..edded81d8 100644
--- a/lib/awful/widget/button.lua
+++ b/lib/awful/widget/button.lua
@@ -1,4 +1,12 @@
 ---------------------------------------------------------------------------
+-- A simple button widget.
+-- @usage local button = awful.widget.button()
+-- button:buttons(awful.util.table.join(
+--     button:buttons(),
+--     awful.button({}, 1, nil, function ()
+--         print("Mouse was clicked")
+--     end)
+-- ))
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @release @AWESOME_VERSION@
@@ -49,6 +57,10 @@ function button.mt:__call(...)
     return button.new(...)
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(button, button.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80