root: Turn root.button() into a property.

This is the first commit of a series to turn all function based
accessors into object properties. This will bring consistency
across the codebase.

lib/awful/_compat.lua

@@ -4,6 +4,7 @@ local gtimer = require("gears.timer")
 local util   = require("awful.util")
 local spawn  = require("awful.spawn")
 local gdebug = require("gears.debug")
+local gprop  = require("gears.object.properties")
 
 local capi = {root = root}
 
@@ -64,13 +65,8 @@ end
 -- 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
+gprop._legacy_accessors(capi.root, "buttons", "_buttons", false, function(new_btns)
+    return new_btns[1] and (
+        type(new_btns[1]) == "button" or new_btns[1]._is_capi_button
+    ) or false
+end, true)

root.c

@@ -374,13 +374,22 @@ luaA_root_keys(lua_State *L)
     return 1;
 }
 
-/* Get or set global mouse bindings.
- * This binding will be available when you click on the root window.
+/**
+ * Store the list of mouse buttons to be applied on the wallpaper (also
+ * known as root window).
  *
- * @param button_table An array of mouse button bindings objects, or nothing.
- * @return The array of mouse button bindings objects.
- * @staticfct buttons
+ * @property buttons
+ * @tparam[opt={}] table buttons The list of buttons.
+ * @see awful.button
+ *
+ * @usage
+ * root.buttons = {
+ *     awful.button({ }, 3, function () mymainmenu:toggle() end),
+ *     awful.button({ }, 4, awful.tag.viewnext),
+ *     awful.button({ }, 5, awful.tag.viewprev),
+ * }
  */
+
 static int
 luaA_root_buttons(lua_State *L)
 {