More documentation

[Lucu.git] / Network / HTTP / Lucu / RFC1123DateTime.hs

diff --git a/Network/HTTP/Lucu/RFC1123DateTime.hs b/Network/HTTP/Lucu/RFC1123DateTime.hs
index ad683a9b490478e35bad9dfcc552de544212f2e2..354286fb1d8da0b262d2d1209f23c421bc971b24 100644 (file)
--- a/Network/HTTP/Lucu/RFC1123DateTime.hs
+++ b/Network/HTTP/Lucu/RFC1123DateTime.hs
@@ -1,3 +1,6 @@
+-- |This module parses and prints RFC 1123 Date and Time string.
+-- 
+-- In general you don't have to use this module directly.
 module Network.HTTP.Lucu.RFC1123DateTime
     ( formatRFC1123DateTime
     , formatHTTPDateTime
@@ -16,6 +19,7 @@ import           Text.Printf
 month = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
 week  = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
 
+-- |Format a @CalendarTime@ to RFC 1123 Date and Time string.
 formatRFC1123DateTime :: CalendarTime -> String
 formatRFC1123DateTime time
     = printf "%s, %02d %s %04d %02d:%02d:%02d %s"
@@ -28,11 +32,25 @@ formatRFC1123DateTime time
       (ctSec    time)
       (ctTZName time)
 
-
+-- |Format a @ClockTime@ to HTTP Date and Time. Time zone will be
+-- always UTC but prints as GMT.
 formatHTTPDateTime :: ClockTime -> String
 formatHTTPDateTime = formatRFC1123DateTime . (\cal -> cal { ctTZName = "GMT" }) . toUTCTime
 
-
+-- |Parse an HTTP Date and Time.
+--
+-- Limitation: RFC 2616 (HTTP\/1.1) says we must accept these three
+-- formats:
+--
+-- * @Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123@
+--
+-- * @Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036@
+--
+-- * @Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format@
+--
+-- ...but currently this function only supports the RFC 1123
+-- format. This is a violation of RFC 2616 so this should be fixed
+-- later. What a bother!
 parseHTTPDateTime :: String -> Maybe ClockTime
 parseHTTPDateTime src
     = case parseStr httpDateTime src of