Merge branch 'master' into playlists

9 files changed, 154 insertions, 203 deletions

diff --git a/doc/templates/devhelp.devhelp2 b/doc/templates/devhelp.devhelp2
index 8bbdb3a..798a8c2 100644
--- a/doc/templates/devhelp.devhelp2
+++ b/doc/templates/devhelp.devhelp2
@@ -8,9 +8,11 @@
  </chapters>
  <functions>
 #for $obj in $spec.everything.values() + $spec.types.values() + $spec.errors.values()
-  <keyword type="$obj.devhelp_name" name="$obj.get_title()" link="$obj.get_url()" #slurp
+#for $entry in $obj.get_index_entries()
+  <keyword type="$obj.devhelp_name" name="$entry" link="$obj.get_url()" #slurp
 #if $obj.deprecated: deprecated="true" #slurp
 />
 #end for
+#end for
  </functions>
 </book>
diff --git a/doc/templates/index.html b/doc/templates/index.html
index 4e44f31..a749f6f 100644
--- a/doc/templates/index.html
+++ b/doc/templates/index.html
@@ -15,14 +15,16 @@
 
   <div class="main">
   <h3 class="version">Version $spec.version</h3>
-  <p class="copyrights">
-   #echo '<br/>'.join($spec.copyrights)
-  </p>
-
-  <div class="license">
-    #for $para in $spec.license
-    <p>$para</p>
+  <div class="legal">
+   <ul class="copyrights">
+    #for c in $spec.copyrights
+    <li>$c</li>
     #end for
+   </ul>
+
+   #for $para in $spec.license
+   <p>$para</p>
+   #end for
   </div>
 
   #def output($items, $external_ul)
diff --git a/doc/templates/interface.html b/doc/templates/interface.html
index 222057c..3420ce8 100644
--- a/doc/templates/interface.html
+++ b/doc/templates/interface.html
@@ -82,6 +82,7 @@
         #if $property.type: (<a href="$property.get_type_url()" title="$property.get_type_title()">$property.get_type().short_name</a>)
        </td>
        <td>$property.get_access()</td>
+       <td>$property.get_flag_summary()</td>
        <td>
         #if $property.deprecated: (deprecated)
        </td>
@@ -160,7 +161,7 @@
    #end if
 
    #if $interface.causes_havoc
-   <div class="havoc"><span class="warning">WARNING:</span>
+   <div class="annotation havoc"><span class="warning">WARNING:</span>
     This interface is $interface.causes_havoc and is likely to cause havoc
     to your API/ABI if bindings are generated. Do not include this interface
     in libraries that care about compatibility.
@@ -170,10 +171,16 @@
    $interface.get_changed()
    $interface.get_deprecated()
 
-   #if $interface.requires
+   #if $interface.requires or $interface.xor_requires
    <div class="requires">
     Objects implementing this interface must also implement:
     <ul>
+    #for $req in $interface.get_xor_requires()
+     <li>
+      #echo " <strong>or</strong> ".join(['<a href="' + x.get_url() + '''"
+             title="''' + x.get_title() + '">' + x.name + '</a>' for x in req])
+     </li>
+    #end for
     #for $req in $interface.get_requires()
      <li><a href="$req.get_url()" title="$req.get_title()">$req.name</a></li>
     #end for
@@ -193,13 +200,14 @@
     <h1>Methods</h1>
     #for $method in $interface.methods
     <div class="inset method">
-     <a name="$method.name"></a>
+     <a name="$method.get_anchor()"></a>
      <span class="permalink">(<a href="$method.get_url()">Permalink</a>)</span>
      <h2>$method.short_name ($method.get_in_args()) &#8594; $method.get_out_args()</h2>
 
      $method.get_added()
      $method.get_changed()
      $method.get_deprecated()
+     $method.get_no_reply()
 
      #if $method.in_args
      <div class="indent">
@@ -265,7 +273,7 @@
     <h1>Signals</h1>
     #for $signal in $interface.signals
     <div class="inset signal">
-     <a name="$signal.name"></a>
+     <a name="$signal.get_anchor()"></a>
      <span class="permalink">(<a href="$signal.get_url()">Permalink</a>)</span>
      <h2>$signal.short_name ($signal.get_args())</h2>
 
@@ -302,11 +310,13 @@
     <a name="properties"></a>
     <h1>Properties</h1>
     <div>
-     Accessed using the org.freedesktop.DBus.Properties interface.
+     Accessed using the <a
+       href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</a>
+     interface.
     </div>
     #for $property in $interface.properties
     <div class="inset property">
-     <a name="$property.name"></a>
+     <a name="$property.get_anchor()"></a>
      <span class="permalink">(<a href="$property.get_url()">Permalink</a>)</span>
      <h2>
       $property.short_name &mdash; $property.dbus_type
@@ -317,86 +327,13 @@
      $property.get_added()
      $property.get_changed()
      $property.get_deprecated()
+     $property.get_emits_changed()
      $property.get_docstring()
     </div>
     #end for
    </div>
    #end if
 
-   #if $interface.tpproperties
-   <div class="outset tpproperties tpproperty">
-    <a name="tpproperties"></a>
-    <h1>Telepathy Properties</h1>
-    <div>
-     Accessed using the org.freedesktop.Telepathy.Properties interface.
-    </div>
-    #for $property in $interface.tpproperties
-    <div class="inset tpproperty">
-     <a name="$property.name"></a>
-     <span class="permalink">(<a href="$property.get_url()">Permalink</a>)</span>
-     <h2>
-      $property.short_name &mdash; $property.dbus_type
-      #if $property.type: (<a href="$property.get_type_url()" title="$property.get_type_title()">$property.get_type().short_name</a>)
-     </h2>
-     $property.get_added()
-     $property.get_changed()
-     $property.get_deprecated()
-     $property.get_docstring()
-    </div>
-    #end for
-   </div>
-   #end if
-
-   #if $interface.contact_attributes
-   <div class="outset contact-attributes">
-    <a name="contact-attributes"></a>
-    <h1>Contact Attributes</h1>
-    <div>
-      Attributes that a contact can have, accessed with the
-      org.freedesktop.Telepathy.Connection.Interface.Contacts interface.
-    </div>
-    #for $token in $interface.contact_attributes
-    <div class="inset contact-attribute">
-     <a name="$token.name"></a>
-     <span class="permalink">(<a href="$token.get_url()">Permalink</a>)</span>
-     <h2>
-      $token.name &mdash; $token.dbus_type
-      #if $token.type: (<a href="$token.get_type_url()" title="$token.get_type_title()">$token.get_type().short_name</a>)
-     </h2>
-     $token.get_added()
-     $token.get_changed()
-     $token.get_deprecated()
-     $token.get_docstring()
-    </div>
-    #end for
-   </div>
-   #end if
-
-   #if $interface.handler_capability_tokens
-   <div class="outset handler-capability-tokens">
-    <a name="handler-capability-tokens"></a>
-    <h1>Handler Capability Tokens</h1>
-    <div>
-      Tokens representing capabilities that a Client.Handler can have.
-    </div>
-    #for $token in $interface.handler_capability_tokens
-    <div class="inset handler-capability-token">
-     <a name="$token.name"></a>
-     <span class="permalink">(<a href="$token.get_url()">Permalink</a>)</span>
-     <h2>
-      $token.name
-      #if $token.is_family
-      (etc.)
-      #end if
-     </h2>
-     $token.get_added()
-     $token.get_changed()
-     $token.get_deprecated()
-     $token.get_docstring()
-    </div>
-    #end for
-   </div>
-   #end if
 
    #if $interface.types
    <div class="outset types type">
@@ -404,7 +341,7 @@
     <h1>Types</h1>
     #for $type in $interface.types
      <div class="inset type">
-      <a name="$type.name"></a>
+      <a name="$type.get_anchor()"></a>
       <span class="permalink">$type.get_type_name() (<a href="$type.get_url()">Permalink</a>)</span>
       <h2>
        $type.short_name &mdash; $type.dbus_type
diff --git a/doc/templates/oldspec.html b/doc/templates/oldspec.html
deleted file mode 100644
index fc3cf89..0000000
--- a/doc/templates/oldspec.html
+++ /dev/null
@@ -1,11 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <meta http-equiv="refresh" content="0; URL=spec/index.html" />
-    <title>MPRIS D-Bus Interface Specification</title>
-  </head>
-  <body>
-    <h1 class="topbox">MPRIS D-Bus Interface Specification</h1>
-    <p><a href="spec/index.html">The MPRIS specification has moved.</a></p>
-  </body>
-</html>
diff --git a/doc/templates/style.css b/doc/templates/style.css
index 2cc644d..a02d743 100644
--- a/doc/templates/style.css
+++ b/doc/templates/style.css
@@ -141,12 +141,18 @@ div.access {
 	margin-left: 1ex;
 }
 
-div.summary {
+div.summary, div.legal {
 	padding: 0.5ex;
 	background-color: #eeeeec;
 	border: 1px solid #d3d7cf;
 }
 
+div.legal ul {
+	list-style: none;
+	padding-left: 0;
+	margin-left: 0;
+}
+
 table.summary {
 	margin: 1ex;
 	font-size: small;
@@ -177,39 +183,65 @@ div.docstring {
 	margin: 1ex;
 }
 
-div.added {
-	border-left: 2px solid #4e9a06;
+div.annotation {
+	border-left: 2px solid;
 	margin: 1ex;
 	padding-left: 1ex;
 }
 
+div.annotation span.version, span.warning, span.note {
+	font-weight: bold;
+}
+
+div.added {
+	border-left-color: #4e9a06;
+}
+
 div.added span.version {
 	color: #4e9a06;
-	font-weight: bold;
 }
 
 div.changed {
-	border-left: 2px solid #8f5902;
-	margin: 1ex;
-	padding-left: 1ex;
+	border-left-color: #8f5902;
 }
 
 div.changed span.version {
 	color: #8f5902;
-	font-weight: bold;
 }
 
 div.deprecated,
 div.havoc {
-	border-left: 2px solid #a40000;
-	margin: 1ex;
-	padding-left: 1ex;
+	border-left-color: #a40000;
 }
 
 div.deprecated span.version,
+div.deprecated.no-version,
 span.warning {
 	color: #a40000;
-	font-weight: bold;
+}
+
+div.connection-parameter {
+	border-left-color: #0000a4;
+}
+
+div.connection-parameter .note {
+	color: #0000a4;
+}
+
+div.emits-changed {
+	border-left-color: #17BBC3;
+}
+
+div.immutable {
+	border-left-color: #02598f;
+}
+
+div.no-reply {
+	border-left-color: #9C11A1;
+}
+
+div.requestable {
+	border-left-color: #598f02;
 }
 
 div.rationale {
@@ -296,14 +328,6 @@ h3.chapter {
 	font-weight: bold;
 }
 
-div.license {
-	border: 1px solid black;
-	background: #ddd;
-	padding: 1em;
-	margin-top: 1em;
-	margin-bottom: 1em;
-}
-
 div.main {
 	margin-bottom: 3em;
 }
diff --git a/spec/Player_Node.xml b/spec/Player_Node.xml
index 4daa00c..06ba4f2 100644
--- a/spec/Player_Node.xml
+++ b/spec/Player_Node.xml
@@ -304,11 +304,6 @@
         <p>
           May be "Playing", "Paused" or "Stopped".
         </p>
-        <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
       </tp:docstring>
     </property>
 
@@ -325,11 +320,6 @@
           </ul>
         </p>
         <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
-        <p>
           This property is optional, and clients should deal with NotSupported
           errors gracefully.
         </p>
@@ -368,11 +358,6 @@
           Clients are recommended to only use sensible fractions or multiples
           of 1 (eg: 0.5, 0.25, 1.5, 2.0, etc).
         </p>
-        <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
         <tp:rationale>
           <p>
             This allows clients to display (reasonably) accurate progress bars
@@ -392,11 +377,6 @@
           means playback is progressing through a playlist in some other order.
         </p>
         <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
-        <p>
           This property is optional, and clients should deal with NotSupported
           errors gracefully.
         </p>
@@ -420,11 +400,6 @@
         <p>
           See the type documentation for more details.
         </p>
-        <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
       </tp:docstring>
     </property>
 
@@ -441,11 +416,6 @@
           <strong>false</strong>, attempting to set this property should have
           no effect and raise an error.
         </p>
-        <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
       </tp:docstring>
     </property>
 
@@ -468,10 +438,6 @@
             <tp:member-ref>Rate</tp:member-ref> property, the
             <tp:member-ref>Seeked</tp:member-ref> signal is emited.
           </p>
-          <p>
-            The <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-            is <strong>not</strong> emited when this property changes.
-          </p>
         </tp:docstring>
     </property>
 
@@ -490,11 +456,6 @@
           to 0.0.
         </p>
         <p>This value should always be 1.0 or less.</p>
-        <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
       </tp:docstring>
     </property>
 
@@ -510,11 +471,6 @@
         <p>
           This value should always be 1.0 or greater.
         </p>
-        <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
       </tp:docstring>
     </property>
 
@@ -526,11 +482,6 @@
           method on this interface and expect the current track to change.
         </p>
         <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
-        <p>
           If <tp:member-ref>CanControl</tp:member-ref> is
           <strong>false</strong>, this property should also be
           <strong>false</strong>.
@@ -558,11 +509,6 @@
           expect the current track to change.
         </p>
         <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
-        <p>
           If <tp:member-ref>CanControl</tp:member-ref> is
           <strong>false</strong>, this property should also be
           <strong>false</strong>.
@@ -597,11 +543,6 @@
           this should be <strong>true</strong>.
         </p>
         <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
-        <p>
           If <tp:member-ref>CanControl</tp:member-ref> is
           <strong>false</strong>, this property should also be
           <strong>false</strong>.
@@ -631,11 +572,6 @@
           this should be <strong>true</strong>.
         </p>
         <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
-        <p>
           If <tp:member-ref>CanControl</tp:member-ref> is
           <strong>false</strong>, this property should also be
           <strong>false</strong>.
@@ -659,11 +595,6 @@
           different tracks.
         </p>
         <p>
-          When this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited with the new value.
-        </p>
-        <p>
           If <tp:member-ref>CanControl</tp:member-ref> is
           <strong>false</strong>, this property should also be
           <strong>false</strong>.
diff --git a/spec/Root_Node.xml b/spec/Root_Node.xml
index b9ca580..191acaa 100644
--- a/spec/Root_Node.xml
+++ b/spec/Root_Node.xml
@@ -3,12 +3,6 @@
   <interface name="org.mpris.MediaPlayer2">
     <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
 
-    <tp:docstring>
-      Every time the value of this interface's properties changes, the
-      <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-      signal is emited with the new values.
-    </tp:docstring>
-
     <method name="Raise" tp:name-for-bindings="Raise">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>
diff --git a/spec/TrackList_Node.xml b/spec/TrackList_Node.xml
index 82079b4..4663ae2 100644
--- a/spec/TrackList_Node.xml
+++ b/spec/TrackList_Node.xml
@@ -229,11 +229,6 @@
           <tp:member-ref>RemoveTrack</tp:member-ref> will have no effect,
           and may raise a NotSupported error.
         </p>
-        <p>
-          Every time this property changes, the
-          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-          signal is emited.
-        </p>
       </tp:docstring>
     </property>
 
diff --git a/tools/specparser.py b/tools/specparser.py
index d4eab19..37ded16 100644
--- a/tools/specparser.py
+++ b/tools/specparser.py
@@ -75,6 +75,13 @@ def getChildrenByName(dom, namespace, name):
                             n.localName == name,
                   dom.childNodes)
 
+def getChildrenByNameAndAttribute(dom, namespace, name, attribute, value):
+    return filter(lambda n: n.nodeType == n.ELEMENT_NODE and \
+                            n.namespaceURI == namespace and \
+                            n.localName == name and \
+                            n.getAttribute(attribute) == value,
+                  dom.childNodes)
+
 def getOnlyChildByName(dom, namespace, name):
     kids = getChildrenByName(dom, namespace, name)
 
@@ -88,6 +95,19 @@ def getOnlyChildByName(dom, namespace, name):
 
     return kids[0]
 
+def getAnnotationByName(dom, name):
+    kids = getChildrenByNameAndAttribute(dom, None, 'annotation', 'name', name)
+
+    if len(kids) == 0:
+        return None
+
+    if len(kids) > 1:
+        raise WrongNumberOfChildren(
+            '<%s> node should have at most one %s annotation' %
+            (dom.tagName, name))
+
+    return kids[0].getAttribute('value')
+
 def getNamespace(n):
     if n.namespaceURI is not None:
         return n.namespaceURI
@@ -142,6 +162,9 @@ class Base(object):
         self.docstring = getOnlyChildByName(dom, XMLNS_TP, 'docstring')
         self.added = getOnlyChildByName(dom, XMLNS_TP, 'added')
         self.deprecated = getOnlyChildByName(dom, XMLNS_TP, 'deprecated')
+        self.is_deprecated = True
+        if self.deprecated == None:
+            self.is_deprecated = getAnnotationByName(dom, 'org.freedesktop.DBus.Deprecated') == 'true'
 
         self.changed = getChildrenByName(dom, XMLNS_TP, 'changed')
 
@@ -211,8 +234,14 @@ class Base(object):
                                           "Added in %s.")
 
     def get_deprecated(self):
-        return self._get_generic_with_ver(self.deprecated, 'deprecated',
-                                          "Deprecated since %s.")
+        if self.deprecated is None:
+            if self.is_deprecated:
+                return '<div class="annotation deprecated no-version">Deprecated.</div>'
+            else:
+                return ''
+        else:
+            return self._get_generic_with_ver(self.deprecated, 'deprecated',
+                                              "Deprecated since %s.")
 
     def get_changed(self):
         return '\n'.join(map(lambda n:
@@ -480,6 +509,8 @@ class Method(DBusConstruct):
         self.possible_errors = build_list(self, PossibleError, None,
                         dom.getElementsByTagNameNS(XMLNS_TP, 'error'))
 
+        self.no_reply = getAnnotationByName(dom, 'org.freedesktop.DBus.Method.NoReply') == 'true'
+
     def get_in_args(self):
         return ', '.join(map(lambda a: a.spec_name(), self.in_args))
 
@@ -489,6 +520,13 @@ class Method(DBusConstruct):
         else:
             return 'nothing'
 
+    def get_no_reply(self):
+        if self.no_reply:
+            return '<div class="annotation no-reply">' \
+                   'The caller should not expect a reply when calling this method.</div>'
+        else:
+            return ''
+
     def check_consistency(self):
         for x in self.in_args:
             x.check_consistency()
@@ -557,6 +595,11 @@ class Property(DBusConstruct, Typed):
 
     ACCESS_READWRITE = ACCESS_READ | ACCESS_WRITE
 
+    EMITS_CHANGED_UNKNOWN     = 0
+    EMITS_CHANGED_NONE        = 1
+    EMITS_CHANGED_UPDATES     = 2
+    EMITS_CHANGED_INVALIDATES = 3
+
     def __init__(self, parent, namespace, dom):
         super(Property, self).__init__(parent, namespace, dom)
 
@@ -581,6 +624,21 @@ class Property(DBusConstruct, Typed):
         self.requestable = requestable != ''
         self.sometimes_requestable = requestable == 'sometimes'
 
+        # According to the D-Bus specification, EmitsChangedSignal defaults
+        # to true, but - realistically - this cannot be assumed for old specs.
+        # As a result, we treat the absence of the annotation as "unknown".
+        emits_changed = getAnnotationByName(dom, 'org.freedesktop.DBus.Property.EmitsChangedSignal')
+        if emits_changed is None:
+            emits_changed = getAnnotationByName(dom.parentNode, 'org.freedesktop.DBus.Property.EmitsChangedSignal')
+        if emits_changed == 'true':
+            self.emits_changed = self.EMITS_CHANGED_UPDATES;
+        elif emits_changed == 'invalidates':
+            self.emits_changed = self.EMITS_CHANGED_INVALIDATES;
+        elif emits_changed == 'false':
+            self.emits_changed = self.EMITS_CHANGED_NONE;
+        else:
+            self.emits_changed = self.EMITS_CHANGED_UNKNOWN;
+
     def get_access(self):
         if self.access & self.ACCESS_READ and self.access & self.ACCESS_WRITE:
             return 'Read/Write'
@@ -604,6 +662,25 @@ class Property(DBusConstruct, Typed):
 
         return ', '.join(descriptions)
 
+    def get_emits_changed(self):
+        if self.emits_changed == self.EMITS_CHANGED_UPDATES:
+            return '<div class="annotation emits-changed emits-changed-updates">' \
+                   'When this property changes, the ' \
+                   '<literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal> ' \
+                   'signal is emitted with the new value.</div>';
+        elif self.emits_changed == self.EMITS_CHANGED_INVALIDATES:
+            return '<div class="annotation emits-changed emits-changed-invalidates">' \
+                   'When this property changes, the ' \
+                   '<literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal> ' \
+                   'signal is emitted, but the new value is not sent.</div>';
+        elif self.emits_changed == self.EMITS_CHANGED_NONE:
+            return '<div class="annotation emits-changed emits-changed-none">' \
+                   'The ' \
+                   '<literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal> ' \
+                   'signal is <strong>not</strong> emitted when this property changes.</div>';
+	else:
+            return '';
+
 class AwkwardTelepathyProperty(Typed):
     def get_type_name(self):
         return 'Telepathy Property'
@@ -773,10 +850,10 @@ WARNING: Interface not known: '%s'
 
     def check_for_odd_children(self, dom):
         expected = [
+            (None, 'annotation'),
             (None, 'method'),
             (None, 'property'),
             (None, 'signal'),
-            (None, 'annotation'),
             (XMLNS_TP, 'property'),
             (XMLNS_TP, 'handler-capability-token'),
             (XMLNS_TP, 'hct'),