2 files changed, 42 insertions, 22 deletions

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 3d6a207f..ad21af62 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -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">
diff --git a/doc/introspect.dtd b/doc/introspect.dtd
index 5e1c96df..fd6aa472 100644
--- a/doc/introspect.dtd
+++ b/doc/introspect.dtd
@@ -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>