Socket.xml: document the Socket interface

1 files changed, 40 insertions, 1 deletions

diff --git a/xml/Socket.xml b/xml/Socket.xml
index ab51850f..a1d19754 100644
--- a/xml/Socket.xml
+++ b/xml/Socket.xml
@@ -1,7 +1,30 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<node>
+<node xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+  <!--
+      org.a11y.atspi.Socket:
+      @short_description: Interface to register an application on the registry.
+  -->
   <interface name="org.a11y.atspi.Socket">
 
+    <!--
+        Embed:
+        @plug: a string for the unique bus name of the application, and an object path
+        for the application's' root object.
+
+        This is the entry point for an application that wants to register itself against
+        the accessibility registry.  The application's root object, which it passes in
+        @plug, must support the org.a11y.atspi.Application interface.
+
+        When an application calls this method on the registry, the following handshake happens:
+
+        * Application calls this method on the registry to identify itself.
+
+        * The registry sets the "Id" property on the org.a11y.atspi.Application interface on the @plug object.
+
+        * The Embed method returns with the bus name and object path for the registry's root object.
+
+        Returns: the bus name and object path of the registry's root object.
+    -->
     <method name="Embed">
       <arg direction="in" name="plug" type="(so)"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiObjectReference"/>
@@ -9,11 +32,27 @@
       <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiObjectReference"/>
     </method>
 
+    <!--
+        Unembed:
+        @plug: a string for the unique bus name of the application, and an object path
+        for the application's' root object.
+
+        Unregisters an application from the accesibility registry.  It is not necessary to
+        call this method; the accessibility registry detects when an application
+        disconnects from the bus.
+    -->
     <method name="Unembed">
       <arg direction="in" name="plug" type="(so)"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiObjectReference"/>
     </method>
 
+    <!--
+        Available:
+        @socket: application and object path for the registry's root object.
+
+        The accessibility registry emits this signal early during startup, when it has
+        registered with the DBus daemon and is available for calls from applications.
+    -->
     <signal name="Available">
       <arg name="socket" type="(so)"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiObjectReference"/>