Remove Stream::next

This is a temporary change only, as we wait to resolve dynamic dispatch issues. The `Stream::next` method and corresponding documentation are expected to be fully restored once we have a path to proceed.

Ref: https://github.com/rust-lang/rfcs/pull/2996#issuecomment-757386206

update docs

library/core/src/stream/mod.rs

@@ -16,13 +16,12 @@
 //!   exist and what you can do with them. The methods of these traits are worth
 //!   putting some extra study time into.
 //! * Functions provide some helpful ways to create some basic streams.
-//! * [Structs] are often the return types of the various methods on this
+//! * Structs are often the return types of the various methods on this
 //!   module's traits. You'll usually want to look at the method that creates
 //!   the `struct`, rather than the `struct` itself. For more detail about why,
 //!   see '[Implementing Stream](#implementing-stream)'.
 //!
 //! [Traits]: #traits
-//! [Structs]: #structs
 //!
 //! That's it! Let's dig into streams.
 //!
@@ -41,17 +40,17 @@
 //! ```
 //!
 //! Unlike `Iterator`, `Stream` makes a distinction between the [`poll_next`]
-//! method which is used when implementing a `Stream`, and the [`next`] method
+//! method which is used when implementing a `Stream`, and a (to-be-implemented)
-//! which is used when consuming a stream. Consumers of `Stream` only need to
+//! `next` method which is used when consuming a stream. Consumers of `Stream`
-//! consider [`next`], which when called, returns a future which yields
+//! only need to consider `next`, which when called, returns a future which
-//! yields [`Option`][`<Item>`].
+//! yields `Option<Stream::Item>`.
 //!
-//! The future returned by [`next`] will yield `Some(Item)` as long as there are
+//! The future returned by `next` will yield `Some(Item)` as long as there are
 //! elements, and once they've all been exhausted, will yield `None` to indicate
 //! that iteration is finished. If we're waiting on something asynchronous to
 //! resolve, the future will wait until the stream is ready to yield again.
 //!
-//! Individual streams may choose to resume iteration, and so calling [`next`]
+//! Individual streams may choose to resume iteration, and so calling `next`
 //! again may or may not eventually yield `Some(Item)` again at some point.
 //!
 //! [`Stream`]'s full definition includes a number of other methods as well,
@@ -60,8 +59,6 @@
 //!
 //! [`Poll`]: super::task::Poll
 //! [`poll_next`]: Stream::poll_next
-//! [`next`]: Stream::next
-//! [`<Item>`]: Stream::Item
 //!
 //! # Implementing Stream
 //!
@@ -112,36 +109,12 @@
 //!         }
 //!     }
 //! }
-//!
-//! // And now we can use it!
-//! # async fn run() {
-//! #
-//! let mut counter = Counter::new();
-//!
-//! let x = counter.next().await.unwrap();
-//! println!("{}", x);
-//!
-//! let x = counter.next().await.unwrap();
-//! println!("{}", x);
-//!
-//! let x = counter.next().await.unwrap();
-//! println!("{}", x);
-//!
-//! let x = counter.next().await.unwrap();
-//! println!("{}", x);
-//!
-//! let x = counter.next().await.unwrap();
-//! println!("{}", x);
-//! #
-//! }
 //! ```
 //!
-//! This will print `1` through `5`, each on their own line.
-//!
 //! # Laziness
 //!
 //! Streams are *lazy*. This means that just creating a stream doesn't _do_ a
-//! whole lot. Nothing really happens until you call [`next`]. This is sometimes a
+//! whole lot. Nothing really happens until you call `next`. This is sometimes a
 //! source of confusion when creating a stream solely for its side effects. The
 //! compiler will warn us about this kind of behavior:
 //!
@@ -151,4 +124,4 @@
 
 mod stream;
 
-pub use stream::{Next, Stream};
+pub use stream::Stream;

library/core/src/stream/stream/mod.rs

@@ -1,7 +1,3 @@
-mod next;
-
-pub use next::Next;
-
 use crate::ops::DerefMut;
 use crate::pin::Pin;
 use crate::task::{Context, Poll};
@@ -81,21 +77,6 @@ pub trait Stream {
     fn size_hint(&self) -> (usize, Option<usize>) {
         (0, None)
     }
-
-    /// Advances the stream and returns a future which yields the next value.
-    ///
-    /// The returned future yields [`None`] when iteration is finished.
-    /// Individual stream implementations may choose to resume iteration, and so
-    /// calling `next()` again may or may not eventually start yielding
-    /// [`Some(Item)`] again at some point.
-    ///
-    /// [`Some(Item)`]: Some
-    fn next(&mut self) -> Next<'_, Self>
-    where
-        Self: Unpin,
-    {
-        Next::new(self)
-    }
 }
 
 #[unstable(feature = "async_stream", issue = "79024")]

library/core/src/stream/stream/next.rs

@@ -1,30 +0,0 @@
-use crate::future::Future;
-use crate::pin::Pin;
-use crate::stream::Stream;
-use crate::task::{Context, Poll};
-
-/// A future which advances the stream and returns the next value.
-///
-/// This `struct` is created by [`Stream::next`]. See its documentation for more.
-#[unstable(feature = "async_stream", issue = "79024")]
-#[derive(Debug)]
-#[must_use = "futures do nothing unless you `.await` or poll them"]
-pub struct Next<'a, S: ?Sized> {
-    stream: &'a mut S,
-}
-
-impl<'a, S: ?Sized> Next<'a, S> {
-    /// Create a new instance of `Next`.
-    pub(crate) fn new(stream: &'a mut S) -> Self {
-        Self { stream }
-    }
-}
-
-#[unstable(feature = "async_stream", issue = "79024")]
-impl<S: Stream + Unpin + ?Sized> Future for Next<'_, S> {
-    type Output = Option<S::Item>;
-
-    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
-        Pin::new(&mut *self.stream).poll_next(cx)
-    }
-}