From 7f8a0787b84ebef5736c35cfcce5e8cf85b3e708 Mon Sep 17 00:00:00 2001
From: "Ignas Anikevicius (gns_ank)" <anikevicius@gmail.com>
Date: Tue, 20 May 2014 12:02:39 +0100
Subject: [PATCH] Docs: General work on the awful module.

This is basically an initial stab for some modules and some
experimenting with the `@classmod` directive.

For most of the docs only basic transforming was done.

At the moment the tooltip module looks the best.

Signed-off-by: Ignas Anikevicius (gns_ank) <anikevicius@gmail.com>
---
 lib/awful/autofocus.lua.in            | 12 +++--
 lib/awful/button.lua.in               | 21 ++++----
 lib/awful/client.lua.in               |  4 +-
 lib/awful/completion.lua.in           |  8 ++--
 lib/awful/dbus.lua.in                 | 11 +++--
 lib/awful/ewmh.lua.in                 | 17 +++++--
 lib/awful/init.lua.in                 |  6 +--
 lib/awful/key.lua.in                  |  5 +-
 lib/awful/keygrabber.lua.in           |  5 +-
 lib/awful/menu.lua.in                 |  4 +-
 lib/awful/mouse/finder.lua.in         | 36 +++++++-------
 lib/awful/mouse/init.lua.in           |  5 +-
 lib/awful/placement.lua.in            |  5 +-
 lib/awful/prompt.lua.in               |  5 +-
 lib/awful/remote.lua.in               |  6 +--
 lib/awful/rules.lua.in                |  3 +-
 lib/awful/screen.lua.in               |  5 +-
 lib/awful/startup_notification.lua.in |  6 +--
 lib/awful/tag.lua.in                  |  7 +--
 lib/awful/titlebar.lua.in             |  3 ++
 lib/awful/tooltip.lua.in              | 69 ++++++++++++++++-----------
 lib/awful/util.lua.in                 |  5 +-
 lib/awful/wibox.lua.in                |  9 ++--
 lib/awful/widget/button.lua.in        |  3 +-
 lib/awful/widget/graph.lua.in         | 33 ++++++-------
 lib/awful/widget/init.lua.in          |  6 +--
 lib/awful/widget/launcher.lua.in      |  2 +-
 lib/awful/widget/layoutbox.lua.in     |  5 +-
 lib/awful/widget/progressbar.lua.in   | 37 +++++++-------
 lib/awful/widget/prompt.lua.in        |  4 +-
 lib/awful/widget/taglist.lua.in       |  5 +-
 lib/awful/widget/tasklist.lua.in      |  5 +-
 lib/awful/widget/textclock.lua.in     |  6 ++-
 33 files changed, 212 insertions(+), 151 deletions(-)

diff --git a/lib/awful/autofocus.lua.in b/lib/awful/autofocus.lua.in
index 091967a3..c55444a0 100644
--- a/lib/awful/autofocus.lua.in
+++ b/lib/awful/autofocus.lua.in
@@ -1,7 +1,13 @@
 ---------------------------------------------------------------------------
+--- Autofocus functions.
+--
+-- When loaded, this module makes sure that there's always a client that will
+-- have focus on events such as tag switching, client unmanaging, etc.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.autofocus
 ---------------------------------------------------------------------------
 
 local client = client
@@ -10,11 +16,8 @@ local aclient = require("awful.client")
 local atag = require("awful.tag")
 local timer = require("gears.timer")
 
---- When loaded, this module makes sure that there's always a client that will have focus
--- on events such as tag switching, client unmanaging, etc.
--- awful.autofocus
-
 -- Give focus when clients appear/disappear.
+--
 -- @param obj An object that should have a .screen property.
 local function check_focus(obj)
     -- When no visible client has the focus...
@@ -33,6 +36,7 @@ local function check_focus_delayed(obj)
 end
 
 -- Give focus on tag selection change.
+--
 -- @param tag A tag object
 local function check_focus_tag(t)
     local s = atag.getscreen(t)
diff --git a/lib/awful/button.lua.in b/lib/awful/button.lua.in
index 1d3b31c3..759474d3 100644
--- a/lib/awful/button.lua.in
+++ b/lib/awful/button.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Create easily new buttons objects ignoring certain modifiers.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.button
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -10,28 +13,30 @@ local ipairs = ipairs
 local capi = { button = button }
 local util = require("awful.util")
 
---- Create easily new buttons objects ignoring certain modifiers.
--- awful.button
 local button = { mt = {} }
 
---- Modifiers to ignore.
--- By default this is initialized as { "Lock", "Mod2" }
--- so the Caps Lock or Num Lock modifier are not taking into account by awesome
+-- Modifiers to ignore.
+--
+-- By default this is initialized as `{ "Lock", "Mod2" }`
+-- so the `Caps Lock` or `Num Lock` modifier are not taking into account by awesome
 -- when pressing keys.
--- @name ignore_modifiers
--- @class table
+--
+-- @table ignore_modifiers
 local ignore_modifiers = { "Lock", "Mod2" }
 
 --- Create a new button to use as binding.
+--
 -- This function is useful to create several buttons from one, because it will use
 -- the ignore_modifier variable to create more button with or without the ignored
 -- modifiers activated.
+--
 -- For example if you want to ignore CapsLock in your buttonbinding (which is
 -- ignored by default by this function), creating button binding with this function
 -- will return 2 button objects: one with CapsLock on, and the other one with
 -- CapsLock off.
+--
 -- @see button
--- @return A table with one or several button objects.
+-- @treturn table A table with one or several button objects.
 function button.new(mod, _button, press, release)
     local ret = {}
     local subsets = util.subsets(ignore_modifiers)
diff --git a/lib/awful/client.lua.in b/lib/awful/client.lua.in
index 8b1499f4..987473f6 100644
--- a/lib/awful/client.lua.in
+++ b/lib/awful/client.lua.in
@@ -5,7 +5,6 @@
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
 -- @module awful.client
--- @alias client
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -281,6 +280,7 @@ function client.next(i, c)
 end
 
 --- Focus a client by the given direction.
+--
 -- @tparam string dir The direction, can be either 
 --   `"up"`, `"down"`, `"left"` or `"right"`.
 -- @client[opt] c Optional client.
@@ -303,6 +303,7 @@ function client.focus.bydirection(dir, c)
 end
 
 --- Focus a client by the given direction. Moves across screens.
+--
 -- @param dir The direction, can be either "up", "down", "left" or "right".
 -- @client[opt] c Optional client.
 function client.focus.global_bydirection(dir, c)
@@ -335,6 +336,7 @@ function client.focus.global_bydirection(dir, c)
 end
 
 --- Focus a client by its relative index.
+--
 -- @param i The index.
 -- @client[opt] c Optional client.
 function client.focus.byidx(i, c)
diff --git a/lib/awful/completion.lua.in b/lib/awful/completion.lua.in
index 52f7ff2a..6e371004 100644
--- a/lib/awful/completion.lua.in
+++ b/lib/awful/completion.lua.in
@@ -1,8 +1,13 @@
 ---------------------------------------------------------------------------
+--- Completion module.
+--
+-- This module store a set of function using shell to complete commands name.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @author Sébastien Gross &lt;seb-awesome@chezwam.org&gt;
 -- @copyright 2008 Julien Danjou, Sébastien Gross
 -- @release @AWESOME_VERSION@
+-- @module awful.completion
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -15,9 +20,6 @@ local pairs = pairs
 local string = string
 local util = require("awful.util")
 
---- Completion module.
--- This module store a set of function using shell to complete commands name.
--- awful.completion
 local completion = {}
 
 -- mapping of command/completion function
diff --git a/lib/awful/dbus.lua.in b/lib/awful/dbus.lua.in
index 323df02f..c76e7664 100644
--- a/lib/awful/dbus.lua.in
+++ b/lib/awful/dbus.lua.in
@@ -1,17 +1,18 @@
 ---------------------------------------------------------------------------
+--- D-Bus module for awful.
+--
+-- This module simply request the org.naquadah.awesome.awful name on the D-Bus
+-- for futur usage by other awful modules.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.dbus
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
 local dbus = dbus
 
---- D-Bus module for awful.
--- This module simply request the org.naquadah.awesome.awful name on the D-Bus
--- for futur usage by other awful modules.
--- awful.dbus
-
 if dbus then
     dbus.request_name("session", "org.naquadah.awesome.awful")
 end
diff --git a/lib/awful/ewmh.lua.in b/lib/awful/ewmh.lua.in
index d3dd608c..07300f3e 100644
--- a/lib/awful/ewmh.lua.in
+++ b/lib/awful/ewmh.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Implements EWMH requests handling.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.ewmh
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -12,8 +15,6 @@ local math = math
 local atag = require("awful.tag")
 local aclient = require("awful.client")
 
---- Implements EWMH requests handling.
--- awful.ewmh
 local ewmh = {}
 
 local data = setmetatable({}, { __mode = 'k' })
@@ -26,6 +27,7 @@ local function store_geometry(window, reqtype)
 end
 
 -- Maximize a window horizontally.
+--
 -- @param window The window.
 -- @param set Set or unset the maximized values.
 local function maximized_horizontal(window, set)
@@ -43,6 +45,7 @@ local function maximized_horizontal(window, set)
 end
 
 -- Maximize a window vertically.
+--
 -- @param window The window.
 -- @param set Set or unset the maximized values.
 local function maximized_vertical(window, set)
@@ -60,6 +63,7 @@ local function maximized_vertical(window, set)
 end
 
 -- Fullscreen a window.
+--
 -- @param window The window.
 -- @param set Set or unset the fullscreen values.
 local function fullscreen(window, set)
@@ -139,7 +143,9 @@ local function geometry_change(window)
     geometry_change_lock = false
 end
 
--- Activate a window
+--- Activate a window
+--
+-- @client c A client to use
 function ewmh.activate(c)
     if awesome.startup or c:isvisible() then
         client.focus = c
@@ -149,7 +155,10 @@ function ewmh.activate(c)
     end
 end
 
--- Tag a window with its requested tag
+--- Tag a window with its requested tag
+-- 
+-- @client c A client to tag
+-- @tag[opt] t A tag to use. If omitted, then the client is made sticky.
 function ewmh.tag(c, t)
     if not t then
         c.sticky = true
diff --git a/lib/awful/init.lua.in b/lib/awful/init.lua.in
index f299c995..d35d2562 100644
--- a/lib/awful/init.lua.in
+++ b/lib/awful/init.lua.in
@@ -1,12 +1,12 @@
 ---------------------------------------------------------------------------
+--- AWesome Functions very UsefuL
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful
 ---------------------------------------------------------------------------
 
---- AWesome Functions very UsefuL
--- awful
-
 -- TODO: This is a hack for backwards-compatibility with 3.5, remove!
 local util = require("awful.util")
 local gtimer = require("gears.timer")
diff --git a/lib/awful/key.lua.in b/lib/awful/key.lua.in
index 5e211fde..1170d368 100644
--- a/lib/awful/key.lua.in
+++ b/lib/awful/key.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Create easily new key objects ignoring certain modifiers.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.key
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -10,8 +13,6 @@ local ipairs = ipairs
 local capi = { key = key }
 local util = require("awful.util")
 
---- Create easily new key objects ignoring certain modifiers.
--- awful.key
 local key = { mt = {} }
 
 --- Modifiers to ignore.
diff --git a/lib/awful/keygrabber.lua.in b/lib/awful/keygrabber.lua.in
index 88db1dd9..f1c98457 100644
--- a/lib/awful/keygrabber.lua.in
+++ b/lib/awful/keygrabber.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Keygrabber Stack
+--
 -- @author dodo
 -- @copyright 2012 dodo
 -- @release @AWESOME_VERSION@
+-- @module awful.keygrabber
 ---------------------------------------------------------------------------
 
 local ipairs = ipairs
@@ -9,8 +12,6 @@ local table = table
 local capi = {
     keygrabber = keygrabber }
 
---- Keygrabber Stack
--- awful.keygrabber
 local keygrabber = {}
 
 -- Private data
diff --git a/lib/awful/menu.lua.in b/lib/awful/menu.lua.in
index 3919dfcd..27f66aa9 100644
--- a/lib/awful/menu.lua.in
+++ b/lib/awful/menu.lua.in
@@ -1,9 +1,12 @@
 --------------------------------------------------------------------------------
+--- A menu for awful
+--
 -- @author Damien Leone &lt;damien.leone@gmail.com&gt;
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @author dodo
 -- @copyright 2008, 2011 Damien Leone, Julien Danjou, dodo
 -- @release @AWESOME_VERSION@
+-- @module awful.menu
 --------------------------------------------------------------------------------
 
 local wibox = require("wibox")
@@ -31,7 +34,6 @@ local capi = {
     client = client }
 
 
--- awful.menu
 local menu = { mt = {} }
 
 
diff --git a/lib/awful/mouse/finder.lua.in b/lib/awful/mouse/finder.lua.in
index 827dbfde..71515259 100644
--- a/lib/awful/mouse/finder.lua.in
+++ b/lib/awful/mouse/finder.lua.in
@@ -1,7 +1,10 @@
 -------------------------------------------------------------------------
+-- Mouse finder for awful
+--
 -- @author Sébastien Gross &lt;seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt
 -- @copyright 2009 Sébastien Gross
 -- @release @AWESOME_VERSION@
+-- @module awful.mouse.finder
 -------------------------------------------------------------------------
 
 local mouse = mouse
@@ -15,24 +18,23 @@ local setmetatable = setmetatable
 
 --- Find the mouse pointer on the screen.
 -- Mouse finder highlights the mouse cursor on the screen
--- <p>To enable this feature, a <code>awful.mouse.finder</code> object needs to
--- be bound to a key:<br/>
--- <code>mymousefinder = awful.mouse.finder()</code><br/>
--- Then bind the <code>find</code> function a key binding.
--- <p>Some configuration variable can be set in the theme:<br/>
--- The mouse_finder display duration<br/>
--- <code>theme.mouse_finder_timeout = 3</code><br/>
--- The animation speed<br/>
--- <code>theme.mouse_finder_animate_timeout = 0.05</code><br/>
--- The mouse_finder radius<br/>
--- <code>theme.mouse_finder_radius = 20</code><br/>
--- The growth factor<br/>
--- <code>theme.mouse_finder_factor = 2</code><br/>
--- The mouse_finder color<br/>
--- <code>theme.mouse_finder_color = "#ff0000"</code><br/>
--- </p>
+-- To enable this feature, a `awful.mouse.finder` object needs to be bound to a
+-- key:
+--     mymousefinder = awful.mouse.finder()
+-- Then bind the `find` function a key binding.
+--
+-- Some configuration variable can be set in the theme:
+-- The mouse_finder display duration
+--     theme.mouse_finder_timeout = 3
+-- The animation speed
+--     theme.mouse_finder_animate_timeout = 0.05
+-- The mouse_finder radius
+--     theme.mouse_finder_radius = 20
+-- The growth factor
+--     theme.mouse_finder_factor = 2
+-- The mouse_finder color
+--     theme.mouse_finder_color = "#ff0000"
 
--- awful.mouse.finder
 local finder = { mt = {} }
 
 -- Mouse finder private data.
diff --git a/lib/awful/mouse/init.lua.in b/lib/awful/mouse/init.lua.in
index 1fbab97c..5127e0b0 100644
--- a/lib/awful/mouse/init.lua.in
+++ b/lib/awful/mouse/init.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Mouse module for awful
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.mouse
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -25,8 +28,6 @@ local capi =
 
 local finder = require("awful.mouse.finder")
 
---- Mouse module for awful
--- awful.mouse
 local mouse = {}
 
 mouse.client = {}
diff --git a/lib/awful/placement.lua.in b/lib/awful/placement.lua.in
index 275416e0..029fbb65 100644
--- a/lib/awful/placement.lua.in
+++ b/lib/awful/placement.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Places client according to special criteria.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.placement
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -19,8 +22,6 @@ local client = require("awful.client")
 local layout = require("awful.layout")
 local a_screen = require("awful.screen")
 
---- Places client according to special criteria.
--- awful.placement
 local placement = {}
 
 -- Check if an area intersect another area.
diff --git a/lib/awful/prompt.lua.in b/lib/awful/prompt.lua.in
index 6d2e3136..d9f2ea88 100644
--- a/lib/awful/prompt.lua.in
+++ b/lib/awful/prompt.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Prompt module for awful
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.prompt
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -19,8 +22,6 @@ local keygrabber = require("awful.keygrabber")
 local util = require("awful.util")
 local beautiful = require("beautiful")
 
---- Prompt module for awful
--- awful.prompt
 local prompt = {}
 
 --- Private data
diff --git a/lib/awful/remote.lua.in b/lib/awful/remote.lua.in
index ccc9ec20..0f5188fa 100644
--- a/lib/awful/remote.lua.in
+++ b/lib/awful/remote.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Remote control module allowing usage of awesome-client.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.remote
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -14,9 +17,6 @@ local unpack = unpack or table.unpack -- v5.1: unpack, v5.2: table.unpack
 local dbus = dbus
 local type = type
 
---- Remote control module allowing usage of awesome-client.
--- awful.remote
-
 if dbus then
     dbus.connect_signal("org.naquadah.awesome.awful.Remote", function(data, code)
         if data.member == "Eval" then
diff --git a/lib/awful/rules.lua.in b/lib/awful/rules.lua.in
index 4b7d2d0a..2811c9a5 100644
--- a/lib/awful/rules.lua.in
+++ b/lib/awful/rules.lua.in
@@ -1,9 +1,10 @@
 ---------------------------------------------------------------------------
--- Apply rules to clients at startup.
+--- Apply rules to clients at startup.
 --
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.rules
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
diff --git a/lib/awful/screen.lua.in b/lib/awful/screen.lua.in
index 07a9bc17..6fd0056c 100644
--- a/lib/awful/screen.lua.in
+++ b/lib/awful/screen.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Screen module for awful
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.screen
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -16,8 +19,6 @@ local util = require("awful.util")
 -- we use require("awful.client") inside functions to prevent circular dependencies.
 local client
 
---- Screen module for awful
--- awful.screen
 local screen = {}
 
 local data = {}
diff --git a/lib/awful/startup_notification.lua.in b/lib/awful/startup_notification.lua.in
index 80a0a367..85e72bd8 100644
--- a/lib/awful/startup_notification.lua.in
+++ b/lib/awful/startup_notification.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Startup notification module for awful
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.startup_notification
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -13,9 +16,6 @@ local capi =
     root = root
 }
 
---- Startup notification module for awful
--- awful.startup_notification
-
 local app_starting = {}
 
 local cursor_waiting = "watch"
diff --git a/lib/awful/tag.lua.in b/lib/awful/tag.lua.in
index 401c61fa..57f98be0 100644
--- a/lib/awful/tag.lua.in
+++ b/lib/awful/tag.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Useful functions for tag manipulation.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.tag
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -21,8 +24,6 @@ local capi =
     root = root
 }
 
---- Useful functions for tag manipulation.
--- awful.tag
 local tag = { mt = {} }
 
 -- Private data
@@ -552,7 +553,7 @@ function tag.getdata(_tag)
 end
 
 --- Get a tag property.
--- @param _tag The tag.
+-- @tparam tag _tag The tag.
 -- @tparam string prop The property name.
 -- @return The property.
 function tag.getproperty(_tag, prop)
diff --git a/lib/awful/titlebar.lua.in b/lib/awful/titlebar.lua.in
index aff36308..7654083d 100644
--- a/lib/awful/titlebar.lua.in
+++ b/lib/awful/titlebar.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+-- Titlebars for awful.
+--
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @module awful.titlebar
 ---------------------------------------------------------------------------
 
 local error = error
diff --git a/lib/awful/tooltip.lua.in b/lib/awful/tooltip.lua.in
index b84fc8ec..2735511b 100644
--- a/lib/awful/tooltip.lua.in
+++ b/lib/awful/tooltip.lua.in
@@ -1,40 +1,43 @@
+-------------------------------------------------------------------------
 --- Tooltip module for awesome objects.
 --
 -- A tooltip is a small hint displayed when the mouse cursor
 -- hovers a specific item.
 -- In awesome, a tooltip can be linked with almost any
--- object having a <code>connect_signal()</code> method and receiving
--- <code>mouse::enter</code> and <code>mouse::leave</code> signals.
--- <p>How to create a tooltip?<br/>
---  <code>
---  myclock = awful.widget.textclock({}, "%T", 1)<br/>
---  myclock_t = awful.tooltip({<br/>
---      objects = { myclock },<br/>
---      timer_function = function()<br/>
---              return os.date("Today is %A %B %d %Y\nThe time is %T")<br/>
---          end,<br/>
---      })<br/>
---  </code>
--- </p>
--- <p>How to add the same tooltip to several objects?<br/>
--- <code>
---     myclock_t:add_to_object(obj1)<br/>
---     myclock_t:add_to_object(obj2)<br/>
--- </code>
--- Now the same tooltip is attached to <code>myclock</code>, <code>obj1</code>,
---    <code>obj2</code>.<br/>
--- </p>
--- <p>How to remove tooltip from many objects?<br/>
--- <code>
---     myclock_t:remove_from_object(obj1)<br/>
---     myclock_t:remove_from_object(obj2)<br/>
--- </code>
--- Now the same tooltip is only attached to <code>myclock</code>.<br/>
--- </p>
+-- object having a `:connect_signal()` method and receiving
+-- `mouse::enter` and `mouse::leave` signals.
 --
--- @author Sébastien Gross &lt;seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt
+-- How to create a tooltip?
+-- ---
+--
+--     myclock = awful.widget.textclock({}, "%T", 1)
+--     myclock_t = awful.tooltip({
+--         objects = { myclock },
+--         timer_function = function()
+--                 return os.date("Today is %A %B %d %Y\nThe time is %T")
+--             end,
+--         })
+--
+-- How to add the same tooltip to several objects?
+-- ---
+--
+--     myclock_t:add_to_object(obj1)
+--     myclock_t:add_to_object(obj2)
+--
+-- Now the same tooltip is attached to `myclock`, `obj1`, `obj2`.
+--
+-- How to remove tooltip from many objects?
+-- ---
+--
+--     myclock_t:remove_from_object(obj1)
+--     myclock_t:remove_from_object(obj2)
+--
+-- Now the same tooltip is only attached to `myclock`.
+--
+-- @author Sébastien Gross &lt;seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt;
 -- @copyright 2009 Sébastien Gross
 -- @release @AWESOME_VERSION@
+-- @module awful.tooltip
 -------------------------------------------------------------------------
 
 local mouse = mouse
@@ -73,6 +76,7 @@ local function place(self)
 end
 
 -- Place the tooltip under the mouse.
+--
 -- @param self A tooltip object.
 local function set_geometry(self)
     local my_geo = self.wibox:geometry()
@@ -84,6 +88,7 @@ local function set_geometry(self)
 end
 
 -- Show a tooltip.
+--
 -- @param self The tooltip to show.
 local function show(self)
     -- do nothing if the tooltip is already shown
@@ -101,6 +106,7 @@ local function show(self)
 end
 
 -- Hide a tooltip.
+--
 -- @param self The tooltip to hide.
 local function hide(self)
     -- do nothing if the tooltip is already hidden
@@ -115,6 +121,7 @@ local function hide(self)
 end
 
 --- Change displayed text.
+--
 -- @param self The tooltip object.
 -- @param text New tooltip text.
 tooltip.set_text = function(self, text)
@@ -123,6 +130,7 @@ tooltip.set_text = function(self, text)
 end
 
 --- Change displayed text.
+--
 -- @param self The tooltip object.
 -- @param text New tooltip text, including pango markup.
 tooltip.set_markup = function(self, text)
@@ -131,6 +139,7 @@ tooltip.set_markup = function(self, text)
 end
 
 --- Change the tooltip's update interval.
+--
 -- @param self A tooltip object.
 -- @param timeout The timeout value.
 -- @function set_timeout
@@ -141,6 +150,7 @@ tooltip.set_timeout = function(self, timeout)
 end
 
 --- Add tooltip to an object.
+--
 -- @param self The tooltip.
 -- @param object An object.
 tooltip.add_to_object = function(self, object)
@@ -149,6 +159,7 @@ tooltip.add_to_object = function(self, object)
 end
 
 --- Remove tooltip from an object.
+--
 -- @param self The tooltip.
 -- @param object An object.
 -- @function remove_from_object
diff --git a/lib/awful/util.lua.in b/lib/awful/util.lua.in
index 4e765805..83d8d446 100644
--- a/lib/awful/util.lua.in
+++ b/lib/awful/util.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Utility module for awful
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.util
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -23,8 +26,6 @@ local capi =
     mouse = mouse
 }
 
---- Utility module for awful
--- awful.util
 local util = {}
 util.table = {}
 
diff --git a/lib/awful/wibox.lua.in b/lib/awful/wibox.lua.in
index f48ece3b..c514a992 100644
--- a/lib/awful/wibox.lua.in
+++ b/lib/awful/wibox.lua.in
@@ -1,7 +1,12 @@
 ---------------------------------------------------------------------------
+--- Wibox module for awful.
+-- This module allows you to easily create wibox and attach them to the edge of
+-- a screen.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.wibox
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -19,10 +24,6 @@ local error = error
 local wibox = require("wibox")
 local beautiful = require("beautiful")
 
---- Wibox module for awful.
--- This module allows you to easily create wibox and attach them to the edge of
--- a screen.
--- awful.wibox
 local awfulwibox = { mt = {} }
 
 -- Array of table with wiboxes inside.
diff --git a/lib/awful/widget/button.lua.in b/lib/awful/widget/button.lua.in
index 204081e7..25f2da64 100644
--- a/lib/awful/widget/button.lua.in
+++ b/lib/awful/widget/button.lua.in
@@ -2,6 +2,7 @@
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008-2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.button
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -13,11 +14,11 @@ local surface = require("gears.surface")
 local cairo = require("lgi").cairo
 local capi = { mouse = mouse }
 
--- awful.widget.button
 local button = { mt = {} }
 
 --- Create a button widget. When clicked, the image is deplaced to make it like
 -- a real button.
+--
 -- @param args Widget arguments. "image" is the image to display.
 -- @return A textbox widget configured as a button.
 function button.new(args)
diff --git a/lib/awful/widget/graph.lua.in b/lib/awful/widget/graph.lua.in
index 4f5dc134..17e0a9ca 100644
--- a/lib/awful/widget/graph.lua.in
+++ b/lib/awful/widget/graph.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- A graph widget.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.graph
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -12,54 +15,52 @@ local type = type
 local color = require("gears.color")
 local base = require("wibox.widget.base")
 
---- A graph widget.
--- awful.widget.graph
 local graph = { mt = {} }
 
 local data = setmetatable({}, { __mode = "k" })
 
 --- Set the graph border color.
 -- If the value is nil, no border will be drawn.
--- @name set_border_color
--- @class function
+--
+-- @function set_border_color
 -- @param graph The graph.
 -- @param color The border color to set.
 
 --- Set the graph foreground color.
--- @name set_color
--- @class function
+--
+-- @function set_color
 -- @param graph The graph.
 -- @param color The graph color.
 
 --- Set the graph background color.
--- @name set_background_color
--- @class function
+--
+-- @function set_background_color
 -- @param graph The graph.
 -- @param color The graph background color.
 
 --- Set the maximum value the graph should handle.
 -- If "scale" is also set, the graph never scales up below this value, but it
 -- automatically scales down to make all data fit.
--- @name set_max_value
--- @class function
+--
+-- @function set_max_value
 -- @param graph The graph.
 -- @param value The value.
 
 --- Set the graph to automatically scale its values. Default is false.
--- @name set_scale
--- @class function
+--
+-- @function set_scale
 -- @param graph The graph.
 -- @param scale A boolean value
 
 --- Set the graph to draw stacks. Default is false.
--- @name set_stack
--- @class function
+--
+-- @function set_stack
 -- @param graph The graph.
 -- @param stack A boolean value.
 
 --- Set the graph stacking colors. Order matters.
--- @name set_stack_colors
--- @class function
+--
+-- @function set_stack_colors
 -- @param graph The graph.
 -- @param stack_colors A table with stacking colors.
 
diff --git a/lib/awful/widget/init.lua.in b/lib/awful/widget/init.lua.in
index c414d132..96ec4615 100644
--- a/lib/awful/widget/init.lua.in
+++ b/lib/awful/widget/init.lua.in
@@ -1,12 +1,12 @@
 ---------------------------------------------------------------------------
+--- Widget module for awful
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008-2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @module awful.widget
 ---------------------------------------------------------------------------
 
---- Widget module for awful
--- awful.widget
-
 return
 {
     taglist = require("awful.widget.taglist");
diff --git a/lib/awful/widget/launcher.lua.in b/lib/awful/widget/launcher.lua.in
index aff7ff9b..91833f26 100644
--- a/lib/awful/widget/launcher.lua.in
+++ b/lib/awful/widget/launcher.lua.in
@@ -2,6 +2,7 @@
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008-2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.launcher
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -9,7 +10,6 @@ local util = require("awful.util")
 local wbutton = require("awful.widget.button")
 local button = require("awful.button")
 
--- awful.widget.launcher
 local launcher = { mt = {} }
 
 --- Create a button widget which will launch a command.
diff --git a/lib/awful/widget/layoutbox.lua.in b/lib/awful/widget/layoutbox.lua.in
index f332b8d5..ee6d2b79 100644
--- a/lib/awful/widget/layoutbox.lua.in
+++ b/lib/awful/widget/layoutbox.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Layoutbox widget.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.layoutbox
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -12,8 +15,6 @@ local tag = require("awful.tag")
 local beautiful = require("beautiful")
 local imagebox = require("wibox.widget.imagebox")
 
---- Layoutbox widget.
--- awful.widget.layoutbox
 local layoutbox = { mt = {} }
 
 local function update(w, screen)
diff --git a/lib/awful/widget/progressbar.lua.in b/lib/awful/widget/progressbar.lua.in
index b8c906d5..e85d1d95 100644
--- a/lib/awful/widget/progressbar.lua.in
+++ b/lib/awful/widget/progressbar.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- A progressbar widget.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.progressbar
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -10,58 +13,56 @@ local math = math
 local base = require("wibox.widget.base")
 local color = require("gears.color")
 
---- A progressbar widget.
--- awful.widget.progressbar
 local progressbar = { mt = {} }
 
 local data = setmetatable({}, { __mode = "k" })
 
 --- Set the progressbar border color.
 -- If the value is nil, no border will be drawn.
--- @name set_border_color
--- @class function
+--
+-- @function set_border_color
 -- @param progressbar The progressbar.
 -- @param color The border color to set.
 
 --- Set the progressbar foreground color.
--- @name set_color
--- @class function
+--
+-- @function set_color
 -- @param progressbar The progressbar.
 -- @param color The progressbar color.
 
 --- Set the progressbar background color.
--- @name set_background_color
--- @class function
+--
+-- @function set_background_color
 -- @param progressbar The progressbar.
 -- @param color The progressbar background color.
 
 --- Set the progressbar to draw vertically. Default is false.
--- @name set_vertical
--- @class function
+--
+-- @function set_vertical
 -- @param progressbar The progressbar.
 -- @param vertical A boolean value.
 
 --- Set the progressbar to draw ticks. Default is false.
--- @name set_ticks
--- @class function
+--
+-- @function set_ticks
 -- @param progressbar The progressbar.
 -- @param ticks A boolean value.
 
 --- Set the progressbar ticks gap.
--- @name set_ticks_gap
--- @class function
+--
+-- @function set_ticks_gap
 -- @param progressbar The progressbar.
 -- @param value The value.
 
 --- Set the progressbar ticks size.
--- @name set_ticks_size
--- @class function
+--
+-- @function set_ticks_size
 -- @param progressbar The progressbar.
 -- @param value The value.
 
 --- Set the maximum value the progressbar should handle.
--- @name set_max_value
--- @class function
+--
+-- @function set_max_value
 -- @param progressbar The progressbar.
 -- @param value The value.
 
diff --git a/lib/awful/widget/prompt.lua.in b/lib/awful/widget/prompt.lua.in
index f058828a..bbcde7b7 100644
--- a/lib/awful/widget/prompt.lua.in
+++ b/lib/awful/widget/prompt.lua.in
@@ -2,6 +2,7 @@
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.prompt
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -13,10 +14,10 @@ local widget_base = require("wibox.widget.base")
 local textbox = require("wibox.widget.textbox")
 local type = type
 
--- awful.widget.prompt
 local widgetprompt = { mt = {} }
 
 --- Run method for promptbox.
+--
 -- @param promptbox The promptbox to run.
 local function run(promptbox)
     return prompt.run({ prompt = promptbox.prompt },
@@ -32,6 +33,7 @@ local function run(promptbox)
 end
 
 --- Create a prompt widget which will launch a command.
+--
 -- @param args Arguments table. "prompt" is the prompt to use.
 -- @return A launcher widget.
 function widgetprompt.new(args)
diff --git a/lib/awful/widget/taglist.lua.in b/lib/awful/widget/taglist.lua.in
index be783268..bf30508d 100644
--- a/lib/awful/widget/taglist.lua.in
+++ b/lib/awful/widget/taglist.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Taglist widget module for awful
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008-2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.taglist
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -20,8 +23,6 @@ local beautiful = require("beautiful")
 local fixed = require("wibox.layout.fixed")
 local surface = require("gears.surface")
 
---- Taglist widget module for awful
--- awful.widget.taglist
 local taglist = { mt = {} }
 taglist.filter = {}
 
diff --git a/lib/awful/widget/tasklist.lua.in b/lib/awful/widget/tasklist.lua.in
index 4f24e847..7eef4dab 100644
--- a/lib/awful/widget/tasklist.lua.in
+++ b/lib/awful/widget/tasklist.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Tasklist widget module for awful
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008-2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.tasklist
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -17,8 +20,6 @@ local util = require("awful.util")
 local tag = require("awful.tag")
 local flex = require("wibox.layout.flex")
 
---- Tasklist widget module for awful
--- awful.widget.tasklist
 local tasklist = { mt = {} }
 
 -- Public structures
diff --git a/lib/awful/widget/textclock.lua.in b/lib/awful/widget/textclock.lua.in
index 9b6f2014..5501c7eb 100644
--- a/lib/awful/widget/textclock.lua.in
+++ b/lib/awful/widget/textclock.lua.in
@@ -1,7 +1,10 @@
 ---------------------------------------------------------------------------
+--- Text clock widget.
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2009 Julien Danjou
 -- @release @AWESOME_VERSION@
+-- @classmod awful.widget.textclock
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -9,8 +12,6 @@ local os = os
 local textbox = require("wibox.widget.textbox")
 local timer = require("gears.timer")
 
---- Text clock widget.
--- awful.widget.textclock
 local textclock = { mt = {} }
 
 -- This lowers the timeout so that it occurs "correctly". For example, a timeout
@@ -20,6 +21,7 @@ local function calc_timeout(real_timeout)
 end
 
 --- Create a textclock widget. It draws the time it is in a textbox.
+--
 -- @param format The time format. Default is " %a %b %d, %H:%M ".
 -- @param timeout How often update the time. Default is 60.
 -- @return A textbox widget.