From 1949c6599d7d088eca6893f1c118b05e5c5d1679 Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Tue, 15 Aug 2017 09:42:11 -0400
Subject: [PATCH 1/3] Add comments clarifying behavior of unix `set_readonly`
 behavior.

---
 src/libstd/sys/unix/fs.rs | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/libstd/sys/unix/fs.rs b/src/libstd/sys/unix/fs.rs
index 4e6fde5c29d..cb0f687e072 100644
--- a/src/libstd/sys/unix/fs.rs
+++ b/src/libstd/sys/unix/fs.rs
@@ -170,11 +170,17 @@ impl AsInner<stat64> for FileAttr {
 }
 
 impl FilePermissions {
-    pub fn readonly(&self) -> bool { self.mode & 0o222 == 0 }
+    pub fn readonly(&self) -> bool {
+        // check if any class (owner, group, others) has write permission
+        self.mode & 0o222 == 0
+    }
+
     pub fn set_readonly(&mut self, readonly: bool) {
         if readonly {
+            // remove write permission for all classes; equivalent to `chmod a-w <file>`
             self.mode &= !0o222;
         } else {
+            // add write permission for all classes; equivalent to `chmod a+w <file>`
             self.mode |= 0o222;
         }
     }

From 5a93be48c360bb1d874c53e8445cb3bce2bf5a1f Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Tue, 15 Aug 2017 10:09:43 -0400
Subject: [PATCH 2/3] Clarify `readonly` method is also about being
 'unwritable'.

---
 src/libstd/fs.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index 1e692abaff2..e6968f41af4 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -916,7 +916,7 @@ impl AsInner<fs_imp::FileAttr> for Metadata {
 }
 
 impl Permissions {
-    /// Returns whether these permissions describe a readonly file.
+    /// Returns whether these permissions describe a readonly (unwritable) file.
     ///
     /// # Examples
     ///

From 10a479ebe170398e70f872a7afa222d00a9c8f53 Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Tue, 15 Aug 2017 10:13:35 -0400
Subject: [PATCH 3/3] Clarify 'writable'-changing behavior of `set_readonly`.

Fixes https://github.com/rust-lang/rust/issues/41984.
---
 src/libstd/fs.rs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index e6968f41af4..a438b4afdd0 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -934,7 +934,11 @@ impl Permissions {
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn readonly(&self) -> bool { self.0.readonly() }
 
-    /// Modifies the readonly flag for this set of permissions.
+    /// Modifies the readonly flag for this set of permissions. If the
+    /// `readonly` argument is `true`, using the resulting `Permission` will
+    /// update file permissions to forbid writing. Conversely, if it's `false`,
+    /// using the resulting `Permission` will update file permissions to allow
+    /// writing.
     ///
     /// This operation does **not** modify the filesystem. To modify the
     /// filesystem use the `fs::set_permissions` function.