From 7f8a0787b84ebef5736c35cfcce5e8cf85b3e708 Mon Sep 17 00:00:00 2001 From: "Ignas Anikevicius (gns_ank)" 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) --- 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 091967a32..c55444a02 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 <julien@danjou.info> -- @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 1d3b31c3a..759474d3c 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 <julien@danjou.info> -- @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 8b1499f4e..987473f67 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 52f7ff2a1..6e371004d 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 <julien@danjou.info> -- @author Sébastien Gross <seb-awesome@chezwam.org> -- @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 323df02f7..c76e76649 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 <julien@danjou.info> -- @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 d3dd608c9..07300f3e2 100644 --- a/lib/awful/ewmh.lua.in +++ b/lib/awful/ewmh.lua.in @@ -1,7 +1,10 @@ --------------------------------------------------------------------------- +--- Implements EWMH requests handling. +-- -- @author Julien Danjou <julien@danjou.info> -- @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 f299c9958..d35d25629 100644 --- a/lib/awful/init.lua.in +++ b/lib/awful/init.lua.in @@ -1,12 +1,12 @@ --------------------------------------------------------------------------- +--- AWesome Functions very UsefuL +-- -- @author Julien Danjou <julien@danjou.info> -- @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 5e211fde3..1170d3681 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 <julien@danjou.info> -- @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 88db1dd96..f1c984574 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 3919dfcde..27f66aa9e 100644 --- a/lib/awful/menu.lua.in +++ b/lib/awful/menu.lua.in @@ -1,9 +1,12 @@ -------------------------------------------------------------------------------- +--- A menu for awful +-- -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> -- @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 827dbfdee..715152598 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 <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org> -- @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 ---

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"
---

+-- 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 1fbab97ca..5127e0b04 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 <julien@danjou.info> -- @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 275416e0c..029fbb657 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 <julien@danjou.info> -- @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 6d2e31369..d9f2ea88d 100644 --- a/lib/awful/prompt.lua.in +++ b/lib/awful/prompt.lua.in @@ -1,7 +1,10 @@ --------------------------------------------------------------------------- +--- Prompt module for awful +-- -- @author Julien Danjou <julien@danjou.info> -- @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 ccc9ec209..0f5188fab 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 <julien@danjou.info> -- @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 4b7d2d0aa..2811c9a59 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 <julien@danjou.info> -- @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 07a9bc179..6fd0056c8 100644 --- a/lib/awful/screen.lua.in +++ b/lib/awful/screen.lua.in @@ -1,7 +1,10 @@ --------------------------------------------------------------------------- +--- Screen module for awful +-- -- @author Julien Danjou <julien@danjou.info> -- @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 80a0a3677..85e72bd8f 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 <julien@danjou.info> -- @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 401c61fa1..57f98be03 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 <julien@danjou.info> -- @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 aff36308a..7654083d9 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 b84fc8ec5..2735511bb 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 connect_signal() method and receiving --- mouse::enter and mouse::leave signals. ---

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.
---

+-- object having a `:connect_signal()` method and receiving +-- `mouse::enter` and `mouse::leave` signals. -- --- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org> +-- 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 <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org> -- @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 4e765805d..83d8d446c 100644 --- a/lib/awful/util.lua.in +++ b/lib/awful/util.lua.in @@ -1,7 +1,10 @@ --------------------------------------------------------------------------- +--- Utility module for awful +-- -- @author Julien Danjou <julien@danjou.info> -- @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 f48ece3bc..c514a9927 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 <julien@danjou.info> -- @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 204081e75..25f2da642 100644 --- a/lib/awful/widget/button.lua.in +++ b/lib/awful/widget/button.lua.in @@ -2,6 +2,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @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 4f5dc134c..17e0a9ca7 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 <julien@danjou.info> -- @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 c414d1323..96ec4615b 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 <julien@danjou.info> -- @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 aff7ff9bf..91833f265 100644 --- a/lib/awful/widget/launcher.lua.in +++ b/lib/awful/widget/launcher.lua.in @@ -2,6 +2,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @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 f332b8d5a..ee6d2b798 100644 --- a/lib/awful/widget/layoutbox.lua.in +++ b/lib/awful/widget/layoutbox.lua.in @@ -1,7 +1,10 @@ --------------------------------------------------------------------------- +--- Layoutbox widget. +-- -- @author Julien Danjou <julien@danjou.info> -- @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 b8c906d5f..e85d1d951 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 <julien@danjou.info> -- @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 f058828ad..bbcde7b76 100644 --- a/lib/awful/widget/prompt.lua.in +++ b/lib/awful/widget/prompt.lua.in @@ -2,6 +2,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @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 be7832685..bf30508d7 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 <julien@danjou.info> -- @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 4f24e847c..7eef4dab2 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 <julien@danjou.info> -- @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 9b6f2014a..5501c7ebb 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 <julien@danjou.info> -- @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.