From e53e0aa78f5afae7e50d1acbf75123e40613634e Mon Sep 17 00:00:00 2001
From: Stein Magnus Jodal <stein.magnus@jodal.no>
Date: Thu, 19 May 2011 20:51:30 +0200
Subject: [PATCH] Update BaseOutput docs. Make build_bin() private.

---
 mopidy/outputs/__init__.py | 55 +++++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 22 deletions(-)

diff --git a/mopidy/outputs/__init__.py b/mopidy/outputs/__init__.py
index a85088a6..ba242c4b 100644
--- a/mopidy/outputs/__init__.py
+++ b/mopidy/outputs/__init__.py
@@ -7,7 +7,7 @@ import logging
 logger = logging.getLogger('mopidy.outputs')
 
 class BaseOutput(object):
-    """Base class for providing support for multiple pluggable outputs."""
+    """Base class for pluggable audio outputs."""
 
     MESSAGE_EOS = gst.MESSAGE_EOS
     MESSAGE_ERROR = gst.MESSAGE_ERROR
@@ -15,43 +15,49 @@ class BaseOutput(object):
 
     def __init__(self, gstreamer):
         self.gstreamer = gstreamer
-        self.bin = self.build_bin()
+        self.bin = self._build_bin()
         self.bin.set_name(self.get_name())
 
         self.modify_bin()
 
-    def build_bin(self):
-        """
-        Build output bin that will attached to pipeline.
-        """
+    def _build_bin(self):
         description = 'queue ! %s' % self.describe_bin()
         logger.debug('Creating new output: %s', description)
-
         return gst.parse_bin_from_description(description, True)
 
     def connect(self):
-        """Attach output to GStreamer pipeline"""
+        """Attach output to GStreamer pipeline."""
         self.gstreamer.connect_output(self.bin)
         self.on_connect()
 
     def on_connect(self):
-        """Called after output has been connected to GStreamer pipeline"""
+        """
+        Called after output has been connected to GStreamer pipeline.
+
+        *MAY be implemented by subclass.*
+        """
         pass
 
     def remove(self):
-        """Remove output from GStreamer pipeline"""
+        """Remove output from GStreamer pipeline."""
         self.gstreamer.remove_output(self.bin)
         self.on_remove()
 
     def on_remove(self):
-        """Called after output has been remove from GStreamer pipeline"""
+        """
+        Called after output has been removed from GStreamer pipeline.
+
+        *MAY be implemented by subclass.*
+        """
         pass
 
     def get_name(self):
         """
-        Return name of output in gstreamer context.
+        Get name of the output. Defaults to the output's class name.
 
-        Defaults to class name, can be overriden by subclasses if required.
+        *MAY be implemented by subclass.*
+
+        :rtype: string
         """
         return self.__class__.__name__
 
@@ -62,31 +68,36 @@ class BaseOutput(object):
         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.
+
+        *MAY be implemented by subclass.*
         """
         pass
 
     def describe_bin(self):
         """
-        Return text string describing bin in gst-launch format.
+        Return string describing the output bin in :command:`gst-launch`
+        format.
 
-        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.
+        For simple cases this can just be a sink such as ``autoaudiosink``,
+        or it can be a chain like ``element1 ! element2 ! sink``. See the
+        manpage of :command:`gst-launch` for details on the format.
 
         *MUST be implemented by subclass.*
+
+        :rtype: string
         """
         raise NotImplementedError
 
     def set_properties(self, element, properties):
         """
-        Helper to allow for simple setting of properties on elements.
+        Helper method for setting of properties on elements.
 
-        Will call `set_property` on the element for each key that has a value
-        that is not None.
+        Will call :meth:`gst.Element.set_property` on ``element`` for each key
+        in ``properties`` that has a value that is not :class:`None`.
 
-        :param element: gst.Element to set properties on.
+        :param element: element to set properties on
         :type element: :class:`gst.Element`
-        :param properties: Dictionary of properties to set on element.
+        :param properties: properties to set on element
         :type properties: dict
         """
         for key, value in properties.items():