audio: Add docs to signal handler helper

mopidy/audio/actor.py

@@ -46,20 +46,34 @@ PLAYBIN_VIS_FLAGS = PLAYBIN_FLAGS | (1 << 3)
 
 
 class _Signals(object):
+    """Helper for tracking gobject signal registrations"""
     def __init__(self):
         self._ids = {}
 
-    def connect(self, element, event, *args):
+    def connect(self, element, event, func, *args):
+        """Connect a function + args to signal event on an element.
+
+        Each event may only be handled by one callback in this implementation.
+        """
         assert (element, event) not in self._ids
-        self._ids[(element, event)] = element.connect(event, *args)
+        self._ids[(element, event)] = element.connect(event, func, *args)
 
     def disconnect(self, element, event):
+        """Disconnect whatever handler we have for and element+event pair.
+
+        Does nothing it the handler has already been removed.
+        """
         signal_id = self._ids.pop((element, event), None)
         if signal_id is not None:
             element.disconnect(signal_id)
 
+    def clear(self):
+        """Clear all registered signal handlers."""
+        for element, event in self._ids.keys():
+            element.disconnect(self._ids.pop((element, event)))
 
-# TODO: split out mixer as these are too intertwined right now
+
+# TODO: create a player class which replaces the actors internals
 class Audio(pykka.ThreadingActor):
     """
     Audio output through `GStreamer <http://gstreamer.freedesktop.org/>`_.