data: Document the session_handle type mismatch

This was erroneously implemented as `s` but for backwards
compatibility cannot be changed as it would break existing clients.
Best we can do here is fix the documentation and tell people about it.

See eebb041 ("use correct type for the session object path")
and its revert in e452353.

Closes #1359

Author: whot

data/org.freedesktop.portal.GlobalShortcuts.xml

@@ -67,11 +67,15 @@
 
         The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
 
-        * ``session_handle`` (``o``)
+        * ``session_handle`` (``s``)
 
           The session handle. An object path for the
           org.freedesktop.portal.Session object representing the created
           session.
+
+          .. note::
+            The ``session_handle`` is an object path that was erroneously implemented
+            as ``s``. For backwards compatibility it will remain this type.
     -->
     <method name="CreateSession">
       <arg type="a{sv}" name="options" direction="in"/>

data/org.freedesktop.portal.Inhibit.xml

@@ -99,12 +99,16 @@
 
         The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
 
-        * ``session_handle`` (``o``)
+        * ``session_handle`` (``s``)
 
           The session handle. An object path for the
           :ref:`org.freedesktop.portal.Session` object representing the created
           session.
 
+          .. note::
+            The ``session_handle`` is an object path that was erroneously implemented
+            as ``s``. For backwards compatibility it will remain this type.
+
         This method was added in version 2 of this interface.
     -->
     <method name="CreateMonitor">

data/org.freedesktop.portal.RemoteDesktop.xml

@@ -67,11 +67,15 @@
 
         The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
 
-        * ``session_handle`` (``o``)
+        * ``session_handle`` (``s``)
 
           The session handle. An object path for the
           :ref:`org.freedesktop.portal.Session` object representing the created
           session.
+
+          .. note::
+            The ``session_handle`` is an object path that was erroneously implemented
+            as ``s``. For backwards compatibility it will remain this type.
     -->
     <method name="CreateSession">
       <arg type="a{sv}" name="options" direction="in"/>

data/org.freedesktop.portal.ScreenCast.xml

@@ -54,11 +54,15 @@
 
         The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
 
-        * ``session_handle`` (``o``)
+        * ``session_handle`` (``s``)
 
           The session handle. An object path for the
           :ref:`org.freedesktop.portal.Session` object representing the created
           session.
+
+          .. note::
+            The ``session_handle`` is an object path that was erroneously implemented
+            as ``s``. For backwards compatibility it will remain this type.
     -->
     <method name="CreateSession">
       <arg type="a{sv}" name="options" direction="in"/>