                then liftM (Just . realToFrac) $ peek rSquaredPtr
                else return Nothing
 
+-- | Set @master@ as the master clock for @clock@. The @clock@ will
+--   automatically be calibrated so that 'clockGetTime' reports the
+--   same time as the @master@ clock.
+--   
+--   A clock provider that slaves its clock to a master can get the
+--   current calibration values with 'clockGetCalibration'.
+--   
+--   The @master@ clock can be 'Nothing' in which case @clock@ will
+--   not be slaved any longer. It will, however, continue to report
+--   its time adjusted using the last configured rate and time
+--   offsets.
+--   
+--   Note that if @clock@ does not have the 'ClockFlagCanSetMaster'
+--   flag set, this function will not succeed and return 'False'.
 clockSetMaster :: (ClockClass clock, ClockClass master)
-               => clock
-               -> master
-               -> IO Bool
+               => clock        -- ^ @clock@
+               -> Maybe master -- ^ @master@
+               -> IO Bool      -- ^ 'True' if @clock@ is capable of
+                               --   being slaved to the @master@ clock, otherwise 'False'
 clockSetMaster clock master =
-    liftM toBool $ {# call clock_set_master #} (toClock clock) (toClock master)
-
+    withObject (toClock clock) $ \clockPtr ->
+        maybeWith withObject (liftM toClock $ master) $ \masterPtr ->
+            liftM toBool $ gst_clock_set_master clockPtr masterPtr
+    where
+      _ = {# call clock_set_master #}
+
+-- | Return the master that @clock@ is slaved to, or 'Nothing' if
+--   @clock@ is not slaved.
 clockGetMaster :: ClockClass clock
-               => clock
-               -> IO (Maybe Clock)
+               => clock            -- ^ @clock@
+               -> IO (Maybe Clock) -- ^ the master that @clock@ is slaved to, or 'Nothing'
 clockGetMaster clock =
     {# call clock_get_master #} (toClock clock) >>= maybePeek takeObject
 
+-- | Set the resolution of @clock@. Some clocks have the possibility
+--   to operate with different resolution at the expense of more
+--   resource usage. There is normally no need to change the default
+--   resolution of a clock. The resolution of a clock can only be
+--   changed if the clock has the 'ClockFlagCanSetResolution' flag
+--   set.
 clockSetResolution :: ClockClass clock
                    => clock
                    -> ClockTime

  clockIDWait,
  clockIDUnschedule,
  
  clockTimeout,
  clockWindowSize,
  clockWindowThreshold


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