Merge remote branch 'randomguy3/master'

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=32353
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>

3 files changed, 88 insertions, 4 deletions

diff --git a/doc/templates/interface.html b/doc/templates/interface.html
index 279bed01..26db20ec 100644
--- a/doc/templates/interface.html
+++ b/doc/templates/interface.html
@@ -238,6 +238,10 @@
      $method.get_changed()
      $method.get_deprecated()
 
+     #if $method.no_reply
+     <div class="annotation no-reply">The caller should not expect a reply when calling this method.</div>
+     #end if
+
      #if $method.in_args
      <div class="indent">
       <h3>Parameters</h3>
@@ -413,6 +417,25 @@
      $property.get_changed()
      $property.get_deprecated()
 
+     #if $property.emits_changed == $property.EMITS_CHANGED_UPDATES
+     <div class="annotation emits-changed emits-changed-updates">
+       When this property changes, the
+       <code>org.freedesktop.DBus.Properties.PropertiesChanged</code>
+       signal is emitted with the new value.
+     </div>
+     #elif $property.emits_changed == $property.EMITS_CHANGED_INVALIDATES
+     <div class="annotation emits-changed emits-changed-invalidates">
+       When this property changes, the
+       <code>org.freedesktop.DBus.Properties.PropertiesChanged</code>
+       signal is emitted, but the new value is not sent.
+     </div>
+     #elif $property.emits_changed == $property.EMITS_CHANGED_NONE
+     <div class="annotation emits-changed emits-changed-none">
+       The <code>org.freedesktop.DBus.Properties.PropertiesChanged</code>
+       signal is <strong>not</strong> emitted when this property changes.</div>
+     </div>
+     #end if
+
       #if $property.is_connection_parameter:
       <div class="annotation connection-parameter">
         <p><span class='note'>Note:</span> Connections implementing this
diff --git a/doc/templates/style.css b/doc/templates/style.css
index bca3d8da..85cd6f14 100644
--- a/doc/templates/style.css
+++ b/doc/templates/style.css
@@ -223,6 +223,7 @@ div.havoc {
 }
 
 div.deprecated span.version,
+div.deprecated.no-version,
 span.warning {
 	color: #a40000;
 }
@@ -235,10 +236,18 @@ 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;
 }
diff --git a/tools/specparser.py b/tools/specparser.py
index 0baf3f1b..697d4aff 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,10 @@ class Base(object):
         self.docstring = getOnlyChildByName(dom, XMLNS_TP, 'docstring')
         self.added = getOnlyChildByName(dom, XMLNS_TP, 'added')
         self.deprecated = getOnlyChildByName(dom, XMLNS_TP, 'deprecated')
+        if self.deprecated is None:
+            self.is_deprecated = (getAnnotationByName(dom, 'org.freedesktop.DBus.Deprecated') == 'true')
+        else:
+            self.is_deprecated = True
 
         self.changed = getChildrenByName(dom, XMLNS_TP, 'changed')
 
@@ -211,8 +235,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 +510,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))
 
@@ -552,11 +584,16 @@ class Typed(Base):
         return '%s(%s:%s)' % (self.__class__.__name__, self.name, self.dbus_type)
 
 class Property(DBusConstruct, Typed):
-    ACCESS_READ     = 1
-    ACCESS_WRITE    = 2
+    ACCESS_READ = 1
+    ACCESS_WRITE = 2
 
     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 +618,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'