Fix ReentrantMutex documentation wrt DerefMut

Initial version of PR had an DerefMut implementation, which was later removed
because it may cause mutable reference aliasing.

Suggest how to implement mutability with reentrant mutex and remove the claim we
implement DerefMut.

diff --git a/src/libstd/sys/common/remutex.rs b/src/libstd/sys/common/remutex.rs
index 8f41646417367632637c6fa9798b39968ebee271..0674618396f993a21c90639617fb5502f3a9880d 100644 (file)
--- a/src/libstd/sys/common/remutex.rs
+++ b/src/libstd/sys/common/remutex.rs
@@ -36,11 +36,18 @@ unsafe impl<T: Send> Sync for ReentrantMutex<T> {}
 /// dropped (falls out of scope), the lock will be unlocked.
 ///
 /// The data protected by the mutex can be accessed through this guard via its
-/// Deref and DerefMut implementations
+/// Deref implementation.
+///
+/// # Mutability
+///
+/// Unlike `MutexGuard`, `ReentrantMutexGuard` does not implement `DerefMut`,
+/// because implementation of the trait would violate Rust’s reference aliasing
+/// rules. Use interior mutability (usually `RefCell`) in order to mutate the
+/// guarded data.
 #[must_use]
 pub struct ReentrantMutexGuard<'a, T: 'a> {
-    // funny underscores due to how Deref/DerefMut currently work (they
-    // disregard field privacy).
+    // funny underscores due to how Deref currently works (it disregards field
+    // privacy).
     __lock: &'a ReentrantMutex<T>,
     __poison: poison::Guard,
 }