mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-13 15:56:23 +01:00
gdbus-codegen: Add support for the org.freedesktop.DBus.Deprecated annotation
Signed-off-by: David Zeuthen <davidz@redhat.com>
This commit is contained in:
David Zeuthen
parent
98e6d4b0a9
commit
e19734d6c3
@ -181,6 +181,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>
|
||||
@ -237,28 +314,6 @@ gdbus-codegen --c-namespace MyApp \
|
||||
</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.C.ForceGVariant</literal></term>
|
||||
<listitem>
|
||||
@ -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>
|
||||
|
||||
@ -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')
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user