doc: Add a coords example

This forced the `coords()` documentation to be moved to Lua.
Keeping it in the C file caused yet another example CMake hack.

lib/awful/mouse/init.lua

@@ -304,6 +304,23 @@ capi.mouse.set_index_miss_handler(function(_,key)
     end
 end)
 
+--- Get or set the mouse coords.
+--
+--@DOC_awful_mouse_coords_EXAMPLE@
+--
+-- @tparam[opt=nil] table coords_table None or a table with x and y keys as mouse
+--  coordinates.
+-- @tparam[opt=nil] integer coords_table.x The mouse horizontal position
+-- @tparam[opt=nil] integer coords_table.y The mouse vertical position
+-- @tparam[opt=false] boolean silent Disable mouse::enter or mouse::leave events that
+--  could be triggered by the pointer when moving.
+-- @treturn integer table.x The horizontal position
+-- @treturn integer table.y The vertical position
+-- @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true
+--  when button 1 is pressed.
+-- @function mouse.coords
+
+
 return mouse
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

mouse.c

@@ -237,20 +237,7 @@ luaA_mouse_pushstatus(lua_State *L, int x, int y, uint16_t mask)
     return 1;
 }
 
-/** Get or set the mouse coords.
+/* documented in lib/awful/mouse/init.lua */
- *
- * @tparam[opt=nil] table coords_table None or a table with x and y keys as mouse
- *  coordinates.
- * @tparam[opt=nil] integer coords_table.x The mouse horizontal position
- * @tparam[opt=nil] integer coords_table.y The mouse vertical position
- * @tparam[opt=false] boolean silent Disable mouse::enter or mouse::leave events that
- *  could be triggered by the pointer when moving.
- * @treturn integer table.x The horizontal position
- * @treturn integer table.y The vertical position
- * @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true
- *  when button 1 is pressed.
- * @function coords
- */
 static int
 luaA_mouse_coords(lua_State *L)
 {

tests/examples/awful/mouse/coords.lua

@@ -0,0 +1,13 @@
+screen[1]._resize {x = 175, width = 128, height = 96} --DOC_HIDE
+mouse.coords {x=175+60,y=60} --DOC_HIDE
+
+ -- Get the position
+print(mouse.coords().x)
+ 
+ -- Change the position
+mouse.coords {
+    x = 185,
+    y = 10
+}
+
+mouse.push_history() --DOC_HIDE