diff --git a/lib/awful/_compat.lua b/lib/awful/_compat.lua
index b4226826c..4b3bb2816 100644
--- a/lib/awful/_compat.lua
+++ b/lib/awful/_compat.lua
@@ -56,3 +56,21 @@ do
     root.object = root_object
     assert(root.object == root_object)
 end
+
+-- root.bottons() used to be a capi function. However this proved confusing
+-- as rc.lua used `awful.button` and `root.buttons()` used capi.button. There
+-- was a little documented hack to "flatten" awful.button into a pair of
+-- capi.button. A consequence of this, beside being ugly, was that it was
+-- de-facto read-only due the confusion related the difference between the
+-- capi and "high level" format difference.
+
+
+--- Get or set global mouse bindings.
+--
+-- This binding will be available when you click on the root window (usually
+-- the wallpaper area).
+-- @tparam[opt=nil] table|nil The list of `button` objects to set.
+-- @treturn table The list of root window buttons.
+function root.buttons(btns)
+    return root._buttons(btns)
+end
diff --git a/root.c b/root.c
index 3c467a3ed..c9ed472d9 100644
--- a/root.c
+++ b/root.c
@@ -374,7 +374,7 @@ luaA_root_keys(lua_State *L)
     return 1;
 }
 
-/** Get or set global mouse bindings.
+/* Get or set global mouse bindings.
  * This binding will be available when you click on the root window.
  *
  * @param button_table An array of mouse button bindings objects, or nothing.
@@ -587,7 +587,7 @@ luaA_root_newindex(lua_State *L)
 
 const struct luaL_Reg awesome_root_methods[] =
 {
-    { "buttons", luaA_root_buttons },
+    { "_buttons", luaA_root_buttons },
     { "keys", luaA_root_keys },
     { "cursor", luaA_root_cursor },
     { "fake_input", luaA_root_fake_input },
diff --git a/tests/examples/shims/button.lua b/tests/examples/shims/button.lua
index fb5e995af..5f41d1e7c 100644
--- a/tests/examples/shims/button.lua
+++ b/tests/examples/shims/button.lua
@@ -1,5 +1,6 @@
 return function() return {
     data = {},
+    _is_capi_button = true,
     connect_signal = function() end
 } end