improve docs

Author: pvdrz

src/shims/foreign_items/posix/linux.rs

@@ -19,6 +19,9 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
             }
 
             // File related shims
+
+            // The only reason this is not in the `posix` module is because the `macos` item has a
+            // different name.
             "close" => {
                 let result = this.close(args[0])?;
                 this.write_scalar(Scalar::from_int(result, dest.layout.size), dest)?;
@@ -56,6 +59,8 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
                         // so skip over it.
                         getrandom(this, &args[1..], dest)?;
                     }
+                    // `statx` is used by `libstd` to retrieve metadata information in `linux`
+                    // instead of using `stat`,`lstat` or `fstat` as in the `macos` platform.
                     id if id == sys_statx => {
                         // The first argument is the syscall id,
                         // so skip over it.

src/shims/foreign_items/posix/macos.rs

@@ -19,6 +19,9 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
             }
 
             // File related shims
+
+            // The only reason this is not in the `posix` module is because the `linux` item has a
+            // different name.
             "close$NOCANCEL" => {
                 let result = this.close(args[0])?;
                 this.write_scalar(Scalar::from_int(result, dest.layout.size), dest)?;

src/shims/fs.rs

@@ -383,6 +383,10 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
         macos_stat_write_buf(this, metadata, buf_op)
     }
 
+    /// Emulate `stat` or `lstat` on the `macos` platform. This function is not intended to be
+    /// called directly from `emulate_foreign_item_by_name`, so it does not check if isolation is
+    /// disabled or if the target platform is the correct one. Please use `macos_stat` or
+    /// `macos_lstat` instead.
     fn macos_stat_or_lstat(
         &mut self,
         follow_symlink: bool,