[glib/gdbus-codegen] gdbus-codegen: Add support for the org.freedesktop.DBus.Deprecated annotation
- From: David Zeuthen <davidz src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib/gdbus-codegen] gdbus-codegen: Add support for the org.freedesktop.DBus.Deprecated annotation
- Date: Fri, 15 Apr 2011 16:59:09 +0000 (UTC)
commit e19734d6c3f24076d25ac7f290b97df76cad5056
Author: David Zeuthen <davidz redhat com>
Date: Fri Apr 15 12:56:07 2011 -0400
gdbus-codegen: Add support for the org.freedesktop.DBus.Deprecated annotation
Signed-off-by: David Zeuthen <davidz redhat com>
docs/reference/gio/gdbus-codegen.xml | 124 +++++++++++++++++++++-------------
gio/gdbus-codegen/codegen.py | 28 ++++++++
gio/gdbus-codegen/codegen_docbook.py | 8 ++
gio/gdbus-codegen/dbustypes.py | 16 +++++
gio/tests/test-codegen.xml | 22 ++++++
5 files changed, 151 insertions(+), 47 deletions(-)
---
diff --git a/docs/reference/gio/gdbus-codegen.xml b/docs/reference/gio/gdbus-codegen.xml
index 2a389e2..6eca718 100644
--- 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><interface></literal>,
+ <literal><method></literal>,
+ <literal><signal></literal> and
+ <literal><property></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><interface></literal>,
+ <literal><method></literal>,
+ <literal><signal></literal> and
+ <literal><property></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><interface></literal>,
+ <literal><method></literal>,
+ <literal><signal></literal>,
+ <literal><property></literal> and
+ <literal><arg></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><interface></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><interface></literal>,
- <literal><method></literal>,
- <literal><signal></literal> and
- <literal><property></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><interface></literal>,
- <literal><method></literal>,
- <literal><signal></literal>,
- <literal><property></literal> and
- <literal><arg></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><interface></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
--- 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
--- 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
--- 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
--- 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>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
