From acda478ed3c0781301b3502c9a84b68c7b999d13 Mon Sep 17 00:00:00 2001
From: Stein Magnus Jodal <stein.magnus@jodal.no>
Date: Sun, 31 Oct 2010 23:23:40 +0100
Subject: [PATCH] docs: Start splitting controllers into controllers and
 providers

---
 docs/api/backends.rst | 62 +++++++++++++++++++++++++++++++++----------
 1 file changed, 48 insertions(+), 14 deletions(-)

diff --git a/docs/api/backends.rst b/docs/api/backends.rst
index c8a72b4d..92334ab8 100644
--- a/docs/api/backends.rst
+++ b/docs/api/backends.rst
@@ -6,29 +6,43 @@
     :synopsis: Backend API
 
 
-The backend and its controllers
-===============================
+The backend, controller, and provider concepts
+==============================================
 
-.. graph:: backend_relations
+Backend:
+    The backend is mostly for convenience. It is a container that holds
+    references to all the controllers.
+Controllers:
+    Each controller has responsibility for a given part of the backend
+    functionality. Most, but not all, controllers delegates some work to one or
+    more providers. The controllers are responsible for choosing the right
+    provider for any given task based upon i.e. the track's URI.
+Providers:
+    Anything specific to i.e. Spotify integration or local storage is contained
+    in the providers. To integrate with new music sources, you just add new
+    providers.
 
-    backend -- current_playlist
-    backend -- library
-    backend -- playback
-    backend -- stored_playlists
+.. digraph:: backend_relations
 
+    Backend -> "Current\nplaylist\ncontroller"
+    Backend -> "Library\ncontroller"
+    "Library\ncontroller" -> "Library\nproviders"
+    Backend -> "Playback\ncontroller"
+    "Playback\ncontroller" -> "Playback\nproviders"
+    Backend -> "Stored\nplaylists\ncontroller"
+    "Stored\nplaylists\ncontroller" -> "Stored\nplaylist\nproviders"
+    Backend -> Mixer
+
+.. _backend-api:
 
 Backend API
 ===========
 
 .. note::
 
-    Currently this only documents the API that is available for use by
-    frontends like :mod:`mopidy.frontends.mpd`, and not what is required to
-    implement your own backend. :class:`mopidy.backends.base.BaseBackend` and
-    its controllers implements many of these methods in a matter that should be
-    independent of most concrete backend implementations, so you should
-    generally just implement or override a few of these methods yourself to
-    create a new backend with a complete feature set.
+    The backend API is the interface that is used by frontends like
+    :mod:`mopidy.frontends.mpd`. If you want to implement your own backend, see
+    the :ref:`provider-api`.
 
 .. autoclass:: mopidy.backends.base.BaseBackend
     :members:
@@ -82,6 +96,26 @@ Manages the music library, e.g. searching for tracks to be added to a playlist.
     :undoc-members:
 
 
+.. _provider-api:
+
+Provider API
+============
+
+.. note::
+
+    The provider API is the interface that must be implemented when you create
+    a backend. If you are working on a frontend and need to access the backend,
+    see the :ref:`backend-api`.
+
+
+Playback provider
+-----------------
+
+.. autoclass:: mopidy.backends.base.BasePlaybackProvider
+    :members:
+    :undoc-members:
+
+
 Backend implementations
 =======================