diff --git a/gio/meson.build b/gio/meson.build
index 5382d6a67..d0018673e 100644
--- a/gio/meson.build
+++ b/gio/meson.build
@@ -247,16 +247,6 @@ xdp_dbus_generated = custom_target('xdp-dbus',
                '--output-directory', '@OUTDIR@',
                '--generate-c-code', 'xdp-dbus',
                '--c-namespace', 'GXdp',
-               '--annotate', 'org.freedesktop.portal.Documents.Add()',
-                             'org.gtk.GDBus.C.UnixFD', 'true',
-               '--annotate', 'org.freedesktop.portal.Documents.AddNamed()',
-                             'org.gtk.GDBus.C.UnixFD', 'true',
-               '--annotate', 'org.freedesktop.portal.Documents.AddFull()',
-                             'org.gtk.GDBus.C.UnixFD', 'true',
-               '--annotate', 'org.freedesktop.portal.OpenURI.OpenFile()',
-                             'org.gtk.GDBus.C.UnixFD', 'true',
-               '--annotate', 'org.freedesktop.portal.Trash.TrashFile()',
-                             'org.gtk.GDBus.C.UnixFD', 'true',
                '@INPUT@'])
 
 # Generate gdbus-generated.{c,h}
diff --git a/gio/org.freedesktop.portal.Documents.xml b/gio/org.freedesktop.portal.Documents.xml
index d1cb73912..da2863043 100644
--- a/gio/org.freedesktop.portal.Documents.xml
+++ b/gio/org.freedesktop.portal.Documents.xml
@@ -8,7 +8,7 @@
  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
- version 2.1 of the License, or (at your option) any later version.
+ version 2 of the License, or (at your option) any later version.
 
  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -45,6 +45,12 @@
       The permissions that the application has for a document store entry
       (see org.freedesktop.portal.Documents.GrantPermissions()) are reflected
       in the POSIX mode bits in the fuse filesystem.
+
+      The D-Bus interface for the document portal is available under the
+      bus name org.freedesktop.portal.Documents and the object path
+      /org/freedesktop/portal/documents.
+ 
+      This documentation describes version 3 of this interface.
   -->
   <interface name='org.freedesktop.portal.Documents'>
     <property name="version" type="u" access="read"/>
@@ -72,6 +78,7 @@
         access to the file.
     -->
     <method name="Add">
+      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
       <arg type='h' name='o_path_fd' direction='in'/>
       <arg type='b' name='reuse_existing' direction='in'/>
       <arg type='b' name='persistent' direction='in'/>
@@ -89,6 +96,7 @@
         Creates an entry in the document store for writing a new file.
     -->
     <method name="AddNamed">
+      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
       <arg type='h' name='o_path_parent_fd' direction='in'/>
       <arg type='ay' name='filename' direction='in'/>
       <arg type='b' name='reuse_existing' direction='in'/>
@@ -99,7 +107,7 @@
     <!--
         AddFull:
         @o_path_fds: open file descriptors for the files to export
-        @flags: flags, 1 == reuse_existing, 2 == persistent
+        @flags: flags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app
         @app_id: an application ID, or empty string
         @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
         @doc_ids: the IDs of the files in the document store
@@ -109,6 +117,11 @@
         form of an open file descriptor to prove that the caller has
         access to the file.
 
+        If the as-needed-by-app flag is given, files will only be added to
+        the document store if the application does not already have access to them.
+        For files that are not added to the document store, the doc_ids array will
+        contain an empty string.
+
         Additionally, if app_id is specified, it will be given the permissions
         listed in GrantPermission.
 
@@ -119,6 +132,7 @@
         This method was added in version 2 of the org.freedesktop.portal.Documents interface.
     -->
     <method name="AddFull">
+      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
       <arg type='ah' name='o_path_fds' direction='in'/>
       <arg type='u' name='flags' direction='in'/>
       <arg type='s' name='app_id' direction='in'/>
@@ -127,6 +141,43 @@
       <arg type='a{sv}' name='extra_out' direction='out'/>
     </method>
 
+    <!--
+        AddNamedFull:
+        @o_path_fds: open file descriptor for the parent directory
+        @filename: the basename for the file
+        @flags: flags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app
+        @app_id: an application ID, or empty string
+        @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
+        @doc_id: the ID of the file in the document store
+        @extra_info: Extra info returned
+
+        Creates an entry in the document store for writing a new file.
+
+        If the as-needed-by-app flag is given, file will only be added to
+        the document store if the application does not already have access to it.
+        For file that is not added to the document store, the doc_id will
+        contain an empty string.
+
+        Additionally, if app_id is specified, it will be given the permissions
+        listed in GrantPermission.
+
+        The method also returns some extra info that can be used to avoid
+        multiple roundtrips. For now it only contains as "mountpoint", the
+        fuse mountpoint of the document portal.
+
+        This method was added in version 3 of the org.freedesktop.portal.Documents interface.
+    -->
+    <method name="AddNamedFull">
+      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
+      <arg type='h' name='o_path_fd' direction='in'/>
+      <arg type='ay' name='filename' direction='in'/>
+      <arg type='u' name='flags' direction='in'/>
+      <arg type='s' name='app_id' direction='in'/>
+      <arg type='as' name='permissions' direction='in'/>
+      <arg type='s' name='doc_id' direction='out'/>
+      <arg type='a{sv}' name='extra_out' direction='out'/>
+    </method>
+
     <!--
         GrantPermissions:
         @doc_id: the ID of the file in the document store
@@ -148,8 +199,8 @@
     <!--
         RevokePermissions:
         @doc_id: the ID of the file in the document store
-        @app_id: the ID of the application to which permissions are granted
-        @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
+        @app_id: the ID of the application from which permissions are revoked
+        @permissions: the permissions to revoke, possible values are 'read', 'write', 'grant-permissions' and 'delete'
 
         Revokes access permissions for a file in the document store
         from an application.
@@ -184,7 +235,7 @@
 
         Looks up the document ID for a file.
 
-        This call is no not available inside the sandbox.
+        This call is not available inside the sandbox.
     -->
     <method name="Lookup">
       <arg type='ay' name='filename' direction='in'/>
diff --git a/gio/org.freedesktop.portal.OpenURI.xml b/gio/org.freedesktop.portal.OpenURI.xml
index 0cc79d1cc..5ed054cf1 100644
--- a/gio/org.freedesktop.portal.OpenURI.xml
+++ b/gio/org.freedesktop.portal.OpenURI.xml
@@ -5,7 +5,7 @@
  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
- version 2.1 of the License, or (at your option) any later version.
+ version 2 of the License, or (at your option) any later version.
 
  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -26,25 +26,32 @@
        The OpenURI portal allows sandboxed applications to open
        URIs (e.g. a http: link to the applications homepage)
        under the control of the user.
+
+       This documentation describes version 3 of this interface.
   -->
   <interface name="org.freedesktop.portal.OpenURI">
     <!--
         OpenURI:
-        @parent_window: Identifier for the application window
+        @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
         @uri: The uri to open
         @options: Vardict with optional further onformation
         @handle: Object path for the #org.freedesktop.portal.Request object representing this call
 
         Asks to open a uri.
 
-        The @parent_window identifier must be of the form "x11:$XID" for an X11
-        window. Support for other window systems may be added in the future.
-
         Note that file:// uris are explicitly not supported by this method.
-        To request opening local files, use org.freedesktop.portal.OpenFile().
+        To request opening local files, use org.freedesktop.portal.OpenURI.OpenFile().
 
         Supported keys in the @options vardict include:
         <variablelist>
+          <varlistentry>
+            <term>handle_token s</term>
+            <listitem><para>
+              A string that will be used as the last element of the @handle. Must be a valid
+              object path element. See the #org.freedesktop.portal.Request documentation for
+              more information about the @handle.
+            </para></listitem>
+          </varlistentry>
           <varlistentry>
             <term>writable b</term>
             <listitem><para>
@@ -55,6 +62,15 @@
               is sandboxed itself.
             </para></listitem>
           </varlistentry>
+          <varlistentry>
+            <term>ask b</term>
+            <listitem><para>
+              Whether to ask the user to choose an app. If this is not passed, or false,
+              the portal may use a default or pick the last choice.
+            </para><para>
+              The ask option was introduced in version 3 of the interface.
+            </para></listitem>
+          </varlistentry>
         </variablelist>
 
     -->
@@ -67,18 +83,23 @@
 
     <!--
         OpenFile:
-        @parent_window: Identifier for the application window
+        @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
         @fd: File descriptor for the file to open
         @options: Vardict with optional further onformation
         @handle: Object path for the #org.freedesktop.portal.Request object representing this call
 
         Asks to open a local file.
 
-        The @parent_window identifier must be of the form "x11:$XID" for an X11
-        window. Support for other window systems may be added in the future.
-
         Supported keys in the @options vardict include:
         <variablelist>
+          <varlistentry>
+            <term>handle_token s</term>
+            <listitem><para>
+              A string that will be used as the last element of the @handle. Must be a valid
+              object path element. See the #org.freedesktop.portal.Request documentation for
+              more information about the @handle.
+            </para></listitem>
+          </varlistentry>
           <varlistentry>
             <term>writable b</term>
             <listitem><para>
@@ -89,11 +110,52 @@
               is sandboxed itself.
             </para></listitem>
           </varlistentry>
+          <varlistentry>
+            <term>ask b</term>
+            <listitem><para>
+              Whether to ask the user to choose an app. If this is not passed, or false,
+              the portal may use a default or pick the last choice.
+            </para><para>
+              The ask option was introduced in version 3 of the interface.
+            </para></listitem>
+          </varlistentry>
         </variablelist>
 
         The OpenFile method was introduced in version 2 of the OpenURI portal API.
     -->
     <method name="OpenFile">
+      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
+      <arg type="s" name="parent_window" direction="in"/>
+      <arg type="h" name="fd" direction="in"/>
+      <arg type="a{sv}" name="options" direction="in"/>
+      <arg type="o" name="handle" direction="out"/>
+    </method>
+
+    <!--
+        OpenDirectory:
+        @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
+        @fd: File descriptor for a file
+        @options: Vardict with optional further onformation
+        @handle: Object path for the #org.freedesktop.portal.Request object representing this call
+
+        Asks to open the directory containing a local file in the file browser.
+
+        Supported keys in the @options vardict include:
+        <variablelist>
+          <varlistentry>
+            <term>handle_token s</term>
+            <listitem><para>
+              A string that will be used as the last element of the @handle. Must be a valid
+              object path element. See the #org.freedesktop.portal.Request documentation for
+              more information about the @handle.
+            </para></listitem>
+          </varlistentry>
+        </variablelist>
+
+        The OpenDirectory method was introduced in version 3 of the OpenURI portal API.
+    -->
+    <method name="OpenDirectory">
+      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
       <arg type="s" name="parent_window" direction="in"/>
       <arg type="h" name="fd" direction="in"/>
       <arg type="a{sv}" name="options" direction="in"/>
diff --git a/gio/org.freedesktop.portal.ProxyResolver.xml b/gio/org.freedesktop.portal.ProxyResolver.xml
index c6e9ce9a2..4b39fc078 100644
--- a/gio/org.freedesktop.portal.ProxyResolver.xml
+++ b/gio/org.freedesktop.portal.ProxyResolver.xml
@@ -5,23 +5,45 @@
  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
- version 2.1 of the License, or (at your option) any later version.
+ version 2 of the License, or (at your option) any later version.
 
  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.
 
- You should have received a copy of the GNU Lesser General Public License
- along with this library; if not, see <http://www.gnu.org/licenses/>.
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library. If not, see <http://www.gnu.org/licenses/>.
 
  Author: Matthias Clasen <mclasen@redhat.com>
 -->
-<node xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd" name="/">
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+  <!--
+      org.freedesktop.portal.ProxyResolver:
+      @short_description: Proxy information
+
+      The ProxyResolver interface provides network proxy information to sandboxed
+      applications. It is not a portal in the strict sense, since it does not involve
+      user interaction. Applications are expected to use this interface indirectly,
+      via a library API such as the GLib GProxyResolver interface.
+
+      This documentation describes version 1 of this interface.
+  -->
   <interface name="org.freedesktop.portal.ProxyResolver">
+    <!--
+        Lookup:
+        @uri: Destination to connect to
+        @proxies: List of proxy uris
+
+        Looks up which proxy to use to connect to @uri. The returned
+        proxy uri are of the form 'protocol://[user[:password]@host:port'.
+        The protocol can be http, rtsp, socks or another proxying protocol.
+        'direct://' is used when no proxy is needed.
+    -->
     <method name="Lookup">
       <arg type="s" name="uri" direction="in"/>
       <arg type="as" name="proxies" direction="out"/>
     </method>
+    <property name="version" type="u" access="read"/>
   </interface>
 </node>