core: Fix comments and docstrings per review comments

mopidy/core/tracklist.py

@@ -209,8 +209,8 @@ def index(self, tl_track=None, tlid=None):
 
         :param tl_track: the track to find the index of
         :type tl_track: :class:`mopidy.models.TlTrack` or :class:`None`
-        :param tlid: of the track to find the index of
-        :type tlid: TLID number or :class:`None`
+        :param tlid: TLID of the track to find the index of
+        :type tlid: :class:`int` or :class:`None`
         :rtype: :class:`int` or :class:`None`
 
         .. versionchanged:: 1.1
@@ -237,9 +237,9 @@ def get_eot_tlid(self):
         """
         The TLID of the track that will be played after the given track.
 
-        Not necessarily the same track as :meth:`get_next_tlid`.
+        Not necessarily the same TLID as returned by :meth:`get_next_tlid`.
 
-        :rtype: TLID or :class:`None`
+        :rtype: :class:`int` or :class:`None`
 
         .. versionadded:: 1.1
         """
@@ -369,8 +369,8 @@ def previous_track(self, tl_track):
         if position in (None, 0):
             return None
 
-        # Note that since we know we are at position 1-n we know this will
-        # never be out bounds for the tl_tracks list.
+        # Since we know we are not at zero we have to be somewhere in the range
+        # 1 - len(tracks) Thus 'position - 1' will always be within the list.
         return self._tl_tracks[position - 1]
 
     def add(self, tracks=None, at_position=None, uri=None, uris=None):

mopidy/utils/deprecation.py

@@ -46,11 +46,13 @@
         'tracklist.remove() with "kwargs" as criteria is deprecated',
 
     'core.tracklist.eot_track':
-        'tracklist.eot_track() is deprecated, use tracklist.get_eot_tlid()',
+        'tracklist.eot_track() is pending deprecation, use '
+        'tracklist.get_eot_tlid()',
     'core.tracklist.next_track':
-        'tracklist.next_track() is deprecated, use tracklist.get_next_tlid()',
+        'tracklist.next_track() is pending deprecation, use '
+        'tracklist.get_next_tlid()',
     'core.tracklist.previous_track':
-        'tracklist.previous_track() is deprecated, use '
+        'tracklist.previous_track() is pending deprecation, use '
         'tracklist.get_previous_tlid()',
 
     'models.immutable.copy':