From 00f558ff92a7fe0d3aea3ba5193c382d7e7d7a4b Mon Sep 17 00:00:00 2001 From: "Ignas Anikevicius (gns_ank)" Date: Mon, 19 May 2014 14:15:39 +0100 Subject: [PATCH] Docs: General work on gears module. Signed-off-by: Ignas Anikevicius (gns_ank) --- lib/gears/color.lua.in | 24 +++++++++++++++--------- lib/gears/debug.lua.in | 5 +++-- lib/gears/init.lua.in | 2 +- lib/gears/object.lua.in | 7 ++++--- lib/gears/sort.lua.in | 2 +- lib/gears/surface.lua.in | 2 +- lib/gears/wallpaper.lua.in | 22 +++++++++++----------- 7 files changed, 36 insertions(+), 28 deletions(-) diff --git a/lib/gears/color.lua.in b/lib/gears/color.lua.in index fcc4b16e..f1badc90 100644 --- a/lib/gears/color.lua.in +++ b/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. --- For example, parse_color("#00ff00ff") would return 0, 1, 0, 1. +-- This function can parse colors like `#rrggbb` and `#rrggbbaa`. -- 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:"` -- Alternatively, the pattern can be specified as a table: --- { type = "linear", from = { x0, y0 }, to = { x1, y1 }, --- stops = { } } +-- { type = "linear", from = { x0, y0 }, to = { x1, y1 }, +-- stops = { } } -- `x0,y0` and `x1,y1` are the start and stop point of the pattern. -- For the explanation of ``, 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:"` -- Alternatively, the pattern can be specified as a table: --- { type = "radial", from = { x0, y0, r0 }, to = { x1, y1, r1 }, --- stops = { } } +-- { type = "radial", from = { x0, y0, r0 }, to = { x1, y1, r1 }, +-- 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 ``, 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) diff --git a/lib/gears/debug.lua.in b/lib/gears/debug.lua.in index 534c0ed8..ee3bf65b 100644 --- a/lib/gears/debug.lua.in +++ b/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 diff --git a/lib/gears/init.lua.in b/lib/gears/init.lua.in index 9f6b8e7f..c565e7ff 100644 --- a/lib/gears/init.lua.in +++ b/lib/gears/init.lua.in @@ -2,9 +2,9 @@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @release @AWESOME_VERSION@ +-- @module gears --------------------------------------------------------------------------- ---- gears return { diff --git a/lib/gears/object.lua.in b/lib/gears/object.lua.in index 31ce9179..6c8122a8 100644 --- a/lib/gears/object.lua.in +++ b/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 --- arguments that are given to emit_signal() +-- function receives the object as first argument and then any extra arguments +-- that are given to emit_signal() function object:emit_signal(name, ...) local sig = find_signal(self, name, "emit") for func in pairs(sig) do diff --git a/lib/gears/sort.lua.in b/lib/gears/sort.lua.in index 0c7c4b6a..b8de9e49 100644 --- a/lib/gears/sort.lua.in +++ b/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) diff --git a/lib/gears/surface.lua.in b/lib/gears/surface.lua.in index 339df2ce..2cb32515 100644 --- a/lib/gears/surface.lua.in +++ 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' }) diff --git a/lib/gears/wallpaper.lua.in b/lib/gears/wallpaper.lua.in index 2f07b98e..8610b239 100644 --- a/lib/gears/wallpaper.lua.in +++ b/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 --- for drawing to this surface +-- that should be used for setting the wallpaper and a cairo context for +-- 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)