[glib: 1/2] gfile: Document usefulness of g_file_dup()

[Xavier Claessens <xclaesse src gnome org>]

commit 628474948769beb3143a1f594fe74e48c770d8d0
Author: Philip Withnall <withnall endlessm com>
Date:   Tue Jun 19 12:36:37 2018 +0100

    gfile: Document usefulness of g_file_dup()
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    https://gitlab.gnome.org/GNOME/glib/issues/807

 gio/gfile.c | 5 +++++
 1 file changed, 5 insertions(+)
---
diff --git a/gio/gfile.c b/gio/gfile.c
index 1b67002c4..a5709a4cc 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -702,6 +702,11 @@ g_file_get_parse_name (GFile *file)
  * the actual file or directory represented by the #GFile; see
  * g_file_copy() if attempting to copy a file.
  *
+ * g_file_dup() is useful when a second handle is needed to the same underlying
+ * file, for use in a separate thread (#GFile is not thread-safe). For use
+ * within the same thread, use g_object_ref() to increment the existing object’s
+ * reference count.
+ *
  * This call does no blocking I/O.
  *
  * Returns: (transfer full): a new #GFile that is a duplicate