From: PHO <pho@cielonegro.org>
Date: Thu, 18 Mar 2010 04:54:35 +0000 (+0900)
Subject: haddock comments
X-Git-Tag: RELEASE-0.1.0.1~4
X-Git-Url: http://git.cielonegro.org/gitweb.cgi?p=time-http.git;a=commitdiff_plain;h=469170632eee26999634929f964d9cc71e068bf3

haddock comments
---

diff --git a/Data/Time/Asctime.hs b/Data/Time/Asctime.hs
index 0da5305..fd5cca0 100644
--- a/Data/Time/Asctime.hs
+++ b/Data/Time/Asctime.hs
@@ -6,7 +6,7 @@
 --
 -- The exact syntax is as follows:
 --
--- > date-time ::= wday ' ' month ' ' day ' ' time ' ' year
+-- > date-time ::= wday SP month SP day SP time SP year
 -- > wday      ::= "Mon" | "Tue" | "Wed" | "Thu"
 -- >             | "Fri" | "Sat" | "Sun"
 -- > month     ::= "Jan" | "Feb" | "Mar" | "Apr"
diff --git a/Data/Time/HTTP.hs b/Data/Time/HTTP.hs
index 3a3dc3e..9f62806 100644
--- a/Data/Time/HTTP.hs
+++ b/Data/Time/HTTP.hs
@@ -1,3 +1,41 @@
+-- |This module provides functions to parse and format HTTP\/1.1 date
+-- and time formats.
+--
+-- The HTTP\/1.1 specification (RFC 2616) says that HTTP\/1.1 clients
+-- and servers which parse the date value MUST accept all the
+-- following formats, though they MUST only generate the RFC 1123
+-- format for representing HTTP-date values in header fields:
+--
+-- > 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
+--
+-- It also says that all HTTP date\/time stamps MUST be represented in
+-- Greenwich Mean Time (GMT), without exception. For the purposes of
+-- HTTP, GMT is exactly equal to UTC (Coordinated Universal
+-- Time). This is indicated in the first two formats by the inclusion
+-- of @\"GMT\"@ as the three-letter abbreviation for time zone, and
+-- MUST be assumed when reading the asctime format.
+--
+-- > HTTP-date    = rfc1123-date | rfc850-date | asctime-date
+-- > rfc1123-date = wkday "," SP date1 SP time SP "GMT"
+-- > rfc850-date  = weekday "," SP date2 SP time SP "GMT"
+-- > asctime-date = wkday SP date3 SP time SP 4DIGIT
+-- > date1        = 2DIGIT SP month SP 4DIGIT
+-- >                ; day month year (e.g., 02 Jun 1982)
+-- > date2        = 2DIGIT "-" month "-" 2DIGIT
+-- >                ; day-month-year (e.g., 02-Jun-82)
+-- > date3        = month SP ( 2DIGIT | ( SP 1DIGIT ))
+-- >                ; month day (e.g., Jun  2)
+-- > time         = 2DIGIT ":" 2DIGIT ":" 2DIGIT
+-- >                ; 00:00:00 - 23:59:59
+-- > wkday        = "Mon" | "Tue" | "Wed"
+-- >              | "Thu" | "Fri" | "Sat" | "Sun"
+-- > weekday      = "Monday" | "Tuesday" | "Wednesday"
+-- >              | "Thursday" | "Friday" | "Saturday" | "Sunday"
+-- > month        = "Jan" | "Feb" | "Mar" | "Apr"
+-- >              | "May" | "Jun" | "Jul" | "Aug"
+-- >              | "Sep" | "Oct" | "Nov" | "Dec"
 module Data.Time.HTTP
     ( format
     , parse
@@ -10,7 +48,7 @@ import qualified Text.Parsec as P
 import Data.Time
 import Data.Time.HTTP.Parsec
 
-
+-- |Format an 'UTCTime' in RFC 1123 date and time.
 format :: UTCTime -> String
 format utcTime
     = let timeZone  = TimeZone 0 False "GMT"
@@ -18,7 +56,15 @@ format utcTime
       in
         RFC1123.format zonedTime
 
-
+-- |Parse a date and time string in any of RFC 822, RFC 1123, RFC 850
+-- and ANSI C's asctime() formats. When the string can't be parsed, it
+-- returns 'Nothing'.
+--
+-- This function is even more permissive than what HTTP\/1.1
+-- specifies. That is, it accepts 2-digit years in RFC 822, omitted
+-- separator symbols in RFC 850, omitted sec fields, and non-GMT time
+-- zones. I believe this behavior will not cause a problem but you
+-- should know this.
 parse :: String -> Maybe UTCTime
 parse src = case P.parse p "" src of
               Right ut -> Just ut
diff --git a/Data/Time/HTTP/Parsec.hs b/Data/Time/HTTP/Parsec.hs
index 03bd54c..117837e 100644
--- a/Data/Time/HTTP/Parsec.hs
+++ b/Data/Time/HTTP/Parsec.hs
@@ -11,7 +11,8 @@ import Data.Time.RFC733.Parsec
 import Data.Time.Asctime.Parsec
 import Text.Parsec
 
-
+-- |This is a parsec parser for date and time formats allowed in
+-- HTTP\/1.1 (RFC 2616).
 rfc2616DateAndTime :: Stream s m Char => ParsecT s u m UTCTime
 rfc2616DateAndTime
     = choice [ liftM zonedTimeToUTC $ try rfc1123DateAndTime
diff --git a/time-http.cabal b/time-http.cabal
index c703beb..2550adc 100644
--- a/time-http.cabal
+++ b/time-http.cabal
@@ -3,7 +3,7 @@ Version:             0.1
 Synopsis:            Parse and format HTTP/1.1 Date and Time string
 Description:
         This package provides functionalities to parse and format
-        various Date and Time formats allowed by HTTP\/1.1 (RFC 2616).
+        various Date and Time formats allowed in HTTP\/1.1 (RFC 2616).
 
 Homepage:            http://cielonegro.org/HTTPDateTime.html
 License:             PublicDomain