libs/web: Cleanup and inline documentation

libs/web/luasrc/http.lua

@@ -31,7 +31,6 @@ require("luci.util")
 
 context = luci.util.threadlocal()
 
-
 Request = luci.util.class()
 function Request.__init__(self, env, sourcein, sinkerr)
 	self.input = sourcein
@@ -109,7 +108,7 @@ function Request._parse_input(self)
 	self.parsed_input = true
 end
 
-
+--- Close the HTTP-Connection.
 function close()
 	if not context.eoh then
 		context.eoh = true
@@ -122,34 +121,45 @@ function close()
 	end
 end
 
-function formvalue(...)
-	return context.request:formvalue(...)
+--- Get a certain HTTP input value or a table of all input values.
+-- @param name		Name of the GET or POST variable to fetch
+-- @param noparse	Don't parse POST data before getting the value
+-- @return			HTTP input value or table of all input value
+function formvalue(name, noparse)
+	return context.request:formvalue(name, noparse)
 end
 
-function formvaluetable(...)
-	return context.request:formvaluetable(...)
+--- Get a table of all HTTP input values with a certain prefix.
+-- @param prefix	Prefix
+-- @return			Table of all HTTP input values with given prefix
+function formvaluetable(prefix)
+	return context.request:formvaluetable(prefix)
 end
 
-function getcookie(...)
-	return context.request:getcookie(...)
+--- Get the value of a certain HTTP-Cookie.
+-- @param name		Cookie Name
+-- @return			String containing cookie data
+function getcookie(name)
+	return context.request:getcookie(name)
 end
 
-function getvalue(...)
-	return context.request:getvalue(...)
+--- Get the value of a certain HTTP environment variable 
+-- or the environment table itself.
+-- @param name		Environment variable
+-- @return			HTTP environment value or environment table
+function getenv(name)
+	return context.request:getenv(name)
 end
 
-function postvalue(...)
-	return context.request:postvalue(...)
-end
-
-function getenv(...)
-	return context.request:getenv(...)
-end
-
-function setfilehandler(...)
-	return context.request:setfilehandler(...)
+--- Set a handler function for incoming user file uploads.
+-- @param callback	Handler function
+function setfilehandler(callback)
+	return context.request:setfilehandler(callback)
 end
 
+--- Send a HTTP-Header.
+-- @param key	Header key
+-- @param value Header value
 function header(key, value)
 	if not context.headers then
 		context.headers = {}
@@ -158,10 +168,15 @@ function header(key, value)
 	coroutine.yield(2, key, value)
 end
 
+--- Set the mime type of following content data.
+-- @param mime	Mimetype of following content
 function prepare_content(mime)
 	header("Content-Type", mime)
 end
 
+--- Set the HTTP status code and status message.
+-- @param code		Status code
+-- @param message	Status message
 function status(code, message)
 	code = code or 200
 	message = message or "OK"
@@ -169,6 +184,12 @@ function status(code, message)
 	coroutine.yield(1, code, message)
 end
 
+--- Send a chunk of content data to the client.
+-- This function is as a valid LTN12 sink.
+-- If the content chunk is nil this function will automatically invoke close.
+-- @param content	Content chunk
+-- @param src_err	Error object from source (optional)
+-- @see close
 function write(content, src_err)
 	if not content then
 		if src_err then
@@ -200,12 +221,17 @@ function write(content, src_err)
 	end
 end
 
+--- Redirects the client to a new URL and closes the connection.
+-- @param url	Target URL
 function redirect(url)
 	status(302, "Found")
 	header("Location", url)
 	close()
 end
 
+--- Create a querystring out of a table of key - value pairs.
+-- @param table		Query string source table
+-- @return			Encoded HTTP query string
 function build_querystring(table)
 	local s="?"
 	
@@ -216,5 +242,15 @@ function build_querystring(table)
 	return s
 end
 
+--- Return the URL-decoded equivalent of a string.
+-- @param str		URL-encoded string
+-- @param no_plus	Don't decode + to " "
+-- @return			URL-decoded string
+-- @see urlencode
 urldecode = luci.http.protocol.urldecode
+
+--- Return the URL-encoded equivalent of a string.
+-- @param str		Source string
+-- @return			URL-encoded string
+-- @see urldecode
 urlencode = luci.http.protocol.urlencode