[gtk+/wip/alexl/file-chooser-portal] Add some docs

[Matthias Clasen <matthiasc src gnome org>]

commit 20025b41a432c91ce49dcd6de131ea1f67ce0463
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jun 11 10:44:08 2016 -0400

    Add some docs
    
    Mention the portal case in the general native file chooser docs,
    and give some details.

 gtk/gtkfilechoosernative.c |   19 ++++++++++++++++++-
 1 files changed, 18 insertions(+), 1 deletions(-)
---
diff --git a/gtk/gtkfilechoosernative.c b/gtk/gtkfilechoosernative.c
index 7290f7a..6e347eb 100644
--- a/gtk/gtkfilechoosernative.c
+++ b/gtk/gtkfilechoosernative.c
@@ -51,7 +51,10 @@
  * for use with “File/Open” or “File/Save as” commands. By default, this
  * just uses a #GtkFileChooserDialog to implement the actual dialog.
  * However, on certain platforms, such as Windows, the native platform
- * file chooser is uses instead.
+ * file chooser is uses instead. When the application is running in a
+ * sandboxed environment without direct filesystem access (such as Flatpak),
+ * #GtkFileChooserNative may call the proper APIs (portals) to let the user
+ * choose a file and make it available to the application.
  *
  * While the API of #GtkFileChooserNative closely mirrors #GtkFileChooserDialog, the main
  * difference is that there is no access to any #GtkWindow or #GtkWidget for the dialog.
@@ -170,6 +173,20 @@
  *
  * If any of these features are used the regular #GtkFileChooserDialog
  * will be used in place of the native one.
+ *
+ * ## Portal details ## {#gtkfilechooserdialognative-portal}
+ *
+ * When the org.freedesktop.portal.FileChooser portal is available on the
+ * session bus, it is used to bring up an out-of-process file chooser. Depending
+ * on the kind of session the application is running in, this may or may not
+ * be a GTK+ file chooser. In this situation, the following things are not
+ * supported and will be silently ignored:
+ *
+ * * Extra widgets added with gtk_file_chooser_set_extra_widget().
+ *
+ * * Use of custom previews by connecting to #GtkFileChooser::update-preview.
+ *
+ * * Any #GtkFileFilter added with a custom filter.
  */
 
 enum {