* luci/libs/core: add inline documentation to luci.sys

libs/core/luasrc/sys.lua

@@ -24,13 +24,15 @@ limitations under the License.
 
 ]]--
 
+--- LuCI system utilities.
 module("luci.sys", package.seeall)
 require("posix")
 require("luci.bits")
 require("luci.util")
 require("luci.fs")
 
--- Returns whether a system is bigendian
+--- Test wheather the current system is operating in big endian mode.
+-- @return	Boolean value indicating wheather system is big endian
 function bigendian()
 	local fp = io.open("/bin/sh")
 	fp:seek("set", 5)
@@ -39,7 +41,9 @@ function bigendian()
 	return be
 end
 
--- Runs "command" and returns its output
+--- Execute given commandline and gather stdout.
+-- @param command	String containing command to execute
+-- @return			String containing the command's stdout
 function exec(command)
 	local pp   = io.popen(command)
 	local data = pp:read("*a")
@@ -48,7 +52,9 @@ function exec(command)
 	return data
 end
 
--- Runs "command" and returns its output as a array of lines
+--- Execute given commandline and gather stdout.
+-- @param command	String containing the command to execute
+-- @return			Table containing the command's stdout splitted up in lines
 function execl(command)
 	local pp   = io.popen(command)
 	local line = ""
@@ -64,7 +70,9 @@ function execl(command)
 	return data
 end
 
--- Uses "luci-flash" to flash a new image file to the system
+--- Invoke the luci-flash executable to write an image to the flash memory.
+-- @param kpattern	kpattern (ToDo: clearify this)
+-- @return			Return value of os.execute()
 function flash(image, kpattern)
 	local cmd = "luci-flash "
 	if kpattern then
@@ -75,36 +83,63 @@ function flash(image, kpattern)
 	return os.execute(cmd)
 end
 
--- Returns the enivornment
+--- Retrieve environment variables. If no variable is given then a table
+-- containing the whole environment is returned otherwise this function returns
+-- the corresponding string value for the given name or nil if no such variable
+-- exists.
+-- @class		function
+-- @name		getenv
+-- @param var	Name of the environment variable to retrieve (optional)
+-- @return		String containg the value of the specified variable
+-- @return		Table containing all variables if no variable name is given
 getenv = posix.getenv
 
--- Returns the hostname
+--- Determine the current hostname.
+-- @return		String containing the system hostname
 function hostname()
 	return io.lines("/proc/sys/kernel/hostname")()
 end
 
--- Returns the contents of a documented referred by an URL
+--- Returns the contents of a documented referred by an URL.
+-- @param url	The URL to retrieve
+-- @return		String containing the contents of given the URL
 function httpget(url)
 	return exec("wget -qO- '"..url:gsub("'", "").."'")
 end
 
--- Returns the FFLuci-Basedir
+--- Returns the absolute path to LuCI base directory.
+-- @return		String containing the directory path
 function libpath()
 	return luci.fs.dirname(require("luci.debug").__file__)
 end
 
--- Returns the load average
+--- Returns the system load average values.
+-- @return	String containing the average load value 1 minute ago
+-- @return	String containing the average load value 5 minutes ago
+-- @return	String containing the average load value 15 minutes ago
+-- @return	String containing the active and total number of processes
+-- @return	String containing the last used pid
 function loadavg()
 	local loadavg = io.lines("/proc/loadavg")()
 	return loadavg:match("^(.-) (.-) (.-) (.-) (.-)$")
 end
 
--- Reboots the system
+--- Initiate a system reboot.
+-- @return	Return value of os.execute()
 function reboot()
 	return os.execute("reboot >/dev/null 2>&1")
 end
 
--- Returns the system type, cpu name, and installed physical memory
+--- Returns the system type, cpu name and installed physical memory.
+-- @return	String containing the system or platform identifier
+-- @return	String containing hardware model information
+-- @return	String containing the total memory amount in kB
+-- @return	String containing the memory used for caching in kB
+-- @return	String containing the memory used for buffering in kB
+-- @return	String containing the free memory amount in kB
+-- @return	Number containing free memory in percent
+-- @return	Number containing buffer memory in percent
+-- @return	Number containing cache memory in percent
 function sysinfo()
 	local c1 = "cat /proc/cpuinfo|grep system\\ typ|cut -d: -f2 2>/dev/null"
 	local c2 = "uname -m 2>/dev/null"
@@ -135,13 +170,15 @@ function sysinfo()
 	return system, model, memtotal, memcached, membuffers, memfree, perc_memfree, perc_membuffers, perc_memcached
 end
 
--- Reads the syslog
+--- Retrieves the output of the "logread" command.
+-- @return	String containing the current log buffer
 function syslog()
 	return exec("logread")
 end
 
-
+--- Generates a random id with specified length.
--- Generates a random key of length BYTES
+-- @param bytes	Number of bytes for the unique id
+-- @return		String containing hex encoded id
 function uniqueid(bytes)
 	local fp    = io.open("/dev/urandom")
 	local chunk = { fp:read(bytes):byte(1, bytes) }
@@ -157,29 +194,47 @@ function uniqueid(bytes)
 	return hex
 end
 
-
+--- Returns the current system uptime stats.
--- Returns uptime stats
+-- @return	String containing total uptime in seconds
+-- @return	String containing idle time in seconds
 function uptime()
 	local loadavg = io.lines("/proc/uptime")()
 	return loadavg:match("^(.-) (.-)$")
 end
 
-
+--- Get group information
+-- @return	Group (ToDo: clearify)
 group = {}
 group.getgroup = posix.getgroup
 
+
+--- LuCI system utilities / network related functions.
+-- @class	module
+-- @name	luci.sys.net
 net = {}
--- Returns the ARP-Table
+
+--- Returns the current arp-table entries as two-dimensional table.
+-- @return	Table of table containing the current arp entries.
+--			The following fields are defined for arp entry objects:
+--			{ "IP address", "HW address", "HW type", "Flags", "Mask", "Device" }
 function net.arptable()
 	return _parse_delimited_table(io.lines("/proc/net/arp"), "%s%s+")
 end
 
--- Returns whether an IP-Adress belongs to a certain net
+--- Test whether an IP-Adress belongs to a certain net.
+-- @param ip		IPv4 address to test
+-- @param ipnet		IPv4 network address of the net range to compare against
+-- @param prefix	Network prefix of the net range to compare against
+-- @return			Boolean indicating wheather the ip is within the range
 function net.belongs(ip, ipnet, prefix)
 	return (net.ip4bin(ip):sub(1, prefix) == net.ip4bin(ipnet):sub(1, prefix))
 end
 
--- Detect the default route
+--- Determine the current default route.
+-- @return	Table with the properties of the current default route.
+--			The following fields are defined:
+--			{ "Mask", "RefCnt", "Iface", "Flags", "Window", "IRTT",
+--			  "MTU", "Gateway", "Destination", "Metric", "Use" }
 function net.defaultroute()
 	local routes = net.routes()
 	local route = nil
@@ -193,7 +248,8 @@ function net.defaultroute()
 	return route
 end
 
--- Returns all available network interfaces
+--- Determine the names of available network interfaces.
+-- @return	Table containing all current interface names
 function net.devices()
 	local devices = {}
 	for line in io.lines("/proc/net/dev") do
@@ -202,7 +258,9 @@ function net.devices()
 	return devices
 end
 
--- Returns the MAC-Address belonging to the given IP-Address
+-- Determine the MAC address belonging to the given IP address.
+-- @param ip	IPv4 address
+-- @return		String containing the MAC address or nil if it cannot be found
 function net.ip4mac(ip)
 	local mac = nil
 
@@ -215,7 +273,9 @@ function net.ip4mac(ip)
 	return mac
 end
 
--- Returns the prefix to a given netmask
+--- Calculate the prefix from a given netmask.
+-- @param mask	IPv4 net mask
+-- @return		Number containing the corresponding numerical prefix
 function net.mask4prefix(mask)
 	local bin = net.ip4bin(mask)
 
@@ -226,12 +286,19 @@ function net.mask4prefix(mask)
 	return #luci.util.split(bin, "1")-1
 end
 
--- Returns the kernel routing table
+--- Returns the current kernel routing table entries.
+-- @return	Table of tables with properties of the corresponding routes.
+--			The following fields are defined for route entry tables:
+--			{ "Mask", "RefCnt", "Iface", "Flags", "Window", "IRTT",
+--			  "MTU", "Gateway", "Destination", "Metric", "Use" }
 function net.routes()
 	return _parse_delimited_table(io.lines("/proc/net/route"))
 end
 
--- Returns the numeric IP to a given hexstring
+--- Convert hexadecimal 32 bit value to IPv4 address.
+-- @param hex	String containing the hexadecimal value
+-- @param be	Boolean indicating wheather the given value is big endian
+-- @return		String containing the corresponding IP4 address
 function net.hexip4(hex, be)
 	if #hex ~= 8 then
 		return nil
@@ -257,7 +324,9 @@ function net.hexip4(hex, be)
 	return ip
 end
 
--- Returns the binary IP to a given IP
+--- Convert given IPv4 address to binary value.
+-- @param ip	String containing a IPv4 address
+-- @return		String containing corresponding binary value
 function net.ip4bin(ip)
 	local parts = luci.util.split(ip, '.')
 	if #parts ~= 4 then
@@ -275,30 +344,61 @@ function net.ip4bin(ip)
 	return bin
 end
 
--- Tests whether a host is pingable
+--- Tests whether the given host responds to ping probes.
+-- @param host	String containing a hostname or IPv4 address
+-- @return		Number containing 0 on success and >= 1 on error
 function net.pingtest(host)
 	return os.execute("ping -c1 '"..host:gsub("'", '').."' >/dev/null 2>&1")
 end
 
 
+--- LuCI system utilities / process related functions.
+-- @class	module
+-- @name	luci.sys.process
 process = {}
+
+--- Get the current process id.
+-- @return	Number containing the current pid
 process.info = posix.getpid
 
--- Sets the gid of a process
+--- Set the gid of a process identified by given pid.
+-- @param pid	Number containing the process id
+-- @param gid	Number containing the Unix group id
+-- @return		Boolean indicating successful operation
+-- @return		String containing the error message if failed
+-- @return		Number containing the error code if failed
 function process.setgroup(pid, gid)
 	return posix.setpid("g", pid, gid)
 end
 
--- Sets the uid of a process
+--- Set the uid of a process identified by given pid.
+-- @param pid	Number containing the process id
+-- @param uid	Number containing the Unix user id
+-- @return		Boolean indicating successful operation
+-- @return		String containing the error message if failed
+-- @return		Number containing the error code if failed
 function process.setuser(pid, uid)
 	return posix.setpid("u", pid, uid)
 end
 
+
+--- LuCI system utilities / user related functions.
+-- @class	module
+-- @name	luci.sys.user
 user = {}
--- returns user information to a given uid
+
+--- Retrieve user informations for given uid.
+-- @class		function
+-- @name		getuser
+-- @param uid	Number containing the Unix user id
+-- @return		Table containing the following fields:
+--				{ "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
 user.getuser = posix.getpasswd
 
--- checks whether a string matches the password of a certain system user
+--- Test whether given string matches the password of a given system user.
+-- @param username	String containing the Unix user name
+-- @param password	String containing the password to compare
+-- @return			Boolean indicating wheather the passwords are equal
 function user.checkpasswd(username, password)
 	local account = user.getuser(username)
 
@@ -314,24 +414,32 @@ function user.checkpasswd(username, password)
 	end
 end
 
--- Changes the user password of given user
+--- Change the password of given user.
-function user.setpasswd(user, pwd)
+-- @param username	String containing the Unix user name
-	if pwd then
+-- @param password	String containing the password to compare
-		pwd = pwd:gsub("'", "")
+-- @return			Number containing 0 on success and >= 1 on error
+function user.setpasswd(username, password)
+	if password then
+		password = password:gsub("'", "")
 	end
 
-	if user then
+	if username then
-		user = user:gsub("'", "")
+		username = username:gsub("'", "")
 	end
 
-	local cmd = "(echo '"..pwd.."';sleep 1;echo '"..pwd.."')|"
+	local cmd = "(echo '"..password.."';sleep 1;echo '"..password.."')|"
-	cmd = cmd .. "passwd '"..user.."' >/dev/null 2>&1"
+	cmd = cmd .. "passwd '"..username.."' >/dev/null 2>&1"
 	return os.execute(cmd)
 end
 
 
+--- LuCI system utilities / wifi related functions.
+-- @class	module
+-- @name	luci.sys.wifi
 wifi = {}
 
+--- Get iwconfig output for all wireless devices.
+-- @return	Table of tables containing the iwconfing output for each wifi device
 function wifi.getiwconfig()
 	local cnt = exec("/usr/sbin/iwconfig 2>/dev/null")
 	local iwc = {}
@@ -347,6 +455,8 @@ function wifi.getiwconfig()
 	return iwc
 end
 
+--- Get iwlist scan output from all wireless devices.
+-- @return	Table of tables contaiing all scan results
 function wifi.iwscan()
 	local cnt = exec("iwlist scan 2>/dev/null")
 	local iws = {}