Polish the docstrings

3 files changed, 22 insertions, 15 deletions

diff --git a/spec/Player_Node.xml b/spec/Player_Node.xml
index 1ac9db9..fbd3394 100644
--- a/spec/Player_Node.xml
+++ b/spec/Player_Node.xml
@@ -67,7 +67,7 @@
         <p>Audio volume level</p>
         <ul>
           <li>0.0 means mute.</li>
-          <li>1.0 is a sensible maximum volume level.</li>
+          <li>1.0 is a sensible maximum volume level (ex: 0dB).</li>
         </ul>
       </tp:docstring>
     </tp:simple-type>
diff --git a/spec/TrackList_Node.xml b/spec/TrackList_Node.xml
index 2494d00..db41c06 100644
--- a/spec/TrackList_Node.xml
+++ b/spec/TrackList_Node.xml
@@ -3,7 +3,13 @@
   <interface name="org.mpris.MediaPlayer2.TrackList">
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>Provides access to the track listing of the media player.</p>
+      <p>
+        Provides access to a short list of tracks which were recently played or
+        will be played shortly.
+        For example, it can represent the list of tracks from the same album
+        as the currently playing song or the
+        <a href="http://projects.gnome.org/rhythmbox/">Rhythmbox</a> play queue
+      </p>
       <p>
         Each track in the tracklist has a unique identifier.
         The intention is that this uniquely identifies the track within
@@ -11,27 +17,23 @@
         (a particular music file, say) occurs twice in the track list, each
         occurrence should have a different identifier. If a track is removed
         from the middle of the playlist, it should not affect the track ids
-        of any other tracks in the playlist.
+        of any other tracks in the tracklist.
       </p>
       <p>
         As a result, the traditional track identifiers of URLs and position
-        in the playlist cannot be used. It is recognised that this may pose
-        some difficulties for media player implementations. A potential
-        scheme would be to use the URI and, in the case of duplicates,
-        appending a fragment and a number (eg: the second
-        "file:///home/jim/foo.mp3" occurance could be
-        "file:///home/jim/foo.mp3#2", which will keep this track id even if
-        the first occurance is then removed). Any scheme that satisfies the
-        uniqueness requirements is valid, however, as clients should not
-        make any assumptions about the value of the track id beyond the fact
+        in the playlist cannot be used. Any scheme which satisfies the
+        uniqueness requirements is valid, as clients should not make any
+        assumptions about the value of the track id beyond the fact
         that it is a unique identifier.
       </p>
       <p>
         Note that the (memory and processing) burden of implementing the
         TrackList interface and maintaining unique track ids for the
-        playlist may be mitigated by only exposing part of the playlist when
+        playlist can be mitigated by only exposing a subset of the playlist when
         it is very long (the 20 or so tracks around the currently playing
-        track, for example).
+        track, for example). This is a recommended as the tracklist interface
+        is not designed to enable browsing through a large list of tracks, but
+        rather to provide clients with context about the currently playing track.
       </p>
     </tp:docstring>
 
diff --git a/spec/all.xml b/spec/all.xml
index 86fabd2..bf4534e 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -45,13 +45,18 @@
         interface which aims to provide a common programmatic API
         for controlling media players.
       </p>
+      <p>
+        It provides a mechanism for compliant media players discovery,
+        basic playback and media player state control as well as a tracklist
+        interface which is used to add context to the current item.
+      </p>
     </tp:docstring>
   </tp:section>
 
   <tp:section name="Bus Name Policy">
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>
-        Each media player <strong>must</strong> request an unique bus name
+        Each media player <strong>must</strong> request a unique bus name
         which begins with <b>org.mpris.MediaPlayer2</b>. For example:
       </p>
       <ul>