Adjust language as per suggestions

2 files changed, 11 insertions, 9 deletions

diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index da9af214207..23fded0669a 100644
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -25,10 +25,6 @@ fn _assert_is_object_safe(_: &Iterator<Item=()>) {}
 /// generally, please see the [module-level documentation]. In particular, you
 /// may want to know how to [implement `Iterator`][impl].
 ///
-/// Note: Methods on infinite iterators that generally require traversing every
-/// element to produce a result may not terminate, even on traits for which a
-/// result is determinable in finite time.
-///
 /// [module-level documentation]: index.html
 /// [impl]: index.html#implementing-iterator
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -1430,6 +1426,10 @@ pub trait Iterator {
     /// Folding is useful whenever you have a collection of something, and want
     /// to produce a single value from it.
     ///
+    /// Note: `fold()`, and similar methods that traverse the entire iterator,
+    /// may not terminate for infinite iterators, even on traits for which a
+    /// result is determinable in finite time.
+    ///
     /// # Examples
     ///
     /// Basic usage:
diff --git a/src/libcore/iter/mod.rs b/src/libcore/iter/mod.rs
index ae10ac385ab..d1fdedd1b23 100644
--- a/src/libcore/iter/mod.rs
+++ b/src/libcore/iter/mod.rs
@@ -299,15 +299,17 @@
 //! This will print the numbers `0` through `4`, each on their own line.
 //!
 //! Bear in mind that methods on infinite iterators, even those for which a
-//! result can be computed in finite time, may not terminate. Specifically,
-//! methods such as [`min`], which in the general case require traversing
-//! every element in the iterator, are likely never to terminate for any
-//! infinite iterators.
+//! result can be determined mathematically in finite time, may not terminate.
+//! Specifically, methods such as [`min`], which in the general case require
+//! traversing every element in the iterator, are likely not to return
+//! successfully for any infinite iterators.
 //!
 //! ```no_run
 //! let positives = 1..;
 //! let least = positives.min().unwrap(); // Oh no! An infinite loop!
-//! // `positives.min` causes an infinite loop, so we won't reach this point!
+//! // `positives.min` will either overflow and panic (in debug mode),
+//! // or cause an infinite loop (in release mode), so we won't reach
+//! // this point!
 //! println!("The least positive number is {}.", least);
 //! ```
 //!