Update some documentation

Author: tobz1000

src/lib.rs

@@ -1145,9 +1145,6 @@ pub trait Itertools : Iterator {
     /// Iterator element type is `Vec<Self::Item>`. The iterator produces a new Vec per iteration,
     /// and clones the iterator elements.
     ///
-    /// If the input iterator is empty, or `k` is 0, or `k` greater than the
-    /// length of the input iterator, the resultant iterator adaptor will be empty.
-    ///
     /// ```
     /// use itertools::Itertools;
     ///
@@ -1243,6 +1240,8 @@ pub trait Itertools : Iterator {
     /// ]);
     /// ```
     ///
+    /// Note: The source iterator is collected lazily, and will not be
+    /// re-iterated if the permutations adaptor is completed and re-iterated.
     #[cfg(feature = "use_std")]
     fn permutations(self, k: usize) -> Permutations<Self>
         where Self: Sized,

src/permutations.rs

@@ -3,15 +3,11 @@ use std::iter::once;
 
 use super::lazy_buffer::LazyBuffer;
 
-/// An iterator to iterate through all the `k`-permutations of a series of items.
+/// An iterator adaptor that iterates through all the `k`-permutations of the
+/// elements from an iterator.
 ///
-/// Source items are distinguished by their position, not value; so if there
-/// are identical items in the source, there will be some identical permutation
-/// iterations.
-///
-/// Can be constructed from an in-memory list of items directly; or from an
-/// iterator, with the
-/// [`.permuatations()`](../trait.Itertools.html#method.permutations) method.
+/// See [`.permutations()`](../trait.Itertools.html#method.permutations) for
+/// more information.
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Permutations<I: Iterator> {
     vals: LazyBuffer<I>,