Permalink
Browse files

add doc

  • Loading branch information...
1 parent 0f42890 commit ab02a5a4dc6e32479a3345f161dad70060464752 @dodo committed Feb 7, 2011
Showing with 130 additions and 51 deletions.
  1. +9 −29 getinfo.lua
  2. +5 −1 init.lua
  3. +11 −2 layout.lua
  4. +18 −4 menu.lua
  5. +16 −1 util.lua
  6. +16 −9 vardump.lua
  7. +55 −5 widget.lua
View
@@ -1,22 +1,8 @@
---
--------------------------------------------------------------------------------
--- FILE: getinfo.lua
--- USAGE: ./getinfo.lua
--- DESCRIPTION:
--- OPTIONS: ---
--- REQUIREMENTS: ---
--- BUGS: ---
--- NOTES: ---
--- AUTHOR: (), <>
--- COMPANY:
--- VERSION: 1.0
--- CREATED: 07.02.2011 02:09:01 CET
--- REVISION: ---
+-- @author john
+-- @copyright 2011 https://github.com/tuxcodejohn
+-- @release v3.4-503-g4972a28
--------------------------------------------------------------------------------
---
-
--- while debug: --
---require("vardump")
local io = io
local table = table
@@ -25,7 +11,8 @@ local assert = assert
module("uzful.getinfo")
-
+--- Network Interfaces
+-- @return list of all network interfaces (without `lo`)
function interfaces()
local f = io.popen("ls /sys/class/net", "r")
local out = assert(f:read("*a"))
@@ -41,7 +28,8 @@ function interfaces()
return ret
end
-
+--- CPUs
+-- @return list of all cpus
function local_cpus()
local cpu_lines = {}
local c = ""
@@ -56,18 +44,10 @@ function local_cpus()
return cpu_lines
end
-
+--- CPU Count
+-- @return number of cpus
function cpu_count()
return #local_cpus()
end
--- print "---------------------"
--- print (vardump(get_interfaces()))
--- print "---------------------"
---
--- print (vardump(john_num_cpus()))
--- print "---------------------"
-
---print (vardump(local_cpus()))
-
View
@@ -1,4 +1,8 @@
-
+--------------------------------------------------------------------------------
+-- @author dodo
+-- @copyright 2011 https://github.com/dodo
+-- @release v3.4-503-g4972a28
+--------------------------------------------------------------------------------
require("uzful.util")
require("uzful.menu")
View
@@ -1,11 +1,20 @@
-
+--------------------------------------------------------------------------------
+-- @author dodo
+-- @copyright 2011 https://github.com/dodo
+-- @release v3.4-503-g4972a28
+--------------------------------------------------------------------------------
local type = type
local pairs = pairs
module("uzful.layout")
-
+--- Builds a layout from a table tree
+-- When inserted a function it returns the result without parameters.
+-- When given table has property layout it will instancate it add all list items from the table to it.
+-- Whe given table has properties it will try to invoke the `set_[key]` function of the layout.
+-- @param tree the table describing the layout (can be recursive)
+-- @return a layout or the result of the given function or just the input
function build(tree)
if type(tree) == "function" then
return tree()
View
@@ -1,4 +1,8 @@
-
+--------------------------------------------------------------------------------
+-- @author dodo
+-- @copyright 2011 https://github.com/dodo
+-- @release v3.4-503-g4972a28
+--------------------------------------------------------------------------------
local awful = require("awful")
local ipairs = ipairs
@@ -8,13 +12,18 @@ local vicious = nil
module("uzful.menu")
-
+--- uzful.menu initiator
+-- Needs to be executed once if `uztful.menu.layouts` and `uzful.menu.toggle_widgets` should work.
+-- @param btfl the required beautiful library
+-- @param vcs the required vicious library
function init(btfl, vcs)
beautiful = btfl
vicious = vcs
end
-
+--- Layout Menu
+-- Generates a `awful.menu` with all layouts (names and icons).
+-- @param layouts list of layouts the user wants to use.
function layouts(Layouts)
local items = {}
for _, layout in ipairs(Layouts) do
@@ -28,7 +37,12 @@ function layouts(Layouts)
return awful.menu({ items = items })
end
-
+--- Widget Toggler
+-- Builds a useful little environment for widgets which are registered on vicious.
+-- The function `toggle` turns all vicious widgets on or off.
+-- The function `visible` returns if vicious widgets are off or on.
+-- @return a table with this properties: widgets, toggle, visible
+-- @usage add widgets to returning widgets list to enable the feature.
function toggle_widgets ()
local widgets = {}
local show = true
View
@@ -1,10 +1,17 @@
-
+--------------------------------------------------------------------------------
+-- @author dodo
+-- @copyright 2011 https://github.com/dodo
+-- @release v3.4-503-g4972a28
+--------------------------------------------------------------------------------
local awful = require("awful")
module("uzful.util")
patch = {
+ --- Enables always vicious.cache for all registered vicious widgets
+ -- It overrides `vicious.register`.
+ -- @param vicious The required vicious library
vicious = function (vicious)
local cache = {}
local register = vicious.register
@@ -18,6 +25,14 @@ patch = {
end,
}
+--- Change system volume
+-- use it like this for example:
+-- <code>
+-- awful.key({ modkey }, "<", function () uzful.util.change_volume("1%-") end),
+-- awful.key({ modkey, "Shift" }, "<", function () uzful.util.change_volume("1%+") end),
+-- </code>
+-- thanks to <a href="https://github.com/twobit">twobit</a>.
+-- @param delta The volume delta to change in percentage (e.g. "1%+")
function change_volume(delta)
awful.util.spawn("amixer -q set Master " .. delta)
end
View
@@ -1,18 +1,25 @@
-
-
+--------------------------------------------------------------------------------
+-- @author john
+-- @copyright 2011 https://github.com/tuxcodejohn
+-- @release v3.4-503-g4972a28
+--------------------------------------------------------------------------------
+
+--- Table dumping
+-- @param data a table
+-- @return stringified table
function vardump(data)
local function rvardump (rdata, erg,indent,key)
local linePrefix = ""
- if key ~= nil then
+ if key ~= nil then
linePrefix = string.format("[%s]",key)
end
if(indent == nil) then
indent = 0
- else
+ else
indent = indent +1
- table.insert(erg,string.rep(" ",indent))
+ table.insert(erg,string.rep(" ",indent))
end
if type(rdata) == 'table' then
@@ -23,14 +30,14 @@ function vardump(data)
else
table.insert(erg ,"(metatable)")
rdata = mTable
- end
+ end
table.insert(erg,"\n")
for tableKey, tableValue in pairs(rdata) do
rvardump(tableValue, erg,indent,tableKey)
end
elseif type(rdata) == 'function' or
- type(rdata) == 'thread' or
- type(rdata) == 'userdata' or
+ type(rdata) == 'thread' or
+ type(rdata) == 'userdata' or
rdata == nil then
table.insert(erg,tostring(rdata))
@@ -43,7 +50,7 @@ function vardump(data)
local erg= {}
rvardump(data,erg)
-
+
return table.concat(erg)
end
View
@@ -1,3 +1,8 @@
+--------------------------------------------------------------------------------
+-- @author dodo
+-- @copyright 2011 https://github.com/dodo
+-- @release v3.4-503-g4972a28
+--------------------------------------------------------------------------------
local Wibox = require("wibox")
local awful = require("awful")
@@ -10,12 +15,20 @@ local getinfo = require("uzful.getinfo")
module("uzful.widget")
-
+--- uzful.widget initiator
+-- Needs to be executed once if `uztful.menu.netgraphs` and `uzful.menu.cpugraphs` should work.
+-- @param vcs the required vicious library
function init(vcs)
vicious = vcs
end
-
+--- wibox helper
+-- Just a wrapper for a nicer interface for `wibox`
+-- @param args any wibox args plus screen, visible and widget
+-- @param args.screen when given `wibox.screen` will be set
+-- @param args.visible when given `wibox.visible` will be set
+-- @param args.widget when given `wibox:set_widget` will be invoked
+-- @return wibox object
function wibox(args)
local w = Wibox(args)
w.screen = args.screen or 1
@@ -26,7 +39,11 @@ function wibox(args)
return w
end
-
+--- widget property setter
+-- Any given property will invoke `widget:set_[property_key]([property_value])`.
+-- @param widget the widget to be filled with properties
+-- @param properties a table with the properties
+-- @return the given widget
function set_properties(widget, properties)
local fun = nil
for name, property in pairs(properties) do
@@ -38,7 +55,23 @@ function set_properties(widget, properties)
return widget
end
-
+--- fency CPU Graphs for all CPUs
+-- @param args table with all relevant properties
+-- @param args.label_height <i>(needed) </i> the height for a single `wibox.widget.textbox`
+-- @param args.load <i>(optional) </i> displays load as text (replaces '$1', '$2' and '$3' with values) in big graphs layout (only available when `args.big` is given)
+-- @param args.small <i>(optional) </i> generates a small cpurgaph with all cpu usage combined when table given
+-- @param args.small.width <i>(need when `args.small` given) </i> width of small cpu graph
+-- @param args.small.height <i>(need when `args.small` given) </i> height of small cpu graph
+-- @param args.small.fgcolor <i>/optional when `args.small` given) </i> foreground color of small cpu graph
+-- @param args.small.bgcolor <i>/optional when `args.small` given) </i> background color of small cpu graph
+-- @param args.big <i>(optional) </i> generates a big cpurgaph for each cpu core when table given
+-- @param args.big.width <i>(need when `args.big` given) </i> width of a single big cpu graph
+-- @param args.big.height <i>(need when `args.big` given) </i> height of a single big cpu graph
+-- @param args.big.fgcolor <i>/optional when `args.big` given) </i> foreground color of big cpu graphs
+-- @param args.big.bgcolor <i>/optional when `args.big` given) </i> background color of big cpu graphs
+-- @param args.fgcolor <i>(optional) </i> default value of `args.small.fgcolor` and `args.big.fgcolor`
+-- @param args.bgcolor <i>(optional) </i> default value of `args.small.bgcolor` and `args.big.bgcolor`
+-- @return a table with this properties: small <i>(when `args.small` given)</i> (with properties: widget, width, height), big <i>(wher `args.big` given)</i> (with properties: layout, widgets, width, height), load <i>(when `args.load` given)</i>
function cpugraphs(args)
local ret = {}
for _, size in ipairs({"small", "big"}) do
@@ -101,7 +134,24 @@ function cpugraphs(args)
return ret
end
-
+--- fency Net Graphs for all network interfaces
+-- @param args table with all relevant properties
+-- @param args.normal <i>(default: "$1") </i> display every interface name as text (replaces '$1' with interface name) in big graphs layout (only available when `args.big` is given)
+-- @param args.hightlight <i>(default: "$1") </i> display selected interface name as text (replaces '$1' with interface name) in big graphs layout (only available when `args.big` is given)
+-- @param args.label_height <i>(needed) </i> the height for a single `wibox.widget.textbox`
+-- @param args.small <i>(optional) </i> generates a small cpurgaph with all cpu usage combined when table given
+-- @param args.small.width <i>(need when `args.small` given) </i> width of small cpu graph
+-- @param args.small.height <i>(need when `args.small` given) </i> height of small cpu graph
+-- @param args.small.fgcolor <i>/optional when `args.small` given) </i> foreground color of small cpu graph
+-- @param args.small.bgcolor <i>/optional when `args.small` given) </i> background color of small cpu graph
+-- @param args.big <i>(optional) </i> generates a big cpurgaph for each cpu core when table given
+-- @param args.big.width <i>(need when `args.big` given) </i> width of a single big cpu graph
+-- @param args.big.height <i>(need when `args.big` given) </i> height of a single big cpu graph
+-- @param args.big.fgcolor <i>/optional when `args.big` given) </i> foreground color of big cpu graphs
+-- @param args.big.bgcolor <i>/optional when `args.big` given) </i> background color of big cpu graphs
+-- @param args.fgcolor <i>(optional) </i> default value of `args.small.fgcolor` and `args.big.fgcolor`
+-- @param args.bgcolor <i>(optional) </i> default value of `args.small.bgcolor` and `args.big.bgcolor`
+-- @return a table with this properties: small <i>(when `args.small` given)</i> (with properties: layout, widgets, width, height), big <i>(wher `args.big` given)</i> (with properties: layout, widgets, width, height)
function netgraphs(args)
local ret = {}
for _, size in ipairs({"small", "big"}) do

0 comments on commit ab02a5a

Please sign in to comment.