[commit: packages/time] format-widths, master, tasty: haddock for Data.Time.Clock.System (2a35a49)

[git at git.haskell.org]

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

On branches: format-widths,master,tasty
Link       : http://git.haskell.org/packages/time.git/commitdiff/2a35a490ea93a83d40ca0ff58c76435b11602e14

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

commit 2a35a490ea93a83d40ca0ff58c76435b11602e14
Author: Ashley Yakeley <ashley at yakeley.org>
Date:   Sun Jan 15 14:01:59 2017 -0800

    haddock for Data.Time.Clock.System


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

2a35a490ea93a83d40ca0ff58c76435b11602e14
 lib/Data/Time/Clock/Internal/SystemTime.hs | 2 +-
 lib/Data/Time/Clock/System.hs              | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/lib/Data/Time/Clock/Internal/SystemTime.hs b/lib/Data/Time/Clock/Internal/SystemTime.hs
index 840e207..75af1fa 100644
--- a/lib/Data/Time/Clock/Internal/SystemTime.hs
+++ b/lib/Data/Time/Clock/Internal/SystemTime.hs
@@ -27,7 +27,7 @@ import Foreign.C.Types (CLong(..))
 --------------------------------------------------------------------------------
 
 -- | 'SystemTime' is time returned by system clock functions.
--- Its semantics depends on the clock function.
+-- Its semantics depends on the clock function, but the epoch is typically the beginning of 1970.
 -- Note that 'systemNanoseconds' of 1E9 to 2E9-1 can be used to represent leap seconds.
 data SystemTime = MkSystemTime
     { systemSeconds ::     {-# UNPACK #-} !Int64
diff --git a/lib/Data/Time/Clock/System.hs b/lib/Data/Time/Clock/System.hs
index a9664bc..6b41e2d 100644
--- a/lib/Data/Time/Clock/System.hs
+++ b/lib/Data/Time/Clock/System.hs
@@ -17,10 +17,13 @@ import Data.Time.Calendar.Days
 import Data.Int (Int64)
 
 
+-- | Map leap-second values to the start of the following second.
+-- The resulting 'systemNanoseconds' will always be in the range 0 to 1E9-1.
 truncateSystemTimeLeapSecond :: SystemTime -> SystemTime
 truncateSystemTimeLeapSecond (MkSystemTime seconds nanoseconds) | nanoseconds >= 1000000000 = MkSystemTime (succ seconds) 0
 truncateSystemTimeLeapSecond t = t
 
+-- | Convert 'SystemTime' to 'UTCTime', matching zero 'SystemTime' to midnight of 'systemEpochDay' UTC.
 systemToUTCTime :: SystemTime -> UTCTime
 systemToUTCTime (MkSystemTime seconds nanoseconds) = let
     days :: Int64
@@ -40,6 +43,7 @@ systemToUTCTime (MkSystemTime seconds nanoseconds) = let
     time = picosecondsToDiffTime $ fromIntegral timePicoseconds
     in UTCTime day time
 
+-- | Convert 'UTCTime' to 'SystemTime', matching zero 'SystemTime' to midnight of 'systemEpochDay' UTC.
 utcToSystemTime :: UTCTime -> SystemTime
 utcToSystemTime (UTCTime day time) = let
     days :: Int64
@@ -63,11 +67,13 @@ utcToSystemTime (UTCTime day time) = let
 systemEpochAbsolute :: AbsoluteTime
 systemEpochAbsolute = taiNominalDayStart systemEpochDay
 
+-- | Convert 'SystemTime' to 'AbsoluteTime', matching zero 'SystemTime' to midnight of 'systemEpochDay' TAI.
 systemToTAITime :: SystemTime -> AbsoluteTime
 systemToTAITime (MkSystemTime s ns) = let
     diff :: DiffTime
     diff = (fromIntegral s) + (fromIntegral ns) * 1E-9
     in addAbsoluteTime diff systemEpochAbsolute
 
+-- | The day of the epoch of 'SystemTime', 1970-01-01
 systemEpochDay :: Day
 systemEpochDay = ModifiedJulianDay 40587