Repository: tokio-rs/tokio
File: tokio-stream/src/stream_close.rs (Rust)

Code before:
    ///     map.insert(1, stream2);
    ///     while let Some((key, val)) = map.next().await {
    ///         match val {
    ///             Some(val) => println!("got {val:?} from stream {key:?}"),
    ///             None => println!("stream {key:?} closed"),
    ///         }
    ///     }
    /// }
    /// ```
    #[must_use = "streams do nothing unless polled"]
    pub struct StreamNotifyClose<S> {
        #[pin]
        inner: Option<S>,
    }
}

impl<S> StreamNotifyClose<S> {
    /// Create a new `StreamNotifyClose`.
    pub fn new(stream: S) -> Self {
        Self {
            inner: Some(stream),
        }
    }

    /// Get back the inner `Stream`.
    /// Returns `None` if the stream has reached its end.
    pub fn into_inner(self) -> Option<S> {
        self.inner
    }
}

impl<S> Stream for StreamNotifyClose<S>
where
    S: Stream,
{
    type Item = Option<S::Item>;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        // We can't invoke poll_next after it ended, so we unset the inner stream as a marker.
        match self
            .as_mut()
            .project()
            .inner
            .as_pin_mut()
            .map(|stream| S::poll_next(stream, cx))
        {
            Some(Poll::Ready(Some(item))) => Poll::Ready(Some(Some(item))),
            Some(Poll::Ready(None)) => {
                self.project().inner.set(None);
                Poll::Ready(Some(None))
            }

Review comment (suggestion):
You need an empty line for there to be a line break in the generated documentation.
```suggestion
    /// Get back the inner `Stream`.
    ///
    /// Returns `None` if the stream has reached its end.
```

Code after:
    ///     map.insert(1, stream2);
    ///     while let Some((key, val)) = map.next().await {
    ///         match val {
    ///             Some(val) => println!("got {val:?} from stream {key:?}"),
    ///             None => println!("stream {key:?} closed"),
    ///         }
    ///     }
    /// }
    /// ```
    #[must_use = "streams do nothing unless polled"]
    pub struct StreamNotifyClose<S> {
        #[pin]
        inner: Option<S>,
    }
}

impl<S> StreamNotifyClose<S> {
    /// Create a new `StreamNotifyClose`.
    pub fn new(stream: S) -> Self {
        Self {
            inner: Some(stream),
        }
    }

    /// Get back the inner `Stream`.
    ///
    /// Returns `None` if the stream has reached its end.
    pub fn into_inner(self) -> Option<S> {
        self.inner
    }
}

impl<S> Stream for StreamNotifyClose<S>
where
    S: Stream,
{
    type Item = Option<S::Item>;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        // We can't invoke poll_next after it ended, so we unset the inner stream as a marker.
        match self
            .as_mut()
            .project()
            .inner
            .as_pin_mut()
            .map(|stream| S::poll_next(stream, cx))
        {
            Some(Poll::Ready(Some(item))) => Poll::Ready(Some(Some(item))),
            Some(Poll::Ready(None)) => {
                self.project().inner.set(None);
                Poll::Ready(Some(None))