Give the docs for gears.color some improvements

Signed-off-by: Uli Schlachter <psychon@znc.in>

lib/gears/color.lua

@@ -1,4 +1,42 @@
 ---------------------------------------------------------------------------
+-- This module simplifies the creation of cairo pattern objects.
+--
+-- In most places in awesome where a color is needed, the provided argument is
+-- passed to @{gears.color}, which actually calls @{create_pattern} and creates
+-- a pattern from a given string or table.
+--
+-- This function can create solid, linear, radial and png patterns.
+--
+-- A simple example for a solid pattern is a hexadecimal color specification.
+-- For example `#ff8000` creates a solid pattern with 100% red, 50% green and 0%
+-- blue. Limited support for named colors (`red`) is also provided.
+--
+-- In general, patterns are specified as strings formatted as
+-- `"type:arguments"`. `"arguments"` is specific to the pattern being used. For
+-- example, one can use:
+--     "radial:50,50,10:55,55,30:0,#ff0000:0.5,#00ff00:1,#0000ff"
+-- The above will call @{create_radial_pattern} with the provided string, after
+-- stripping the `radial:` prefix.
+--
+-- Alternatively, patterns can be specified via tables. In this case, the
+-- table's 'type' member specifies the type. For example:
+--     {
+--       type = "radial",
+--       from = { 50, 50, 10 },
+--       to = { 55, 55, 30 },
+--       stops = { { 0, "#ff0000" }, { 0.5, "#00ff00" }, { 1, "#0000ff" } }
+--     }
+-- Any argument that cannot be understood is passed to @{create_solid_pattern}.
+--
+-- Please note that you MUST NOT modify the returned pattern, for example by
+-- calling :set_matrix() on it, because this function uses a cache and your
+-- changes could thus have unintended side effects. Use @{create_pattern_uncached}
+-- if you need to modify the returned pattern.
+-- @see create_pattern_uncached, create_solid_pattern, create_png_pattern,
+--   create_linear_pattern, create_radial_pattern
+-- @tparam string col The string describing the pattern.
+-- @return a cairo pattern object
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @module gears.color
@@ -20,31 +58,6 @@ local surface = require("gears.surface")
 local color = { mt = {} }
 local pattern_cache
 
---- Create a pattern from a given string.
--- This function can create solid, linear, radial and png patterns. In general,
--- patterns are specified as strings formatted as "type:arguments". "arguments"
--- is specific to the pattern being used. For example, one can use
--- "radial:50,50,10:55,55,30:0,#ff0000:0.5,#00ff00:1,#0000ff".
--- Alternatively, patterns can be specified via tables. In this case, the
--- table's 'type' member specifies the type. For example:
--- {
---   type = "radial",
---   from = { 50, 50, 10 },
---   to = { 55, 55, 30 },
---   stops = { { 0, "#ff0000" }, { 0.5, "#00ff00" }, { 1, "#0000ff" } }
--- }
--- Any argument that cannot be understood is passed to @{create_solid_pattern}.
---
--- Please note that you MUST NOT modify the returned pattern, for example by
--- calling :set_matrix() on it, because this function uses a cache and your
--- changes could thus have unintended side effects. Use @{create_pattern_uncached}
--- if you need to modify the returned pattern.
--- @see create_pattern_uncached, create_solid_pattern, create_png_pattern,
---   create_linear_pattern, create_radial_pattern
--- @tparam string col The string describing the pattern.
--- @return a cairo pattern object
--- @function gears.color
-
 --- Parse a HTML-color.
 -- This function can parse colors like `#rrggbb` and `#rrggbbaa` and also `red`.
 -- Max 4 chars per channel.
@@ -258,7 +271,7 @@ function color.create_pattern_uncached(col)
     return color.create_solid_pattern(col)
 end
 
---- Create a pattern from a given string, same as `gears.color`.
+--- Create a pattern from a given string, same as @{gears.color}.
 -- @see gears.color
 function color.create_pattern(col)
     if cairo.Pattern:is_type_of(col) then