Merge pull request #2165 from psychon/wallpaper_docs

Improve docs for gears.wallpaper and gears.color

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

lib/gears/wallpaper.lua

@@ -1,4 +1,23 @@
 ---------------------------------------------------------------------------
+-- Functions for setting the wallpaper.
+--
+-- There are two levels of functionality provided by this module:
+--
+-- The low-level functionality consists of two functions.
+-- @{set} an already-prepared wallpaper on all screens and @{prepare_context}
+-- prepares things to draw a new wallpaper.
+--
+-- The low-level API can for example be used to set solid red as a wallpaper
+-- (see @{gears.color} for details on the supported syntax):
+--
+--     gears.wallpaper.set("#ff0000")
+--
+-- Ontop of these low-level functions, the remaining functions implement more
+-- useful functionality. For example, given a screen object `s`, an image can be
+-- set as the wallpaper as follows:
+--
+--     gears.wallpaper.maximized("path/to/image.png", s)
+--
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
 -- @module gears.wallpaper