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)
@@ -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())