Cleanup and documentation

3 files changed, 180 insertions, 93 deletions

diff --git a/libs/core/luasrc/ltn12.lua b/libs/core/luasrc/ltn12.lua
index a6ce11bf1..c9b663463 100644
--- a/libs/core/luasrc/ltn12.lua
+++ b/libs/core/luasrc/ltn12.lua
@@ -20,6 +20,11 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 ]]--
+--[[
+	Changes made by LuCI project:
+		* Renamed to luci.ltn12 to avoid collisions with luasocket
+		* Added inline documentation
+]]--
 -----------------------------------------------------------------------------
 -- LTN12 - Filters, sources, sinks and pumps.
 -- LuaSocket toolkit.
@@ -33,6 +38,9 @@ DEALINGS IN THE SOFTWARE.
 local string = require("string")
 local table = require("table")
 local base = _G
+
+--- Diego Nehab's LTN12 - Filters, sources, sinks and pumps.
+-- See http://lua-users.org/wiki/FiltersSourcesAndSinks for design concepts 
 module("luci.ltn12")
 
 filter = {}
@@ -47,7 +55,17 @@ _VERSION = "LTN12 1.0.1"
 -----------------------------------------------------------------------------
 -- Filter stuff
 -----------------------------------------------------------------------------
--- returns a high level filter that cycles a low-level filter
+
+--- LTN12 Filter constructors
+-- @class module
+-- @name luci.ltn12.filter
+
+--- Return a high level filter that cycles a low-level filter
+-- by passing it each chunk and updating a context between calls. 
+-- @param low   Low-level filter
+-- @param ctx   Context
+-- @param extra Extra argument passed to the low-level filter
+-- @return LTN12 filter
 function filter.cycle(low, ctx, extra)
     base.assert(low)
     return function(chunk)
@@ -57,8 +75,10 @@ function filter.cycle(low, ctx, extra)
     end
 end
 
--- chains a bunch of filters together
+--- Chain a bunch of filters together.
 -- (thanks to Wim Couwenberg)
+-- @param ... filters to be chained
+-- @return LTN12 filter
 function filter.chain(...)
     local n = table.getn(arg)
     local top, index = 1, 1
@@ -91,23 +111,35 @@ end
 -----------------------------------------------------------------------------
 -- Source stuff
 -----------------------------------------------------------------------------
+
+--- LTN12 Source constructors
+-- @class module
+-- @name luci.ltn12.source
+
 -- create an empty source
 local function empty()
     return nil
 end
 
+--- Create an empty source.
+-- @return LTN12 source
 function source.empty()
     return empty
 end
 
--- returns a source that just outputs an error
+--- Return a source that just outputs an error.
+-- @param err Error object
+-- @return LTN12 source
 function source.error(err)
     return function()
         return nil, err
     end
 end
 
--- creates a file source
+--- Create a file source.
+-- @param handle File handle ready for reading
+-- @param io_err IO error object
+-- @return LTN12 source
 function source.file(handle, io_err)
     if handle then
         return function()
@@ -118,7 +150,9 @@ function source.file(handle, io_err)
     else return source.error(io_err or "unable to open file") end
 end
 
--- turns a fancy source into a simple source
+--- Turn a fancy source into a simple source.
+-- @param src fancy source
+-- @return LTN12 source
 function source.simplify(src)
     base.assert(src)
     return function()
@@ -129,7 +163,9 @@ function source.simplify(src)
     end
 end
 
--- creates string source
+--- Create a string source.
+-- @param s Data
+-- @return LTN12 source
 function source.string(s)
     if s then
         local i = 1
@@ -142,7 +178,9 @@ function source.string(s)
     else return source.empty() end
 end
 
--- creates rewindable source
+--- Creates rewindable source.
+-- @param src LTN12 source to be made rewindable
+-- @return LTN12 source
 function source.rewind(src)
     base.assert(src)
     local t = {}
@@ -157,6 +195,10 @@ function source.rewind(src)
     end
 end
 
+--- Chain a source and a filter together.
+-- @param src LTN12 source
+-- @param f LTN12 filter
+-- @return LTN12 source
 function source.chain(src, f)
     base.assert(src and f)
     local last_in, last_out = "", ""
@@ -204,9 +246,11 @@ function source.chain(src, f)
     end
 end
 
--- creates a source that produces contents of several sources, one after the
--- other, as if they were concatenated
+--- Create a source that produces contents of several sources.
+-- Sources will be used one after the other, as if they were concatenated
 -- (thanks to Wim Couwenberg)
+-- @param ... LTN12 sources
+-- @return LTN12 source
 function source.cat(...)
     local src = table.remove(arg, 1)
     return function()
@@ -222,7 +266,14 @@ end
 -----------------------------------------------------------------------------
 -- Sink stuff
 -----------------------------------------------------------------------------
--- creates a sink that stores into a table
+
+--- LTN12 sink constructors
+-- @class module
+-- @name luci.ltn12.sink
+
+--- Create a sink that stores into a table.
+-- @param t output table to store into
+-- @return LTN12 sink
 function sink.table(t)
     t = t or {}
     local f = function(chunk, err)
@@ -232,7 +283,9 @@ function sink.table(t)
     return f, t
 end
 
--- turns a fancy sink into a simple sink
+--- Turn a fancy sink into a simple sink.
+-- @param snk fancy sink
+-- @return LTN12 sink
 function sink.simplify(snk)
     base.assert(snk)
     return function(chunk, err)
@@ -243,7 +296,10 @@ function sink.simplify(snk)
     end
 end
 
--- creates a file sink
+--- Create a file sink.
+-- @param handle file handle to write to
+-- @param io_err IO error
+-- @return LTN12 sink
 function sink.file(handle, io_err)
     if handle then
         return function(chunk, err)
@@ -260,18 +316,25 @@ local function null()
     return 1
 end
 
+--- Create a sink that discards data.
+-- @return LTN12 sink
 function sink.null()
     return null
 end
 
--- creates a sink that just returns an error
+--- Create a sink that just returns an error.
+-- @param err Error object
+-- @return LTN12 sink
 function sink.error(err)
     return function()
         return nil, err
     end
 end
 
--- chains a sink with a filter
+--- Chain a sink with a filter.
+-- @param f LTN12 filter
+-- @param snk LTN12 sink
+-- @return LTN12 sink
 function sink.chain(f, snk)
     base.assert(f and snk)
     return function(chunk, err)
@@ -291,7 +354,16 @@ end
 -----------------------------------------------------------------------------
 -- Pump stuff
 -----------------------------------------------------------------------------
--- pumps one chunk from the source to the sink
+
+--- LTN12 pump functions
+-- @class module
+-- @name luci.ltn12.pump
+
+--- Pump one chunk from the source to the sink.
+-- @param src LTN12 source
+-- @param snk LTN12 sink
+-- @return Chunk of data or nil if an error occured
+-- @return Error object
 function pump.step(src, snk)
     local chunk, src_err = src()
     local ret, snk_err = snk(chunk, src_err)
@@ -299,7 +371,12 @@ function pump.step(src, snk)
     else return nil, src_err or snk_err end
 end
 
--- pumps all data from a source to a sink, using a step function
+--- Pump all data from a source to a sink, using a step function.
+-- @param src LTN12 source
+-- @param snk LTN12 sink
+-- @param step step function (optional)
+-- @return 1 if the operation succeeded otherwise nil
+-- @return Error object
 function pump.all(src, snk, step)
     base.assert(src and snk)
     step = step or pump.step
diff --git a/libs/ipkg/luasrc/model/ipkg.lua b/libs/ipkg/luasrc/model/ipkg.lua
index 4c2716a38..97d0c1932 100644
--- a/libs/ipkg/luasrc/model/ipkg.lua
+++ b/libs/ipkg/luasrc/model/ipkg.lua
@@ -1,75 +1,33 @@
 --[[
-LuCI - IPKG wrapper library
+LuCI - Lua Configuration Interface
 
-Description:
-Wrapper for the ipkg Package manager
-
-Any return value of false or nil can be interpreted as an error
-
-FileId:
-$Id$
-
-License:
-Copyright 2008 Steven Barth <steven@midlink.org>
+(c) 2008 Jo-Philipp Wich <xm@leipzig.freifunk.net>
+(c) 2008 Steven Barth <steven@midlink.org>
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
-You may obtain a copy of the License at 
-
-	http://www.apache.org/licenses/LICENSE-2.0 
+You may obtain a copy of the License at
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+http://www.apache.org/licenses/LICENSE-2.0
 
+$Id$
 ]]--
-module("luci.model.ipkg", package.seeall)
-require("luci.util")
-require("luci.fs")
-
-ipkg = luci.fs.access("/bin/opkg") and "opkg" or "ipkg"
-
--- Returns repository information
-function info(pkg)
-	return _lookup("info", pkg)
-end
-
--- Returns a table with status information
-function status(pkg)
-	return _lookup("status", pkg)
-end
-
--- Installs packages
-function install(...)
-	return _action("install", ...)
-end
 
--- Returns whether a package is installed
-function installed(pkg, ...)
-	local p = status(...)[pkg]
-	return (p and p.Status and p.Status.installed)
-end
+local os   = require "os"
+local util = require "luci.util"
 
--- Removes packages
-function remove(...)
-	return _action("remove", ...)
-end
+local type  = type
+local pairs = pairs
+local error = error
 
--- Updates package lists
-function update()
-	return _action("update")
-end
+local ipkg = "opkg"
 
--- Upgrades installed packages
-function upgrade()
-	return _action("upgrade")
-end
+--- LuCI IPKG/OPKG call abstraction library
+module "luci.model.ipkg"
 
 
 -- Internal action function
-function _action(cmd, ...)
+local function _action(cmd, ...)
 	local pkg = ""
 	arg.n = nil
 	for k, v in pairs(arg) do
@@ -81,39 +39,29 @@ function _action(cmd, ...)
 	return (r == 0), r	
 end
 
--- Internal lookup function
-function _lookup(act, pkg)
-	local cmd = ipkg .. " " .. act
-	if pkg then
-		cmd = cmd .. " '" .. pkg:gsub("'", "") .. "'"
-	end
-	
-	return _parselist(luci.util.exec(cmd .. " 2>/dev/null"))
-end
-
 -- Internal parser function
-function _parselist(rawdata)	
+local function _parselist(rawdata)	
 	if type(rawdata) ~= "string" then
 		error("IPKG: Invalid rawdata given")
 	end
 	
-	rawdata = luci.util.split(rawdata) 
+	rawdata = util.split(rawdata) 
 	local data = {}
 	local c = {}
 	local l = nil
 	
 	for k, line in pairs(rawdata) do
 		if line:sub(1, 1) ~= " " then
-			local split = luci.util.split(line, ":", 1)
+			local split = util.split(line, ":", 1)
 			local key = nil
 			local val = nil
 			
 			if split[1] then
-				key = luci.util.trim(split[1])
+				key = util.trim(split[1])
 			end
 			
 			if split[2] then
-				val = luci.util.trim(split[2])
+				val = util.trim(split[2])
 			end
 			
 			if key and val then
@@ -137,4 +85,68 @@ function _parselist(rawdata)
 	end
 	
 	return data
-end
\ No newline at end of file
+end
+
+-- Internal lookup function
+local function _lookup(act, pkg)
+	local cmd = ipkg .. " " .. act
+	if pkg then
+		cmd = cmd .. " '" .. pkg:gsub("'", "") .. "'"
+	end
+	
+	return _parselist(util.exec(cmd .. " 2>/dev/null"))
+end
+
+
+--- Return information about installed and available packages.
+-- @param pkg Limit output to a (set of) packages
+-- @return Table containing package information
+function info(pkg)
+	return _lookup("info", pkg)
+end
+
+--- Return the package status of one or more packages.
+-- @param pkg Limit output to a (set of) packages
+-- @return Table containing package status information
+function status(pkg)
+	return _lookup("status", pkg)
+end
+
+--- Install one or more packages.
+-- @param ... List of packages to install
+-- @return Boolean indicating the status of the action
+-- @return IPKG return code
+function install(...)
+	return _action("install", ...)
+end
+
+--- Determine whether a given package is installed.
+-- @param pkg Package
+-- @return Boolean
+function installed(pkg)
+	local p = status(pkg)[pkg]
+	return (p and p.Status and p.Status.installed)
+end
+
+--- Remove one or more packages.
+-- @param ... List of packages to install
+-- @return Boolean indicating the status of the action
+-- @return IPKG return code
+function remove(...)
+	return _action("remove", ...)
+end
+
+--- Update package lists.
+-- @return Boolean indicating the status of the action
+-- @return IPKG return code
+function update()
+	return _action("update")
+end
+
+--- Upgrades all installed packages.
+-- @return Boolean indicating the status of the action
+-- @return IPKG return code
+function upgrade()
+	return _action("upgrade")
+end
+
diff --git a/libs/uci/luasrc/model/uci.lua b/libs/uci/luasrc/model/uci.lua
index 7fc0c79fd..3b135c532 100644
--- a/libs/uci/luasrc/model/uci.lua
+++ b/libs/uci/luasrc/model/uci.lua
@@ -34,6 +34,7 @@ local error, pairs, ipairs, tostring = error, pairs, ipairs, tostring
 local require, getmetatable = require, getmetatable
 
 --- LuCI UCI model library.
+-- @cstyle	instance
 module("luci.model.uci")
 
 --- Create a new UCI-Cursor.
@@ -50,10 +51,7 @@ function cursor_state()
 	return cursor(nil, "/var/state")
 end
 
---- UCI-Cursor
--- @class	module
--- @cstyle	instance
--- @name	luci.model.uci.Cursor
+
 local Cursor = getmetatable(cursor())
 
 --- Applies the new config