From c2bcab55b09db9adc5d33b48011a31587a8e80a1 Mon Sep 17 00:00:00 2001
From: Christian Poveda <git@christianpoveda.xyz>
Date: Sat, 22 Feb 2020 08:55:45 -0500
Subject: [PATCH] improve docs

---
 src/shims/foreign_items/posix/linux.rs | 5 +++++
 src/shims/foreign_items/posix/macos.rs | 3 +++
 src/shims/fs.rs                        | 4 ++++
 3 files changed, 12 insertions(+)

diff --git a/src/shims/foreign_items/posix/linux.rs b/src/shims/foreign_items/posix/linux.rs
index 098d0566354..9da54b6d407 100644
--- a/src/shims/foreign_items/posix/linux.rs
+++ b/src/shims/foreign_items/posix/linux.rs
@@ -19,6 +19,9 @@ fn emulate_foreign_item_by_name(
             }
 
             // 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 @@ fn emulate_foreign_item_by_name(
                         // 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.
diff --git a/src/shims/foreign_items/posix/macos.rs b/src/shims/foreign_items/posix/macos.rs
index 3698df95bd1..25ac7e93867 100644
--- a/src/shims/foreign_items/posix/macos.rs
+++ b/src/shims/foreign_items/posix/macos.rs
@@ -19,6 +19,9 @@ fn emulate_foreign_item_by_name(
             }
 
             // 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)?;
diff --git a/src/shims/fs.rs b/src/shims/fs.rs
index afa71f65407..b3d8d6a0ac7 100644
--- a/src/shims/fs.rs
+++ b/src/shims/fs.rs
@@ -383,6 +383,10 @@ fn macos_fstat(
         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,
-- 
2.44.0