renamed some items and improved docs for clarity

Author: Erik Rhodes

src/lib.rs

@@ -1397,7 +1397,7 @@ pub trait Itertools : Iterator {
     ///
     /// The [`.take_while()`][std::iter::Iterator::take_while] adaptor is useful
     /// when you want items satisfying a predicate, but to know when to stop
-    /// taking elements, we have to consume that last element that doesn't
+    /// taking elements, we have to consume that first element that doesn't
     /// satisfy the predicate. This adaptor includes that element where
     /// [`.take_while()`][std::iter::Iterator::take_while] would drop it.
     ///
@@ -1407,7 +1407,6 @@ pub trait Itertools : Iterator {
     ///
     /// ```rust
     /// # use itertools::Itertools;
-    ///
     /// let items = vec![1, 2, 3, 4, 5];
     /// let filtered: Vec<_> = items
     ///     .into_iter()
@@ -1421,18 +1420,20 @@ pub trait Itertools : Iterator {
     /// # use itertools::Itertools;
     /// let items = vec![1, 2, 3, 4, 5];
     ///
-    /// let take_until_result: Vec<_> = items
-    ///     .clone()
-    ///     .into_iter()
+    /// let take_while_inclusive_result: Vec<_> = items
+    ///     .iter()
+    ///     .copied()
     ///     .take_while_inclusive(|&n| n % 3 != 0)
     ///     .collect();
     /// let take_while_result: Vec<_> = items
     ///     .into_iter()
     ///     .take_while(|&n| n % 3 != 0)
     ///     .collect();
     ///
-    /// assert_eq!(take_until_result, vec![1, 2, 3]);
+    /// assert_eq!(take_while_inclusive_result, vec![1, 2, 3]);
     /// assert_eq!(take_while_result, vec![1, 2]);
+    /// // both iterators have the same items remaining at this point---the 3
+    /// // is lost from the `take_while` vec
     /// ```
     ///
     /// ```rust
@@ -2763,7 +2764,6 @@ pub trait Itertools : Iterator {
     /// itertools::assert_equal(oldest_people_first,
     ///                         vec!["Jill", "Jack", "Jane", "John"]);
     /// ```
-    /// ```
     #[cfg(feature = "use_alloc")]
     fn sorted_by_cached_key<K, F>(self, f: F) -> VecIntoIter<Self::Item>
     where

src/take_while_inclusive.rs

@@ -1,14 +1,16 @@
 use core::iter::FusedIterator;
 use std::fmt;
 
-/// An iterator adaptor that consumes elements while the given predicate is `true`, including the
-/// element for which the predicate first returned `false`.
+/// An iterator adaptor that consumes elements while the given predicate is
+/// `true`, including the element for which the predicate first returned
+/// `false`.
 ///
-/// See [`.take_while_inclusive()`](crate::Itertools::take_while_inclusive) for more information.
+/// See [`.take_while_inclusive()`](crate::Itertools::take_while_inclusive)
+/// for more information.
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct TakeWhileInclusive<'a, I: 'a, F> {
     iter: &'a mut I,
-    f: F,
+    predicate: F,
     done: bool,
 }
 
@@ -18,8 +20,8 @@ where
     F: FnMut(&I::Item) -> bool,
 {
     /// Create a new [`TakeWhileInclusive`] from an iterator and a predicate.
-    pub fn new(iter: &'a mut I, f: F) -> Self {
-        Self { iter, f, done: false}
+    pub fn new(iter: &'a mut I, predicate: F) -> Self {
+        Self { iter, predicate, done: false}
     }
 }
 
@@ -41,7 +43,7 @@ where
             None
         } else {
             self.iter.next().map(|item| {
-                if !(self.f)(&item) {
+                if !(self.predicate)(&item) {
                     self.done = true;
                 }
                 item