Merge pull request #121 from awesomeWM/doc-fix-tooltip

doc: fix/improve markup for awful.tooltip

lib/awful/tooltip.lua.in

@@ -1,21 +1,5 @@
--------------------------------------------------------------------------
--- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt
--- @copyright 2009 Sébastien Gross
--- @release @AWESOME_VERSION@
--------------------------------------------------------------------------
-
-local mouse = mouse
-local screen = screen
-local timer = require("gears.timer")
-local wibox = require("wibox")
-local a_placement = require("awful.placement")
-local beautiful = require("beautiful")
-local textbox = require("wibox.widget.textbox")
-local background = require("wibox.widget.background")
-local setmetatable = setmetatable
-local ipairs = ipairs
-
 --- 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
@@ -47,27 +31,41 @@ local ipairs = ipairs
 -- </code>
 -- Now the same tooltip is only attached to <code>myclock</code>.<br/>
 -- </p>
--- awful.tooltip
-local tooltip = { mt = {} }
+--
+-- @author Sébastien Gross &lt;seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt
+-- @copyright 2009 Sébastien Gross
+-- @release @AWESOME_VERSION@
+-------------------------------------------------------------------------
 
-local data = setmetatable({}, { __mode = 'k' })
+local mouse = mouse
+local screen = screen
+local timer = require("gears.timer")
+local wibox = require("wibox")
+local a_placement = require("awful.placement")
+local beautiful = require("beautiful")
+local textbox = require("wibox.widget.textbox")
+local background = require("wibox.widget.background")
+local setmetatable = setmetatable
+local ipairs = ipairs
 
 --- Tooltip object definition.
--- @name tooltip
+-- @table awful.tooltip
 -- @field wibox The wibox displaying the tooltip.
 -- @field visible True if tooltip is visible.
--- @class table
+local tooltip = { mt = {}  }
 
--- Tooltip private data.
--- @name awful.tooltip.data
+--- Tooltip private data.
+-- @local
+-- @table awful.tooltip.data
 -- @field fg tooltip foreground color.
 -- @field font Tooltip font.
 -- @field hide The hide() function.
 -- @field show The show() function.
 -- @field timer The text update timer.
 -- @field timer_function The text update timer function.
+local data = setmetatable({}, { __mode = 'k' })
 
--- Place to tooltip on th screen.
+-- Place the tooltip on the screen.
 -- @param self A tooltip object.
 local function place(self)
     a_placement.under_mouse(self.wibox)
@@ -119,7 +117,7 @@ end
 --- Change displayed text.
 -- @param self The tooltip object.
 -- @param text New tooltip text.
-local function set_text(self, text)
+tooltip.set_text = function(self, text)
     self.textbox:set_text(text)
     set_geometry(self)
 end
@@ -127,7 +125,7 @@ end
 --- Change displayed text.
 -- @param self The tooltip object.
 -- @param text New tooltip text, including pango markup.
-local function set_markup(self, text)
+tooltip.set_markup = function(self, text)
     self.textbox:set_markup(text)
     set_geometry(self)
 end
@@ -135,7 +133,8 @@ end
 --- Change the tooltip's update interval.
 -- @param self A tooltip object.
 -- @param timeout The timeout value.
-local function set_timeout(self, timeout)
+-- @function set_timeout
+tooltip.set_timeout = function(self, timeout)
     if data[self].timer then
         data[self].timer.timeout = timeout
     end
@@ -144,7 +143,7 @@ end
 --- Add tooltip to an object.
 -- @param self The tooltip.
 -- @param object An object.
-local function add_to_object(self, object)
+tooltip.add_to_object = function(self, object)
     object:connect_signal("mouse::enter", data[self].show)
     object:connect_signal("mouse::leave", data[self].hide)
 end
@@ -152,24 +151,25 @@ end
 --- Remove tooltip from an object.
 -- @param self The tooltip.
 -- @param object An object.
-local function remove_from_object(self, object)
+-- @function remove_from_object
+tooltip.remove_from_object = function(self, object)
     object:disconnect_signal("mouse::enter", data[self].show)
     object:disconnect_signal("mouse::leave", data[self].hide)
 end
 
 
 --- Create a new tooltip and link it to a widget.
--- @param args Arguments for tooltip creation may containt:<br/>
--- <code>timeout</code>: The timeout value for update_func.<br/>
--- <code>timer_function</code>: A function to dynamically change the tooltip
---     text.<br/>
--- <code>objects</code>: A list of objects linked to the tooltip.<br/>
+-- @tparam table    args Arguments for tooltip creation.
+-- @tparam number   args.timeout The timeout value for update_func.
+-- @tparam function args.timer_function A function to dynamically change the
+--                                      tooltip text.
+-- @tparam table    args.objects A list of objects linked to the tooltip.
 -- @return The created tooltip.
 -- @see add_to_object
 -- @see set_timeout
 -- @see set_text
 -- @see set_markup
-local function new(args)
+tooltip.new = function(args)
     local self = {
         wibox =  wibox({ }),
         visible = false,
@@ -182,11 +182,11 @@ local function new(args)
     }
 
     -- export functions
-    self.set_text = set_text
-    self.set_markup = set_markup
-    self.set_timeout = set_timeout
-    self.add_to_object = add_to_object
-    self.remove_from_object = remove_from_object
+    self.set_text = tooltip.set_text
+    self.set_markup = tooltip.set_markup
+    self.set_timeout = tooltip.set_timeout
+    self.add_to_object = tooltip.add_to_object
+    self.remove_from_object = tooltip.remove_from_object
 
     -- setup the timer action only if needed
     if args.timer_function then
@@ -229,7 +229,7 @@ local function new(args)
 end
 
 function tooltip.mt:__call(...)
-    return new(...)
+    return tooltip.new(...)
 end
 
 return setmetatable(tooltip, tooltip.mt)