diff --git a/gio/gfile.c b/gio/gfile.c
index 442e9f6f1..38b1931ac 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -783,9 +783,17 @@ g_file_hash (gconstpointer file)
  *
  * Checks if the two given #GFiles refer to the same file.
  *
+ * This function can be used with [method@Gio.File.hash] to insert
+ * [iface@Gio.File]s efficiently in a hash table.
+ *
  * Note that two #GFiles that differ can still refer to the same
  * file on the filesystem due to various forms of filename
- * aliasing.
+ * aliasing. For local files, this function essentially compares the file paths,
+ * so two [iface@Gio.File]s which point to different hard or soft links will not
+ * be considered equal, despite pointing to the same content.
+ *
+ * For determining whether two files are hardlinked, see
+ * [const@Gio.FILE_ATTRIBUTE_ID_FILE].
  *
  * This call does no blocking I/O.
  *
diff --git a/gio/gfileinfo.h b/gio/gfileinfo.h
index 6e4f02dce..30c49f99b 100644
--- a/gio/gfileinfo.h
+++ b/gio/gfileinfo.h
@@ -311,6 +311,13 @@ typedef struct _GFileInfoClass   GFileInfoClass;
  *
  * An example use would be during listing files, to avoid recursive
  * directory scanning.
+ *
+ * For local files on Linux, this is a combination of the file’s device number
+ * and inode, so is invariant with respect to hard linking. The format used by
+ * other VFS implementations may vary, and some VFS backends may not set it.
+ *
+ * For simply seeing if two [iface@Gio.File] instances refer to the same path
+ * on disk, see [method@Gio.File.equal].
  **/
 #define G_FILE_ATTRIBUTE_ID_FILE "id::file"                     /* string */