Rollup merge of #45052 - steveklabnik:gh44105, r=dtolnay

Modify Rc/Arc language around mutability

There are a few exceptions to the rule that Arc/Rc are immutable. Rather
than dig into the details, add "generally" to hint at this difference,
as it's kind of a distraction at this point in the docs.

Additionally, Arc's docs were slightly different here generally, so add
in both the existing language and the exception.

Fixes #44105

2 files changed, 5 insertions, 3 deletions

diff --git a/src/liballoc/arc.rs b/src/liballoc/arc.rs
index 3b7dbd813cf..9481cd4e1a4 100644
--- a/src/liballoc/arc.rs
+++ b/src/liballoc/arc.rs
@@ -52,8 +52,10 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
 /// also destroyed.
 ///
 /// Shared references in Rust disallow mutation by default, and `Arc` is no
-/// exception. If you need to mutate through an `Arc`, use [`Mutex`][mutex],
-/// [`RwLock`][rwlock], or one of the [`Atomic`][atomic] types.
+/// exception: you cannot generally obtain a mutable reference to something
+/// inside an `Arc`. If you need to mutate through an `Arc`, use
+/// [`Mutex`][mutex], [`RwLock`][rwlock], or one of the [`Atomic`][atomic]
+/// types.
 ///
 /// ## Thread Safety
 ///
diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs
index 553980d463f..2f8620cc750 100644
--- a/src/liballoc/rc.rs
+++ b/src/liballoc/rc.rs
@@ -19,7 +19,7 @@
 //! given value is destroyed, the pointed-to value is also destroyed.
 //!
 //! Shared references in Rust disallow mutation by default, and [`Rc`]
-//! is no exception: you cannot obtain a mutable reference to
+//! is no exception: you cannot generally obtain a mutable reference to
 //! something inside an [`Rc`]. If you need mutability, put a [`Cell`]
 //! or [`RefCell`] inside the [`Rc`]; see [an example of mutability
 //! inside an Rc][mutability].