From 5b43543226fa29dc7d899e9fc82f0179aefcb56b Mon Sep 17 00:00:00 2001
From: Steven Barth <steven@midlink.org>
Date: Tue, 29 Jul 2008 20:32:02 +0000
Subject: [PATCH] libs/web: Small improvements, added inline documentation

---
 libs/web/luasrc/config.lua     |  4 +-
 libs/web/luasrc/dispatcher.lua | 69 +++++++++++++++++++++++++++-------
 libs/web/luasrc/i18n.lua       | 28 +++++++++++---
 libs/web/luasrc/sauth.lua      | 12 +++++-
 libs/web/luasrc/template.lua   | 12 ++++--
 5 files changed, 100 insertions(+), 25 deletions(-)

diff --git a/libs/web/luasrc/config.lua b/libs/web/luasrc/config.lua
index 557303f88..72bd5aa92 100644
--- a/libs/web/luasrc/config.lua
+++ b/libs/web/luasrc/config.lua
@@ -27,5 +27,7 @@ limitations under the License.
 
 module("luci.config",
 	function(m)
-		setmetatable(m, {__index = require("luci.model.uci").get_all("luci")})
+		if pcall(require, "luci.model.uci") then
+			setmetatable(m, {__index = luci.model.uci.get_all("luci")})
+		end
 	end)
\ No newline at end of file
diff --git a/libs/web/luasrc/dispatcher.lua b/libs/web/luasrc/dispatcher.lua
index 682511db2..628b4e3ee 100644
--- a/libs/web/luasrc/dispatcher.lua
+++ b/libs/web/luasrc/dispatcher.lua
@@ -23,6 +23,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 ]]--
+
+--- LuCI web dispatcher.
 module("luci.dispatcher", package.seeall)
 require("luci.init")
 require("luci.http")
@@ -38,12 +40,16 @@ local index = nil
 local fi
 
 
--- Builds a URL
+--- Build the URL relative to the server webroot from given virtual path.
+-- @param ...	Virtual path
+-- @return 		Relative URL
 function build_url(...)
 	return luci.http.getenv("SCRIPT_NAME") .. "/" .. table.concat(arg, "/")
 end
 
--- Sends a 404 error code and renders the "error404" template if available
+--- Send a 404 error code and render the "error404" template if available.
+-- @param message	Custom error message (optional)
+-- @return			false
 function error404(message)
 	luci.http.status(404, "Not Found")
 	message = message or "Not Found"
@@ -56,7 +62,9 @@ function error404(message)
 	return false
 end
 
--- Sends a 500 error code and renders the "error500" template if available
+--- Send a 500 error code and render the "error500" template if available.
+-- @param message	Custom error message (optional)#
+-- @return			false
 function error500(message)
 	luci.http.status(500, "Internal Server Error")
 
@@ -68,7 +76,9 @@ function error500(message)
 	return false
 end
 
--- Renders an authorization form
+--- Render and evaluate the system authentication login form.
+-- @param default	Default username
+-- @return			Authentication status
 function sysauth(default)
 	local user = luci.http.formvalue("username")
 	local pass = luci.http.formvalue("password")
@@ -87,7 +97,8 @@ function sysauth(default)
 	end
 end
 
--- Creates a request object for dispatching
+--- Dispatch an HTTP request.
+-- @param request	LuCI HTTP Request object
 function httpdispatch(request)
 	luci.http.context.request = request
 	context.request = {}
@@ -101,7 +112,8 @@ function httpdispatch(request)
 	luci.http.close()
 end
 
--- Dispatches a request
+--- Dispatches a LuCI virtual path.
+-- @param request	Virtual path
 function dispatch(request)
 	context.path = request
 	
@@ -187,7 +199,7 @@ function dispatch(request)
 	end
 end
 
--- Generates the dispatching tree
+--- Generate the dispatching index using the best possible strategy.
 function createindex()
 	local path = luci.sys.libpath() .. "/controller/"
 	local suff = ".lua"
@@ -199,7 +211,9 @@ function createindex()
 	end
 end
 
--- Uses fastindex to create the dispatching tree
+--- Generate the dispatching index using the fastindex C-indexer.
+-- @param path		Controller base directory
+-- @param suffix	Controller file suffix
 function createindex_fastindex(path, suffix)
 	index = {}
 		
@@ -215,8 +229,9 @@ function createindex_fastindex(path, suffix)
 	end
 end
 
--- Calls the index function of all available controllers
--- Fallback for transition purposes / Leave it in as long as it works otherwise throw it away
+--- Generate the dispatching index using the native file-cache based strategy.
+-- @param path		Controller base directory
+-- @param suffix	Controller file suffix
 function createindex_plain(path, suffix)
 	index = {}
 
@@ -265,7 +280,8 @@ function createindex_plain(path, suffix)
 	end
 end
 
--- Creates the dispatching tree from the index
+--- Create the dispatching tree from the index.
+-- Build the index before if it does not exist yet.
 function createtree()
 	if not index then
 		createindex()
@@ -297,7 +313,12 @@ function createtree()
 	end
 end
 
--- Reassigns a node to another position
+--- Clone a node of the dispatching tree to another position.
+-- @param	path	Virtual path destination
+-- @param	clone	Virtual path source
+-- @param	title	Destination node title (optional)
+-- @param	order	Destination node order value (optional)
+-- @return			Dispatching tree node
 function assign(path, clone, title, order)
 	local obj  = node(unpack(path))
 	obj.nodes  = nil
@@ -320,7 +341,12 @@ function assign(path, clone, title, order)
 	return obj
 end
 
--- Shortcut for creating a dispatching node
+--- Create a new dispatching node and define common parameters.
+-- @param	path	Virtual path
+-- @param	target	Target function to call when dispatched. 
+-- @param	title	Destination node title
+-- @param	order	Destination node order value (optional)
+-- @return			Dispatching tree node
 function entry(path, target, title, order)
 	local c = node(unpack(path))
 	
@@ -332,7 +358,9 @@ function entry(path, target, title, order)
 	return c
 end
 
--- Fetch a dispatching node
+--- Fetch or create a new dispatching node.
+-- @param	...		Virtual path
+-- @return			Dispatching tree node
 function node(...)
 	local c = context.tree
 	arg.n = nil
@@ -353,6 +381,9 @@ function node(...)
 end
 
 -- Subdispatchers --
+
+--- Create a redirect to another dispatching node.
+-- @param	...		Virtual path destination
 function alias(...)
 	local req = arg
 	return function()
@@ -360,6 +391,9 @@ function alias(...)
 	end
 end
 
+--- Rewrite the first x path values of the request.
+-- @param	n		Number of path values to replace
+-- @param	...		Virtual path to replace removed path values with
 function rewrite(n, ...)
 	local req = arg
 	return function()
@@ -375,16 +409,23 @@ function rewrite(n, ...)
 	end
 end
 
+--- Create a function-call dispatching target.
+-- @param	nane	Target function of local controller 
+-- @param	...		Additional parameters passed to the function
 function call(name, ...)
 	local argv = {...}
 	return function() return getfenv()[name](unpack(argv)) end
 end
 
+--- Create a template render dispatching target.
+-- @param	nane	Template to be rendered
 function template(name)
 	require("luci.template")
 	return function() luci.template.render(name) end
 end
 
+--- Create a CBI model dispatching target.
+-- @param	model	CBI model tpo be rendered
 function cbi(model)
 	require("luci.cbi")
 	require("luci.template")
diff --git a/libs/web/luasrc/i18n.lua b/libs/web/luasrc/i18n.lua
index e30116202..5f0ee8a01 100644
--- a/libs/web/luasrc/i18n.lua
+++ b/libs/web/luasrc/i18n.lua
@@ -24,6 +24,7 @@ limitations under the License.
 
 ]]--
 
+--- LuCI translation library.
 module("luci.i18n", package.seeall)
 require("luci.sys")
 
@@ -33,12 +34,16 @@ loaded  = {}
 context = luci.util.threadlocal()
 default = "en"
 
--- Clears the translation table
+--- Clear the translation table.
 function clear()
 	table = {}
 end
 
--- Loads a translation and copies its data into the global translation table
+--- Load a translation and copy its data into the translation table.
+-- @param file	Language file
+-- @param lang	Two-letter language code
+-- @param force	Force reload even if already loaded (optional)
+-- @return		Success status
 function load(file, lang, force)
 	lang = lang or ""
 	if force or not loaded[lang] or not loaded[lang][file] then
@@ -58,25 +63,36 @@ function load(file, lang, force)
 	end
 end
 
--- Same as load but autocompletes the filename with .LANG from config.lang
+--- Load a translation file using the default translation language.
+-- Alternatively load the translation of the fallback language.
+-- @param file	Language file
+-- @param force	Force reload even if already loaded (optional)
 function loadc(file, force)
 	load(file, default, force)
 	return load(file, context.lang, force)
 end
 
--- Sets the context language
+--- Set the context default translation language.
+-- @param lang	Two-letter language code
 function setlanguage(lang)
 	context.lang = lang
 end
 
--- Returns the i18n-value defined by "key" or if there is no such: "default"
+--- Return the translated value for a specific translation key.
+-- @param key	Translation key
+-- @param def	Default translation
+-- @return		Translated string
 function translate(key, def)
 	return (table[context.lang] and table[context.lang][key])
 		or (table[default] and table[default][key])
 		or def
 end
 
--- Translate shourtcut with sprintf/string.format inclusion
+--- Return the translated value for a specific translation key and use it as sprintf pattern.
+-- @param key		Translation key
+-- @param default	Default translation
+-- @param ...		Format parameters
+-- @return			Translated and formatted string
 function translatef(key, default, ...)
 	return translate(key, default):format(...)
 end
\ No newline at end of file
diff --git a/libs/web/luasrc/sauth.lua b/libs/web/luasrc/sauth.lua
index fc4942b97..d25f287c5 100644
--- a/libs/web/luasrc/sauth.lua
+++ b/libs/web/luasrc/sauth.lua
@@ -12,6 +12,8 @@ You may obtain a copy of the License at
 $Id$
 
 ]]--
+
+--- LuCI session library.
 module("luci.sauth", package.seeall)
 require("luci.fs")
 require("luci.util")
@@ -22,7 +24,7 @@ luci.config.sauth = luci.config.sauth or {}
 sessionpath = luci.config.sauth.sessionpath
 sessiontime = tonumber(luci.config.sauth.sessiontime)
 
-
+--- Manually clean up expired sessions.
 function clean()
 	local now   = os.time()
 	local files = luci.fs.dir(sessionpath)
@@ -40,11 +42,15 @@ function clean()
 	end
 end
 
+--- Prepare session storage by creating the session directory.
 function prepare()
 	luci.fs.mkdir(sessionpath)
 	luci.fs.chmod(sessionpath, "a-rwx,u+rwx")
 end
 
+--- Read a session and return its content.
+-- @param id	Session identifier
+-- @return		Session data
 function read(id)
 	if not id then
 		return
@@ -53,6 +59,10 @@ function read(id)
 	return luci.fs.readfile(sessionpath .. "/" .. id)
 end
 
+
+--- Write session data to a session file.
+-- @param id	Session identifier
+-- @param data	Session data
 function write(id, data)
 	if not luci.fs.stat(sessionpath) then
 		prepare()
diff --git a/libs/web/luasrc/template.lua b/libs/web/luasrc/template.lua
index 12b80bec8..17e1daad7 100644
--- a/libs/web/luasrc/template.lua
+++ b/libs/web/luasrc/template.lua
@@ -23,6 +23,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 ]]--
+
+--- LuCI template library.
 module("luci.template", package.seeall)
 
 require("luci.config")
@@ -50,9 +52,11 @@ viewns = {
 	include    = function(name) Template(name):render(getfenv(2)) end,
 }
 
--- Compiles a given template into an executable Lua module
+--- Manually  compile a given template into an executable Lua function
+-- @param template	LuCI template
+-- @return 			Lua template function
 function compile(template)	
-	-- Search all <% %> expressions (remember: Lua table indexes begin with #1)
+	-- Search all <% %> expressions
 	local function expr_add(ws1, skip1, command, skip2, ws2)
 		table.insert(expr, command)
 		return ( #skip1 > 0 and "" or ws1 ) .. 
@@ -114,7 +118,9 @@ function compile(template)
 	return loadstring(template)
 end
 
--- Oldstyle render shortcut
+--- Render a certain template.
+-- @param name		Template name
+-- @param scope		Scope to assign to template
 function render(name, scope, ...)
 	scope = scope or getfenv(2)
 	local s, t = luci.util.copcall(Template, name)
-- 
2.25.1