state also in the intro that UnsafeCell has no effect on &mut

diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index f74e945b3cc1bf58b652e938f4629ce727026e87..0aaf5269a3d47c81e52fad46b7bb3640689fffc2 100644 (file)
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -1412,8 +1412,9 @@ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 /// If you have a reference `&SomeStruct`, then normally in Rust all fields of `SomeStruct` are
 /// immutable. The compiler makes optimizations based on the knowledge that `&T` is not mutably
 /// aliased or mutated, and that `&mut T` is unique. `UnsafeCell<T>` is the only core language
-/// feature to work around this restriction. All other types that allow internal mutability, such as
-/// `Cell<T>` and `RefCell<T>`, use `UnsafeCell` to wrap their internal data.
+/// feature to work around the restriction that `&T` may not be mutated. All other types that
+/// allow internal mutability, such as `Cell<T>` and `RefCell<T>`, use `UnsafeCell` to wrap their
+/// internal data. There is *no* legal way to obtain aliasing `&mut`, not even with `UnsafeCell<T>`.
 ///
 /// The `UnsafeCell` API itself is technically very simple: it gives you a raw pointer `*mut T` to
 /// its contents. It is up to _you_ as the abstraction designer to use that raw pointer correctly.