* luci/libs/http: added inline documentation to luci.http.protocol & friends, fixed...

[project/luci.git] / libs / http / luasrc / http / protocol / date.lua

diff --git a/libs/http/luasrc/http/protocol/date.lua b/libs/http/luasrc/http/protocol/date.lua
index d403604..24da1ba 100644 (file)
--- a/libs/http/luasrc/http/protocol/date.lua
+++ b/libs/http/luasrc/http/protocol/date.lua
@@ -13,6 +13,8 @@ $Id$
 
 ]]--
 
+--- 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)
 
 MONTHS = {
@@ -20,7 +22,9 @@ MONTHS = {
        "Sep", "Oct", "Nov", "Dec"
 }
 
--- This list is stolen from Perl's Time::Timezone
+--- The "TZ" table contains lowercased timezone names associated with their
+-- corresponding time offsets sepcified in seconds.
+-- @class table
 TZ = {
        -- DST zones
        ["brst"]  =   -2*3600;   -- Brazil Summer Time (East Daylight)
@@ -123,8 +127,9 @@ TZ = {
        ["idle"]  =  12*3600;    -- International Date Line East
 }
 
-
--- Find corresponding timezone offset
+--- 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
@@ -148,7 +153,9 @@ function tz_offset(tz)
        return 0
 end
 
--- Convert a HTTP date to unixtime
+--- 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(
@@ -182,12 +189,19 @@ function to_unix(date)
        return 0
 end
 
--- Convert a unixtime to HTTP date
+--- 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
+--- 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