Create artificial gears.color documentation.

Point from parse_color function to gears.color in documentation.
Fix minor issues (typos, indentation) in docs.

lib/gears/color.lua

@@ -20,13 +20,38 @@ 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. Thanks to #lua for this. :)
+-- Max 4 chars per channel.
 --
 -- @param col The color to parse
--- @return 4 values representing color in RGBA format (each of them in [0, 1]
+-- @treturn table 4 values representing color in RGBA format (each of them in
--- range) or nil if input is incorrect.
+-- [0, 1] range) or nil if input is incorrect.
 -- @usage -- This will return 0, 1, 0, 1
 -- gears.color.parse_color("#00ff00ff")
 function color.parse_color(col)
@@ -45,7 +70,7 @@ function color.parse_color(col)
         if chars_per_channel > 4 then
             return nil
         end
-        local dividor = 0x10^chars_per_channel - 1
+        local dividor = (0x10 ^ chars_per_channel) - 1
         for idx=1,#hex_str,chars_per_channel do
             local channel_val = tonumber(hex_str:sub(idx,idx+chars_per_channel-1), 16)
             table.insert(rgb, channel_val / dividor)
@@ -233,27 +258,9 @@ function color.create_pattern_uncached(col)
     return color.create_solid_pattern(col)
 end
 
---- Create a pattern from a given string.
+--- Create a pattern from a given string, same as `gears.color`.
--- This function can create solid, linear, radial and png patterns. In general,
+-- @see gears.color
--- patterns are specified as strings formatted as"type:arguments". "arguments"
--- is specific to the pattern 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
--- @param col The string describing the pattern.
--- @return a cairo pattern object
 function color.create_pattern(col)
-    -- If it already is a cairo pattern, just leave it as that
     if cairo.Pattern:is_type_of(col) then
         return col
     end