From 628474948769beb3143a1f594fe74e48c770d8d0 Mon Sep 17 00:00:00 2001
From: Philip Withnall <withnall@endlessm.com>
Date: Tue, 19 Jun 2018 12:36:37 +0100
Subject: [PATCH] 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