Some more doc fixes all over the place.

Signed-off-by: Julian Wollrath <jwollrath@web.de>

lib/awful/autofocus.lua.in

@@ -16,7 +16,7 @@ local aclient = require("awful.client")
 local atag = require("awful.tag")
 local timer = require("gears.timer")
 
--- Give focus when clients appear/disappear.
+--- Give focus when clients appear/disappear.
 --
 -- @param obj An object that should have a .screen property.
 local function check_focus(obj)
@@ -29,13 +29,13 @@ local function check_focus(obj)
     end
 end
 
--- Check client focus (delayed).
+--- Check client focus (delayed).
 -- @param obj An object that should have a .screen property.
 local function check_focus_delayed(obj)
     timer.delayed_call(check_focus, {screen = obj.screen})
 end
 
--- Give focus on tag selection change.
+--- Give focus on tag selection change.
 --
 -- @param tag A tag object
 local function check_focus_tag(t)

lib/awful/button.lua.in

@@ -15,7 +15,7 @@ local util = require("awful.util")
 
 local button = { mt = {} }
 
--- Modifiers to ignore.
+--- 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

lib/awful/client.lua.in

@@ -720,7 +720,7 @@ function client.restore(s)
     return nil
 end
 
--- Normalize a set of numbers to 1
+--- Normalize a set of numbers to 1
 -- @param set the set of numbers to normalize
 -- @param num the number of numbers to normalize
 local function normalize(set, num)

lib/awful/ewmh.lua.in

@@ -26,7 +26,7 @@ local function store_geometry(window, reqtype)
     data[window][reqtype].screen = window.screen
 end
 
--- Maximize a window horizontally.
+--- Maximize a window horizontally.
 --
 -- @param window The window.
 -- @param set Set or unset the maximized values.
@@ -44,7 +44,7 @@ local function maximized_horizontal(window, set)
     end
 end
 
--- Maximize a window vertically.
+--- Maximize a window vertically.
 --
 -- @param window The window.
 -- @param set Set or unset the maximized values.
@@ -62,7 +62,7 @@ local function maximized_vertical(window, set)
     end
 end
 
--- Fullscreen a window.
+--- Fullscreen a window.
 --
 -- @param window The window.
 -- @param set Set or unset the fullscreen values.
@@ -119,7 +119,7 @@ local function screen_change(window)
     end
 end
 
--- Update a client's settings when its geometry changes, skipping signals
+--- Update a client's settings when its geometry changes, skipping signals
 -- resulting from calls within.
 local geometry_change_lock = false
 local function geometry_change(window)

lib/awful/layout/suit/fair.lua.in

@@ -87,7 +87,7 @@ function fair.horizontal.arrange(p)
     return do_fair(p, "east")
 end
 
--- Vertical fair layout.
+--- Vertical fair layout.
 -- @param screen The screen to arrange.
 fair.name = "fairv"
 function fair.arrange(p)

lib/awful/menu.lua.in

@@ -425,8 +425,7 @@ function menu:add(args, index)
     return item
 end
 
--- Delete menu entry at given position
--- @param _menu The menu
+--- Delete menu entry at given position
 -- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself
 function menu:delete(num)
     if type(num) == "table" then

lib/awful/mouse/finder.lua.in

@@ -1,22 +1,7 @@
 -------------------------------------------------------------------------
--- Mouse finder for awful
+--- Mouse finder for awful
 --
--- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt
--- @copyright 2009 Sébastien Gross
--- @release @AWESOME_VERSION@
--- @module awful.mouse.finder
--------------------------------------------------------------------------
-
-local mouse = mouse
-local screen = screen
-local timer = require("gears.timer")
-local wibox = require("wibox")
-local a_placement = require("awful.placement")
-local a_wibox = require("awful.wibox")
-local beautiful = require("beautiful")
-local setmetatable = setmetatable
-
---- Find the mouse pointer on the screen.
+-- 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:
@@ -34,10 +19,25 @@ local setmetatable = setmetatable
 --     theme.mouse_finder_factor = 2
 -- The mouse_finder color
 --     theme.mouse_finder_color = "#ff0000"
+--
+-- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt
+-- @copyright 2009 Sébastien Gross
+-- @release @AWESOME_VERSION@
+-- @module awful.mouse.finder
+-------------------------------------------------------------------------
+
+local mouse = mouse
+local screen = screen
+local timer = require("gears.timer")
+local wibox = require("wibox")
+local a_placement = require("awful.placement")
+local a_wibox = require("awful.wibox")
+local beautiful = require("beautiful")
+local setmetatable = setmetatable
 
 local finder = { mt = {} }
 
--- Mouse finder private data.
+--- Mouse finder private data.
 -- @name data
 -- @field color Background color.
 -- @field hide The hide() function.
@@ -47,14 +47,14 @@ local finder = { mt = {} }
 -- @field wibox The mouse finder wibox show on the screen.
 local data = setmetatable({}, { __mode = 'k' })
 
--- Place a mouse finder on the screen.
+--- Place a mouse finder on the screen.
 -- @param self A mouse finder object.
 local function place(self)
     a_placement.under_mouse(data[self].wibox)
     a_placement.no_offscreen(data[self].wibox)
 end
 
--- Animate a mouse finder.
+--- Animate a mouse finder.
 -- @param self A mouse finder object.
 local function animate(self)
     local r = data[self].wibox:geometry().width
@@ -76,7 +76,7 @@ local function animate(self)
 end
 
 
--- Show a mouse finder.
+--- Show a mouse finder.
 -- @param self The mouse finder to show.
 local function show(self)
     -- do nothing if the mouse finder is already shown
@@ -92,7 +92,7 @@ local function show(self)
     data[self].wibox.visible = true
 end
 
--- Hide a mouse finder.
+--- Hide a mouse finder.
 -- @param self The mouse finder to hide.
 local function hide(self)
     -- do nothing if the mouse finder is already hidden
@@ -104,7 +104,7 @@ local function hide(self)
     data[self].wibox.visible = false
 end
 
--- Load Default values.
+--- Load Default values.
 -- @param self A mouse finder object.
 local function set_defaults(self)
     data[self].wibox.border_width = 0

lib/awful/placement.lua.in

@@ -24,7 +24,7 @@ local a_screen = require("awful.screen")
 
 local placement = {}
 
--- Check if an area intersect another area.
+--- Check if an area intersect another area.
 -- @param a The area.
 -- @param b The other area.
 -- @return True if they intersect, false otherwise.
@@ -35,7 +35,7 @@ local function area_intersect_area(a, b)
             and b.y + b.height > a.y)
 end
 
--- Get the intersect area between a and b.
+--- Get the intersect area between a and b.
 -- @param a The area.
 -- @param b The other area.
 -- @return The intersect area.
@@ -48,7 +48,7 @@ local function area_intersect_area_get(a, b)
     return g
 end
 
--- Remove an area from a list, splitting the space between several area that
+--- Remove an area from a list, splitting the space between several area that
 -- can overlap.
 -- @param areas Table of areas.
 -- @param elem Area to remove.

lib/awful/prompt.lua.in

@@ -35,7 +35,7 @@ local function itera (inc,a, i)
 	if v then return i,v end
 end
 
--- Load history file in history table
+--- Load history file in history table
 -- @param id The data.history identifier which is the path to the filename
 -- @param max Optional parameter, the maximum number of entries in file
 local function history_check_load(id, max)
@@ -64,7 +64,7 @@ local function history_check_load(id, max)
     end
 end
 
--- Save history table in history file
+--- Save history table in history file
 -- @param id The data.history identifier
 local function history_save(id)
     if data.history[id] then
@@ -84,7 +84,7 @@ local function history_save(id)
     end
 end
 
--- Return the number of items in history table regarding the id
+--- Return the number of items in history table regarding the id
 -- @param id The data.history identifier
 -- @return the number of items in history table, -1 if history is disabled
 local function history_items(id)
@@ -95,7 +95,7 @@ local function history_items(id)
     end
 end
 
--- Add an entry to the history file
+--- Add an entry to the history file
 -- @param id The data.history identifier
 -- @param command The command to add
 local function history_add(id, command)
@@ -120,16 +120,16 @@ local function history_add(id, command)
 end
 
 
--- Draw the prompt text with a cursor.
--- @param args The table of arguments.
--- @param text The text.
--- @param font The font.
--- @param prompt The text prefix.
--- @param text_color The text color.
--- @param cursor_color The cursor color.
--- @param cursor_pos The cursor position.
--- @param cursor_ul The cursor underline style.
--- @param selectall If true cursor is rendered on the entire text.
+--- Draw the prompt text with a cursor.
+-- @tparam table args The table of arguments.
+-- @field text The text.
+-- @field font The font.
+-- @field prompt The text prefix.
+-- @field text_color The text color.
+-- @field cursor_color The cursor color.
+-- @field cursor_pos The cursor position.
+-- @field cursor_ul The cursor underline style.
+-- @field selectall If true cursor is rendered on the entire text.
 local function prompt_text_with_cursor(args)
     local char, spacer, text_start, text_end, ret
     local text = args.text or ""

lib/awful/titlebar.lua.in

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- Titlebars for awful.
+--- Titlebars for awful.
 --
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter

lib/awful/util.lua.in

@@ -277,7 +277,7 @@ function util.subsets(set)
     return ret
 end
 
--- Return true whether rectangle B is in the right direction
+--- Return true whether rectangle B is in the right direction
 -- compared to rectangle A.
 -- @param dir The direction.
 -- @param gA The geometric specification for rectangle A.
@@ -296,12 +296,12 @@ local function is_in_direction(dir, gA, gB)
     return false
 end
 
--- Calculate distance between two points.
+--- Calculate distance between two points.
 -- i.e: if we want to move to the right, we will take the right border
 -- of the currently focused screen and the left side of the checked screen.
 -- @param dir The direction.
--- @param gA The first rectangle.
--- @param gB The second rectangle.
+-- @param _gA The first rectangle.
+-- @param _gB The second rectangle.
 -- @return The distance between the screens.
 local function calculate_distance(dir, _gA, _gB)
     local gAx = _gA.x
@@ -322,7 +322,7 @@ local function calculate_distance(dir, _gA, _gB)
     return math.sqrt(math.pow(gBx - gAx, 2) + math.pow(gBy - gAy, 2))
 end
 
--- Get the nearest rectangle in the given direction. Every rectangle is specified as a table
+--- Get the nearest rectangle in the given direction. Every rectangle is specified as a table
 -- with 'x', 'y', 'width', 'height' keys, the same as client or screen geometries.
 -- @param dir The direction, can be either "up", "down", "left" or "right".
 -- @param recttbl A table of rectangle specifications.

lib/awful/wibox.lua.in

@@ -26,7 +26,7 @@ local beautiful = require("beautiful")
 
 local awfulwibox = { mt = {} }
 
--- Array of table with wiboxes inside.
+--- Array of table with wiboxes inside.
 -- It's an array so it is ordered.
 local wiboxes = {}
 
@@ -71,7 +71,7 @@ function awfulwibox.set_position(wibox, position, screen)
     end
 end
 
--- Reset all wiboxes positions.
+--- Reset all wiboxes positions.
 local function update_all_wiboxes_position()
     for _, wprop in ipairs(wiboxes) do
         awfulwibox.set_position(wprop.wibox, wprop.position, wprop.screen)

lib/awful/widget/textclock.lua.in

@@ -14,7 +14,7 @@ local timer = require("gears.timer")
 
 local textclock = { mt = {} }
 
--- This lowers the timeout so that it occurs "correctly". For example, a timeout
+--- This lowers the timeout so that it occurs "correctly". For example, a timeout
 -- of 60 is rounded so that it occurs the next time the clock reads ":00 seconds".
 local function calc_timeout(real_timeout)
     return real_timeout - os.time() % real_timeout

lib/beautiful.lua.in

@@ -35,9 +35,9 @@ local descs = setmetatable({}, { __mode = 'k' })
 local fonts = setmetatable({}, { __mode = 'v' })
 local active_font
 
--- Load a font name
+--- Load a font name
 --
--- @param Font name, which can be a string or a table
+-- @param name Font name, which can be a string or a table
 local function load_font(name)
     name = name or active_font
     if name and type(name) ~= "string" and descs[name] then
@@ -64,7 +64,7 @@ local function load_font(name)
     return font
 end
 
--- Set an active font
+--- Set an active font
 --
 -- @param name The font
 local function set_font(name)

lib/gears/color.lua.in

@@ -82,7 +82,7 @@ function color.create_png_pattern(file)
     return pattern
 end
 
--- Add stops to the given pattern.
+--- Add stops to the given pattern.
 -- @param p The cairo pattern to add stops to
 -- @param iterator An iterator that returns strings. Each of those strings
 --   should be in the form place,color where place is in [0, 1].
@@ -94,14 +94,14 @@ local function add_iterator_stops(p, iterator)
     end
 end
 
--- Add a list of stops to a given pattern
+--- Add a list of stops to a given pattern
 local function add_stops_table(pat, arg)
     for _, stop in ipairs(arg) do
         pat:add_color_stop_rgba(stop[1], color.parse_color(stop[2]))
     end
 end
 
--- Create a pattern from a string
+--- Create a pattern from a string
 local function string_pattern(creator, arg)
     local iterator = string.gmatch(arg, "[^:]+")
     -- Create a table where each entry is a number from the original string

lib/gears/debug.lua.in

@@ -25,7 +25,7 @@ function debug.assert(cond, message)
     end
 end
 
--- Given a table (or any other data) return a string that contains its
+--- Given a table (or any other data) return a string that contains its
 -- tag, value and type. If data is a table then recursively call d_raw
 -- on each of its values.
 -- @param data Value to inspect.

lib/gears/object.lua.in

@@ -12,7 +12,7 @@ local error = error
 
 local object = { mt = {} }
 
--- Verify that obj is indeed a valid object as returned by new()
+--- Verify that obj is indeed a valid object as returned by new()
 local function check(obj)
     if type(obj) ~= "table" or type(obj._signals) ~= "table" then
         error("add_signal() called on non-object")
@@ -72,7 +72,7 @@ function object:emit_signal(name, ...)
     end
 end
 
--- Returns a new object. You can call :emit_signal(), :disconnect_signal,
+--- Returns a new object. You can call :emit_signal(), :disconnect_signal,
 -- :connect_signal() and :add_signal() on the resulting object.
 local function new()
     local ret = {}

lib/gears/timer.lua.in

@@ -1,8 +1,10 @@
---- Timer objects and functions.
 ---------------------------------------------------------------------------
+--- Timer objects and functions.
+--
 -- @author Uli Schlachter
 -- @copyright 2014 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @module gears.timer
 ---------------------------------------------------------------------------
 
 local capi = { awesome = awesome }

lib/menubar/init.lua.in

@@ -81,7 +81,7 @@ local instance = { prompt = nil,
 local common_args = { w = wibox.layout.fixed.horizontal(),
                       data = setmetatable({}, { __mode = 'kv' }) }
 
--- Wrap the text with the color span tag.
+--- Wrap the text with the color span tag.
 -- @param s The text.
 -- @param c The desired text color.
 -- @return the text wrapped in a span tag.
@@ -89,7 +89,7 @@ local function colortext(s, c)
     return "<span color='" .. c .. "'>" .. s .. "</span>"
 end
 
--- Get how the menu item should be displayed.
+--- Get how the menu item should be displayed.
 -- @param o The menu item.
 -- @return item name, item background color, background image, item icon.
 local function label(o)
@@ -101,7 +101,7 @@ local function label(o)
     end
 end
 
--- Perform an action for the given menu item.
+--- Perform an action for the given menu item.
 -- @param o The menu item.
 -- @return if the function processed the callback, new awful.prompt command, new awful.prompt prompt text.
 local function perform_action(o)
@@ -120,8 +120,8 @@ local function perform_action(o)
     end
 end
 
--- Cut item list to return only current page
--- @tparam table all_item All items list
+--- Cut item list to return only current page.
+-- @tparam table all_item All items list.
 -- @tparam str query Search query.
 -- @return table List of items for current page.
 local function get_current_page(all_items, query)
@@ -159,8 +159,8 @@ local function get_current_page(all_items, query)
     return current_page
 end
 
--- Update the menubar according to the command entered by user.
--- @param query The text to filter entries by.
+--- Update the menubar according to the command entered by user.
+-- @tparam str query Search query.
 local function menulist_update(query)
     query = query or ""
     shownitems = {}
@@ -225,7 +225,7 @@ local function menulist_update(query)
                        get_current_page(shownitems, query))
 end
 
--- Create the menubar wibox and widgets.
+--- Create the menubar wibox and widgets.
 local function initialize()
     instance.wibox = wibox({})
     instance.widget = menubar.get()
@@ -242,7 +242,7 @@ function menubar.refresh()
     menubar.menu_entries = menubar.menu_gen.generate()
 end
 
--- Awful.prompt keypressed callback to be used when the user presses a key.
+--- Awful.prompt keypressed callback to be used when the user presses a key.
 -- @param mod Table of key combination modifiers (Control, Shift).
 -- @param key The key that was pressed.
 -- @param comm The current command in the prompt.

lib/menubar/menu_gen.lua.in

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- Menu generation module for menubar
+--- Menu generation module for menubar
 --
 -- @author Antonio Terceiro
 -- @copyright 2009, 2011-2012 Antonio Terceiro, Alexander Yakushev
@@ -60,7 +60,7 @@ function menu_gen.lookup_category_icons()
     end
 end
 
--- Get category key name and whether it is used by its app_type.
+--- Get category key name and whether it is used by its app_type.
 -- @param app_type Application category as written in .desktop file.
 -- @return category key name in all_categories, whether the category is used
 local function get_category_name_and_usage_by_type(app_type)
@@ -71,7 +71,7 @@ local function get_category_name_and_usage_by_type(app_type)
     end
 end
 
--- Remove CR\LF newline from the end of the string.
+--- Remove CR\LF newline from the end of the string.
 -- @param s string to trim
 local function trim(s)
     if not s then return end

lib/menubar/utils.lua.in

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- Utility module for menubar
+--- Utility module for menubar
 --
 -- @author Antonio Terceiro
 -- @copyright 2009, 2011-2012 Antonio Terceiro, Alexander Yakushev
@@ -29,7 +29,7 @@ local utils = {}
 --- Terminal which applications that need terminal would open in.
 utils.terminal = 'xterm'
 
--- The default icon for applications that don't provide any icon in
+--- The default icon for applications that don't provide any icon in
 -- their .desktop files.
 local default_icon = nil
 
@@ -51,10 +51,10 @@ local all_icon_sizes = {
     '16x16'
 }
 
--- List of supported icon formats.
+--- List of supported icon formats.
 local icon_formats = { "png", "xpm", "svg" }
 
--- Check whether the icon format is supported.
+--- Check whether the icon format is supported.
 -- @param icon_file Filename of the icon.
 -- @return true if format is supported, false otherwise.
 local function is_format_supported(icon_file)

lib/naughty/core.lua.in

@@ -167,13 +167,14 @@ function naughty.toggle()
     end
 end
 
--- Evaluate desired position of the notification by index - internal
+--- Evaluate desired position of the notification by index - internal
 --
--- @param idx Index of the notification
+-- @param screen Screen to use
 -- @param position top_right | top_left | bottom_right | bottom_left
 --             | top_middle | bottom_middle
--- @param height Popup height
+-- @param idx Index of the notification
 -- @param width Popup width (optional)
+-- @param height Popup height
 -- @return Absolute position and index in { x = X, y = Y, idx = I } table
 local function get_offset(screen, position, idx, width, height)
     local ws = capi.screen[screen].workarea
@@ -214,7 +215,7 @@ local function get_offset(screen, position, idx, width, height)
     return v
 end
 
--- Re-arrange notifications according to their position and index - internal
+--- Re-arrange notifications according to their position and index - internal
 --
 -- @return None
 local function arrange(screen)
@@ -256,7 +257,7 @@ function naughty.destroy(notification, reason)
     end
 end
 
--- Get notification by ID
+--- Get notification by ID
 --
 -- @param id ID of the notification
 -- @return notification object if it was found, nil otherwise

lib/wibox/widget/imagebox.lua.in

@@ -113,7 +113,7 @@ function imagebox:set_resize(allowed)
     self:emit_signal("widget::updated")
 end
 
--- Returns a new imagebox
+--- Returns a new imagebox
 -- @param image the image to display, may be nil
 -- @param resize_allowed If false, the image will be clipped, else it will be resized
 --                       to fit into the available space.

lib/wibox/widget/textbox.lua.in

@@ -19,7 +19,7 @@ local error = error
 
 local textbox = { mt = {} }
 
--- Setup a pango layout for the given textbox and cairo context
+--- Setup a pango layout for the given textbox and cairo context
 local function setup_layout(box, width, height)
     local layout = box._layout
     layout.width = Pango.units_from_double(width)