[at-spi2-core: 3/8] Cache.xml: document the Cache interface

[Federico Mena Quintero <federico src gnome org>]

commit 89bfb3bbe6d0979dd70507bc23a910dd92a9d665
Author: Federico Mena Quintero <federico gnome org>
Date:   Tue Aug 16 17:41:20 2022 -0500

    Cache.xml: document the Cache interface

 xml/Cache.xml | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
---
diff --git a/xml/Cache.xml b/xml/Cache.xml
index 45fb1704..650e36bb 100644
--- a/xml/Cache.xml
+++ b/xml/Cache.xml
@@ -1,17 +1,100 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node>
+  <!--
+      org.a11y.atspi.Cache:
+      @short_description: Interface to query accessible objects in bulk.
+
+      The application should expose this interface at the /org/a11y/atspi/cache object
+      path.
+
+      The org.a11y.atspi.Accessible interface has methods like GetChildren and
+      GetChildAtIndex, but these only transfer an object's DBus id.  The caller has to
+      then query the object's properties individually.  Transfering objects one by one and
+      then their properties produces a lot of traffic in the accessibility bus.
+
+      So, this Cache interface can be used to query objects in bulk.  Assistive tech
+      should try to do a bulk query of all the objects in a new window with the GetItems
+      method, and then update them dynamically from the AddAccessible and RemoveAccessible
+      signals.
+
+      FIXME: Does GetItems only get called if an application implements
+      GetApplicationBusAddress?  GTK4 doesn't implement that, but it implements GetItems -
+      does that ever get called?
+  -->
   <interface name="org.a11y.atspi.Cache">
 
+    <!--
+        GetItems: bulk query an application's accessible objects.
+
+        Returns: an array with one element for each available object.  Each element's
+        fields are like this:
+
+        - (so): accessible object reference - DBus name and object
+          path.  The rest of the fields refer to this main object.
+
+        - (so): application reference - DBus name and object path.  This is the owner of
+          the main object; the root path of the application that registered via
+          the Embed method of the org.a11y.atspi.Socket interface.
+
+        - (so): parent object reference - DBus name and object path.
+                If the main object has no parent:
+
+                - If it is a control, or a window, return the parent application.
+
+                - If the object has the application role, return a null reference.  FIXME:
+                  atk-adaptor/adaptors/cache-adaptor.c:append_cache_item() returns a
+                  reference to the registry in this case (the one it obtained from the
+                  initial Socket::Embed call); GTK4 returns a null reference.
+
+                - Otherwise, return a null reference ("" for the application name name and
+                  "/org/a11y/atspi/null" for the object path).
+
+        - i: index in parent, or -1 for transient widgets/menu items.  Equivalent to the
+          GetIndexInParent method of the org.a11y.atspi.Accessible interface.
+
+        - i: child count of main object, or -1 for defunct/menus.  Equivalent to the
+          ChildCount property of the org.a11y.atspi.Accessible interface.
+
+        - as: array of names of the interfaces that the main object supports.  Equivalent
+          to the GetInterfaces method of the org.a11y.atspi.Accessible interface.
+
+        - s: human-readable, localized, short name for the main object.  Equivalent to the
+          Name property of the org.a11y.atspi.Accessible interface.
+
+        - u: role.  Equivalent to the GetRole method of the org.a11y.atspi.Accessible interface.
+
+        - s: human-readable, localized description of the object in more detail.
+          Equivalent to the Description property of the org.a11y.atspi.Accessible interface.
+
+        - au: Set of states currently held by an object.  Equivalent to the GetState
+          method of the org.a11y.atspi.Accessible interface.
+
+        Historical note: This method used to have a different signature for the return
+        value.  Some old applications return a value whose signature is
+        "a((so)(so)(so)a(so)assusau)".  The "a(so)" instead of "ii" is a list of
+        references to child objects.  The implementation in atspi-misc.c can handle either
+        version.
+    -->
     <method name="GetItems">
       <arg direction="out" name="nodes" type="a((so)(so)(so)iiassusau)"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiAccessibleCacheArray"/>
     </method>
 
+    <!--
+        AddAccessible: to be emitted when a new object is added.
+
+        See the GetItems method for a description of the signature.
+    -->
     <signal name="AddAccessible">
       <arg name="nodeAdded" type="((so)(so)(so)iiassusau)"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiAccessibleCacheItem"/>
     </signal>
 
+    <!--
+        RemoveAccessible: to be emitted when an object is no longer available.
+
+        @nodeRemoved: (so) string for the application name and object path.
+    -->
     <signal name="RemoveAccessible">
       <arg name="nodeRemoved" type="(so)"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiObjectReference"/>