[commit: packages/time] format-widths, improve-leapseconds, master, posix-perf, tasty, wip/travis: more time doc (8cea925)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/time

On branches: format-widths,improve-leapseconds,master,posix-perf,tasty,wip/travis
Link       : http://git.haskell.org/packages/time.git/commitdiff/8cea925e57e0498cab65f7d92e1aef6fc84e1d07

>---------------------------------------------------------------

commit 8cea925e57e0498cab65f7d92e1aef6fc84e1d07
Author: Ashley Yakeley <ashley at semantic.org>
Date:   Sat Aug 6 14:03:50 2005 -0700

    more time doc
    
    darcs-hash:20050806210350-ac6dd-137bddea624190e5df0f8db7b5eaf47662da1d26


>---------------------------------------------------------------

8cea925e57e0498cab65f7d92e1aef6fc84e1d07
 Data/Time/Calendar/ISOWeekDay.hs | 3 ++-
 Data/Time/Calendar/TimeOfDay.hs  | 6 ++++++
 Data/Time/Calendar/Timezone.hs   | 8 +++++++-
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/Data/Time/Calendar/ISOWeekDay.hs b/Data/Time/Calendar/ISOWeekDay.hs
index 0c23495..ea6522b 100644
--- a/Data/Time/Calendar/ISOWeekDay.hs
+++ b/Data/Time/Calendar/ISOWeekDay.hs
@@ -30,7 +30,8 @@ isoWeekDay date@(ModJulianDay mjd) = (y1,fromInteger (w1 + 1),fromInteger (mod d
 			else (y0,w0)
 		else (y0,w0)
 
--- | convert from ISO 8601 Week format. First argument is year, second week number (1-53), third day of week (1 for Monday to 7 for Sunday).
+-- | convert from ISO 8601 Week format. First argument is year, second week number (1-52 or 53), third day of week (1 for Monday to 7 for Sunday).
+-- Invalid week and day values will be clipped to the correct range.
 fromISOWeekDay :: Integer -> Int -> Int -> Date
 fromISOWeekDay y w d = ModJulianDay (k - (mod k 7) + (toInteger (((clip 1 (if longYear then 53 else 52) w) * 7) + (clip 1 7 d))) - 10) where
 		k = getModJulianDay (fromYearAndDay y 6)
diff --git a/Data/Time/Calendar/TimeOfDay.hs b/Data/Time/Calendar/TimeOfDay.hs
index b064048..c8598c2 100644
--- a/Data/Time/Calendar/TimeOfDay.hs
+++ b/Data/Time/Calendar/TimeOfDay.hs
@@ -17,14 +17,20 @@ import Data.Fixed
 
 -- | Time of day as represented in hour, minute and second (with picoseconds), typically used to express local time of day.
 data TimeOfDay = TimeOfDay {
+	-- | range 0 - 23
 	todHour    :: Int,
+	-- | range 0 - 59
 	todMin     :: Int,
+	-- | Note that 0 <= todSec < 61, accomodating leap seconds.
+	-- Any local minute may have a leap second, since leap seconds happen in all zones simultaneously
 	todSec     :: Pico
 } deriving (Eq,Ord)
 
+-- | Hour zero
 midnight :: TimeOfDay
 midnight = TimeOfDay 0 0 0
 
+-- | Hour twelve
 midday :: TimeOfDay
 midday = TimeOfDay 12 0 0
 
diff --git a/Data/Time/Calendar/Timezone.hs b/Data/Time/Calendar/Timezone.hs
index 525b91b..f2b3ea6 100644
--- a/Data/Time/Calendar/Timezone.hs
+++ b/Data/Time/Calendar/Timezone.hs
@@ -18,22 +18,28 @@ import Data.Time.Clock.POSIX
 import Foreign
 import Foreign.C
 
--- | count of minutes
+-- | A Timezone is a whole number of minutes offset from UTC, together with a name and a "just for summer" flag.
 data Timezone = MkTimezone {
+	-- | The number of minutes offset from UTC. Positive means local time will be later in the day than UTC.
 	timezoneMinutes :: Int,
+	-- | Is this time zone just persisting for the summer?
 	timezoneDST :: Bool,
+	-- | The name of the zone, typically a three- or four-letter acronym.
 	timezoneName :: String
 } deriving (Eq,Ord)
 
+-- | Create a nameless non-summer timezone for this number of minutes
 minutesToTimezone :: Int -> Timezone
 minutesToTimezone m = MkTimezone m False ""
 
+-- | Create a nameless non-summer timezone for this number of hours
 hoursToTimezone :: Int -> Timezone
 hoursToTimezone i = minutesToTimezone (60 * i)
 
 showT :: Int -> String
 showT t = (show2 (div t 60)) ++ (show2 (mod t 60))
 
+-- | Text representing the offset of this timezone, such as \"-0800\" or \"+0400\" (like %z in formatTime)
 timezoneOffsetString :: Timezone -> String
 timezoneOffsetString (MkTimezone t _ _) | t < 0 = '-':(showT (negate t))
 timezoneOffsetString (MkTimezone t _ _) = '+':(showT t)