From: PHO <pho@cielonegro.org>
Date: Mon, 15 Mar 2010 08:35:10 +0000 (+0900)
Subject: Haddock comments
X-Git-Tag: RELEASE-0.1.0.1~4
X-Git-Url: https://git.cielonegro.org/gitweb.cgi?a=commitdiff_plain;h=376869bc3a4e7c2e22fb47152ba2d459b82efdd0;p=time-w3c.git

Haddock comments
---

diff --git a/Data/Time/W3C.hs b/Data/Time/W3C.hs
index 5cf1822..8c7346d 100644
--- a/Data/Time/W3C.hs
+++ b/Data/Time/W3C.hs
@@ -1,3 +1,9 @@
+-- | This package provides functionalities to parse and format W3C
+-- Date and Time. The package can also be used to convert it from/to
+-- 'Data.Time.Calendar.Day' and 'Data.Time.LocalTime.ZonedTime'.
+--
+-- See: <http://www.w3.org/TR/NOTE-datetime>
+
 module Data.Time.W3C
     ( W3CDateTime(..)
     , format
diff --git a/Data/Time/W3C/Format.hs b/Data/Time/W3C/Format.hs
index f3f9fac..928032b 100644
--- a/Data/Time/W3C/Format.hs
+++ b/Data/Time/W3C/Format.hs
@@ -1,3 +1,4 @@
+-- | Format W3C Date and Time strings.
 module Data.Time.W3C.Format
     ( format
     )
@@ -9,6 +10,9 @@ import Data.Time
 import Data.Time.W3C.Types
 
 
+-- | Format W3C Date and Time string from anything convertible to
+-- 'W3CDateTime' type. The most obvious acceptable type is the
+-- 'W3CDateTime' itself.
 format :: Convertible t W3CDateTime => t -> String
 format = format' . convert
     where
diff --git a/Data/Time/W3C/Parser.hs b/Data/Time/W3C/Parser.hs
index 8104ce8..5bf2f9e 100644
--- a/Data/Time/W3C/Parser.hs
+++ b/Data/Time/W3C/Parser.hs
@@ -1,3 +1,4 @@
+-- | Parse W3C Date and Time string.
 module Data.Time.W3C.Parser
     ( parse
     )
@@ -9,6 +10,10 @@ import Data.Convertible
 import Data.Time.W3C.Parser.Parsec
 import Data.Time.W3C.Types
 
+-- | Parse W3C Date and Time string to anything convertible from
+-- 'W3CDateTime' type. The most obvious acceptable type is the
+-- 'W3CDateTime' itself. If the given string is ill-formatted, 'parse'
+-- returns 'Prelude.Nothing'.
 parse :: Convertible W3CDateTime t => String -> Maybe t
 parse src = case P.parse p "" src of
               Right w3c -> Just (convert w3c)
diff --git a/Data/Time/W3C/Parser/Parsec.hs b/Data/Time/W3C/Parser/Parsec.hs
index 6b960ac..862430c 100644
--- a/Data/Time/W3C/Parser/Parsec.hs
+++ b/Data/Time/W3C/Parser/Parsec.hs
@@ -1,3 +1,4 @@
+-- | W3C Date and Time parser combinator for "Text.Parsec".
 module Data.Time.W3C.Parser.Parsec
     ( w3cDateTime
     )
@@ -8,7 +9,7 @@ import Data.Time
 import Data.Time.W3C.Types
 import Text.Parsec
 
-
+-- | This is a parser combinator for "Text.Parsec".
 w3cDateTime :: Stream s m Char => ParsecT s u m W3CDateTime
 w3cDateTime = read4 >>= mdhmst
     where
diff --git a/Data/Time/W3C/Types.hs b/Data/Time/W3C/Types.hs
index 3a996cb..c270e36 100644
--- a/Data/Time/W3C/Types.hs
+++ b/Data/Time/W3C/Types.hs
@@ -1,3 +1,4 @@
+-- | Data types defined by this package.
 module Data.Time.W3C.Types
     ( W3CDateTime(..)
     )
@@ -9,8 +10,26 @@ import Data.Time
 import Data.Typeable
 
 
+-- |'W3CDateTime' represents a W3C Date and Time format.
+--
+-- The field 'w3cYear' is mandatory while other fields are
+-- optional. But you should be careful about combinations of such
+-- optional fields. No combinations are allowed except for the
+-- following list:
+--
+--   * YYYY
+--
+--   * YYYY-MM
+--
+--   * YYYY-MM-DD
+--
+--   * YYYY-MM-DDThh:mmTZD
+--
+--   * YYYY-MM-DDThh:mm:ss.sTZD
+--
 -- This data type is /partially ordered/ so we can't make it an
--- instance of Ord (e.g. "2010" and "2010-01" can't be compared).
+-- instance of Ord (e.g. @\"2010\"@ and @\"2010-01\"@ can't be
+-- compared).
 data W3CDateTime
     = W3CDateTime {
         w3cYear     :: !Integer
diff --git a/time-w3c.cabal b/time-w3c.cabal
index dabe6dd..69c0ee7 100644
--- a/time-w3c.cabal
+++ b/time-w3c.cabal
@@ -2,11 +2,13 @@ Name:                time-w3c
 Version:             0.1
 Synopsis:            Parse, format and convert W3C Date and Time
 Description:
-        This module provides functionalities to parse and format W3C
-        Date and Time. The module can also be used to convert it
+        This package provides functionalities to parse and format W3C
+        Date and Time. The package can also be used to convert it
         from/to 'Data.Time.Calendar.Day' and
         'Data.Time.LocalTime.ZonedTime'.
 
+        See: <http://www.w3.org/TR/NOTE-datetime>
+
 License:             PublicDomain
 License-file:        COPYING
 Author:              PHO <pho AT cielonegro DOT org>