libs/web: Cleanup and inline documentation

[project/luci.git] / libs / web / luasrc / http.lua

diff --git a/libs/web/luasrc/http.lua b/libs/web/luasrc/http.lua
index 2540d08..154f51a 100644 (file)
--- a/libs/web/luasrc/http.lua
+++ b/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(...)
-end
-
-function formvaluetable(...)
-       return context.request:formvaluetable(...)
+--- 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 getcookie(...)
-       return context.request:getcookie(...)
+--- 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 getvalue(...)
-       return context.request:getvalue(...)
+--- 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 postvalue(...)
-       return context.request:postvalue(...)
+--- 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 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