From 8e8a7cd037fbc2c34173960be70d1629339d0a4d Mon Sep 17 00:00:00 2001
From: Thomas Adamcik <adamcik@samfundet.no>
Date: Tue, 3 May 2011 23:41:01 +0200
Subject: [PATCH] Add docstring for BaseOutput

---
 mopidy/outputs/__init__.py | 49 ++++++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 13 deletions(-)

diff --git a/mopidy/outputs/__init__.py b/mopidy/outputs/__init__.py
index 3aac4105..8ff43a5f 100644
--- a/mopidy/outputs/__init__.py
+++ b/mopidy/outputs/__init__.py
@@ -10,45 +10,68 @@ logger = logging.getLogger('mopidy.outputs')
 
 
 class BaseOutput(object):
-    """TODO adamcik"""
+    """Base class for providing support for multiple pluggable outputs."""
 
-    def connect_bin(self, pipeline, element_to_link_to):
+    def connect_bin(self, pipeline, element):
         """
         Connect output bin to pipeline and given element.
+
+        In normal cases the element will probably be a `tee`,
+        thus allowing us to connect any number of outputs. This
+        however is why each bin is forced to have its own `queue`
+        after the `tee`.
+
+        :param pipeline: gst.Pipeline to add output to.
+        :type pipeline: :class:`gst.Pipeline`
+        :param element: gst.Element in pipeline to connect output to.
+        :type element: :class:`gst.Element`
         """
         description = 'queue ! %s' % self.describe_bin()
         logger.debug('Adding new output to tee: %s', description)
 
-        output = self.parse_bin(description)
+        output = gst.parse_bin_from_description(description, True)
         self.modify_bin(output)
 
         pipeline.add(output)
-        output.sync_state_with_parent()
-        gst.element_link_many(element_to_link_to, output)
-
-    def parse_bin(self, description):
-        return gst.parse_bin_from_description(description, True)
+        output.sync_state_with_parent() # Required to add to running pipe
+        gst.element_link_many(element, output)
 
     def modify_bin(self, output):
         """
-        Modifies bin before it is installed if needed
+        Modifies bin before it is installed if needed.
+
+        Overriding this method allows for outputs to modify the constructed bin
+        before it is installed. This can for instance be a good place to call
+        `set_properties` on elements that need to be configured.
         """
         pass
 
     def describe_bin(self):
         """
-        Describe bin to be parsed.
+        Return text string describing bin in gst-launch format.
 
-        Must be implemented by subclasses.
+        For simple cases this can just be a plain sink such as `autoaudiosink`
+        or it can be a chain `element1 ! element2 ! sink`. See `man
+        gst-launch0.10` for details on format.
+
+        *MUST be implemented by subclass.*
         """
         raise NotImplementedError
 
     def set_properties(self, element, properties):
         """
-        Set properties on element if they have a value.
+        Helper to allow for simple setting of properties on elements.
+
+        Will call `set_property` on the element for each key that has a value
+        that is not None.
+
+        :param element: gst.Element to set properties on.
+        :type element: :class:`gst.Element`
+        :param properties: Dictionary of properties to set on element.
+        :type element: dict
         """
         for key, value in properties.items():
-            if value:
+            if value is not None:
                 element.set_property(key, value)