Use annotations to indicate optional properties

Also, add in tp:added elements where appropriate to indicate when things
were added to the spec.

5 files changed, 18 insertions, 10 deletions

diff --git a/doc/templates/interface.html b/doc/templates/interface.html
index c6b6062..b990afb 100644
--- a/doc/templates/interface.html
+++ b/doc/templates/interface.html
@@ -94,6 +94,7 @@
        <td>$property.get_flag_summary()</td>
        <td>
         #if $property.is_deprecated: (deprecated)
+        #if $property.is_optional: (optional)
        </td>
       </tr>
       #end for
@@ -416,6 +417,7 @@
      $property.get_added()
      $property.get_changed()
      $property.get_deprecated()
+     $property.get_optional()
 
      #if $property.emits_changed == $property.EMITS_CHANGED_UPDATES
      <div class="annotation emits-changed emits-changed-updates">
diff --git a/spec/Player_Node.xml b/spec/Player_Node.xml
index bd39984..ccb6864 100644
--- a/spec/Player_Node.xml
+++ b/spec/Player_Node.xml
@@ -322,6 +322,7 @@
     <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"/>
+      <annotation name="org.mpris.MediaPlayer2.property.optional" value="true"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The current loop / repeat status</p>
         <p>May be:
@@ -332,10 +333,6 @@
           </ul>
         </p>
         <p>
-          This property is optional, and clients should deal with NotSupported
-          errors gracefully.
-        </p>
-        <p>
           If <tp:member-ref>CanControl</tp:member-ref> is
           <strong>false</strong>, attempting to set this property should have
           no effect and raise an error.
@@ -382,6 +379,7 @@
 
     <property name="Shuffle" tp:name-for-bindings="Shuffle" type="b" access="readwrite">
       <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
+      <annotation name="org.mpris.MediaPlayer2.property.optional" value="true"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>
           A value of <strong>false</strong> indicates that playback is
@@ -389,10 +387,6 @@
           means playback is progressing through a playlist in some other order.
         </p>
         <p>
-          This property is optional, and clients should deal with NotSupported
-          errors gracefully.
-        </p>
-        <p>
           If <tp:member-ref>CanControl</tp:member-ref> is
           <strong>false</strong>, attempting to set this property should have
           no effect and raise an error.
diff --git a/spec/Playlists.xml b/spec/Playlists.xml
index 96c7aa8..7fa3acb 100644
--- a/spec/Playlists.xml
+++ b/spec/Playlists.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Playlists" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   <interface name="org.mpris.MediaPlayer2.Playlists">
+    <tp:added version="2.1" />
     <tp:docstring>
       <p>Provides access to the media player's playlists.</p>
       <p>
diff --git a/spec/Root_Node.xml b/spec/Root_Node.xml
index 26c0028..4a98557 100644
--- a/spec/Root_Node.xml
+++ b/spec/Root_Node.xml
@@ -50,6 +50,8 @@
     </property>
 
     <property name="Fullscreen" type="b" tp:name-for-bindings="Fullscreen" access="readwrite">
+      <tp:added version="2.2" />
+      <annotation name="org.mpris.MediaPlayer2.property.optional" value="true"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Whether the media player is occupying the fullscreen.</p>
         <p>
@@ -72,7 +74,6 @@
           may still be unable to fulfil the request, in which case attempting to set
           this property will have no effect (but should not raise an error).
         </p>
-        <p>This property is optional. Clients should handle its absence gracefully.</p>
         <tp:rationale>
           <p>
             This allows remote control interfaces, such as LIRC or mobile devices like
@@ -83,6 +84,8 @@
     </property>
 
     <property name="CanSetFullscreen" type="b" tp:name-for-bindings="Can_Set_Fullscreen" access="read">
+      <tp:added version="2.2" />
+      <annotation name="org.mpris.MediaPlayer2.property.optional" value="true"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>
           If <strong>false</strong>, attempting to set
@@ -139,6 +142,7 @@
     </property>
 
     <property name="DesktopEntry" type="s" tp:name-for-bindings="Desktop_Entry" access="read">
+      <annotation name="org.mpris.MediaPlayer2.property.optional" value="true"/>
       <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>
@@ -146,7 +150,6 @@
           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/tools/specparser.py b/tools/specparser.py
index d680896..9ea9d41 100644
--- a/tools/specparser.py
+++ b/tools/specparser.py
@@ -638,6 +638,8 @@ class Property(DBusConstruct, Typed):
         else:
             raise UnknownAccess("Unknown access '%s' on %s" % (access, self))
 
+        self.is_optional = (getAnnotationByName(dom, 'org.mpris.MediaPlayer2.property.optional') == 'true')
+
         is_cp = dom.getAttributeNS(XMLNS_TP, 'is-connection-parameter')
         self.is_connection_parameter = is_cp != ''
 
@@ -687,6 +689,12 @@ class Property(DBusConstruct, Typed):
 
         return ', '.join(descriptions)
 
+    def get_optional(self):
+        if self.is_optional:
+            return '<div class="annotation optional">This property is optional.  Clients should handle its absence gracefully.</div>'
+        else:
+            return ''
+
 class AwkwardTelepathyProperty(Typed):
     def get_type_name(self):
         return 'Telepathy Property'