From 426c669d58231ca22cd900f6fd86d59138d6a6ea Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Wed, 29 Jan 2025 20:03:34 -0500
Subject: [PATCH] doc: Expand `from_fs` doc

This expands and slightly corrects the `gix_index::entry::from_fs`
documentation:

- To be more precise about the expectation of where the metadata
  come from (it needn't specifically be the `symlink_metadata`
  function, and it is sometimes even an `fstat`-like function
  rather than an `lstat`-like function, though not `stat`).

- To mention that default values are used for unavailable data.

- To mention that truncation is sometimes performed on some fields.

Comments are also updated regarding some cases of truncation: why
casting down to 32-bit should be okay for `st_dev` and `st_ino`
(see #1817).
---
 gix-index/src/entry/stat.rs | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/gix-index/src/entry/stat.rs b/gix-index/src/entry/stat.rs
index 258b3d28886..72fa6ed20e9 100644
--- a/gix-index/src/entry/stat.rs
+++ b/gix-index/src/entry/stat.rs
@@ -75,7 +75,14 @@ impl Stat {
         }
     }
 
-    /// Creates stat information from the result of `symlink_metadata`.
+    /// Creates stat information from file metadata.
+    ///
+    /// The information passed to this function should originate from a function like
+    /// `symlink_metadata`/`lstat` or `File::metadata`/`fstat`.
+    ///
+    /// The data are adjusted for use in the index, using default values of fields that are not
+    /// meaningful on the target operating system or that are unavailable, and truncating data
+    /// where doing so does not lose essential information for keeping track of file status.
     pub fn from_fs(stat: &crate::fs::Metadata) -> Result<Stat, SystemTimeError> {
         let mtime = stat.modified().unwrap_or(std::time::UNIX_EPOCH);
         let ctime = stat.created().unwrap_or(std::time::UNIX_EPOCH);
@@ -88,7 +95,7 @@ impl Stat {
             ino: 0,
             uid: 0,
             gid: 0,
-            // truncation to 32 bits is on purpose (git does the same).
+            // Truncation to 32 bits is on purpose (git does the same).
             size: stat.len() as u32,
         };
         #[cfg(not(windows))]
@@ -96,15 +103,14 @@ impl Stat {
             Stat {
                 mtime: mtime.try_into().unwrap_or_default(),
                 ctime: ctime.try_into().unwrap_or_default(),
-                // truncating to 32 bits is fine here because
-                // that's what the linux syscalls returns
-                // just rust upcasts to 64 bits for some reason?
-                // numbers this large are impractical anyway (that's a lot of hard-drives).
+                // Truncating the device and inode numbers to 32 bits should be fine even on
+                // targets where they are represented as 64 bits, since we do not use them
+                // precisely for tracking changes and we do not map them back to the inode.
                 dev: stat.dev() as u32,
                 ino: stat.ino() as u32,
                 uid: stat.uid(),
                 gid: stat.gid(),
-                // truncation to 32 bits is on purpose (git does the same).
+                // Truncation to 32 bits is on purpose (git does the same).
                 size: stat.len() as u32,
             }
         };