From 996af72af7abc6dbfc409dbf034f0c183ef75c4d Mon Sep 17 00:00:00 2001
From: Thomas Adamcik <thomas@adamcik.no>
Date: Fri, 24 Apr 2015 00:14:22 +0200
Subject: [PATCH] docs: Refresh PlaybackController documentation

---
 docs/api/core.rst       | 54 +++++++++++++++++++++++++++++++++++------
 mopidy/core/playback.py |  6 +++--
 2 files changed, 51 insertions(+), 9 deletions(-)

diff --git a/docs/api/core.rst b/docs/api/core.rst
index f03835e1..e4a4515b 100644
--- a/docs/api/core.rst
+++ b/docs/api/core.rst
@@ -101,14 +101,41 @@ Options
 Playback controller
 ===================
 
-Manages playback, with actions like play, pause, stop, next, previous,
-seek, and volume control.
-
-.. autoclass:: mopidy.core.PlaybackState
-    :members:
-
 .. autoclass:: mopidy.core.PlaybackController
-    :members:
+
+Playback control
+----------------
+
+.. automethod:: mopidy.core.PlaybackController.play
+.. automethod:: mopidy.core.PlaybackController.next
+.. automethod:: mopidy.core.PlaybackController.previous
+.. automethod:: mopidy.core.PlaybackController.stop
+.. automethod:: mopidy.core.PlaybackController.pause
+.. automethod:: mopidy.core.PlaybackController.resume
+.. automethod:: mopidy.core.PlaybackController.seek
+
+Current track
+-------------
+
+.. automethod:: mopidy.core.PlaybackController.get_current_tl_track
+.. automethod:: mopidy.core.PlaybackController.get_current_track
+.. automethod:: mopidy.core.PlaybackController.get_stream_title
+.. automethod:: mopidy.core.PlaybackController.get_time_position
+
+Playback states
+---------------
+
+.. automethod:: mopidy.core.PlaybackController.get_state
+.. automethod:: mopidy.core.PlaybackController.set_state
+
+.. class:: mopidy.core.PlaybackState
+
+  .. attribute:: STOPPED
+    :annotation: = 'stopped'
+  .. attribute:: PLAYING
+    :annotation: = 'playing'
+  .. attribute:: PAUSED
+    :annotation: = 'paused'
 
 History controller
 ==================
@@ -168,3 +195,16 @@ TracklistController
 .. autoattribute:: mopidy.core.TracklistController.random
 .. autoattribute:: mopidy.core.TracklistController.repeat
 .. autoattribute:: mopidy.core.TracklistController.single
+
+PlaylistsController
+-------------------
+
+.. automethod:: mopidy.core.PlaybackController.get_mute
+.. automethod:: mopidy.core.PlaybackController.get_volume
+
+.. autoattribute:: mopidy.core.PlaybackController.current_tl_track
+.. autoattribute:: mopidy.core.PlaybackController.current_track
+.. autoattribute:: mopidy.core.PlaybackController.state
+.. autoattribute:: mopidy.core.PlaybackController.time_position
+.. autoattribute:: mopidy.core.PlaybackController.mute
+.. autoattribute:: mopidy.core.PlaybackController.volume
diff --git a/mopidy/core/playback.py b/mopidy/core/playback.py
index 99deee05..2b1bbbc3 100644
--- a/mopidy/core/playback.py
+++ b/mopidy/core/playback.py
@@ -267,8 +267,10 @@ class PlaybackController(object):
 
     def play(self, tl_track=None, tlid=None):
         """
-        Play the given track, or if the given track is :class:`None`, play the
-        currently active track.
+        Play the given track, or if the given tl_track and tlid is
+        :class:`None`, play the currently active track.
+
+        Note that the track **must** already be in the tracklist.
 
         :param tl_track: track to play
         :type tl_track: :class:`mopidy.models.TlTrack` or :class:`None`