rewrite iterator `Default` tests as doctests

9 files changed, 67 insertions, 9 deletions

diff --git a/library/core/src/iter/adapters/chain.rs b/library/core/src/iter/adapters/chain.rs
index 21fc3bc6f6f..0f5e3718408 100644
--- a/library/core/src/iter/adapters/chain.rs
+++ b/library/core/src/iter/adapters/chain.rs
@@ -288,6 +288,21 @@ where
     A: Iterator + Default,
     B: Iterator + Default,
 {
+    /// Creates a `Chain` from the default values for `A` and `B`.
+    ///
+    /// ```
+    /// # use core::iter::Chain;
+    /// # use core::slice;
+    /// # use std::collections::{btree_set, BTreeSet};
+    /// # use std::mem;
+    /// struct Foo<'a>(Chain<slice::Iter<'a, u8>, btree_set::Iter<'a, u8>>);
+    ///
+    /// let set = BTreeSet::<u8>::new();
+    /// let slice: &[u8] = &[];
+    /// let mut foo = Foo(slice.iter().chain(set.iter()));
+    ///
+    /// // take requires `Default`
+    /// let _: Chain<_, _> = mem::take(&mut foo.0);
     fn default() -> Self {
         Chain::new(Default::default(), Default::default())
     }
diff --git a/library/core/src/iter/adapters/cloned.rs b/library/core/src/iter/adapters/cloned.rs
index d22a6e721f5..b9e2700860c 100644
--- a/library/core/src/iter/adapters/cloned.rs
+++ b/library/core/src/iter/adapters/cloned.rs
@@ -160,6 +160,13 @@ where
     I: Default + Iterator<Item = &'a T>,
     T: Clone,
 {
+    /// Creates a `Cloned` iterator from the default value of `I`
+    /// ```
+    /// # use core::slice;
+    /// # use core::iter::Cloned;
+    /// let iter: Cloned<slice::Iter<'_, u8>> = Default::default();
+    /// assert_eq!(iter.len(), 0);
+    /// ```
     fn default() -> Self {
         Self::new(Default::default())
     }
diff --git a/library/core/src/iter/adapters/copied.rs b/library/core/src/iter/adapters/copied.rs
index d5e579834ee..0aa466e37a2 100644
--- a/library/core/src/iter/adapters/copied.rs
+++ b/library/core/src/iter/adapters/copied.rs
@@ -247,6 +247,13 @@ where
     I: Default + Iterator<Item = &'a T>,
     T: Copy,
 {
+    /// Creates a `Copied` iterator from the default value of `I`
+    /// ```
+    /// # use core::slice;
+    /// # use core::iter::Copied;
+    /// let iter: Copied<slice::Iter<'_, u8>> = Default::default();
+    /// assert_eq!(iter.len(), 0);
+    /// ```
     fn default() -> Self {
         Self::new(Default::default())
     }
diff --git a/library/core/src/iter/adapters/enumerate.rs b/library/core/src/iter/adapters/enumerate.rs
index 0b44139a83b..5b0025cb984 100644
--- a/library/core/src/iter/adapters/enumerate.rs
+++ b/library/core/src/iter/adapters/enumerate.rs
@@ -270,6 +270,13 @@ impl<I> Default for Enumerate<I>
 where
     I: Iterator + Default,
 {
+    /// Creates an `Enumerate` iterator from the default value of `I`
+    /// ```
+    /// # use core::slice;
+    /// # use std::iter::Enumerate;
+    /// let iter: Enumerate<slice::Iter<'_, u8>> = Default::default();
+    /// assert_eq!(iter.len(), 0);
+    /// ```
     fn default() -> Self {
         Enumerate::new(Default::default())
     }
diff --git a/library/core/src/iter/adapters/flatten.rs b/library/core/src/iter/adapters/flatten.rs
index c0a347a7c1d..cb68c807bf5 100644
--- a/library/core/src/iter/adapters/flatten.rs
+++ b/library/core/src/iter/adapters/flatten.rs
@@ -308,6 +308,14 @@ where
     I: Iterator + Default,
     <I as Iterator>::Item: IntoIterator,
 {
+    /// Creates a `Flatten` iterator from the default value of `I`.
+    ///
+    /// ```
+    /// # use core::slice;
+    /// # use std::iter::Flatten;
+    /// let iter: Flatten<slice::Iter<'_, [u8; 4]>> = Default::default();
+    /// assert_eq!(iter.count(), 0);
+    /// ```
     fn default() -> Self {
         Flatten::new(Default::default())
     }
diff --git a/library/core/src/iter/adapters/fuse.rs b/library/core/src/iter/adapters/fuse.rs
index 87275fa3951..de91c188eeb 100644
--- a/library/core/src/iter/adapters/fuse.rs
+++ b/library/core/src/iter/adapters/fuse.rs
@@ -183,6 +183,14 @@ where
 
 #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")]
 impl<I: Default> Default for Fuse<I> {
+    /// Creates a `Fuse` iterator from the default value of `I`.
+    ///
+    /// ```
+    /// # use core::slice;
+    /// # use std::iter::Fuse;
+    /// let iter: Fuse<slice::Iter<'_, u8>> = Default::default();
+    /// assert_eq!(iter.len(), 0);
+    /// ```
     fn default() -> Self {
         Fuse { iter: Default::default() }
     }
diff --git a/library/core/src/iter/adapters/rev.rs b/library/core/src/iter/adapters/rev.rs
index 4ad75ec0ea2..0b132e13813 100644
--- a/library/core/src/iter/adapters/rev.rs
+++ b/library/core/src/iter/adapters/rev.rs
@@ -141,6 +141,13 @@ impl<I> Default for Rev<I>
 where
     I: Default + Iterator,
 {
+    /// Creates a `Rev` iterator from the default value of `I`
+    /// ```
+    /// # use core::slice;
+    /// # use core::iter::Rev;
+    /// let iter: Rev<slice::Iter<'_, u8>> = Default::default();
+    /// assert_eq!(iter.len(), 0);
+    /// ```
     fn default() -> Self {
         Rev::new(Default::default())
     }
diff --git a/library/core/src/slice/iter/macros.rs b/library/core/src/slice/iter/macros.rs
index 57754182c4e..a800da546b4 100644
--- a/library/core/src/slice/iter/macros.rs
+++ b/library/core/src/slice/iter/macros.rs
@@ -396,6 +396,13 @@ macro_rules! iterator {
 
         #[stable(feature = "default_iters", since = "CURRENT_RUSTC_VERSION")]
         impl<T> Default for $name<'_, T> {
+            /// Creates an empty slice iterator.
+            ///
+            /// ```
+            #[doc = concat!("# use core::slice::", stringify!($name), ";")]
+            #[doc = concat!("let iter: ", stringify!($name<'_, u8>), " = Default::default();")]
+            /// assert_eq!(iter.len(), 0);
+            /// ```
             fn default() -> Self {
                 (& $( $mut_ )? []).into_iter()
             }
diff --git a/library/core/tests/slice.rs b/library/core/tests/slice.rs
index 294de77a6b0..39559cdbb5e 100644
--- a/library/core/tests/slice.rs
+++ b/library/core/tests/slice.rs
@@ -1,10 +1,8 @@
 use core::cell::Cell;
 use core::cmp::Ordering;
-use core::iter::ExactSizeIterator;
 use core::mem::MaybeUninit;
 use core::result::Result::{Err, Ok};
-use core::slice::Iter;
-use core::{assert_eq, slice};
+use core::slice;
 
 #[test]
 fn test_position() {
@@ -227,12 +225,6 @@ fn test_iterator_count() {
 }
 
 #[test]
-fn test_iterator_default() {
-    let iter: Iter<'_, u8> = Iter::default();
-    assert_eq!(iter.len(), 0);
-}
-
-#[test]
 fn test_chunks_count() {
     let v: &[i32] = &[0, 1, 2, 3, 4, 5];
     let c = v.chunks(3);