Rollup merge of #86397 - Eosis:alter-cell-docs, r=JohnTitor

Alter std::cell::Cell::get_mut documentation

I felt that there was some inconsistency between between Cell and RefCell with regards to their `get_mut` method documentation: `RefCell` flags this method as "unusual" in that it takes `&mut self`, while `Cell` does not. I attempted to flag this in `Cell`s documentation as well, and point to `RefCell`s method in the case where it is required.

Find relevant parts of docs and the new version below.

The current docs for `Cell::get_mut`:
> Returns a mutable reference to the underlying data.
This call borrows Cell mutably (at compile-time) which guarantees that we possess the only reference.

And `RefCell::get_mut`:
> Returns a mutable reference to the underlying data.
 This call borrows `RefCell` mutably (at compile-time) so there is no need for dynamic checks.
However be cautious: this method expects self to be mutable, which is generally not the case when using a `RefCell`. Take a look at the `borrow_mut` method instead if self isn’t mutable.
Also, please be aware that this method is only for special circumstances and is usually not what you want. In case of doubt, use `borrow_mut` instead.

My attempt to make `Cell::get_mut` clearer:
> Returns a mutable reference to the underlying data.
This call borrows `Cell` mutably (at compile-time) which guaranteesthat we possess the only reference.
However be cautious: this method expects `self` to be mutable, which is generally not the case when using a `Cell`. If you require interior mutability by reference, consider using `RefCell` which provides run-time checked mutable borrows through its `borrow_mut` method.

1 files changed, 7 insertions, 0 deletions

diff --git a/library/core/src/cell.rs b/library/core/src/cell.rs
index f88a6e418c7..6fd49361585 100644
--- a/library/core/src/cell.rs
+++ b/library/core/src/cell.rs
@@ -488,6 +488,13 @@ impl<T: ?Sized> Cell<T> {
     /// This call borrows `Cell` mutably (at compile-time) which guarantees
     /// that we possess the only reference.
     ///
+    /// However be cautious: this method expects `self` to be mutable, which is
+    /// generally not the case when using a `Cell`. If you require interior
+    /// mutability by reference, consider using `RefCell` which provides
+    /// run-time checked mutable borrows through its [`borrow_mut`] method.
+    ///
+    /// [`borrow_mut`]: RefCell::borrow_mut()
+    ///
     /// # Examples
     ///
     /// ```