                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

        {# call clock_set_resolution #} (toClock clock)
                                        (fromIntegral resolution)

clockGetResolution :: ClockClass clock
                   => clock
                   -> IO ClockTime
clockGetResolution clock =
    liftM fromIntegral $
        {# call clock_get_resolution #} (toClock clock)

clockGetTime :: ClockClass clock
             => clock
             -> IO ClockTime
clockGetTime clock =
    liftM fromIntegral $
        {# call clock_get_time #} (toClock clock)

clockNewSingleShotID :: ClockClass clock
                     => clock
                     -> ClockTime
                     -> IO ClockID
clockNewSingleShotID clock time =
    {# call clock_new_single_shot_id #} (toClock clock)
                                        (fromIntegral time) >>=
        takeClockID . castPtr

clockNewPeriodicID :: ClockClass clock
                   => clock
                   -> ClockTime
                   -> ClockTime
                   -> IO ClockID
clockNewPeriodicID clock startTime interval =
    {# call clock_new_periodic_id #} (toClock clock)
                                     (fromIntegral startTime)
                                     (fromIntegral interval) >>=
        takeClockID . castPtr

clockGetInternalTime :: ClockClass clock
                     => clock
                     -> IO ClockTime
clockGetInternalTime clock =
    liftM fromIntegral $
        {# call clock_get_internal_time #} (toClock clock)

clockGetCalibration :: ClockClass clock
                    => clock
                    -> IO (ClockTime, ClockTime, Ratio ClockTime)
clockGetCalibration clock =
    alloca $ \internalPtr ->
        alloca $ \externalPtr ->

                       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)
