Merge branch 'file-equal-docs' into 'main'

gfile: Expand documentation around file equality

See merge request GNOME/glib!4815

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.
  *

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 */