Move inline documentation into separate files.

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

6 files changed, 165 insertions, 56 deletions

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
+]]
+