doc: Merge awful.mouse and mouse documentation pages

Just like client, tag and screen, this is to avoid new users some
confusing implementation details.

docs/aliases/awful_mouse.lua

@@ -0,0 +1,6 @@
+---------------------------------------------------------------------------
+--- This module is deprecated, use `mouse`
+--  ===============================
+--
+-- @module awful.mouse
+---------------------------------------------------------------------------

docs/config.ld

@@ -67,6 +67,7 @@ file = {
     '../docs/aliases/awful_client.lua',
     '../docs/aliases/awful_screen.lua',
     '../docs/aliases/awful_tag.lua',
+    '../docs/aliases/awful_mouse.lua',
     exclude = {
         -- exclude these modules, as they do not contain any written
         -- documentation

lib/awful/mouse/init.lua

@@ -4,7 +4,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
--- @module awful.mouse
+-- @module mouse
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -51,6 +51,7 @@ mouse.wibox = {}
 -- @tparam function shape A `gears.shape` compatible function
 
 --- Get the client object under the pointer.
+-- @deprecated awful.mouse.client_under_pointer
 -- @return The client object under the pointer, if one can be found.
 function mouse.client_under_pointer()
     local obj = capi.mouse.object_under_pointer()
@@ -60,6 +61,7 @@ function mouse.client_under_pointer()
 end
 
 --- Get the drawin object under the pointer.
+-- @deprecated awful.mouse.drawin_under_pointer
 -- @return The drawin object under the pointer, if one can be found.
 function mouse.drawin_under_pointer()
     local obj = capi.mouse.object_under_pointer()
@@ -69,6 +71,7 @@ function mouse.drawin_under_pointer()
 end
 
 --- Move a client.
+-- @function awful.mouse.client.move
 -- @param c The client to move, or the focused one if nil.
 -- @param snap The pixel to snap clients.
 -- @param finished_cb Deprecated, do not use
@@ -106,7 +109,8 @@ end
 
 mouse.client.dragtotag = { }
 
---- Move a client to a tag by dragging it onto the left / right side of the screen
+--- Move a client to a tag by dragging it onto the left / right side of the screen.
+-- @function awful.mouse.client.dragtotag.border
 -- @param c The client to move
 function mouse.client.dragtotag.border(c)
     capi.mousegrabber.run(function (_mouse)
@@ -146,7 +150,8 @@ function mouse.client.dragtotag.border(c)
                             end, "fleur")
 end
 
---- Move the wibox under the cursor
+--- Move the wibox under the cursor.
+-- @function awful.mouse.wibox.move
 --@param w The wibox to move, or none to use that under the pointer
 function mouse.wibox.move(w)
     w = w or mouse.wibox_under_pointer()
@@ -187,6 +192,7 @@ function mouse.wibox.move(w)
 end
 
 --- Get a client corner coordinates.
+-- @deprecated awful.mouse.client.corner
 -- @tparam[opt=client.focus] client c The client to get corner from, focused one by default.
 -- @tparam string corner The corner to use: auto, top_left, top_right, bottom_left,
 -- bottom_right, left, right, top bottom. Default is auto, and auto find the
@@ -215,6 +221,7 @@ function mouse.client.corner(c, corner)
 end
 
 --- Resize a client.
+-- @function awful.mouse.client.resize
 -- @param c The client to resize, or the focused one by default.
 -- @tparam string corner The corner to grab on resize. Auto detected by default.
 -- @tparam[opt={}] table args A set of `awful.placement` arguments
@@ -239,6 +246,7 @@ function mouse.client.resize(c, corner, args)
 end
 
 --- Default handler for `request::geometry` signals with `mouse.resize` context.
+-- @function awful.mouse.resize_handler
 -- @tparam client c The client
 -- @tparam string context The context
 -- @tparam[opt={}] table hints The hints to pass to the handler

lib/awful/mouse/resize.lua

@@ -7,7 +7,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @release @AWESOME_VERSION@
--- @submodule awful.mouse
+-- @submodule mouse
 ---------------------------------------------------------------------------
 
 local aplace = require("awful.placement")
@@ -27,6 +27,7 @@ local callbacks = {enter={}, move={}, leave={}}
 --
 -- Some clients, such as XTerm, may lose information if resized too often.
 --
+-- @function awful.mouse.resize.set_mode
 -- @tparam string m The mode
 function module.set_mode(m)
     assert(m == "live" or m == "after")
@@ -35,6 +36,7 @@ end
 
 --- Add a initialization callback.
 -- This callback will be executed before the mouse grabbing start
+-- @function awful.mouse.resize.add_enter_callback
 -- @tparam function cb The callback (or nil)
 -- @tparam[default=other] string context The callback context
 function module.add_enter_callback(cb, context)
@@ -46,6 +48,7 @@ end
 --- Add a "move" callback.
 -- This callback is executed in "after" mode (see `set_mode`) instead of
 -- applying the operation.
+-- @function awful.mouse.resize.add_move_callback
 -- @tparam function cb The callback (or nil)
 -- @tparam[default=other] string context The callback context
 function module.add_move_callback(cb, context)
@@ -56,6 +59,7 @@ end
 
 --- Add a "leave" callback
 -- This callback is executed just before the `mousegrabber` stop
+-- @function awful.mouse.resize.add_leave_callback
 -- @tparam function cb The callback (or nil)
 -- @tparam[default=other] string context The callback context
 function module.add_leave_callback(cb, context)
@@ -64,7 +68,7 @@ function module.add_leave_callback(cb, context)
     table.insert(callbacks.leave[context], cb)
 end
 
--- Resize, the drawable
+-- Resize, the drawable.
 --
 -- Valid `args` are:
 --
@@ -73,9 +77,11 @@ end
 -- * *leave_callback*: A function called before the `mousegrabber` is released
 -- * *mode*: The resize mode
 --
+-- @function awful.mouse.resize
 -- @tparam client client A client
 -- @tparam[default=mouse.resize] string context The resizing context
 -- @tparam[opt={}] table args A set of `awful.placement` arguments
+
 local function handler(_, client, context, args) --luacheck: no unused_args
     args = args or {}
     context = context or "mouse.resize"

lib/awful/mouse/snap.lua

@@ -4,7 +4,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
--- @submodule awful.mouse
+-- @submodule mouse
 ---------------------------------------------------------------------------
 
 local aclient   = require("awful.client")
@@ -185,6 +185,7 @@ local function snap_inside(g, sg, snap)
 end
 
 --- Snap a client to the closest client or screen edge.
+-- @function awful.mouse.snap
 -- @param c The client to snap.
 -- @param snap The pixel to snap clients.
 -- @param x The client x coordinate.

mouse.c

@@ -42,22 +42,10 @@
 static int miss_index_handler    = LUA_REFNIL;
 static int miss_newindex_handler = LUA_REFNIL;
 
-/** Mouse library.
- *
- * @table mouse
- */
-
 /**
  * The `screen` under the cursor
- * @field screen
- */
-
-/** A table with X and Y coordinates.
- * @field x X coordinate.
- * @field y Y coordinate.
- * @field buttons Table containing the status of buttons, e.g. field [1] is true
- *        when button 1 is pressed.
- * @table coords_table
+ * @property screen
+ * @param screen
  */
 
 /** Get the pointer position.
@@ -251,11 +239,16 @@ luaA_mouse_pushstatus(lua_State *L, int x, int y, uint16_t mask)
 
 /** Get or set the mouse coords.
  *
- * @tparam coords_table coords_table None or a table with x and y keys as mouse
+ * @tparam[opt=nil] table coords_table None or a table with x and y keys as mouse
  *  coordinates.
- * @tparam boolean silent Disable mouse::enter or mouse::leave events that
+ * @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 coords_table A table with mouse coordinates.
+ * @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