Docs: General work on gears module.

Signed-off-by: Ignas Anikevicius (gns_ank) <anikevicius@gmail.com>

lib/gears/color.lua.in

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @module gears.color
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -19,11 +20,13 @@ local color = { mt = {} }
 local pattern_cache = setmetatable({}, { __mode = 'v' })
 
 --- Parse a HTML-color.
--- This function can parse colors like #rrggbb and #rrggbbaa.
+-- This function can parse colors like `#rrggbb` and `#rrggbbaa`.
--- For example, parse_color("#00ff00ff") would return 0, 1, 0, 1.
 -- Thanks to #lua for this. :)
+--
 -- @param col The color to parse
 -- @return 4 values which each are in the range [0, 1].
+-- @usage -- This will return 0, 1, 0, 1
+-- gears.color.parse_color("#00ff00ff")
 function color.parse_color(col)
     local rgb = {}
     for pair in string.gmatch(col, "[^#].") do
@@ -39,7 +42,8 @@ function color.parse_color(col)
 end
 
 --- Find all numbers in a string
--- @param s The string to parse
+--
+-- @tparam string s The string to parse
 -- @return Each number found as a separate value
 local function parse_numbers(s)
     local res = {}
@@ -50,6 +54,7 @@ local function parse_numbers(s)
 end
 
 --- Create a solid pattern
+--
 -- @param col The color for the pattern
 -- @return A cairo pattern object
 function color.create_solid_pattern(col)
@@ -63,6 +68,7 @@ function color.create_solid_pattern(col)
 end
 
 --- Create an image pattern from a png file
+--
 -- @param file The filename of the file
 -- @return a cairo pattern object
 function color.create_png_pattern(file)
@@ -79,7 +85,7 @@ end
 -- 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].
+--   should be in the form place,color where place is in [0, 1].
 local function add_iterator_stops(p, iterator)
     for k in iterator do
         local sub = string.gmatch(k, "[^,]+")
@@ -116,8 +122,8 @@ end
 -- The pattern is created from a string. This string should have the following
 -- form: `"x0, y0:x1, y1:<stops>"`
 -- Alternatively, the pattern can be specified as a table:
---     { type = "linear", from = { x0, y0 }, to = { x1, y1 },
+--    { type = "linear", from = { x0, y0 }, to = { x1, y1 },
---       stops = { <stops> } }
+--      stops = { <stops> } }
 -- `x0,y0` and `x1,y1` are the start and stop point of the pattern.
 -- For the explanation of `<stops>`, see `color.create_pattern`.
 -- @tparam string|table arg The argument describing the pattern.
@@ -140,8 +146,8 @@ end
 -- The pattern is created from a string. This string should have the following
 -- form: `"x0, y0, r0:x1, y1, r1:<stops>"`
 -- Alternatively, the pattern can be specified as a table:
---     { type = "radial", from = { x0, y0, r0 }, to = { x1, y1, r1 },
+--    { type = "radial", from = { x0, y0, r0 }, to = { x1, y1, r1 },
---       stops = { <stops> } }
+--      stops = { <stops> } }
 -- `x0,y0` and `x1,y1` are the start and stop point of the pattern.
 -- `r0` and `r1` are the radii of the start / stop circle.
 -- For the explanation of `<stops>`, see `color.create_pattern`.
@@ -237,7 +243,7 @@ end
 --- Check if a pattern is opaque.
 -- A pattern is transparent if the background on which it gets drawn (with
 -- operator OVER) doesn't influence the visual result.
--- @param col An argument that @{create_pattern} accepts
+-- @param col An argument that `create_pattern` accepts.
 -- @return The pattern if it is surely opaque, else nil
 function color.create_opaque_pattern(col)
     local pattern = color.create_pattern(col)

lib/gears/debug.lua.in

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @module gears.debug
 ---------------------------------------------------------------------------
 
 local error = error
@@ -11,12 +12,12 @@ local print = print
 local type = type
 local pairs = pairs
 
--- gears.debug
 local debug = {}
 
 --- Check that the given condition holds true, else throw an error
+--
 -- @param cond If this is false, throw a lua error with a backtrace.
--- @param message Message to print in the error (optional).
+-- @param[opt] message Message to print in the error (optional).
 function debug.assert(cond, message)
     local message = message or cond
     if not cond then

lib/gears/init.lua.in

@@ -2,9 +2,9 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @module gears
 ---------------------------------------------------------------------------
 
---- gears
 
 return
 {

lib/gears/object.lua.in

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @classmod gears.object
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -9,7 +10,6 @@ local pairs = pairs
 local type = type
 local error = error
 
--- gears.object
 local object = { mt = {} }
 
 -- Verify that obj is indeed a valid object as returned by new()
@@ -60,10 +60,11 @@ function object:disconnect_signal(name, func)
 end
 
 --- Emit a signal
+--
 -- @param name The name of the signal
 -- @param ... Extra arguments for the callback functions. Each connected
---            function receives the object as first argument and then any extra
+--   function receives the object as first argument and then any extra arguments
---            arguments that are given to emit_signal()
+--   that are given to emit_signal()
 function object:emit_signal(name, ...)
     local sig = find_signal(self, name, "emit")
     for func in pairs(sig) do

lib/gears/sort.lua.in

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @module gears.sort
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -9,7 +10,6 @@ local ipairs = ipairs
 local table = table
 local error = error
 
--- gears.sort
 local sort = { mt = {} }
 
 local function less_than_comp(a, b)

lib/gears/surface.lua.in

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @module gears.surface
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -15,7 +16,6 @@ if tonumber(ver_major) <= 0 and tonumber(ver_minor) < 7 then
     error("lgi too old, need at least version 0.7.0")
 end
 
--- gears.surface
 local surface = { mt = {} }
 local surface_cache = setmetatable({}, { __mode = 'v' })
 

lib/gears/wallpaper.lua.in

@@ -2,13 +2,13 @@
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
 -- @release @AWESOME_VERSION@
+-- @module gears.wallpaper
 ---------------------------------------------------------------------------
 
 local cairo = require("lgi").cairo
 local color = require("gears.color")
 local surface = require("gears.surface")
 
--- gears.wallpaper
 local wallpaper = { mt = {} }
 
 -- The size of the root window
@@ -30,8 +30,8 @@ end
 --- Prepare the needed state for setting a wallpaper
 -- @param s The screen to set the wallpaper on or nil for all screens
 -- @return The available geometry (table with entries width and height), a
---         that should be used for setting the wallpaper and a cairo context
+--   that should be used for setting the wallpaper and a cairo context for
---         for drawing to this surface
+--   drawing to this surface
 local function prepare_wallpaper(s)
     local geom = s and screen[s].geometry or root_geom
     local img = surface(root.wallpaper())
@@ -54,7 +54,7 @@ end
 
 --- Set the current wallpaper.
 -- @param pattern The wallpaper that should be set. This can be a cairo surface,
---                a description for gears.color or a cairo pattern.
+--   a description for gears.color or a cairo pattern.
 function wallpaper.set(pattern)
     if cairo.Surface:is_type_of(pattern) then
         pattern = cairo.Pattern.create_for_surface(pattern)
@@ -71,9 +71,9 @@ end
 --- Set a centered wallpaper.
 -- @param surf The wallpaper to center. Either a cairo surface or a file name.
 -- @param s The screen whose wallpaper should be set. Can be nil, in which case
---          all screens are set.
+--   all screens are set.
 -- @param background The background color that should be used. Gets handled via
---                   gears.color. The default is black.
+--   gears.color. The default is black.
 function wallpaper.centered(surf, s, background)
     local geom, img, cr = prepare_wallpaper(s)
     local surf = surface(surf)
@@ -98,7 +98,7 @@ end
 --- Set a tiled wallpaper.
 -- @param surf The wallpaper to tile. Either a cairo surface or a file name.
 -- @param s The screen whose wallpaper should be set. Can be nil, in which case
---          all screens are set.
+--   all screens are set.
 -- @param offset This can be set to a table with entries x and y.
 function wallpaper.tiled(surf, s, offset)
     local geom, img, cr = prepare_wallpaper(s)
@@ -119,9 +119,9 @@ end
 --- Set a maximized wallpaper.
 -- @param surf The wallpaper to set. Either a cairo surface or a file name.
 -- @param s The screen whose wallpaper should be set. Can be nil, in which case
---          all screens are set.
+--   all screens are set.
 -- @param ignore_aspect If this is true, the image's aspect ratio is ignored.
---                      The default is to honor the aspect ratio.
+--   The default is to honor the aspect ratio.
 -- @param offset This can be set to a table with entries x and y.
 function wallpaper.maximized(surf, s, ignore_aspect, offset)
     local geom, img, cr = prepare_wallpaper(s)
@@ -154,9 +154,9 @@ end
 --- Set a fitting wallpaper.
 -- @param surf The wallpaper to set. Either a cairo surface or a file name.
 -- @param s The screen whose wallpaper should be set. Can be nil, in which case
---          all screens are set.
+--   all screens are set.
 -- @param background The background color that should be used. Gets handled via
---                   gears.color. The default is black.
+--   gears.color. The default is black.
 function wallpaper.fit(surf, s, background)
     local geom, img, cr = prepare_wallpaper(s)
     local surf = surface(surf)