doc: Document the client layouts. (#1247)

This commit doesn't add any useful documentation, but adds
previously hidden documentation variables. It can be the basis
of a better layout documentation.

Fix #1246

docs/config.ld

@@ -49,6 +49,8 @@ new_type("beautiful", "Theme variables", false, "Type")
 new_type("deprecated", "Deprecated functions", false, "param")
 -- For the legacy stateless layout related functions
 new_type("legacylayout", "Layout related functions", false, "param")
+-- Have a category for the client layouts
+new_type("clientlayout", "Client layouts", false, "param")
 
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries'}
@@ -94,9 +96,6 @@ file = {
 
         -- Ignore the drawing window, users should only care about wiboxes
         '../objects/drawin.c',
-
-        -- exclude layout, but we need an extra bit of documentation elsewhere.
-        '../lib/awful/layout/suit/'
     }
 }
 

lib/awful/layout/init.lua

@@ -28,12 +28,8 @@ end
 
 local layout = {}
 
---- Default predefined layouts
---
--- @fixme Add documentation on available layouts as all of them are hidden
 layout.suit = require("awful.layout.suit")
 
--- The default list of layouts
 layout.layouts = {
     layout.suit.floating,
     layout.suit.tile,
@@ -53,6 +49,30 @@ layout.layouts = {
     layout.suit.corner.se,
 }
 
+--- The default list of layouts.
+--
+-- The default value is:
+--
+--    awful.layout.suit.floating,
+--    awful.layout.suit.tile,
+--    awful.layout.suit.tile.left,
+--    awful.layout.suit.tile.bottom,
+--    awful.layout.suit.tile.top,
+--    awful.layout.suit.fair,
+--    awful.layout.suit.fair.horizontal,
+--    awful.layout.suit.spiral,
+--    awful.layout.suit.spiral.dwindle,
+--    awful.layout.suit.max,
+--    awful.layout.suit.max.fullscreen,
+--    awful.layout.suit.magnifier,
+--    awful.layout.suit.corner.nw,
+--    awful.layout.suit.corner.ne,
+--    awful.layout.suit.corner.sw,
+--    awful.layout.suit.corner.se,
+--
+-- @field layout.layouts
+
+
 -- This is a special lock used by the arrange function.
 -- This avoids recurring call by emitted signals.
 local arrange_lock = false

lib/awful/layout/suit/corner.lua

@@ -3,7 +3,7 @@
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- See Pull Request for example : https://github.com/awesomeWM/awesome/pull/251
--- @module awful.layout.suit.corner
+-- @module awful.layout
 -- @author Alexis Brenon <brenon.alexis+awesomewm@gmail.com>
 -- @copyright 2015 Alexis Brenon
 
@@ -32,7 +32,7 @@ local capi = {screen = screen}
 -- @param surface
 -- @see gears.surface
 
---- Actually arrange clients of p.clients for corner layout
+-- Actually arrange clients of p.clients for corner layout
 -- @param p Mandatory table containing required informations for layouts
 -- (clients to arrange, workarea geometry, etc.)
 -- @param orientation String indicating in which corner is the master window.
@@ -162,18 +162,38 @@ end
 
 local corner = {}
 corner.row_privileged = false
+
+--- Corner layout.
+-- Display master client in a corner of the screen, and slaves in one
+-- column and one row around the master.
+-- @clientlayout awful.layout.suit.corner.nw
 corner.nw = {
         name = "cornernw",
         arrange = function (p) return do_corner(p, "NW") end
     }
+
+--- Corner layout.
+-- Display master client in a corner of the screen, and slaves in one
+-- column and one row around the master.
+-- @clientlayout awful.layout.suit.corner.ne
 corner.ne = {
         name = "cornerne",
         arrange = function (p) return do_corner(p, "NE") end
     }
+
+--- Corner layout.
+-- Display master client in a corner of the screen, and slaves in one
+-- column and one row around the master.
+-- @clientlayout awful.layout.suit.corner.sw
 corner.sw = {
         name = "cornersw",
         arrange = function (p) return do_corner(p, "SW") end
     }
+
+--- Corner layout.
+-- Display master client in a corner of the screen, and slaves in one
+-- column and one row around the master.
+-- @clientlayout awful.layout.suit.corner.se
 corner.se = {
         name = "cornerse",
         arrange = function (p) return do_corner(p, "SE") end

lib/awful/layout/suit/fair.lua

@@ -1,9 +1,9 @@
 ---------------------------------------------------------------------------
---- Fair layouts module for awful
+--- Fair layouts module for awful.
 --
 -- @author Josh Komoroske
 -- @copyright 2012 Josh Komoroske
--- @module awful.layout.suit.fair
+-- @module awful.layout
 ---------------------------------------------------------------------------
 
 -- Grab environment we need

lib/awful/layout/suit/floating.lua

@@ -3,7 +3,7 @@
 --
 -- @author Gregor Best
 -- @copyright 2008 Gregor Best
--- @module awful.layout.suit.floating
+-- @module awful.layout
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -102,6 +102,9 @@ end
 function floating.arrange()
 end
 
+--- The floating layout.
+-- @clientlayout awful.layout.suit.
+
 floating.name = "floating"
 
 return floating

lib/awful/layout/suit/init.lua

@@ -2,7 +2,7 @@
 --- Suits for awful
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
--- @module awful.layout.suit
+-- @module awful.layout
 ---------------------------------------------------------------------------
 
 return

lib/awful/layout/suit/magnifier.lua

@@ -3,7 +3,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
--- @module awful.layout.suit.magnifier
+-- @module awful.layout
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -137,6 +137,9 @@ function magnifier.arrange(p)
     end
 end
 
+--- The magnifier layout.
+-- @clientlayout awful.layout.suit.magnifier
+
 magnifier.name = "magnifier"
 
 return magnifier

lib/awful/layout/suit/max.lua

@@ -3,7 +3,7 @@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
--- @module awful.layout.suit.max
+-- @module awful.layout
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -42,14 +42,14 @@ local function fmax(p, fs)
 end
 
 --- Maximized layout.
--- @param screen The screen to arrange.
+-- @clientlayout awful.layout.suit.max.name
 max.name = "max"
 function max.arrange(p)
     return fmax(p, false)
 end
 
 --- Fullscreen layout.
--- @param screen The screen to arrange.
+-- @clientlayout awful.layout.suit.max.fullscreen
 max.fullscreen = {}
 max.fullscreen.name = "fullscreen"
 function max.fullscreen.arrange(p)

lib/awful/layout/suit/spiral.lua

@@ -5,7 +5,7 @@
 -- @copyright 2009 Uli Schlachter
 -- @copyright 2008 Julien Danjou
 --
--- @module awful.layout.suit.spiral
+-- @module awful.layout
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -69,14 +69,16 @@ local function do_spiral(p, _spiral)
     end
 end
 
---- Dwindle layout
+--- Dwindle layout.
+-- @clientlayout awful.layout.suit.spiral.dwindle
 spiral.dwindle = {}
 spiral.dwindle.name = "dwindle"
 function spiral.dwindle.arrange(p)
     return do_spiral(p, false)
 end
 
---- Spiral layout
+--- Spiral layout.
+-- @clientlayout awful.layout.suit.spiral.name
 spiral.name = "spiral"
 function spiral.arrange(p)
     return do_spiral(p, true)

lib/awful/layout/suit/tile.lua

@@ -5,7 +5,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Donald Ephraim Curtis
 -- @copyright 2008 Julien Danjou
--- @module awful.layout.suit.tile
+-- @module awful.layout
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -293,6 +293,9 @@ local function do_tile(param, orientation)
 
 end
 
+--- The main tile algo, on the right.
+-- @param screen The screen number to tile.
+-- @clientlayout awful.layout.suit.tile.top
 tile.right = {}
 tile.right.name = "tile"
 tile.right.arrange = do_tile
@@ -300,8 +303,9 @@ function tile.right.mouse_resize_handler(c, corner, x, y)
     return mouse_resize_handler(c, corner, x, y)
 end
 
---- The main tile algo, on left.
+--- The main tile algo, on the left.
 -- @param screen The screen number to tile.
+-- @clientlayout awful.layout.suit.tile.left
 tile.left = {}
 tile.left.name = "tileleft"
 function tile.left.arrange(p)
@@ -311,8 +315,9 @@ function tile.left.mouse_resize_handler(c, corner, x, y)
     return mouse_resize_handler(c, corner, x, y, "left")
 end
 
---- The main tile algo, on bottom.
+--- The main tile algo, on the bottom.
 -- @param screen The screen number to tile.
+-- @clientlayout awful.layout.suit.tile.bottom
 tile.bottom = {}
 tile.bottom.name = "tilebottom"
 function tile.bottom.arrange(p)
@@ -322,8 +327,9 @@ function tile.bottom.mouse_resize_handler(c, corner, x, y)
     return mouse_resize_handler(c, corner, x, y, "bottom")
 end
 
---- The main tile algo, on top.
+--- The main tile algo, on the top.
 -- @param screen The screen number to tile.
+-- @clientlayout awful.layout.suit.tile.top
 tile.top = {}
 tile.top.name = "tiletop"
 function tile.top.arrange(p)