luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-13 15:56:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Signed-off-by: David Zeuthen <davidz@redhat.com>
This commit is contained in:
David Zeuthen 2011-04-15 12:56:07 -04:00
parent 98e6d4b0a9
commit e19734d6c3
5 changed files with 151 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
docs/reference/gio/gdbus-codegen.xml
View File

@ -181,6 +181,83 @@ gdbus-codegen --c-namespace MyApp \
<variablelist> <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> <varlistentry>
<term><literal>org.gtk.GDBus.C.Name</literal></term> <term><literal>org.gtk.GDBus.C.Name</literal></term>
<listitem> <listitem>
@ -237,28 +314,6 @@ gdbus-codegen --c-namespace MyApp \
</listitem> </listitem>
</varlistentry> </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> <varlistentry>
<term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term> <term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term>
<listitem> <listitem>
@ -271,31 +326,6 @@ gdbus-codegen --c-namespace MyApp \
</listitem> </listitem>
</varlistentry> </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> </variablelist>
<para> <para>

28
gio/gdbus-codegen/codegen.py
View File

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

8
gio/gdbus-codegen/codegen_docbook.py
View File

@ -186,6 +186,8 @@ class DocbookCodeGenerator:
self.out.write('</variablelist>\n') self.out.write('</variablelist>\n')
if len(m.since) > 0: if len(m.since) > 0:
self.out.write('<para role="since">Since %s</para>\n'%(m.since)) 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') self.out.write('</refsect2>\n')
def print_signal(self, i, s): def print_signal(self, i, s):
@ -205,6 +207,8 @@ class DocbookCodeGenerator:
self.out.write('</variablelist>\n') self.out.write('</variablelist>\n')
if len(s.since) > 0: if len(s.since) > 0:
self.out.write('<para role="since">Since %s</para>\n'%(s.since)) 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') self.out.write('</refsect2>\n')
def print_property(self, i, p): def print_property(self, i, p):
@ -217,6 +221,8 @@ class DocbookCodeGenerator:
self.out.write('<para>%s</para>\n'%(self.expand(p.doc_string))) self.out.write('<para>%s</para>\n'%(self.expand(p.doc_string)))
if len(p.since) > 0: if len(p.since) > 0:
self.out.write('<para role="since">Since %s</para>\n'%(p.since)) 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') self.out.write('</refsect2>\n')
def expand(self, s): def expand(self, s):
@ -284,6 +290,8 @@ class DocbookCodeGenerator:
self.out.write(' <para>%s</para>\n'%(self.expand(i.doc_string))) self.out.write(' <para>%s</para>\n'%(self.expand(i.doc_string)))
if len(i.since) > 0: if len(i.since) > 0:
self.out.write(' <para role="since">Since %s</para>\n'%(i.since)) 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'%()) self.out.write('</refsect1>\n'%())
if len(i.methods) > 0: if len(i.methods) > 0:

16
gio/gdbus-codegen/dbustypes.py
View File

@ -183,6 +183,7 @@ class Method:
self.annotations = [] self.annotations = []
self.doc_string = '' self.doc_string = ''
self.since = '' self.since = ''
self.deprecated = False
def post_process(self, interface_prefix, c_namespace): def post_process(self, interface_prefix, c_namespace):
if len(self.doc_string) == 0: if len(self.doc_string) == 0:
@ -209,6 +210,9 @@ class Method:
a.post_process(interface_prefix, c_namespace, arg_count) a.post_process(interface_prefix, c_namespace, arg_count)
arg_count += 1 arg_count += 1
if utils.lookup_annotation(self.annotations, 'org.freedesktop.DBus.Deprecated') == 'true':
self.deprecated = True
class Signal: class Signal:
def __init__(self, name): def __init__(self, name):
self.name = name self.name = name
@ -216,6 +220,7 @@ class Signal:
self.annotations = [] self.annotations = []
self.doc_string = '' self.doc_string = ''
self.since = '' self.since = ''
self.deprecated = False
def post_process(self, interface_prefix, c_namespace): def post_process(self, interface_prefix, c_namespace):
if len(self.doc_string) == 0: if len(self.doc_string) == 0:
@ -238,6 +243,9 @@ class Signal:
a.post_process(interface_prefix, c_namespace, arg_count) a.post_process(interface_prefix, c_namespace, arg_count)
arg_count += 1 arg_count += 1
if utils.lookup_annotation(self.annotations, 'org.freedesktop.DBus.Deprecated') == 'true':
self.deprecated = True
class Property: class Property:
def __init__(self, name, signature, access): def __init__(self, name, signature, access):
self.name = name self.name = name
@ -259,6 +267,7 @@ class Property:
raise RuntimeError('Invalid access type %s'%self.access) raise RuntimeError('Invalid access type %s'%self.access)
self.doc_string = '' self.doc_string = ''
self.since = '' self.since = ''
self.deprecated = False
def post_process(self, interface_prefix, c_namespace): def post_process(self, interface_prefix, c_namespace):
if len(self.doc_string) == 0: if len(self.doc_string) == 0:
@ -280,6 +289,9 @@ class Property:
self.arg.annotations = self.annotations self.arg.annotations = self.annotations
self.arg.post_process(interface_prefix, c_namespace, 0) 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: class Interface:
def __init__(self, name): def __init__(self, name):
self.name = name self.name = name
@ -290,6 +302,7 @@ class Interface:
self.doc_string = '' self.doc_string = ''
self.doc_string_brief = '' self.doc_string_brief = ''
self.since = '' self.since = ''
self.deprecated = False
def post_process(self, interface_prefix, c_namespace): def post_process(self, interface_prefix, c_namespace):
if len(self.doc_string) == 0: 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_lower = utils.camel_case_to_uscore(name_with_ns)
self.name_upper = utils.camel_case_to_uscore(name).upper() 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: for m in self.methods:
m.post_process(interface_prefix, c_namespace) m.post_process(interface_prefix, c_namespace)

22
gio/tests/test-codegen.xml
View File

@ -414,4 +414,26 @@
</property> </property>
</interface> </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> </node>