dbus/doc introspect.dtd,1.1,1.2 dbus-specification.xml,1.29,1.30
Colin Walters
walters at freedesktop.org
Thu Feb 17 13:11:20 PST 2005
Update of /cvs/dbus/dbus/doc
In directory gabe:/tmp/cvs-serv11714/doc
Modified Files:
introspect.dtd dbus-specification.xml
Log Message:
2005-02-17 Colin Walters <walters at verbum.org>
* glib/dbus-gparser.c (struct Parser): Add in_annotation boolean.
(parse_node, parse_interface, parse_method, parse_signal)
(parse_property, parse_annotation): Lose if we're currently in an
annotation.
(parse_annotation): New function.
(parser_start_element, parser_end_element): Handle annotation.
(parse_method, parse_interface): Remove support for c_name attribute,
switch to annotations.
* glib/dbus-gidl.h (interface_info_get_binding_names)
(method_info_get_binding_names)
(interface_info_get_binding_name, method_info_get_binding_name)
(interface_info_set_binding_name, method_info_set_binding_name):
Remove.
(interface_info_get_annotations, method_info_get_annotations)
(interface_info_get_annotation, method_info_get_annotation)
(interface_info_add_annotation, method_info_add_annotation):
Prototype.
* glib/dbus-gidl.c (struct InterfaceInfo): Substitute "annotations"
for "bindings".
(struct MethodInfo): Ditto.
Straightfoward conversion of binding methods into annotation methods
as prototyped.
* glib/dbus-glib-tool.c (pretty_print): Print annotations.
* glib/dbus-binding-tool-glib.h (DBUS_GLIB_ANNOTATION_C_SYMBOL): Define.
* glib/dbus-binding-tool-glib.c (gather_marshallers, generate_glue):
Use new annotation API.
* doc/introspect.dtd: Fix a number of DTD syntax errors. Add
annotation element.
* doc/dbus-specification.xml: Discuss introspection annotations,
include list of well-known annotations.
* test/glib/test-service-glib.xml: Make validate against new DTD.
Index: introspect.dtd
===================================================================
RCS file: /cvs/dbus/dbus/doc/introspect.dtd,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- introspect.dtd 5 Feb 2005 03:24:54 -0000 1.1
+++ introspect.dtd 17 Feb 2005 21:11:18 -0000 1.2
@@ -4,32 +4,33 @@
<!-- see D-BUS specification for documentation -->
-<!ELEMENT node (interface,node)>
+<!ELEMENT node (interface*,node*)>
<!ATTLIST node name CDATA #REQUIRED>
-<!ELEMENT interface (method,signal,property)>
+<!ELEMENT interface (annotation*,method*,signal*,property*)>
<!ATTLIST interface name CDATA #REQUIRED>
-<!ATTLIST interface deprecated CDATA "no">
+<!ELEMENT method (annotation*,arg*)>
<!ATTLIST method name CDATA #REQUIRED>
-<!ATTLIST method deprecated #IMPLIED>
<!ELEMENT arg EMPTY>
-<!ATTLIST arg name CDATA #REQUIRED>
+<!ATTLIST arg name CDATA #IMPLIED>
<!ATTLIST arg type CDATA #REQUIRED>
<!-- Method arguments SHOULD include "direction",
while signal and error arguments SHOULD not (since there's no point).
The DTD format can't express that subtlety. -->
-<!ATTLIST arg direction "in|out" #IMPLIED>
+<!ATTLIST arg direction (in|out) "in">
-<!ELEMENT signal (arg)>
+<!ELEMENT signal (arg,annotation)>
<!ATTLIST signal name CDATA #REQUIRED>
-<!ATTLIST signal deprecated #IMPLIED>
-<!ELEMENT property> <!-- AKA "attribute" -->
+<!ELEMENT property (annotation)> <!-- AKA "attribute" -->
<!ATTLIST property name CDATA #REQUIRED>
<!ATTLIST property type CDATA #REQUIRED>
-<!ATTLIST property access "read|write|readwrite" #REQUIRED>
-<!ATTLIST property deprecated #IMPLIED>
+<!ATTLIST property access (read|write|readwrite) #REQUIRED>
+
+<!ELEMENT annotation EMPTY> <!-- Generic metadata -->
+<!ATTLIST annotation name CDATA #REQUIRED>
+<!ATTLIST annotation value CDATA #REQUIRED>
Index: dbus-specification.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.xml,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -d -r1.29 -r1.30
--- dbus-specification.xml 12 Feb 2005 20:13:08 -0000 1.29
+++ dbus-specification.xml 17 Feb 2005 21:11:18 -0000 1.30
@@ -2296,6 +2296,7 @@
<method name="Frobate">
<arg name="foo" type="int32" direction="in"/>
<arg name="bar" type="string" direction="out"/>
+ <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
</method>
<signal name="Changed">
<arg name="new_value" type="boolean"/>
@@ -2367,23 +2368,41 @@
</listitem>
<listitem>
<para>
- The method, interface, property, and signal elements may have
- an attribute deprecated="yes|no". If the attribute is not
- present, the default value for an interface is "no", and
- the default value for methods, properties, and signals is
- the deprecation status of the interface.
- </para>
- </listitem>
- <listitem>
- <para>
The "name" attribute on arguments is optional.
</para>
</listitem>
</itemizedlist>
</para>
-
+ <para>
+ Method, interface, property, and signal elements may have
+ "annotations", which are generic key/value pairs of metadata.
+ They are similar conceptually to Java's annotations and C# attributes.
+ Well-known annotations:
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values (separated by ,)</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>org.freedesktop.DBus.Deprecated</entry>
+ <entry>true,false</entry>
+ <entry>Whether or not the entity is deprecated; defaults to false</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
+ <entry>(string)</entry>
+ <entry>The C symbol; may be used for methods and interfaces</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</sect1>
-
<sect1 id="message-bus">
<title>Message Bus Specification</title>
<sect2 id="message-bus-overview">
More information about the dbus-commit
mailing list