[at-spi2-core: 6/8] Improve the deprecation note about Cache.GetItems' old signature

[Federico Mena Quintero <federico src gnome org>]

commit 6364851c4b92ab4ed3a3abb0af654f7a5dc9c519
Author: Federico Mena Quintero <federico gnome org>
Date:   Thu Aug 25 21:44:48 2022 -0500

    Improve the deprecation note about Cache.GetItems' old signature

 devel-docs/toolkits.md |  5 +++++
 xml/Cache.xml          | 12 +++++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)
---
diff --git a/devel-docs/toolkits.md b/devel-docs/toolkits.md
index fc04d103..c05318a8 100644
--- a/devel-docs/toolkits.md
+++ b/devel-docs/toolkits.md
@@ -10,6 +10,11 @@ Sources: [`gtk4/gtk/a11y`](https://gitlab.gnome.org/GNOME/gtk/-/tree/main/gtk/a1
 
 Sources: [`qtbase/src/gui/accessible/linux`](https://github.com/qt/qtbase/tree/dev/src/gui/accessible/linux)
 
+Note: Qt's implementation of
+[Cache.GetItems](https://github.com/qt/qtbase/blob/dev/src/gui/accessible/linux/qspi_struct_marshallers.cpp#L41-L71)
+uses the old signature `a((so)(so)(so)a(so)assusau)` instead of the
+preferred/new `a((so)(so)(so)iiassusau)`.
+
 ## WebKit
 
 Sources: 
[`WebKit/Source/WebCore/accessibility/atspi`](https://github.com/WebKit/WebKit/tree/main/Source/WebCore/accessibility/atspi)
diff --git a/xml/Cache.xml b/xml/Cache.xml
index f5ef4d4d..7000bc97 100644
--- a/xml/Cache.xml
+++ b/xml/Cache.xml
@@ -69,11 +69,13 @@
         - 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.
+        Deprecation note: The signature for the return value of this method changed in
+        2015, in commit b2c8c4c7.  It used to be "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, although the intention
+        is to deprecate the code that handles the old version.  Qt still uses this old
+        signature and should be changed to the new scheme (see qspi_struct_marshallers.cpp
+        in the Qt source code).
     -->
     <method name="GetItems">
       <arg direction="out" name="nodes" type="a((so)(so)(so)iiassusau)"/>