std: Add Vec::from_iter comment

Requested by Niko in rust-lang#22200 (and is good to have anyway)

Author: alexcrichton

src/libcollections/vec.rs

@@ -1387,6 +1387,17 @@ impl<T> FromIterator<T> for Vec<T> {
         let (lower, _) = iterator.size_hint();
         let mut vector = Vec::with_capacity(lower);
 
+        // This function should be the moral equivalent of:
+        //
+        //      for item in iterator {
+        //          vector.push(item);
+        //      }
+        //
+        // This equivalent crucially runs the iterator precisely once. The
+        // optimization below (eliding bound/growth checks) means that we
+        // actually run the iterator twice. To ensure the "moral equivalent" we
+        // do a `fuse()` operation to ensure that the iterator continues to
+        // return `None` after seeing the first `None`.
         let mut i = iterator.fuse();
         for element in i.by_ref().take(vector.capacity()) {
             let len = vector.len();