Improve backend API docs

docs/api/backends.rst

@@ -16,6 +16,9 @@ The backend and its controllers
 Backend API
 ===========
 
+.. automodule:: mopidy.backends
+    :synopsis: Backend interface.
+
 .. note::
 
     Currently this only documents the API that is available for use by
@@ -26,8 +29,54 @@ Backend API
     generally just implement or override a few of these methods yourself to
     create a new backend with a complete feature set.
 
-.. automodule:: mopidy.backends
+.. autoclass:: mopidy.backends.BaseBackend
-    :synopsis: Backend interface.
+    :members:
+    :undoc-members:
+
+
+Playback controller
+-------------------
+
+Manages playback, with actions like play, pause, stop, next, previous, and
+seek.
+
+.. autoclass:: mopidy.backends.BasePlaybackController
+    :members:
+    :undoc-members:
+
+
+Mixer controller
+----------------
+
+Manages volume. See :class:`mopidy.mixers.BaseMixer`.
+
+
+Current playlist controller
+---------------------------
+
+Manages everything related to the currently loaded playlist.
+
+.. autoclass:: mopidy.backends.BaseCurrentPlaylistController
+    :members:
+    :undoc-members:
+
+
+Stored playlists controller
+---------------------------
+
+Manages stored playlist.
+
+.. autoclass:: mopidy.backends.BaseStoredPlaylistsController
+    :members:
+    :undoc-members:
+
+
+Library controller
+------------------
+
+Manages the music library, e.g. searching for tracks to be added to a playlist.
+
+.. autoclass:: mopidy.backends.BaseLibraryController
     :members:
     :undoc-members:
 

mopidy/backends/__init__.py

@@ -14,6 +14,15 @@ __all__ = ['BaseBackend', 'BasePlaybackController',
     'BaseLibraryController']
 
 class BaseBackend(object):
+    """
+    :param core_queue: a queue for sending messages to
+        :class:`mopidy.process.CoreProcess`
+    :type core_queue: :class:`multiprocessing.Queue`
+    :param mixer: either a mixer instance, or :class:`None` to use the mixer
+        defined in settings
+    :type mixer: :class:`mopidy.mixers.BaseMixer` or :class:`None`
+    """
+
     def __init__(self, core_queue=None, mixer=None):
         self.core_queue = core_queue
         if mixer is not None:
@@ -22,7 +31,8 @@ class BaseBackend(object):
             self.mixer = get_class(settings.MIXER)()
 
     #: A :class:`multiprocessing.Queue` which can be used by e.g. library
-    #: callbacks to send messages to the core.
+    #: callbacks executing in other threads to send messages to the core
+    #: thread, so that action may be taken in the correct thread.
     core_queue = None
 
     #: The current playlist controller. An instance of
@@ -73,14 +83,17 @@ class BaseCurrentPlaylistController(object):
     """
 
     #: The current playlist version. Integer which is increased every time the
-    #: current playlist is changed. Is not reset before the MPD server is
+    #: current playlist is changed. Is not reset before Mopidy is restarted.
-    #: restarted.
     version = 0
 
     def __init__(self, backend):
         self.backend = backend
         self._playlist = Playlist()
 
+    def destroy(self):
+        """Cleanup after component."""
+        pass
+
     @property
     def playlist(self):
         """The currently loaded :class:`mopidy.models.Playlist`."""
@@ -229,7 +242,7 @@ class BaseCurrentPlaylistController(object):
         self.playlist = self.playlist.with_(tracks=before+shuffled+after)
 
     def destroy(self):
-        """Cleanup after component"""
+        """Cleanup after component."""
         pass
 
 
@@ -242,6 +255,10 @@ class BaseLibraryController(object):
     def __init__(self, backend):
         self.backend = backend
 
+    def destroy(self):
+        """Cleanup after component."""
+        pass
+
     def find_exact(self, field, query):
         """
         Find tracks in the library where ``field`` matches ``query`` exactly.
@@ -285,10 +302,6 @@ class BaseLibraryController(object):
         """
         raise NotImplementedError
 
-    def destroy(self):
-        """Cleanup after component"""
-        pass
-
 
 class BasePlaybackController(object):
     """
@@ -321,9 +334,10 @@ class BasePlaybackController(object):
     random = False
 
     #: :class:`True`
-    #:     The current track is played repeatedly.
+    #:     The current playlist is played repeatedly. To repeat a single track,
+    #:     select both :attr:`repeat` and :attr:`single`.
     #: :class:`False`
-    #:     The current track is played once.
+    #:     The current playlist is played once.
     repeat = False
 
     #: :class:`True`
@@ -340,6 +354,10 @@ class BasePlaybackController(object):
         self._play_time_accumulated = 0
         self._play_time_started = None
 
+    def destroy(self):
+        """Cleanup after component."""
+        pass
+
     @property
     def current_playlist_position(self):
         """The position of the current track in the current playlist."""
@@ -392,8 +410,9 @@ class BasePlaybackController(object):
         """
         The previous :class:`mopidy.models.Track` in the playlist.
 
-        For normal playback this is the previous track in the playlist. If random
+        For normal playback this is the previous track in the playlist. If
-        and/or consume is enabled it should return the current track instead.
+        random and/or consume is enabled it should return the current track
+        instead.
         """
         if self.repeat or self.consume or self.random:
             return self.current_track
@@ -478,7 +497,12 @@ class BasePlaybackController(object):
             self.current_track = None
 
     def new_playlist_loaded_callback(self):
-        """Tell the playback controller that a new playlist has been loaded."""
+        """
+        Tell the playback controller that a new playlist has been loaded.
+
+        Typically called by :class:`mopidy.process.CoreProcess` after a message
+        from a library thread is received.
+        """
         self.current_track = None
         self._first_shuffle = True
         self._shuffled = []
@@ -601,10 +625,6 @@ class BasePlaybackController(object):
     def _stop(self):
         raise NotImplementedError
 
-    def destroy(self):
-        """Cleanup after component"""
-        pass
-
 
 class BaseStoredPlaylistsController(object):
     """
@@ -616,6 +636,10 @@ class BaseStoredPlaylistsController(object):
         self.backend = backend
         self._playlists = []
 
+    def destroy(self):
+        """Cleanup after component."""
+        pass
+
     @property
     def playlists(self):
         """List of :class:`mopidy.models.Playlist`."""
@@ -716,7 +740,3 @@ class BaseStoredPlaylistsController(object):
         :rtype: list of :class:`mopidy.models.Playlist`
         """
         return filter(lambda p: query in p.name, self._playlists)
-
-    def destroy(self):
-        """Cleanup after component"""
-        pass