 
 {# context lib = "gstreamer" prefix = "gst" #}
 
+-- | Gets the flags set on the clock.
 clockGetFlags :: ClockClass clockT
-              => clockT
-              -> IO [ClockFlags]
+              => clockT          -- ^ @clock@
+              -> IO [ClockFlags] -- ^ the flags currently set on the clock
 clockGetFlags = mkObjectGetFlags
 
+-- | Sets the given flags on the clock.
 clockSetFlags :: ClockClass clockT
-              => clockT
-              -> [ClockFlags]
+              => clockT       -- ^ @clock@
+              -> [ClockFlags] -- ^ @flags@ - the flags to be set
               -> IO ()
 clockSetFlags = mkObjectSetFlags
 
+-- | Unsets the given flags on the clock.
 clockUnsetFlags :: ClockClass clockT
-                => clockT
-                -> [ClockFlags]
+                => clockT       -- ^ @clock@
+                -> [ClockFlags] -- ^ @flags@ - the flags to be unset
                 -> IO ()
 clockUnsetFlags = mkObjectUnsetFlags
 
-clockTimeIsValid :: ClockTime
-                 -> Bool
+-- | Returns 'True' if the given 'ClockTime' is valid, and 'False'
+--   otherwise.
+clockTimeIsValid :: ClockTime -- ^ @clockTime@
+                 -> Bool      -- ^ 'True' if @clockTime@ is valid, 'False' otherwise
 clockTimeIsValid = (/= clockTimeNone)
 
+-- | The time master of the master clock and the time slave of the
+--   slave clock are added to the list of observations. If enough
+--   observations are available, a linear regression algorithm is run
+--   on the observations and clock is recalibrated.
+--   
+--   If a calibration is performed, the correlation coefficient of the
+--   interpolation will be returned. A value of 1.0 means the clocks
+--   are in perfect sync. This value can be used to control the
+--   sampling frequency of the master and slave clocks.
 clockAddObservation :: ClockClass clock
                     => clock
                     -> ClockTime

--  available under LGPL Version 2. The documentation included with
--  this library is based on the original GStreamer documentation.
--  
-- | Maintainer  : gtk2hs-devel@lists.sourceforge.net
--   Stability   : alpha
--   Portability : portable (depends on GHC)
module Media.Streaming.GStreamer.Core.Clock (
  
  Clock,
  ClockClass,
  castToClock,
  toClock,
  
  ClockTime,
  clockTimeNone,
  clockTimeIsValid,
  second,
  msecond,
  usecond,
  nsecond,
  
  ClockTimeDiff,
  ClockReturn(..),
  ClockID,
  
  ClockFlags(..),
  clockGetFlags,
  clockSetFlags,
  clockUnsetFlags,
  
  clockAddObservation,
  clockSetMaster,
  clockGetMaster,

                       liftM4 (\a b c d ->
                               (fromIntegral a,
                                fromIntegral b,
                                fromIntegral c % fromIntegral d))
                              (peek internalPtr)
                              (peek externalPtr)
                              (peek rateNumPtr)
                              (peek rateDenomPtr)

-- | Adjusts the rate and time of clock. A rate of @1 % 1@ is the
--   normal speed of the clock. Larger values make the clock go
--   faster.
--   
--   The parameters @internal@ and @external@ specifying that
--   'clockGetTime' should have returned @external@ when the clock had
--   internal time @internal@. The parameter @internal@ should not be
--   in the future; that is, it should be less than the value returned
--   by 'clockGetInternalTime' when this function is called.
--   
--   Subsequent calls to 'clockGetTime' will return clock times
--   computed as follows:
--   
--   > (clock_internal - internal) * rate + external
--   
--   Note that 'clockGetTime' always returns increasing values, so if
--   the clock is moved backwards, 'clockGetTime' will report the
--   previous value until the clock catches up.
clockSetCalibration :: ClockClass clock
                    => clock           -- ^ @clock@
                    -> ClockTime       -- ^ @internal@
                    -> ClockTime       -- ^ @external@
                    -> Ratio ClockTime -- ^ @rate@
                    -> IO ()
clockSetCalibration clock internal external rate =
    {# call clock_set_calibration #} (toClock clock)
