 --   messages, as well as any future messages, until the function is
 --   called with @flushing@ set to 'False'.
 busSetFlushing :: BusClass busT
-               => busT
-               -> Bool
+               => busT  -- ^ @bus@ - a 'Bus'
+               -> Bool  -- ^ @flushing@ - the new flushing state
                -> 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

--   caller is responsible for calling 'busRemoveSignalWatch' as many
--   times.
busAddSignalWatch :: BusClass busT
                  => busT
                  -> Priority
                  -> IO ()
busAddSignalWatch bus priority =
    {# call bus_add_signal_watch_full #} (toBus bus) $ fromIntegral priority

-- | Remove the signal watch that was added with 'busAddSignalWatch'.
busRemoveSignalWatch :: BusClass busT
                     => busT
                     -> IO ()
busRemoveSignalWatch =
    {# call bus_remove_signal_watch #} . toBus

--   
--   This function will run a main loop in the default main context
--   while polling.
busPoll :: BusClass busT
        => busT          -- ^ @bus@ - a 'Bus'
        -> [MessageType] -- ^ @events@ - the set of messages to poll for
        -> ClockTimeDiff -- ^ @timeout@ - the time to wait, or -1 to wait indefinitely
        -> IO Message
busPoll bus events timeout =
    {# call bus_poll #} (toBus bus)
                        (fromIntegral $ fromFlags events)
                        (fromIntegral timeout) >>=
        takeMiniObject

-- | A message has been posted on the bus. This signal is emitted from
--   a 'Source' added to the 'MainLoop', and only when it is running.
busMessage :: BusClass busT
           => Signal busT (Message -> IO ())
busMessage =
    Signal $ connect_BOXED__NONE "message" peekMiniObject

