Rollup merge of #97087 - Nilstrieb:clarify-slice-iteration-order, r=dtolnay

Clarify slice and Vec iteration order

While already being inferable from the doc examples, it wasn't fully specified. This is the only logical way to do a slice iterator, so I think this should be uncontroversial. It also improves the `Vec::into_iter` example to better show the order and that the iterator returns owned values.

Author: Dylan-DPC

library/alloc/src/vec/mod.rs

@@ -2626,10 +2626,13 @@ impl<T, A: Allocator> IntoIterator for Vec<T, A> {
     ///
     /// ```
     /// let v = vec!["a".to_string(), "b".to_string()];
-    /// for s in v.into_iter() {
-    ///     // s has type String, not &String
-    ///     println!("{s}");
-    /// }
+    /// let mut v_iter = v.into_iter();
+    ///
+    /// let first_element: Option<String> = v_iter.next();
+    ///
+    /// assert_eq!(first_element, Some("a".to_string()));
+    /// assert_eq!(v_iter.next(), Some("b".to_string()));
+    /// assert_eq!(v_iter.next(), None);
     /// ```
     #[inline]
     fn into_iter(self) -> IntoIter<T, A> {

library/core/src/slice/mod.rs

@@ -716,6 +716,8 @@ impl<T> [T] {
 
     /// Returns an iterator over the slice.
     ///
+    /// The iterator yields all items from start to end.
+    ///
     /// # Examples
     ///
     /// ```
@@ -735,6 +737,8 @@ impl<T> [T] {
 
     /// Returns an iterator that allows modifying each value.
     ///
+    /// The iterator yields all items from start to end.
+    ///
     /// # Examples
     ///
     /// ```