Remove history doc and write new doc directly in backend based on MPD behavior for next and previous_track

docs/api/history.rst

@@ -1,55 +0,0 @@
-History handling
-================
-
-For correct logical handling of ``previous()`` and ``previous_track`` backends
-will need to keep track of which songs they have played.
-
-Normal playback
-----------------
-
-Each time a new song is played the previous ``current_track`` should be added to
-the history. The ``previous_track`` should always be the most recent history item.
-
-Playback with repeat enabled
------------------------------
-
-History should be handled in same manner as regular playback. ``next_track``
-at end of playlist should loop to first item on playlist.
-
-Playback with random enabled
------------------------------
-
-Each song should only be played once until entire playlist has been played,
-once this has occurred a new random order should be played. History should be
-handled in the same way as regular playback.
-
-A suggested implementation is creating a shuffled copy of the tracks and
-retrieving ``next_track`` from here until it is empty.
-
-Playback with consume enabled
------------------------------
-
-Turning on consume should set history to an empty array, and not add any new
-tracks while it is on. ``previous_track`` should return ``current_track`` to
-match MPD behaviour.
-
-Playback with repeat and random
--------------------------------
-
-Once the shuffled tracks array is empty it should be replaced with a new
-shuffled array of tracks.
-
-Playback with repeat and consume
---------------------------------
-
-Return ``current_track`` for ``previous_track`` to match MPD.
-
-Playback with random and consume
---------------------------------
-
-Return ``current_track`` for ``previous_track`` to match MPD.
-
-Playback with repeat, random and consume
-----------------------------------------
-
-Return ``current_track`` for ``previous_track`` to match MPD.

mopidy/backends/__init__.py

@@ -252,7 +252,14 @@ class BasePlaybackController(object):
 
     @property
     def next_track(self):
-        """The next :class:`mopidy.models.Track` in the playlist."""
+        """
+        The next :class:`mopidy.models.Track` in the playlist.
+
+        For normal playback this is the next track in the playlist. If repeat
+        is enabled the next track can loop around the playlist. When random is
+        enabled this should be a random track, all tracks should be played once
+        before the list repeats.
+        """
         if self.current_track is None:
             return None
         try:
@@ -274,7 +281,12 @@ class BasePlaybackController(object):
 
     @property
     def previous_track(self):
-        """The previous :class:`mopidy.models.Track` in the playlist."""
+        """
+        The previous :class:`mopidy.models.Track` in the playlist.
+
+        For normal playback this is the next track in the playlist. If random
+        and/or consume is enabled it should return the current track instead.
+        """
         if self.current_track is None:
             return None
         try: