Added more documentation

Author: slerpyyy

library/core/src/iter/traits/iterator.rs

@@ -1700,6 +1700,8 @@ pub trait Iterator {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// #![feature(iter_dedup)]
     ///
@@ -1713,6 +1715,15 @@ pub trait Iterator {
     /// assert_eq!(iter.next(), Some(2));
     /// assert_eq!(iter.next(), None);
     /// ```
+    ///
+    /// Example of an infinite loop:
+    ///
+    /// ```no_run
+    /// #![feature(iter_dedup)]
+    ///
+    /// // this will never terminate
+    /// let _ = std::iter::repeat(2).dedup().next();
+    /// ```
     #[unstable(feature = "iter_dedup", reason = "recently added", issue = "83748")]
     #[inline]
     fn dedup(self) -> Dedup<Self, ByPartialEq, Self::Item>
@@ -1736,6 +1747,8 @@ pub trait Iterator {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// #![feature(iter_dedup)]
     ///
@@ -1749,6 +1762,15 @@ pub trait Iterator {
     /// assert_eq!(iter.next(), Some("bar"));
     /// assert_eq!(iter.next(), None);
     /// ```
+    ///
+    /// Example of an infinite loop:
+    ///
+    /// ```no_run
+    /// #![feature(iter_dedup)]
+    ///
+    /// // this will never terminate
+    /// let _ = std::iter::repeat(2).dedup_by(|a, b| a == b).next();
+    /// ```
     #[unstable(feature = "iter_dedup", reason = "recently added", issue = "83748")]
     #[inline]
     fn dedup_by<F>(self, same_bucket: F) -> Dedup<Self, F, Self::Item>
@@ -1769,6 +1791,8 @@ pub trait Iterator {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// #![feature(iter_dedup)]
     ///
@@ -1782,6 +1806,15 @@ pub trait Iterator {
     /// assert_eq!(iter.next(), Some(20));
     /// assert_eq!(iter.next(), None);
     /// ```
+    ///
+    /// Example of an infinite loop:
+    ///
+    /// ```no_run
+    /// #![feature(iter_dedup)]
+    ///
+    /// // this will never terminate
+    /// let _ = std::iter::repeat(2).dedup_by_key(|&n| n).next();
+    /// ```
     #[unstable(feature = "iter_dedup", reason = "recently added", issue = "83748")]
     #[inline]
     fn dedup_by_key<F, K>(self, key: F) -> Dedup<Self, ByKey<F>, Self::Item>