Merge pull request rust-lang#200 from tmiasko/stream-fuse-docs

Update documentation for stream::fuse.

src/stream/fuse.rs

@@ -3,10 +3,9 @@ use stream::Stream;
 
 /// A stream which "fuse"s a stream once it's terminated.
 ///
-/// Normally streams can behave unpredictably after they've terminated or
-/// returned an error, but `Fuse` is always defined to return `None` from `poll`
-/// after terination/errors, and afterwards all calls to `schedule` will be
-/// ignored.
+/// Normally streams can behave unpredictably when used after they have already
+/// finished, but `Fuse` continues to return `None` from `poll` forever when
+/// finished.
 #[must_use = "streams do nothing unless polled"]
 pub struct Fuse<S> {
     stream: Option<S>,
@@ -33,7 +32,7 @@ impl<S> Fuse<S> {
     /// Returns whether the underlying stream has finished or not.
     ///
     /// If this method returns `true`, then all future calls to poll are
-    /// guaranteed to return `NotReady`. If this returns `false`, then the
+    /// guaranteed to return `None`. If this returns `false`, then the
     /// underlying stream is still in use.
     pub fn is_done(&self) -> bool {
         self.stream.is_none()

src/stream/mod.rs

@@ -607,20 +607,18 @@ pub trait Stream {
         skip::new(self, amt)
     }
 
-    /// Fuse a stream such that `poll`/`schedule` will never again be called
-    /// once it has terminated (signaled emptyness or an error).
+    /// Fuse a stream such that `poll` will never again be called once it has
+    /// finished.
     ///
-    /// Currently once a stream has returned `Some(Ok(None))` from `poll` any further
+    /// Currently once a stream has returned `None` from `poll` any further
     /// calls could exhibit bad behavior such as block forever, panic, never
-    /// return, etc. If it is known that `poll` may be called too often then
-    /// this method can be used to ensure that it has defined semantics.
+    /// return, etc. If it is known that `poll` may be called after stream has
+    /// already finished, then this method can be used to ensure that it has
+    /// defined semantics.
     ///
-    /// Once a stream has been `fuse`d and it terminates, then
-    /// it will forever return `None` from `poll` again (never resolve). This,
-    /// unlike the trait's `poll` method, is guaranteed.
-    ///
-    /// Additionally, once a stream has completed, this `Fuse` combinator will
-    /// never call `schedule` on the underlying stream.
+    /// Once a stream has been `fuse`d and it finishes, then it will forever
+    /// return `None` from `poll`. This, unlike for the traits `poll` method,
+    /// is guaranteed.
     fn fuse(self) -> Fuse<Self>
         where Self: Sized
     {