Various improvements as suggested by Bastien Nocera, Zeeshan Ali, and Lennart Poettering

 * Update docstrings, clarify things
 * Change the Seek method's argument name to Offset
 * Use a single property instead loop and repeat as they are mutually exclusive
 * Add an optional DesktopEntry property

3 files changed, 72 insertions, 37 deletions

diff --git a/spec/Player_Node.xml b/spec/Player_Node.xml
index 9a97dd9..49f2f27 100644
--- a/spec/Player_Node.xml
+++ b/spec/Player_Node.xml
@@ -41,7 +41,28 @@
         </tp:docstring>
       </tp:enumvalue>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The playback state.</p>
+        <p>A playback state.</p>
+      </tp:docstring>
+    </tp:enum>
+
+    <tp:enum name="Loop_Status" tp:name-for-bindings="Loop_Status" type="s">
+      <tp:enumvalue suffix="None" value="None">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The playback will stop when there are no more tracks to play</p>
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Track" value="Track">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The current track will start again from the begining once it has finished playing</p>
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Playlist" value="Paylist">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The playback loops through a list of tracks</p>
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A repeat / loop status</p>
       </tp:docstring>
     </tp:enum>
 
@@ -133,7 +154,7 @@
     </method>
 
     <method name="Seek" tp:name-for-bindings="Seek">
-      <arg direction="in" type="x" name="Position" tp:type="Time_In_Us">
+      <arg direction="in" type="x" name="Offset" tp:type="Time_In_Us">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>The number of microseconds to seek forward.</p>
         </tp:docstring>
@@ -204,6 +225,30 @@
       </tp:docstring>
     </property>
 
+    <property name="LoopStatus" type="s" access="readwrite"
+              tp:name-for-bindings="Loop_Status" tp:type="Loop_Status">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The current loop / repeat status</p>
+        <p>May be:
+          <ul>
+            <li>"None" if the playback will stop when there are no more tracks to play</li>
+            <li>"Track" if the current track will start again from the begining once it has finished playing</li>
+            <li>"Playlist" if the playback loops through a list of tracks</li>
+          </ul>
+        </p>
+        <p>
+          When this property changes, the
+          <tp:member-ref>PropertiesChanged</tp:member-ref> signal is emited with
+          the new value.
+        </p>
+        <p>
+          This property is optional, and clients should deal with NotSupported
+          errors gracefully.
+        </p>
+      </tp:docstring>
+    </property>
+
     <property name="Rate" tp:name-for-bindings="Rate" type="d" access="readwrite">
       <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -251,38 +296,6 @@
       </tp:docstring>
     </property>
 
-    <property name="RepeatTrack" tp:name-for-bindings="Repeat_Track" type="b" access="readwrite">
-      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Whether the current track is repeated indefinitely</p>
-        <p>
-          When this property changes, the
-          <tp:member-ref>PropertiesChanged</tp:member-ref> signal is emited with
-          the new value.
-        </p>
-        <p>
-          This property is optional, and clients should deal with NotSupported
-          errors gracefully.
-        </p>
-      </tp:docstring>
-    </property>
-
-    <property name="Loop" tp:name-for-bindings="Loop" type="b" access="readwrite">
-      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Whether the media player is looping over its tracks</p>
-        <p>
-          When this property changes, the
-          <tp:member-ref>PropertiesChanged</tp:member-ref> signal is emited with
-          the new value.
-        </p>
-        <p>
-          This property is optional, and clients should deal with NotSupported
-          errors gracefully.
-        </p>
-      </tp:docstring>
-    </property>
-
     <property name="Shuffle" tp:name-for-bindings="Shuffle" type="b" access="readwrite">
       <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -560,7 +573,6 @@
       </tp:docstring>
     </property>
 
-
     <property name="CanRepeatTrack" tp:name-for-bindings="Can_Repeat_Track" type="b" access="read">
       <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="false"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Root_Node.xml b/spec/Root_Node.xml
index 4195318..174c8b2 100644
--- a/spec/Root_Node.xml
+++ b/spec/Root_Node.xml
@@ -46,6 +46,13 @@
           In this case, the <tp:member-ref>CanQuit</tp:member-ref> property is
           <strong>false</strong> and this method does nothing.
         </p>
+        <p>
+          Note: Media players which can be D-Bus activated, or for which there is
+          no sensibly easy way to terminate a running instance (via the main
+          interface or a notification area icon for example) should allow clients
+          to use this method. Otherwise, it should not be needed.
+        </p>
+        <p>If the media player does not have a UI, this must be implemented</p>
       </tp:docstring>
     </method>
 
@@ -87,10 +94,21 @@
 
     <property name="Identity" type="s" tp:name-for-bindings="Identity" access="read">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A friendly name to identify the media player to users.</p>
+        <p>This should usually match the name found in .desktop files</p>
+        <p>(eg: "VLC media player").</p>
+      </tp:docstring>
+    </property>
+
+    <property name="DesktopEntry" type="s" tp:name-for-bindings="Desktop_Entry" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The basename of an installed .desktop file which complies with the <a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop entry specification</a>,
+        with the ".desktop" extension stripped.</p>
         <p>
-          A friendly name to identify the media player to users
-          (eg: "Totem 2.22.2").
+          Example: The desktop entry file is "/usr/share/applications/vlc.desktop",
+          and this property contains "vlc"
         </p>
+        <p>This property is optional. Clients should handle its absence gracefully</p>
       </tp:docstring>
     </property>
 
diff --git a/spec/all.xml b/spec/all.xml
index 16e389d..f53ec1e 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -62,6 +62,11 @@
       </ul>
 
       <p>
+        This allows clients to list available media players
+        (either already running or which can be activated via D-Bus activation)
+      </p>
+
+      <p>
         In the case where the media player allows multiple instances running
         simultaneously, each additional instance should request a unique bus
         name, adding a dot and a unique identifier (such as a UNIX process