UnsafeCell: mention shared-ref-to-interior case, fix aliasing model inaccuracy

library/core/src/cell.rs

@@ -2174,7 +2174,7 @@ impl<T: ?Sized + fmt::Display> fmt::Display for RefMut<'_, T> {
 ///   `'a`. For example, this means that if you take the `*mut T` from an `UnsafeCell<T>` and cast it
 ///   to an `&T`, then the data in `T` must remain immutable (modulo any `UnsafeCell` data found
 ///   within `T`, of course) until that reference's lifetime expires. Similarly, if you create a
-///   `&mut T` reference that is released to safe code, then you must not access the data within the
+///   `&mut T` reference, then you must not access the data within the
 ///   `UnsafeCell` until that reference expires.
 ///
 /// - For both `&T` without `UnsafeCell<_>` and `&mut T`, you must also not deallocate the data
@@ -2224,9 +2224,9 @@ impl<T: ?Sized + fmt::Display> fmt::Display for RefMut<'_, T> {
 /// thus this can cause distortions in the type size in these cases.
 ///
 /// Note that the only valid way to obtain a `*mut T` pointer to the contents of a
-/// _shared_ `UnsafeCell<T>` is through [`.get()`]  or [`.raw_get()`]. A `&mut T` reference
-/// can be obtained by either dereferencing this pointer or by calling [`.get_mut()`]
-/// on an _exclusive_ `UnsafeCell<T>`. Even though `T` and `UnsafeCell<T>` have the
+/// _shared_ `UnsafeCell<T>` is through [`.get()`]  or [`.raw_get()`]. An `&T` or `&mut T` reference
+/// can then be obtained from that pointer, as long as the alasing rules outlined above are obeyed.
+/// Even though `T` and `UnsafeCell<T>` have the
 /// same memory layout, the following is not allowed and undefined behavior:
 ///
 /// ```rust,compile_fail
@@ -2421,9 +2421,9 @@ impl<T: ?Sized> UnsafeCell<T> {
 
     /// Gets a mutable pointer to the wrapped value.
     ///
-    /// This can be cast to a pointer of any kind. When creating references, you must uphold the
-    /// aliasing rules; see [the type-level docs][UnsafeCell#aliasing-rules] for more discussion and
-    /// caveats.
+    /// This can be cast to a pointer of any kind. When creating (shared or mutable) references, you
+    /// must uphold the aliasing rules; see [the type-level docs][UnsafeCell#aliasing-rules] for
+    /// more discussion and caveats.
     ///
     /// # Examples
     ///
@@ -2473,9 +2473,9 @@ impl<T: ?Sized> UnsafeCell<T> {
     /// The difference from [`get`] is that this function accepts a raw pointer,
     /// which is useful to avoid the creation of temporary references.
     ///
-    /// This can be cast to a pointer of any kind. When creating references, you must uphold the
-    /// aliasing rules; see [the type-level docs][UnsafeCell#aliasing-rules] for more discussion and
-    /// caveats.
+    /// This can be cast to a pointer of any kind. When creating (shared or mutable) references, you
+    /// must uphold the aliasing rules; see [the type-level docs][UnsafeCell#aliasing-rules] for
+    /// more discussion and caveats.
     ///
     /// [`get`]: UnsafeCell::get()
     ///