fix some typos and add some examples that panic

Author: Takashiidobe

src/adaptors/mod.rs

@@ -522,7 +522,7 @@ where
     debug_fmt_fields!(TakeWhileRef, iter);
 }
 
-/// Create a new `TakeWhileRef` from a reference to clonable iterator.
+/// Create a new `TakeWhileRef` from a reference to cloneable iterator.
 pub fn take_while_ref<I, F>(iter: &mut I, f: F) -> TakeWhileRef<'_, I, F>
 where
     I: Iterator + Clone,
@@ -626,7 +626,7 @@ pub trait HasCombination<I>: Sized {
     type Combination: From<I> + Iterator<Item = Self>;
 }
 
-/// Create a new `TupleCombinations` from a clonable iterator.
+/// Create a new `TupleCombinations` from a cloneable iterator.
 pub fn tuple_combinations<T, I>(iter: I) -> TupleCombinations<I, T>
 where
     I: Iterator,

src/combinations.rs

@@ -14,15 +14,15 @@ pub type Combinations<I> = CombinationsGeneric<I, Vec<usize>>;
 /// Iterator for const generic combinations returned by [`.array_combinations()`](crate::Itertools::array_combinations)
 pub type ArrayCombinations<I, const K: usize> = CombinationsGeneric<I, [usize; K]>;
 
-/// Create a new `Combinations` from a clonable iterator.
+/// Create a new `Combinations` from a cloneable iterator.
 pub fn combinations<I: Iterator>(iter: I, k: usize) -> Combinations<I>
 where
     I::Item: Clone,
 {
     Combinations::new(iter, (0..k).collect())
 }
 
-/// Create a new `ArrayCombinations` from a clonable iterator.
+/// Create a new `ArrayCombinations` from a cloneable iterator.
 pub fn array_combinations<I: Iterator, const K: usize>(iter: I) -> ArrayCombinations<I, K>
 where
     I::Item: Clone,

src/combinations_with_replacement.rs

@@ -36,7 +36,7 @@ where
     debug_fmt_fields!(CombinationsWithReplacementGeneric, indices, pool, first);
 }
 
-/// Create a new `ArrayCombinationsWithReplacement`` from a clonable iterator.
+/// Create a new `ArrayCombinationsWithReplacement`` from a cloneable iterator.
 pub fn array_combinations_with_replacement<I: Iterator, const K: usize>(
     iter: I,
 ) -> ArrayCombinationsWithReplacement<I, K>
@@ -45,7 +45,7 @@ where
 {
     ArrayCombinationsWithReplacement::new(iter, [0; K])
 }
-/// Create a new `CombinationsWithReplacement` from a clonable iterator.
+/// Create a new `CombinationsWithReplacement` from a cloneable iterator.
 pub fn combinations_with_replacement<I>(iter: I, k: usize) -> CombinationsWithReplacement<I>
 where
     I: Iterator,

src/either_or_both.rs

@@ -467,7 +467,7 @@ impl<T> EitherOrBoth<T, T> {
     /// Return either value of left, right, or apply a function `f` to both values if both are present.
     /// The input function has to return the same type as both Right and Left carry.
     ///
-    /// This function can be used to preferrably extract the left resp. right value,
+    /// This function can be used to preferably extract the left resp. right value,
     /// but fall back to the other (i.e. right resp. left) if the preferred one is not present.
     ///
     /// # Examples

src/grouping_map.rs

@@ -46,7 +46,7 @@ where
 
 /// `GroupingMapBy` is an intermediate struct for efficient group-and-fold operations.
 ///
-/// See [`GroupingMap`] for more informations.
+/// See [`GroupingMap`] for more information.
 pub type GroupingMapBy<I, F> = GroupingMap<MapForGrouping<I, F>>;
 
 /// `GroupingMap` is an intermediate struct for efficient group-and-fold operations.

src/kmerge_impl.rs

@@ -97,7 +97,7 @@ where
     }
 }
 
-/// An iterator adaptor that merges an abitrary number of base iterators in ascending order.
+/// An iterator adaptor that merges an arbitrary number of base iterators in ascending order.
 /// If all base iterators are sorted (ascending), the result is sorted.
 ///
 /// Iterator element type is `I::Item`.
@@ -146,7 +146,7 @@ where
     kmerge_by(iterable, KMergeByLt)
 }
 
-/// An iterator adaptor that merges an abitrary number of base iterators
+/// An iterator adaptor that merges an arbitrary number of base iterators
 /// according to an ordering function.
 ///
 /// Iterator element type is `I::Item`.

src/lib.rs

@@ -622,6 +622,28 @@ pub trait Itertools: Iterator {
     ///
     /// **Panics** if the iterators reach an end and they are not of equal
     /// lengths.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use itertools::Itertools;
+    ///
+    /// let a = [1, 2];
+    /// let b = [3, 4];
+    ///
+    /// let zipped: Vec<_> = a.into_iter().zip_eq(b.into_iter()).collect();
+    ///
+    /// assert_eq!(zipped, vec![(1, 3), (2, 4)]);
+    /// ```
+    ///
+    /// ```should_panic
+    /// use itertools::Itertools;
+    ///
+    /// let a = [1, 2];
+    /// let b = [3, 4, 5];
+    /// // This example panics because the iterators are not of equal length.
+    /// let _zipped: Vec<_> = a.iter().zip_eq(b.iter()).collect();
+    /// ```
     #[inline]
     fn zip_eq<J>(self, other: J) -> ZipEq<Self, J::IntoIter>
     where
@@ -731,6 +753,8 @@ pub trait Itertools: Iterator {
     ///
     /// **Panics** if `size` is 0.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use itertools::Itertools;
     ///
@@ -744,6 +768,13 @@ pub trait Itertools: Iterator {
     ///     assert_eq!(4, chunk.sum());
     /// }
     /// ```
+    ///
+    /// ```should_panic
+    /// use itertools::Itertools;
+    /// let data = vec![1, 2, 3];
+    /// // Panics because chunk size is 0.
+    /// let _chunks = data.into_iter().chunks(0);
+    /// ```
     #[cfg(feature = "use_alloc")]
     fn chunks(self, size: usize) -> IntoChunks<Self>
     where
@@ -872,7 +903,7 @@ pub trait Itertools: Iterator {
     /// Split into an iterator pair that both yield all elements from
     /// the original iterator.
     ///
-    /// **Note:** If the iterator is clonable, prefer using that instead
+    /// **Note:** If the iterator is cloneable, prefer using that instead
     /// of using this method. Cloning is likely to be more efficient.
     ///
     /// Iterator element type is `Self::Item`.
@@ -1003,7 +1034,7 @@ pub trait Itertools: Iterator {
     /// as long as the original iterator produces `Ok` values.
     ///
     /// If the original iterable produces an error at any point, the adapted
-    /// iterator ends and it will return the error iself.
+    /// iterator ends and it will return the error itself.
     ///
     /// Otherwise, the return value from the closure is returned wrapped
     /// inside `Ok`.
@@ -1601,11 +1632,11 @@ pub trait Itertools: Iterator {
     /// #[derive(Debug, PartialEq)]
     /// struct NoCloneImpl(i32);
     ///
-    /// let non_clonable_items: Vec<_> = vec![1, 2, 3, 4, 5]
+    /// let non_cloneable_items: Vec<_> = vec![1, 2, 3, 4, 5]
     ///     .into_iter()
     ///     .map(NoCloneImpl)
     ///     .collect();
-    /// let filtered: Vec<_> = non_clonable_items
+    /// let filtered: Vec<_> = non_cloneable_items
     ///     .into_iter()
     ///     .take_while_inclusive(|n| n.0 % 3 != 0)
     ///     .collect();
@@ -3797,7 +3828,7 @@ pub trait Itertools: Iterator {
     /// value of type `K` will be used as key to identify the groups and the
     /// value of type `V` as value for the folding operation.
     ///
-    /// See [`GroupingMap`] for more informations
+    /// See [`GroupingMap`] for more information
     /// on what operations are available.
     #[cfg(feature = "use_std")]
     fn into_grouping_map<K, V>(self) -> GroupingMap<Self>
@@ -3814,7 +3845,7 @@ pub trait Itertools: Iterator {
     /// The values from this iterator will be used as values for the folding operation
     /// while the keys will be obtained from the values by calling `key_mapper`.
     ///
-    /// See [`GroupingMap`] for more informations
+    /// See [`GroupingMap`] for more information
     /// on what operations are available.
     #[cfg(feature = "use_std")]
     fn into_grouping_map_by<K, V, F>(self, key_mapper: F) -> GroupingMapBy<Self, F>
@@ -4334,7 +4365,7 @@ pub trait Itertools: Iterator {
         }
     }
 
-    /// Return the postions of the minimum and maximum elements of an
+    /// Return the positions of the minimum and maximum elements of an
     /// iterator, as determined by the specified function.
     ///
     /// The return value is a variant of [`MinMaxResult`] like for
@@ -4382,7 +4413,7 @@ pub trait Itertools: Iterator {
         }
     }
 
-    /// Return the postions of the minimum and maximum elements of an
+    /// Return the positions of the minimum and maximum elements of an
     /// iterator, as determined by the specified comparison function.
     ///
     /// The return value is a variant of [`MinMaxResult`] like for

src/powerset.rs

@@ -31,7 +31,7 @@ where
     debug_fmt_fields!(Powerset, combs);
 }
 
-/// Create a new `Powerset` from a clonable iterator.
+/// Create a new `Powerset` from a cloneable iterator.
 pub fn powerset<I>(src: I) -> Powerset<I>
 where
     I: Iterator,