 --   If the time given is 'Nothing', the function will wait forever.
 --   If the time given is @0@, the function will behave like 'busPop'.
 busTimedPop :: BusClass busT
-            => busT
-            -> Maybe ClockTime
-            -> IO (Maybe Message)
+            => busT               -- ^ @bus@ - a 'Bus'
+            -> Maybe ClockTime    -- ^ @timeoutM@ - the time to wait for,
+                                  --   or 'Nothing' to wait forever
+            -> IO (Maybe Message) -- ^ the first message recieved, or
+                                  --   'Nothing' if the timeout has expired
 busTimedPop bus timeoutM =
     let timeout = case timeoutM of
                     Just timeout' -> timeout'

--   messages, as well as any future messages, until the function is
--   called with @flushing@ set to 'False'.
busSetFlushing :: BusClass busT
               => busT
               -> Bool
               -> IO ()
busSetFlushing bus flushing =
    {# call bus_set_flushing #} (toBus bus) $ fromBool flushing

-- these will leak memory, maybe one day we can set a destroy notifier...

type CBusSyncHandler =  Ptr Bus
                     -> Ptr Message

--   
--   The watch can be removed by calling 'System.Glib.MainLoop.sourceRemove'.
busAddWatch :: BusClass busT
            => busT         -- ^ @bus@ - a 'Bus'
            -> Priority     -- ^ @priority@ - the priority of the watch
            -> BusFunc      -- ^ @func@ - the action to perform when a message is recieved
            -> IO HandlerId -- ^ the event source ID
busAddWatch bus priority func =
    do busFuncPtr <- marshalBusFunc func
       destroyNotify <- mkFunPtrDestroyNotify busFuncPtr
