Auto merge of #52268 - Mark-Simulacrum:rollup, r=Mark-Simulacrum

Rollup of 14 pull requests

Successful merges:

 - #51614 (Correct suggestion for println)
 - #51952 ( hygiene: Decouple transparencies from expansion IDs)
 - #52193 (step_by: leave time of item skip unspecified)
 - #52207 (improve error message shown for unsafe operations)
 - #52223 (Deny bare trait objects in in src/liballoc)
 - #52224 (Deny bare trait objects in in src/libsyntax)
 - #52239 (Remove sync::Once::call_once 'static bound)
 - #52247 (Deny bare trait objects in in src/librustc)
 - #52248 (Deny bare trait objects in in src/librustc_allocator)
 - #52252 (Deny bare trait objects in in src/librustc_codegen_llvm)
 - #52253 (Deny bare trait objects in in src/librustc_data_structures)
 - #52254 (Deny bare trait objects in in src/librustc_metadata)
 - #52261 (Deny bare trait objects in in src/libpanic_unwind)
 - #52265 (Deny bare trait objects in in src/librustc_codegen_utils)

Failed merges:

r? @ghost

1 files changed, 22 insertions, 1 deletions

diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index 8836de3edc8..c0681619bf8 100644
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -271,9 +271,30 @@ pub trait Iterator {
     /// Creates an iterator starting at the same point, but stepping by
     /// the given amount at each iteration.
     ///
-    /// Note that it will always return the first element of the iterator,
+    /// Note 1: The first element of the iterator will always be returned,
     /// regardless of the step given.
     ///
+    /// Note 2: The time at which ignored elements are pulled is not fixed.
+    /// `StepBy` behaves like the sequence `next(), nth(step-1), nth(step-1), …`,
+    /// but is also free to behave like the sequence
+    /// `advance_n_and_return_first(step), advance_n_and_return_first(step), …`
+    /// Which way is used may change for some iterators for performance reasons.
+    /// The second way will advance the iterator earlier and may consume more items.
+    ///
+    /// `advance_n_and_return_first` is the equivalent of:
+    /// ```
+    /// fn advance_n_and_return_first<I>(iter: &mut I, total_step: usize) -> Option<I::Item>
+    /// where
+    ///     I: Iterator,
+    /// {
+    ///     let next = iter.next();
+    ///     if total_step > 1 {
+    ///         iter.nth(total_step-2);
+    ///     }
+    ///     next
+    /// }
+    /// ```
+    ///
     /// # Panics
     ///
     /// The method will panic if the given step is `0`.