Extend the skip_any and take_any docs

Author: cuviper

src/iter/mod.rs

@@ -2198,7 +2198,12 @@ pub trait ParallelIterator: Sized + Send {
         Intersperse::new(self, element)
     }
 
-    /// Creates an iterator that yields the first `n` elements.
+    /// Creates an iterator that yields `n` elements from *anywhere* in the original iterator.
+    ///
+    /// This is similar to [`IndexedParallelIterator::take`] without being
+    /// constrained to the "first" `n` of the original iterator order. The
+    /// taken items will still maintain their relative order where that is
+    /// visible in `collect`, `reduce`, and similar outputs.
     ///
     /// # Examples
     ///
@@ -2212,12 +2217,18 @@ pub trait ParallelIterator: Sized + Send {
     ///     .collect();
     ///
     /// assert_eq!(result.len(), 5);
+    /// assert!(result.windows(2).all(|w| w[0] < w[1]));
     /// ```
     fn take_any(self, n: usize) -> TakeAny<Self> {
         TakeAny::new(self, n)
     }
 
-    /// Creates an iterator that skips the first `n` elements.
+    /// Creates an iterator that skips `n` elements from *anywhere* in the original iterator.
+    ///
+    /// This is similar to [`IndexedParallelIterator::skip`] without being
+    /// constrained to the "first" `n` of the original iterator order. The
+    /// remaining items will still maintain their relative order where that is
+    /// visible in `collect`, `reduce`, and similar outputs.
     ///
     /// # Examples
     ///
@@ -2231,6 +2242,7 @@ pub trait ParallelIterator: Sized + Send {
     ///     .collect();
     ///
     /// assert_eq!(result.len(), 45);
+    /// assert!(result.windows(2).all(|w| w[0] < w[1]));
     /// ```
     fn skip_any(self, n: usize) -> SkipAny<Self> {
         SkipAny::new(self, n)

src/iter/skip_any.rs

@@ -2,7 +2,7 @@ use super::plumbing::*;
 use super::*;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
-/// `SkipAny` is an iterator that skips over the first `n` elements.
+/// `SkipAny` is an iterator that skips over `n` elements from anywhere in `I`.
 /// This struct is created by the [`skip_any()`] method on [`ParallelIterator`]
 ///
 /// [`skip_any()`]: trait.ParallelIterator.html#method.skip_any

src/iter/take_any.rs

@@ -2,7 +2,7 @@ use super::plumbing::*;
 use super::*;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
-/// `TakeAny` is an iterator that iterates over the first `n` elements.
+/// `TakeAny` is an iterator that iterates over `n` elements from anywhere in `I`.
 /// This struct is created by the [`take_any()`] method on [`ParallelIterator`]
 ///
 /// [`take_any()`]: trait.ParallelIterator.html#method.take_any