Auto merge of #82053 - JohnTitor:rollup-ymi9q0g, r=JohnTitor

Rollup of 8 pull requests

Successful merges:

 - #81811 (Fix doc test for Vec::retain(), now passes clippy::eval_order_dependence)
 - #81900 (Organize trait test files)
 - #81995 (Fix suggestion to introduce explicit lifetime)
 - #82031 (Drop an unnecessary intermediate variable)
 - #82033 (Refactor `get_word_attr` to return only `Option`)
 - #82040 (Add test to prevent src link regression)
 - #82041 (Add docs for shared_from_slice From impls)
 - #82050 (Added tests to drain an empty vec)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup

4 files changed, 113 insertions, 3 deletions

diff --git a/library/alloc/src/rc.rs b/library/alloc/src/rc.rs
index f67f5fc533b..dac4acc4692 100644
--- a/library/alloc/src/rc.rs
+++ b/library/alloc/src/rc.rs
@@ -1652,6 +1652,16 @@ impl<T> From<T> for Rc<T> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T: Clone> From<&[T]> for Rc<[T]> {
+    /// Allocate a reference-counted slice and fill it by cloning `v`'s items.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::rc::Rc;
+    /// let original: &[i32] = &[1, 2, 3];
+    /// let shared: Rc<[i32]> = Rc::from(original);
+    /// assert_eq!(&[1, 2, 3], &shared[..]);
+    /// ```
     #[inline]
     fn from(v: &[T]) -> Rc<[T]> {
         <Self as RcFromSlice<T>>::from_slice(v)
@@ -1660,6 +1670,15 @@ impl<T: Clone> From<&[T]> for Rc<[T]> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl From<&str> for Rc<str> {
+    /// Allocate a reference-counted string slice and copy `v` into it.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::rc::Rc;
+    /// let shared: Rc<str> = Rc::from("statue");
+    /// assert_eq!("statue", &shared[..]);
+    /// ```
     #[inline]
     fn from(v: &str) -> Rc<str> {
         let rc = Rc::<[u8]>::from(v.as_bytes());
@@ -1669,6 +1688,16 @@ impl From<&str> for Rc<str> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl From<String> for Rc<str> {
+    /// Allocate a reference-counted string slice and copy `v` into it.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::rc::Rc;
+    /// let original: String = "statue".to_owned();
+    /// let shared: Rc<str> = Rc::from(original);
+    /// assert_eq!("statue", &shared[..]);
+    /// ```
     #[inline]
     fn from(v: String) -> Rc<str> {
         Rc::from(&v[..])
@@ -1677,6 +1706,16 @@ impl From<String> for Rc<str> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T: ?Sized> From<Box<T>> for Rc<T> {
+    /// Move a boxed object to a new, reference counted, allocation.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::rc::Rc;
+    /// let original: Box<i32> = Box::new(1);
+    /// let shared: Rc<i32> = Rc::from(original);
+    /// assert_eq!(1, *shared);
+    /// ```
     #[inline]
     fn from(v: Box<T>) -> Rc<T> {
         Rc::from_box(v)
@@ -1685,6 +1724,16 @@ impl<T: ?Sized> From<Box<T>> for Rc<T> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T> From<Vec<T>> for Rc<[T]> {
+    /// Allocate a reference-counted slice and move `v`'s items into it.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::rc::Rc;
+    /// let original: Box<Vec<i32>> = Box::new(vec![1, 2, 3]);
+    /// let shared: Rc<Vec<i32>> = Rc::from(original);
+    /// assert_eq!(vec![1, 2, 3], *shared);
+    /// ```
     #[inline]
     fn from(mut v: Vec<T>) -> Rc<[T]> {
         unsafe {
diff --git a/library/alloc/src/sync.rs b/library/alloc/src/sync.rs
index 461ca85c030..aeae888dddc 100644
--- a/library/alloc/src/sync.rs
+++ b/library/alloc/src/sync.rs
@@ -2285,6 +2285,16 @@ impl<T> From<T> for Arc<T> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T: Clone> From<&[T]> for Arc<[T]> {
+    /// Allocate a reference-counted slice and fill it by cloning `v`'s items.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::sync::Arc;
+    /// let original: &[i32] = &[1, 2, 3];
+    /// let shared: Arc<[i32]> = Arc::from(original);
+    /// assert_eq!(&[1, 2, 3], &shared[..]);
+    /// ```
     #[inline]
     fn from(v: &[T]) -> Arc<[T]> {
         <Self as ArcFromSlice<T>>::from_slice(v)
@@ -2293,6 +2303,15 @@ impl<T: Clone> From<&[T]> for Arc<[T]> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl From<&str> for Arc<str> {
+    /// Allocate a reference-counted `str` and copy `v` into it.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::sync::Arc;
+    /// let shared: Arc<str> = Arc::from("eggplant");
+    /// assert_eq!("eggplant", &shared[..]);
+    /// ```
     #[inline]
     fn from(v: &str) -> Arc<str> {
         let arc = Arc::<[u8]>::from(v.as_bytes());
@@ -2302,6 +2321,16 @@ impl From<&str> for Arc<str> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl From<String> for Arc<str> {
+    /// Allocate a reference-counted `str` and copy `v` into it.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::sync::Arc;
+    /// let unique: String = "eggplant".to_owned();
+    /// let shared: Arc<str> = Arc::from(unique);
+    /// assert_eq!("eggplant", &shared[..]);
+    /// ```
     #[inline]
     fn from(v: String) -> Arc<str> {
         Arc::from(&v[..])
@@ -2310,6 +2339,16 @@ impl From<String> for Arc<str> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T: ?Sized> From<Box<T>> for Arc<T> {
+    /// Move a boxed object to a new, reference-counted allocation.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::sync::Arc;
+    /// let unique: Box<str> = Box::from("eggplant");
+    /// let shared: Arc<str> = Arc::from(unique);
+    /// assert_eq!("eggplant", &shared[..]);
+    /// ```
     #[inline]
     fn from(v: Box<T>) -> Arc<T> {
         Arc::from_box(v)
@@ -2318,6 +2357,16 @@ impl<T: ?Sized> From<Box<T>> for Arc<T> {
 
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T> From<Vec<T>> for Arc<[T]> {
+    /// Allocate a reference-counted slice and move `v`'s items into it.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::sync::Arc;
+    /// let unique: Vec<i32> = vec![1, 2, 3];
+    /// let shared: Arc<[i32]> = Arc::from(unique);
+    /// assert_eq!(&[1, 2, 3], &shared[..]);
+    /// ```
     #[inline]
     fn from(mut v: Vec<T>) -> Arc<[T]> {
         unsafe {
diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index b40c1a8c57a..b6166617789 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -1385,13 +1385,14 @@ impl<T, A: Allocator> Vec<T, A> {
     /// assert_eq!(vec, [2, 4]);
     /// ```
     ///
-    /// The exact order may be useful for tracking external state, like an index.
+    /// Because the elements are visited exactly once in the original order,
+    /// external state may be used to decide which elements to keep.
     ///
     /// ```
     /// let mut vec = vec![1, 2, 3, 4, 5];
     /// let keep = [false, true, true, false, true];
-    /// let mut i = 0;
-    /// vec.retain(|_| (keep[i], i += 1).0);
+    /// let mut iter = keep.iter();
+    /// vec.retain(|_| *iter.next().unwrap());
     /// assert_eq!(vec, [2, 3, 5]);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
diff --git a/library/alloc/tests/vec.rs b/library/alloc/tests/vec.rs
index e3d74791dcf..2969da58d42 100644
--- a/library/alloc/tests/vec.rs
+++ b/library/alloc/tests/vec.rs
@@ -610,6 +610,17 @@ fn test_move_items_zero_sized() {
 }
 
 #[test]
+fn test_drain_empty_vec() {
+    let mut vec: Vec<i32> = vec![];
+    let mut vec2: Vec<i32> = vec![];
+    for i in vec.drain(..) {
+        vec2.push(i);
+    }
+    assert!(vec.is_empty());
+    assert!(vec2.is_empty());
+}
+
+#[test]
 fn test_drain_items() {
     let mut vec = vec![1, 2, 3];
     let mut vec2 = vec![];