gdbus-codegen: Add support for the org.freedesktop.DBus.Deprecated annotation

Signed-off-by: David Zeuthen <davidz@redhat.com>

diff --git a/docs/reference/gio/gdbus-codegen.xml b/docs/reference/gio/gdbus-codegen.xml
index 2a389e2..6eca718 100644 (file)
--- a/docs/reference/gio/gdbus-codegen.xml
+++ b/docs/reference/gio/gdbus-codegen.xml
@@ -182,6 +182,83 @@ gdbus-codegen --c-namespace MyApp                           \
   <variablelist>
 
     <varlistentry>
+      <term><literal>org.freedesktop.DBus.Deprecated</literal></term>
+      <listitem>
+        <para>
+          Can be used on any <literal>&lt;interface&gt;</literal>,
+          <literal>&lt;method&gt;</literal>,
+          <literal>&lt;signal&gt;</literal> and
+          <literal>&lt;property&gt;</literal> element to specify that
+          the element is deprecated if its value is
+          <literal>true</literal>. Note that this annotation is
+          defined in the <ulink
+          url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
+          specification</ulink> and can only assume the values
+          <literal>true</literal> and <literal>false</literal>. In
+          particular, you cannot specify the version that the element
+          was deprecated in nor any helpful deprecation message. Such
+          information should be added to the element documentation
+          instead.
+        </para>
+        <para>
+          When generating C code, this annotation is used to add
+          #G_GNUC_DEPRECATED to generated functions for the element.
+        </para>
+        <para>
+          When generating Docbook XML, a deprecation warning will
+          appear along the documentation for the element.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>org.gtk.GDBus.Since</literal></term>
+      <listitem>
+        <para>
+          Can be used on any <literal>&lt;interface&gt;</literal>,
+          <literal>&lt;method&gt;</literal>,
+          <literal>&lt;signal&gt;</literal> and
+          <literal>&lt;property&gt;</literal> element to specify the
+          version (any free-form string but compared using a
+          version-aware sort function) the element appeared in.
+        </para>
+        <para>
+          When generating C code, this field is used to ensure
+          function pointer order for preserving ABI/API.
+        </para>
+        <para>
+          When generating Docbook XML, the value of this tag appears
+          in the documentation.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>org.gtk.GDBus.DocString</literal></term>
+      <listitem>
+        <para>
+          A string with Docbook content for documentation. This annotation can
+          be used on <literal>&lt;interface&gt;</literal>,
+          <literal>&lt;method&gt;</literal>,
+          <literal>&lt;signal&gt;</literal>,
+          <literal>&lt;property&gt;</literal> and
+          <literal>&lt;arg&gt;</literal> elements.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>org.gtk.GDBus.DocString.Short</literal></term>
+      <listitem>
+        <para>
+          A string with Docbook content for short/brief
+          documentation. This annotation can only be used on
+          <literal>&lt;interface&gt;</literal> elements.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
       <term><literal>org.gtk.GDBus.C.Name</literal></term>
       <listitem>
         <para>
@@ -238,28 +315,6 @@ gdbus-codegen --c-namespace MyApp                           \
     </varlistentry>
 
     <varlistentry>
-      <term><literal>org.gtk.GDBus.Since</literal></term>
-      <listitem>
-        <para>
-          Can be used on any <literal>&lt;interface&gt;</literal>,
-          <literal>&lt;method&gt;</literal>,
-          <literal>&lt;signal&gt;</literal> and
-          <literal>&lt;property&gt;</literal> element to specify the
-          version (any free-form string but compared using a
-          version-aware sort function) the element appeared in.
-        </para>
-        <para>
-          When generating C code, this field is used to ensure
-          function pointer order for preserving ABI/API.
-        </para>
-        <para>
-          When generating Docbook XML, the value of this tag appears
-          in the documentation.
-        </para>
-      </listitem>
-    </varlistentry>
-
-    <varlistentry>
       <term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term>
       <listitem>
         <para>
@@ -271,31 +326,6 @@ gdbus-codegen --c-namespace MyApp                           \
       </listitem>
     </varlistentry>
 
-    <varlistentry>
-      <term><literal>org.gtk.GDBus.DocString</literal></term>
-      <listitem>
-        <para>
-          A string with Docbook content for documentation. This annotation can
-          be used on <literal>&lt;interface&gt;</literal>,
-          <literal>&lt;method&gt;</literal>,
-          <literal>&lt;signal&gt;</literal>,
-          <literal>&lt;property&gt;</literal> and
-          <literal>&lt;arg&gt;</literal> elements.
-        </para>
-      </listitem>
-    </varlistentry>
-
-    <varlistentry>
-      <term><literal>org.gtk.GDBus.DocString.Short</literal></term>
-      <listitem>
-        <para>
-          A string with Docbook content for short/brief
-          documentation. This annotation can only be used on
-          <literal>&lt;interface&gt;</literal> elements.
-        </para>
-      </listitem>
-    </varlistentry>
-
   </variablelist>
 
   <para>

diff --git a/gio/gdbus-codegen/codegen.py b/gio/gdbus-codegen/codegen.py
index 34bd33e..c1c8ea3 100644 (file)
--- a/gio/gdbus-codegen/codegen.py
+++ b/gio/gdbus-codegen/codegen.py
@@ -295,6 +295,8 @@ class CodeGenerator:
                 self.h.write('\n')
                 self.h.write('/* D-Bus method call completion functions: */\n')
                 for m in i.methods:
+                    if m.deprecated:
+                        self.h.write('G_GNUC_DEPRECATED ')
                     self.h.write('void %s_complete_%s (\n'
                                  '    %s *object,\n'
                                  '    GDBusMethodInvocation *invocation'%(i.name_lower, m.name_lower, i.camel_name))
@@ -309,6 +311,8 @@ class CodeGenerator:
                 self.h.write('\n')
                 self.h.write('/* D-Bus signal emissions functions: */\n')
                 for s in i.signals:
+                    if s.deprecated:
+                        self.h.write('G_GNUC_DEPRECATED ')
                     self.h.write('void %s_emit_%s (\n'
                                  '    %s *object'%(i.name_lower, s.name_lower, i.camel_name))
                     for a in s.args:
@@ -323,6 +327,8 @@ class CodeGenerator:
                 self.h.write('/* D-Bus method calls: */\n')
                 for m in i.methods:
                     # async begin
+                    if m.deprecated:
+                        self.h.write('G_GNUC_DEPRECATED ')
                     self.h.write('void %s_call_%s (\n'
                                  '    %s *proxy'%(i.name_lower, m.name_lower, i.camel_name))
                     for a in m.in_args:
@@ -333,6 +339,8 @@ class CodeGenerator:
                                  '    gpointer user_data);\n')
                     self.h.write('\n')
                     # async finish
+                    if m.deprecated:
+                        self.h.write('G_GNUC_DEPRECATED ')
                     self.h.write('gboolean %s_call_%s_finish (\n'
                                  '    %s *proxy'%(i.name_lower, m.name_lower, i.camel_name))
                     for a in m.out_args:
@@ -342,6 +350,8 @@ class CodeGenerator:
                                  '    GError **error);\n')
                     self.h.write('\n')
                     # sync
+                    if m.deprecated:
+                        self.h.write('G_GNUC_DEPRECATED ')
                     self.h.write('gboolean %s_call_%s_sync (\n'
                                  '    %s *proxy'%(i.name_lower, m.name_lower, i.camel_name))
                     for a in m.in_args:
@@ -360,8 +370,12 @@ class CodeGenerator:
                 self.h.write('/* D-Bus property accessors: */\n')
                 for p in i.properties:
                     # getter
+                    if p.deprecated:
+                        self.h.write('G_GNUC_DEPRECATED ')
                     self.h.write('%s%s_get_%s (%s *object);\n'%(p.arg.ctype_in, i.name_lower, p.name_lower, i.camel_name))
                     # setter
+                    if p.deprecated:
+                        self.h.write('G_GNUC_DEPRECATED ')
                     self.h.write('void %s_set_%s (%s *object, %svalue);\n'%(i.name_lower, p.name_lower, i.camel_name, p.arg.ctype_in, ))
                     self.h.write('\n')
 
@@ -394,6 +408,8 @@ class CodeGenerator:
             self.h.write('GType %s_proxy_get_gtype (void) G_GNUC_CONST;\n'%(i.name_lower))
 
             self.h.write('\n')
+            if i.deprecated:
+                self.h.write('G_GNUC_DEPRECATED ')
             self.h.write('void %s_proxy_new (\n'
                          '    GDBusConnection     *connection,\n'
                          '    GDBusProxyFlags      flags,\n'
@@ -403,10 +419,14 @@ class CodeGenerator:
                          '    GAsyncReadyCallback  callback,\n'
                          '    gpointer             user_data);\n'
                          %(i.name_lower))
+            if i.deprecated:
+                self.h.write('G_GNUC_DEPRECATED ')
             self.h.write('%s *%s_proxy_new_finish (\n'
                          '    GAsyncResult        *res,\n'
                          '    GError             **error);\n'
                          %(i.camel_name, i.name_lower))
+            if i.deprecated:
+                self.h.write('G_GNUC_DEPRECATED ')
             self.h.write('%s *%s_proxy_new_sync (\n'
                          '    GDBusConnection     *connection,\n'
                          '    GDBusProxyFlags      flags,\n'
@@ -416,6 +436,8 @@ class CodeGenerator:
                          '    GError             **error);\n'
                          %(i.camel_name, i.name_lower))
             self.h.write('\n')
+            if i.deprecated:
+                self.h.write('G_GNUC_DEPRECATED ')
             self.h.write('void %s_proxy_new_for_bus (\n'
                          '    GBusType             bus_type,\n'
                          '    GDBusProxyFlags      flags,\n'
@@ -425,10 +447,14 @@ class CodeGenerator:
                          '    GAsyncReadyCallback  callback,\n'
                          '    gpointer             user_data);\n'
                          %(i.name_lower))
+            if i.deprecated:
+                self.h.write('G_GNUC_DEPRECATED ')
             self.h.write('%s *%s_proxy_new_for_bus_finish (\n'
                          '    GAsyncResult        *res,\n'
                          '    GError             **error);\n'
                          %(i.camel_name, i.name_lower))
+            if i.deprecated:
+                self.h.write('G_GNUC_DEPRECATED ')
             self.h.write('%s *%s_proxy_new_for_bus_sync (\n'
                          '    GBusType             bus_type,\n'
                          '    GDBusProxyFlags      flags,\n'
@@ -472,6 +498,8 @@ class CodeGenerator:
             self.h.write('\n')
             self.h.write('GType %s_skeleton_get_gtype (void) G_GNUC_CONST;\n'%(i.name_lower))
             self.h.write('\n')
+            if i.deprecated:
+                self.h.write('G_GNUC_DEPRECATED ')
             self.h.write('%s *%s_skeleton_new (void);\n'%(i.camel_name, i.name_lower))
 
             self.h.write('\n')

diff --git a/gio/gdbus-codegen/codegen_docbook.py b/gio/gdbus-codegen/codegen_docbook.py
index dd5442c..18b1fc0 100644 (file)
--- a/gio/gdbus-codegen/codegen_docbook.py
+++ b/gio/gdbus-codegen/codegen_docbook.py
@@ -186,6 +186,8 @@ class DocbookCodeGenerator:
         self.out.write('</variablelist>\n')
         if len(m.since) > 0:
             self.out.write('<para role="since">Since %s</para>\n'%(m.since))
+        if m.deprecated:
+            self.out.write('<warning><para>The %s() method is deprecated.</para></warning>'%(m.name))
         self.out.write('</refsect2>\n')
 
     def print_signal(self, i, s):
@@ -205,6 +207,8 @@ class DocbookCodeGenerator:
         self.out.write('</variablelist>\n')
         if len(s.since) > 0:
             self.out.write('<para role="since">Since %s</para>\n'%(s.since))
+        if s.deprecated:
+            self.out.write('<warning><para>The "%s" signal is deprecated.</para></warning>'%(s.name))
         self.out.write('</refsect2>\n')
 
     def print_property(self, i, p):
@@ -217,6 +221,8 @@ class DocbookCodeGenerator:
         self.out.write('<para>%s</para>\n'%(self.expand(p.doc_string)))
         if len(p.since) > 0:
             self.out.write('<para role="since">Since %s</para>\n'%(p.since))
+        if p.deprecated:
+            self.out.write('<warning><para>The "%s" property is deprecated.</para></warning>'%(p.name))
         self.out.write('</refsect2>\n')
 
     def expand(self, s):
@@ -284,6 +290,8 @@ class DocbookCodeGenerator:
             self.out.write('  <para>%s</para>\n'%(self.expand(i.doc_string)))
             if len(i.since) > 0:
                 self.out.write('  <para role="since">Since %s</para>\n'%(i.since))
+            if i.deprecated:
+                self.out.write('<warning><para>The %s interface is deprecated.</para></warning>'%(i.name))
             self.out.write('</refsect1>\n'%())
 
             if len(i.methods) > 0:

diff --git a/gio/gdbus-codegen/dbustypes.py b/gio/gdbus-codegen/dbustypes.py
index 8c780f9..d545de4 100644 (file)
--- a/gio/gdbus-codegen/dbustypes.py
+++ b/gio/gdbus-codegen/dbustypes.py
@@ -183,6 +183,7 @@ class Method:
         self.annotations = []
         self.doc_string = ''
         self.since = ''
+        self.deprecated = False
 
     def post_process(self, interface_prefix, c_namespace):
         if len(self.doc_string) == 0:
@@ -209,6 +210,9 @@ class Method:
             a.post_process(interface_prefix, c_namespace, arg_count)
             arg_count += 1
 
+        if utils.lookup_annotation(self.annotations, 'org.freedesktop.DBus.Deprecated') == 'true':
+            self.deprecated = True
+
 class Signal:
     def __init__(self, name):
         self.name = name
@@ -216,6 +220,7 @@ class Signal:
         self.annotations = []
         self.doc_string = ''
         self.since = ''
+        self.deprecated = False
 
     def post_process(self, interface_prefix, c_namespace):
         if len(self.doc_string) == 0:
@@ -238,6 +243,9 @@ class Signal:
             a.post_process(interface_prefix, c_namespace, arg_count)
             arg_count += 1
 
+        if utils.lookup_annotation(self.annotations, 'org.freedesktop.DBus.Deprecated') == 'true':
+            self.deprecated = True
+
 class Property:
     def __init__(self, name, signature, access):
         self.name = name
@@ -259,6 +267,7 @@ class Property:
             raise RuntimeError('Invalid access type %s'%self.access)
         self.doc_string = ''
         self.since = ''
+        self.deprecated = False
 
     def post_process(self, interface_prefix, c_namespace):
         if len(self.doc_string) == 0:
@@ -280,6 +289,9 @@ class Property:
         self.arg.annotations = self.annotations
         self.arg.post_process(interface_prefix, c_namespace, 0)
 
+        if utils.lookup_annotation(self.annotations, 'org.freedesktop.DBus.Deprecated') == 'true':
+            self.deprecated = True
+
 class Interface:
     def __init__(self, name):
         self.name = name
@@ -290,6 +302,7 @@ class Interface:
         self.doc_string = ''
         self.doc_string_brief = ''
         self.since = ''
+        self.deprecated = False
 
     def post_process(self, interface_prefix, c_namespace):
         if len(self.doc_string) == 0:
@@ -334,6 +347,9 @@ class Interface:
                 self.name_lower = utils.camel_case_to_uscore(name_with_ns)
             self.name_upper = utils.camel_case_to_uscore(name).upper()
 
+        if utils.lookup_annotation(self.annotations, 'org.freedesktop.DBus.Deprecated') == 'true':
+            self.deprecated = True
+
         for m in self.methods:
             m.post_process(interface_prefix, c_namespace)
 

diff --git a/gio/tests/test-codegen.xml b/gio/tests/test-codegen.xml
index ae8333c..cec5714 100644 (file)
--- a/gio/tests/test-codegen.xml
+++ b/gio/tests/test-codegen.xml
@@ -414,4 +414,26 @@
     </property>
   </interface>
 
+  <!--
+    OldieInterface:
+    @short_description: A an example of an deprecated interface
+
+    This is an example of a deprecated interface.
+    -->
+  <interface name="OldieInterface">
+    <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
+
+    <method name="Foo">
+      <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
+    </method>
+
+    <signal name="Bar">
+      <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
+    </signal>
+
+    <property name="Bat" type="i" access="readwrite">
+      <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
+    </property>
+  </interface>
+
 </node>