                                      (fromIntegral $ numerator rate)
                                      (fromIntegral $ denominator rate)
 
-clockIDGetTime :: ClockID
+-- | Get the time of @clockID@.
+clockIDGetTime :: ClockID      -- ^ @clockID@
                -> IO ClockTime
 clockIDGetTime clockID =
     liftM fromIntegral $ withClockID clockID $
         {# call clock_id_get_time #} . castPtr
 
-clockIDWait :: ClockID
-            -> IO (ClockReturn, ClockTimeDiff)
+-- | Perform a blocking wait on @clockID@. The parameter @clockID@
+--   should have been created with 'clockNewSingleShotID' or
+--   'clockNewPeriodicID', and should not been unscheduled with a call
+--   to 'clockIDUnschedule'.
+--   
+--   If second value in the returned pair is not 'Nothing', it will
+--   contain the difference against the clock and the time of
+--   @clockID@ when this method was called. Positive values indicate
+--   how late @clockID@ was relative to the clock. Negative values
+--   indicate how much time was spend waiting on the clock before the
+--   function returned.
+clockIDWait :: ClockID -- ^ @clockID@
+            -> IO (ClockReturn, Maybe ClockTimeDiff)
 clockIDWait clockID =
     alloca $ \jitterPtr ->
-        do result <- withClockID clockID $ \clockIDPtr ->
+        do result <- liftM cToEnum $ withClockID clockID $ \clockIDPtr ->
                          {# call clock_id_wait #} (castPtr clockIDPtr) jitterPtr
-           jitter <- peek jitterPtr
-           return $ (cToEnum result, fromIntegral jitter)
-
-clockIDUnschedule :: ClockID
+           jitter <- let peekJitter = liftM (Just . fromIntegral) $ peek jitterPtr
+                     in case result of
+                          ClockOk -> peekJitter
+                          ClockEarly -> peekJitter
+                          _ -> return Nothing
+           return (result, jitter)
+
+-- | Cancel an outstanding request with @clockID@. After this call,
+--   @clockID@ cannot be used anymore to recieve notifications; you
+--   must create a new 'ClockID'.
+clockIDUnschedule :: ClockID -- ^ @clockID@
                   -> IO ()
 clockIDUnschedule clockID =
     withClockID clockID $ {# call clock_id_unschedule #} . castPtr

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

clockSetCalibration :: ClockClass clock
                    => clock
                    -> ClockTime
                    -> ClockTime
                    -> Ratio ClockTime
                    -> IO ()
clockSetCalibration clock internal external rate =
    {# call clock_set_calibration #} (toClock clock)


{# context lib = "gstreamer" prefix = "gst" #}

-- | Gets the flags set on the clock.
clockGetFlags :: ClockClass clockT
              => clockT          -- ^ @clock@
              -> IO [ClockFlags] -- ^ the flags currently set on the clock
clockGetFlags = mkObjectGetFlags

-- | Sets the given flags on the clock.
clockSetFlags :: ClockClass clockT
              => clockT       -- ^ @clock@
              -> [ClockFlags] -- ^ @flags@ - the flags to be set
              -> IO ()
clockSetFlags = mkObjectSetFlags

-- | Unsets the given flags on the clock.
clockUnsetFlags :: ClockClass clockT
                => clockT       -- ^ @clock@
                -> [ClockFlags] -- ^ @flags@ - the flags to be unset
                -> IO ()
clockUnsetFlags = mkObjectUnsetFlags

-- | 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
