Move inline documentation into separate files.

Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>

8 files changed, 307 insertions, 118 deletions

diff --git a/modules/luci-base/luasrc/http/protocol.lua b/modules/luci-base/luasrc/http/protocol.lua
index aeb7ea6211..e9efb44cfa 100644
--- a/modules/luci-base/luasrc/http/protocol.lua
+++ b/modules/luci-base/luasrc/http/protocol.lua
@@ -1,7 +1,6 @@
 -- Copyright 2008 Freifunk Leipzig / Jo-Philipp Wich <jow@openwrt.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI http protocol class.
 -- This class contains several functions useful for http message- and content
 -- decoding and to retrive form data from raw http messages.
 module("luci.http.protocol", package.seeall)
@@ -10,12 +9,7 @@ local ltn12 = require("luci.ltn12")
 
 HTTP_MAX_CONTENT      = 1024*8		-- 8 kB maximum content size
 
---- Decode an urlencoded string - optionally without decoding
 -- the "+" sign to " " - and return the decoded string.
--- @param str		Input string in x-www-urlencoded format
--- @param no_plus	Don't decode "+" signs to spaces
--- @return			The decoded string
--- @see				urlencode
 function urldecode( str, no_plus )
 
 	local function __chrdec( hex )
@@ -33,15 +27,10 @@ function urldecode( str, no_plus )
 	return str
 end
 
---- Extract and split urlencoded data pairs, separated bei either "&" or ";"
 -- from given url or string. Returns a table with urldecoded values.
 -- Simple parameters are stored as string values associated with the parameter
 -- name within the table. Parameters with multiple values are stored as array
 -- containing the corresponding values.
--- @param url	The url or string which contains x-www-urlencoded form data
--- @param tbl	Use the given table for storing values (optional)
--- @return		Table containing the urldecoded parameters
--- @see			urlencode_params
 function urldecode_params( url, tbl )
 
 	local params = tbl or { }
@@ -73,10 +62,6 @@ function urldecode_params( url, tbl )
 	return params
 end
 
---- Encode given string to x-www-urlencoded format.
--- @param str	String to encode
--- @return		String containing the encoded data
--- @see			urldecode
 function urlencode( str )
 
 	local function __chrenc( chr )
@@ -95,12 +80,8 @@ function urlencode( str )
 	return str
 end
 
---- Encode each key-value-pair in given table to x-www-urlencoded format,
 -- separated by "&". Tables are encoded as parameters with multiple values by
 -- repeating the parameter name with each value.
--- @param tbl	Table with the values
--- @return		String containing encoded values
--- @see			urldecode_params
 function urlencode_params( tbl )
 	local enc = ""
 
@@ -122,9 +103,6 @@ end
 -- (Internal function)
 -- Initialize given parameter and coerce string into table when the parameter
 -- already exists.
--- @param tbl	Table where parameter should be created
--- @param key	Parameter name
--- @return		Always nil
 local function __initval( tbl, key )
 	if tbl[key] == nil then
 		tbl[key] = ""
@@ -138,11 +116,6 @@ end
 -- (Internal function)
 -- Append given data to given parameter, either by extending the string value
 -- or by appending it to the last string in the parameter's value table.
--- @param tbl	Table containing the previously initialized parameter value
--- @param key	Parameter name
--- @param chunk	String containing the data to append
--- @return		Always nil
--- @see			__initval
 local function __appendval( tbl, key, chunk )
 	if type(tbl[key]) == "table" then
 		tbl[key][#tbl[key]] = tbl[key][#tbl[key]] .. chunk
@@ -155,12 +128,6 @@ end
 -- Finish the value of given parameter, either by transforming the string value
 -- or - in the case of multi value parameters - the last element in the
 -- associated values table.
--- @param tbl		Table containing the previously initialized parameter value
--- @param key		Parameter name
--- @param handler	Function which transforms the parameter value
--- @return			Always nil
--- @see				__initval
--- @see				__appendval
 local function __finishval( tbl, key, handler )
 	if handler then
 		if type(tbl[key]) == "table" then
@@ -259,10 +226,7 @@ process_states['headers'] = function( msg, chunk )
 end
 
 
---- Creates a ltn12 source from the given socket. The source will return it's
 -- data line by line with the trailing \r\n stripped of.
--- @param sock	Readable network socket
--- @return		Ltn12 source function
 function header_source( sock )
 	return ltn12.source.simplify( function()
 
@@ -289,7 +253,6 @@ function header_source( sock )
 	end )
 end
 
---- Decode a mime encoded http message body with multipart/form-data
 -- Content-Type. Stores all extracted data associated with its parameter name
 -- in the params table withing the given message object. Multiple parameter
 -- values are stored as tables, ordinary ones as strings.
@@ -300,12 +263,6 @@ end
 --  o Table containing decoded (name, file) and raw (headers) mime header data
 --  o String value containing a chunk of the file data
 --  o Boolean which indicates wheather the current chunk is the last one (eof)
--- @param src		Ltn12 source function
--- @param msg		HTTP message object
--- @param filecb	File callback function (optional)
--- @return			Value indicating successful operation (not nil means "ok")
--- @return			String containing the error if unsuccessful
--- @see				parse_message_header
 function mimedecode_message_body( src, msg, filecb )
 
 	if msg and msg.env.CONTENT_TYPE then
@@ -449,15 +406,9 @@ function mimedecode_message_body( src, msg, filecb )
 	return ltn12.pump.all( src, snk )
 end
 
---- Decode an urlencoded http message body with application/x-www-urlencoded
 -- Content-Type. Stores all extracted data associated with its parameter name
 -- in the params table withing the given message object. Multiple parameter
 -- values are stored as tables, ordinary ones as strings.
--- @param src	Ltn12 source function
--- @param msg	HTTP message object
--- @return		Value indicating successful operation (not nil means "ok")
--- @return		String containing the error if unsuccessful
--- @see			parse_message_header
 function urldecode_message_body( src, msg )
 
 	local tlen   = 0
@@ -507,12 +458,8 @@ function urldecode_message_body( src, msg )
 	return ltn12.pump.all( src, snk )
 end
 
---- Try to extract an http message header including information like protocol
 -- version, message headers and resulting CGI environment variables from the
 -- given ltn12 source.
--- @param src	Ltn12 source function
--- @return		HTTP message object
--- @see			parse_message_body
 function parse_message_header( src )
 
 	local ok   = true
@@ -582,19 +529,12 @@ function parse_message_header( src )
 	return msg
 end
 
---- Try to extract and decode a http message body from the given ltn12 source.
 -- This function will examine the Content-Type within the given message object
 -- to select the appropriate content decoder.
 -- Currently the application/x-www-urlencoded and application/form-data
 -- mime types are supported. If the encountered content encoding can't be
 -- handled then the whole message body will be stored unaltered as "content"
 -- property within the given message object.
--- @param src		Ltn12 source function
--- @param msg		HTTP message object
--- @param filecb	File data callback (optional, see mimedecode_message_body())
--- @return			Value indicating successful operation (not nil means "ok")
--- @return			String containing the error if unsuccessful
--- @see				parse_message_header
 function parse_message_body( src, msg, filecb )
 	-- Is it multipart/mime ?
 	if msg.env.REQUEST_METHOD == "POST" and msg.env.CONTENT_TYPE and
@@ -655,8 +595,6 @@ function parse_message_body( src, msg, filecb )
 	end
 end
 
---- Table containing human readable messages for several http status codes.
--- @class table
 statusmsg = {
 	[200] = "OK",
 	[206] = "Partial Content",
diff --git a/modules/luci-base/luasrc/http/protocol.luadoc b/modules/luci-base/luasrc/http/protocol.luadoc
new file mode 100644
index 0000000000..67a60d9e7a
--- /dev/null
+++ b/modules/luci-base/luasrc/http/protocol.luadoc
@@ -0,0 +1,142 @@
+---[[
+LuCI http protocol class.
+
+This class contains several functions useful for http message- and content
+decoding and to retrive form data from raw http messages.
+]]
+module "luci.http.protocol"
+
+---[[
+Decode an urlencoded string - optionally without decoding
+
+the "+" sign to " " - and return the decoded string.
+@class function
+@name urldecode
+@param str		Input string in x-www-urlencoded format
+@param no_plus	Don't decode "+" signs to spaces
+@return			The decoded string
+@see				urlencode
+]]
+
+---[[
+Extract and split urlencoded data pairs, separated bei either "&" or ";"
+
+from given url or string. Returns a table with urldecoded values.
+Simple parameters are stored as string values associated with the parameter
+name within the table. Parameters with multiple values are stored as array
+containing the corresponding values.
+@class function
+@name urldecode_params
+@param url	The url or string which contains x-www-urlencoded form data
+@param tbl	Use the given table for storing values (optional)
+@return		Table containing the urldecoded parameters
+@see			urlencode_params
+]]
+
+---[[
+Encode given string to x-www-urlencoded format.
+
+@class function
+@name urlencode
+@param str	String to encode
+@return		String containing the encoded data
+@see			urldecode
+]]
+
+---[[
+Encode each key-value-pair in given table to x-www-urlencoded format,
+
+separated by "&". Tables are encoded as parameters with multiple values by
+repeating the parameter name with each value.
+@class function
+@name urlencode_params
+@param tbl	Table with the values
+@return		String containing encoded values
+@see			urldecode_params
+]]
+
+---[[
+Creates a ltn12 source from the given socket. The source will return it's
+
+data line by line with the trailing \r\n stripped of.
+@class function
+@name header_source
+@param sock	Readable network socket
+@return		Ltn12 source function
+]]
+
+---[[
+Decode a mime encoded http message body with multipart/form-data
+
+Content-Type. Stores all extracted data associated with its parameter name
+in the params table withing the given message object. Multiple parameter
+values are stored as tables, ordinary ones as strings.
+If an optional file callback function is given then it is feeded with the
+file contents chunk by chunk and only the extracted file name is stored
+within the params table. The callback function will be called subsequently
+with three arguments:
+ o Table containing decoded (name, file) and raw (headers) mime header data
+ o String value containing a chunk of the file data
+ o Boolean which indicates wheather the current chunk is the last one (eof)
+@class function
+@name mimedecode_message_body
+@param src		Ltn12 source function
+@param msg		HTTP message object
+@param filecb	File callback function (optional)
+@return			Value indicating successful operation (not nil means "ok")
+@return			String containing the error if unsuccessful
+@see				parse_message_header
+]]
+
+---[[
+Decode an urlencoded http message body with application/x-www-urlencoded
+
+Content-Type. Stores all extracted data associated with its parameter name
+in the params table withing the given message object. Multiple parameter
+values are stored as tables, ordinary ones as strings.
+@class function
+@name urldecode_message_body
+@param src	Ltn12 source function
+@param msg	HTTP message object
+@return		Value indicating successful operation (not nil means "ok")
+@return		String containing the error if unsuccessful
+@see			parse_message_header
+]]
+
+---[[
+Try to extract an http message header including information like protocol
+
+version, message headers and resulting CGI environment variables from the
+given ltn12 source.
+@class function
+@name parse_message_header
+@param src	Ltn12 source function
+@return		HTTP message object
+@see			parse_message_body
+]]
+
+---[[
+Try to extract and decode a http message body from the given ltn12 source.
+
+This function will examine the Content-Type within the given message object
+to select the appropriate content decoder.
+Currently the application/x-www-urlencoded and application/form-data
+mime types are supported. If the encountered content encoding can't be
+handled then the whole message body will be stored unaltered as "content"
+property within the given message object.
+@class function
+@name parse_message_body
+@param src		Ltn12 source function
+@param msg		HTTP message object
+@param filecb	File data callback (optional, see mimedecode_message_body())
+@return			Value indicating successful operation (not nil means "ok")
+@return			String containing the error if unsuccessful
+@see				parse_message_header
+]]
+
+---[[
+Table containing human readable messages for several http status codes.
+
+@class table
+]]
+
diff --git a/modules/luci-base/luasrc/http/protocol/conditionals.lua b/modules/luci-base/luasrc/http/protocol/conditionals.lua
index 1d40425ff9..d31a4e38a4 100644
--- a/modules/luci-base/luasrc/http/protocol/conditionals.lua
+++ b/modules/luci-base/luasrc/http/protocol/conditionals.lua
@@ -1,7 +1,6 @@
 -- Copyright 2008 Freifunk Leipzig / Jo-Philipp Wich <jow@openwrt.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI http protocol implementation - HTTP/1.1 bits.
 -- This class provides basic ETag handling and implements most of the
 -- conditional HTTP/1.1 headers specified in RFC2616 Sct. 14.24 - 14.28 .
 module("luci.http.protocol.conditionals", package.seeall)
@@ -9,22 +8,14 @@ module("luci.http.protocol.conditionals", package.seeall)
 local date = require("luci.http.protocol.date")
 
 
---- Implement 14.19 / ETag.
--- @param stat	A file.stat structure
--- @return		String containing the generated tag suitable for ETag headers
 function mk_etag( stat )
 	if stat ~= nil then
 		return string.format( '"%x-%x-%x"', stat.ino, stat.size, stat.mtime )
 	end
 end
 
---- 14.24 / If-Match
 -- Test whether the given message object contains an "If-Match" header and
 -- compare it against the given stat object.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
 function if_match( req, stat )
 	local h    = req.headers
 	local etag = mk_etag( stat )
@@ -43,14 +34,8 @@ function if_match( req, stat )
 	return true
 end
 
---- 14.25 / If-Modified-Since
 -- Test whether the given message object contains an "If-Modified-Since" header
 -- and compare it against the given stat object.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
--- @return		Table containing extra HTTP headers if the precondition failed
 function if_modified_since( req, stat )
 	local h = req.headers
 
@@ -72,14 +57,8 @@ function if_modified_since( req, stat )
 	return true
 end
 
---- 14.26 / If-None-Match
 -- Test whether the given message object contains an "If-None-Match" header and
 -- compare it against the given stat object.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
--- @return		Table containing extra HTTP headers if the precondition failed
 function if_none_match( req, stat )
 	local h      = req.headers
 	local etag   = mk_etag( stat )
@@ -105,26 +84,16 @@ function if_none_match( req, stat )
 	return true
 end
 
---- 14.27 / If-Range
 -- The If-Range header is currently not implemented due to the lack of general
 -- byte range stuff in luci.http.protocol . This function will always return
 -- false, 412 to indicate a failed precondition.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
 function if_range( req, stat )
 	-- Sorry, no subranges (yet)
 	return false, 412
 end
 
---- 14.28 / If-Unmodified-Since
 -- Test whether the given message object contains an "If-Unmodified-Since"
 -- header and compare it against the given stat object.
--- @param req	HTTP request message object
--- @param stat	A file.stat object
--- @return		Boolean indicating whether the precondition is ok
--- @return		Alternative status code if the precondition failed
 function if_unmodified_since( req, stat )
 	local h = req.headers
 
diff --git a/modules/luci-base/luasrc/http/protocol/conditionals.luadoc b/modules/luci-base/luasrc/http/protocol/conditionals.luadoc
new file mode 100644
index 0000000000..9cfe02dd50
--- /dev/null
+++ b/modules/luci-base/luasrc/http/protocol/conditionals.luadoc
@@ -0,0 +1,85 @@
+---[[
+LuCI http protocol implementation - HTTP/1.1 bits.
+
+This class provides basic ETag handling and implements most of the
+conditional HTTP/1.1 headers specified in RFC2616 Sct. 14.24 - 14.28 .
+]]
+module "luci.http.protocol.conditionals"
+
+---[[
+Implement 14.19 / ETag.
+
+@class function
+@name mk_etag
+@param stat	A file.stat structure
+@return		String containing the generated tag suitable for ETag headers
+]]
+
+---[[
+14.24 / If-Match
+
+Test whether the given message object contains an "If-Match" header and
+compare it against the given stat object.
+@class function
+@name if_match
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+]]
+
+---[[
+14.25 / If-Modified-Since
+
+Test whether the given message object contains an "If-Modified-Since" header
+and compare it against the given stat object.
+@class function
+@name if_modified_since
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+@return		Table containing extra HTTP headers if the precondition failed
+]]
+
+---[[
+14.26 / If-None-Match
+
+Test whether the given message object contains an "If-None-Match" header and
+compare it against the given stat object.
+@class function
+@name if_none_match
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+@return		Table containing extra HTTP headers if the precondition failed
+]]
+
+---[[
+14.27 / If-Range
+
+The If-Range header is currently not implemented due to the lack of general
+byte range stuff in luci.http.protocol . This function will always return
+false, 412 to indicate a failed precondition.
+@class function
+@name if_range
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+]]
+
+---[[
+14.28 / If-Unmodified-Since
+
+Test whether the given message object contains an "If-Unmodified-Since"
+header and compare it against the given stat object.
+@class function
+@name if_unmodified_since
+@param req	HTTP request message object
+@param stat	A file.stat object
+@return		Boolean indicating whether the precondition is ok
+@return		Alternative status code if the precondition failed
+]]
+
diff --git a/modules/luci-base/luasrc/http/protocol/date.lua b/modules/luci-base/luasrc/http/protocol/date.lua
index 3105f37f63..e440219a9c 100644
--- a/modules/luci-base/luasrc/http/protocol/date.lua
+++ b/modules/luci-base/luasrc/http/protocol/date.lua
@@ -1,7 +1,6 @@
 -- Copyright 2008 Freifunk Leipzig / Jo-Philipp Wich <jow@openwrt.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI http protocol implementation - date helper class.
 -- This class contains functions to parse, compare and format http dates.
 module("luci.http.protocol.date", package.seeall)
 
@@ -13,9 +12,6 @@ MONTHS = {
 	"Sep", "Oct", "Nov", "Dec"
 }
 
---- Return the time offset in seconds between the UTC and given time zone.
--- @param tz	Symbolic or numeric timezone specifier
--- @return		Time offset to UTC in seconds
 function tz_offset(tz)
 
 	if type(tz) == "string" then
@@ -39,9 +35,6 @@ function tz_offset(tz)
 	return 0
 end
 
---- Parse given HTTP date string and convert it to unix epoch time.
--- @param data	String containing the date
--- @return		Unix epoch time
 function to_unix(date)
 
 	local wd, day, mon, yr, hr, min, sec, tz = date:match(
@@ -75,19 +68,10 @@ function to_unix(date)
 	return 0
 end
 
---- Convert the given unix epoch time to valid HTTP date string.
--- @param time	Unix epoch time
--- @return		String containing the formatted date
 function to_http(time)
 	return os.date( "%a, %d %b %Y %H:%M:%S GMT", time )
 end
 
---- Compare two dates which can either be unix epoch times or HTTP date strings.
--- @param d1	The first date or epoch time to compare
--- @param d2	The first date or epoch time to compare
--- @return		-1  -  if d1 is lower then d2
--- @return		0   -  if both dates are equal
--- @return		1   -  if d1 is higher then d2
 function compare(d1, d2)
 
 	if d1:match("[^0-9]") then d1 = to_unix(d1) end
diff --git a/modules/luci-base/luasrc/http/protocol/date.luadoc b/modules/luci-base/luasrc/http/protocol/date.luadoc
new file mode 100644
index 0000000000..d6f1c8d658
--- /dev/null
+++ b/modules/luci-base/luasrc/http/protocol/date.luadoc
@@ -0,0 +1,46 @@
+---[[
+LuCI http protocol implementation - date helper class.
+
+This class contains functions to parse, compare and format http dates.
+]]
+module "luci.http.protocol.date"
+
+---[[
+Return the time offset in seconds between the UTC and given time zone.
+
+@class function
+@name tz_offset
+@param tz	Symbolic or numeric timezone specifier
+@return		Time offset to UTC in seconds
+]]
+
+---[[
+Parse given HTTP date string and convert it to unix epoch time.
+
+@class function
+@name to_unix
+@param data	String containing the date
+@return		Unix epoch time
+]]
+
+---[[
+Convert the given unix epoch time to valid HTTP date string.
+
+@class function
+@name to_http
+@param time	Unix epoch time
+@return		String containing the formatted date
+]]
+
+---[[
+Compare two dates which can either be unix epoch times or HTTP date strings.
+
+@class function
+@name compare
+@param d1	The first date or epoch time to compare
+@param d2	The first date or epoch time to compare
+@return		-1  -  if d1 is lower then d2
+@return		0   -  if both dates are equal
+@return		1   -  if d1 is higher then d2
+]]
+
diff --git a/modules/luci-base/luasrc/http/protocol/mime.lua b/modules/luci-base/luasrc/http/protocol/mime.lua
index 15da15cf8b..2b99d8e74e 100644
--- a/modules/luci-base/luasrc/http/protocol/mime.lua
+++ b/modules/luci-base/luasrc/http/protocol/mime.lua
@@ -1,15 +1,12 @@
 -- Copyright 2008 Freifunk Leipzig / Jo-Philipp Wich <jow@openwrt.org>
 -- Licensed to the public under the Apache License 2.0.
 
---- LuCI http protocol implementation - mime helper class.
 -- This class provides functions to guess mime types from file extensions and
 -- vice versa.
 module("luci.http.protocol.mime", package.seeall)
 
 require("luci.util")
 
---- MIME mapping table containg extension - mimetype relations.
--- @class table
 MIME_TYPES = {
     ["txt"]   = "text/plain";
     ["js"]    = "text/javascript";
@@ -54,10 +51,7 @@ MIME_TYPES = {
     ["avi"]   = "video/x-msvideo";
 }
 
---- Extract extension from a filename and return corresponding mime-type or
 -- "application/octet-stream" if the extension is unknown.
--- @param filename	The filename for which the mime type is guessed
--- @return			String containign the determined mime type
 function to_mime(filename)
 	if type(filename) == "string" then
 		local ext = filename:match("[^%.]+$")
@@ -70,10 +64,7 @@ function to_mime(filename)
 	return "application/octet-stream"
 end
 
---- Return corresponding extension for a given mime type or nil if the
 -- given mime-type is unknown.
--- @param mimetype	The mimetype to retrieve the extension from
--- @return			String with the extension or nil for unknown type
 function to_ext(mimetype)
 	if type(mimetype) == "string" then
 		for ext, type in luci.util.kspairs( MIME_TYPES ) do
diff --git a/modules/luci-base/luasrc/http/protocol/mime.luadoc b/modules/luci-base/luasrc/http/protocol/mime.luadoc
new file mode 100644
index 0000000000..195b5fcc89
--- /dev/null
+++ b/modules/luci-base/luasrc/http/protocol/mime.luadoc
@@ -0,0 +1,34 @@
+---[[
+LuCI http protocol implementation - mime helper class.
+
+This class provides functions to guess mime types from file extensions and
+vice versa.
+]]
+module "luci.http.protocol.mime"
+
+---[[
+MIME mapping table containg extension - mimetype relations.
+
+@class table
+]]
+
+---[[
+Extract extension from a filename and return corresponding mime-type or
+
+"application/octet-stream" if the extension is unknown.
+@class function
+@name to_mime
+@param filename	The filename for which the mime type is guessed
+@return			String containign the determined mime type
+]]
+
+---[[
+Return corresponding extension for a given mime type or nil if the
+
+given mime-type is unknown.
+@class function
+@name to_ext
+@param mimetype	The mimetype to retrieve the extension from
+@return			String with the extension or nil for unknown type
+]]
+