Rollup merge of #120266 - steffahn:a_rc_into_inner_docs, r=Mark-Simulacrum

Improve documentation for [A]Rc::into_inner

General improvements, and also aims to better encourage the reader to actually check out Arc::try_unwrap.

This addresses concerns from https://github.com/rust-lang/rust/issues/106894#issuecomment-1905627234.

Rendered:

![Screenshot_20240123_114436](https://github.com/rust-lang/rust/assets/3986214/68896d62-13e0-4f3a-8073-91d8e77c5554)
![Screenshot_20240123_114455](https://github.com/rust-lang/rust/assets/3986214/dc58e4bd-dd7f-40b1-bc50-fd6200dde593)
This commit is contained in:
Dylan DPC
2024-01-29 12:56:52 +00:00
committed by GitHub
2 changed files with 12 additions and 5 deletions

View File

@@ -939,8 +939,11 @@ impl<T, A: Allocator> Rc<T, A> {
/// it is guaranteed that exactly one of the calls returns the inner value.
/// This means in particular that the inner value is not dropped.
///
/// This is equivalent to `Rc::try_unwrap(this).ok()`. (Note that these are not equivalent for
/// [`Arc`](crate::sync::Arc), due to race conditions that do not apply to `Rc`.)
/// [`Rc::try_unwrap`] is conceptually similar to `Rc::into_inner`.
/// And while they are meant for different use-cases, `Rc::into_inner(this)`
/// is in fact equivalent to <code>[Rc::try_unwrap]\(this).[ok][Result::ok]()</code>.
/// (Note that the same kind of equivalence does **not** hold true for
/// [`Arc`](crate::sync::Arc), due to race conditions that do not apply to `Rc`!)
#[inline]
#[stable(feature = "rc_into_inner", since = "1.70.0")]
pub fn into_inner(this: Self) -> Option<T> {