From dbcd9ffc984142fa3a3e7316bbb073efc7280ffc Mon Sep 17 00:00:00 2001 From: olegnn Date: Fri, 7 Feb 2020 15:51:49 +0300 Subject: [PATCH 1/2] Misc docs fixes --- futures-channel/src/mpsc/mod.rs | 16 +++++++------- futures-channel/src/oneshot.rs | 2 +- futures-executor/src/unpark_mutex.rs | 2 +- futures-util/src/io/mod.rs | 2 +- futures-util/src/stream/stream/mod.rs | 26 ++++++++++++++++------- futures-util/src/stream/try_stream/mod.rs | 11 +++++++--- futures/tests/stream.rs | 6 +++--- 7 files changed, 40 insertions(+), 25 deletions(-) diff --git a/futures-channel/src/mpsc/mod.rs b/futures-channel/src/mpsc/mod.rs index f69f440439..bce5e2e1e0 100644 --- a/futures-channel/src/mpsc/mod.rs +++ b/futures-channel/src/mpsc/mod.rs @@ -109,7 +109,7 @@ struct BoundedSenderInner { // unblocked. sender_task: Arc>, - // True if the sender might be blocked. This is an optimization to avoid + // `true` if the sender might be blocked. This is an optimization to avoid // having to lock the mutex most of the time. maybe_parked: bool, } @@ -189,7 +189,7 @@ impl fmt::Display for SendError { impl std::error::Error for SendError {} impl SendError { - /// Returns true if this error is a result of the channel being full. + /// Returns `true` if this error is a result of the channel being full. pub fn is_full(&self) -> bool { match self.kind { SendErrorKind::Full => true, @@ -197,7 +197,7 @@ impl SendError { } } - /// Returns true if this error is a result of the receiver being dropped. + /// Returns `true` if this error is a result of the receiver being dropped. pub fn is_disconnected(&self) -> bool { match self.kind { SendErrorKind::Disconnected => true, @@ -227,12 +227,12 @@ impl fmt::Display for TrySendError { impl std::error::Error for TrySendError {} impl TrySendError { - /// Returns true if this error is a result of the channel being full. + /// Returns `true` if this error is a result of the channel being full. pub fn is_full(&self) -> bool { self.err.is_full() } - /// Returns true if this error is a result of the receiver being dropped. + /// Returns `true` if this error is a result of the receiver being dropped. pub fn is_disconnected(&self) -> bool { self.err.is_disconnected() } @@ -536,7 +536,7 @@ impl BoundedSenderInner { // This operation will also atomically determine if the sender task // should be parked. // - // None is returned in the case that the channel has been closed by the + // `None` is returned in the case that the channel has been closed by the // receiver. This happens when `Receiver::close` is called or the // receiver is dropped. let park_self = match self.inc_num_messages() { @@ -997,7 +997,7 @@ impl Receiver { /// no longer empty. /// /// This function will panic if called after `try_next` or `poll_next` has - /// returned None. + /// returned `None`. pub fn try_next(&mut self) -> Result, TryRecvError> { match self.next_message() { Poll::Ready(msg) => { @@ -1127,7 +1127,7 @@ impl UnboundedReceiver { /// no longer empty. /// /// This function will panic if called after `try_next` or `poll_next` has - /// returned None. + /// returned `None`. pub fn try_next(&mut self) -> Result, TryRecvError> { match self.next_message() { Poll::Ready(msg) => { diff --git a/futures-channel/src/oneshot.rs b/futures-channel/src/oneshot.rs index d3be67e71e..d9f21d3083 100644 --- a/futures-channel/src/oneshot.rs +++ b/futures-channel/src/oneshot.rs @@ -126,7 +126,7 @@ impl Inner { } // Note that this lock acquisition may fail if the receiver - // is closed and sets the `complete` flag to true, whereupon + // is closed and sets the `complete` flag to `true`, whereupon // the receiver may call `poll()`. if let Some(mut slot) = self.data.try_lock() { assert!(slot.is_none()); diff --git a/futures-executor/src/unpark_mutex.rs b/futures-executor/src/unpark_mutex.rs index 3497faac12..1f69aed756 100644 --- a/futures-executor/src/unpark_mutex.rs +++ b/futures-executor/src/unpark_mutex.rs @@ -108,7 +108,7 @@ impl UnparkMutex { self.status.store(POLLING, SeqCst); } - /// Alert the mutex that polling completed with NotReady. + /// Alert the mutex that polling completed with `Pending`. /// /// # Safety /// diff --git a/futures-util/src/io/mod.rs b/futures-util/src/io/mod.rs index 43f183f424..9f10bce308 100644 --- a/futures-util/src/io/mod.rs +++ b/futures-util/src/io/mod.rs @@ -312,7 +312,7 @@ pub trait AsyncReadExt: AsyncRead { /// use futures::io::{self, AsyncReadExt, Cursor}; /// /// // Note that for `Cursor` the read and write halves share a single - /// // seek position. This may or may not be true for other types that + /// // seek position. This may or may not be `true` for other types that /// // implement both `AsyncRead` and `AsyncWrite`. /// /// let reader = Cursor::new([1, 2, 3, 4]); diff --git a/futures-util/src/stream/stream/mod.rs b/futures-util/src/stream/stream/mod.rs index da5ade85bb..d1f6b09c5b 100644 --- a/futures-util/src/stream/stream/mod.rs +++ b/futures-util/src/stream/stream/mod.rs @@ -315,7 +315,9 @@ pub trait StreamExt: Stream { /// /// Note that this function consumes the stream passed into it and returns a /// wrapped version of it, similar to the existing `filter` methods in the - /// standard library. + /// standard library. Because of current HRTB limitations, reference to item + /// can't be captured by the future. When it will be possible, method's signature + /// may be changed. /// /// # Examples /// @@ -544,10 +546,14 @@ pub trait StreamExt: Stream { Flatten::new(self) } - /// Combinator similar to [`StreamExt::fold`] that holds internal state and produces a new stream. + /// Combinator similar to [`StreamExt::fold`] that holds internal state + /// and produces a new stream. /// - /// Accepts initial state and closure which will be applied to each element of the stream until provided closure - /// returns `None`. Once `None` is returned, stream will be terminated. + /// Accepts initial state and closure which will be applied to each element + /// of the stream until provided closure returns `None`. Once `None` is + /// returned, stream will be terminated. Because of current HRTB limitations, + /// `&mut` state can't be captured by the future. When it will be possible, + /// method's signature may be changed. /// /// # Examples /// @@ -580,8 +586,10 @@ pub trait StreamExt: Stream { /// /// This function, like `Iterator::skip_while`, will skip elements on the /// stream until the predicate `f` resolves to `false`. Once one element - /// returns false all future elements will be returned from the underlying - /// stream. + /// returns `false`, all future elements will be returned from the underlying + /// stream. Because of current HRTB limitations, reference to item can't be + /// captured by the future. When it will be possible, method's signature may + /// be changed. /// /// # Examples /// @@ -611,7 +619,9 @@ pub trait StreamExt: Stream { /// /// This function, like `Iterator::take_while`, will take elements from the /// stream until the predicate `f` resolves to `false`. Once one element - /// returns false it will always return that the stream is done. + /// returns `false` it will always return that the stream is done. Because + /// of current HRTB limitations, reference to item can't be captured by + /// the future. When it will be possible, method's signature may be changed. /// /// # Examples /// @@ -1117,7 +1127,7 @@ pub trait StreamExt: Stream { Forward::new(self, sink) } - /// Splits this `Stream + Sink` object into separate `Stream` and `Sink` + /// Splits this `Stream + Sink` object into separate `Sink` and `Stream` /// objects. /// /// This can be useful when you want to split ownership between tasks, or diff --git a/futures-util/src/stream/try_stream/mod.rs b/futures-util/src/stream/try_stream/mod.rs index 6a7ced4f8c..06119b1bac 100644 --- a/futures-util/src/stream/try_stream/mod.rs +++ b/futures-util/src/stream/try_stream/mod.rs @@ -385,8 +385,11 @@ pub trait TryStreamExt: TryStream { /// Skip elements on this stream while the provided asynchronous predicate /// resolves to `true`. /// - /// This function is similar to [`StreamExt::skip_while`](crate::stream::StreamExt::skip_while) - /// but exits early if an error occurs. + /// This function is similar to + /// [`StreamExt::skip_while`](crate::stream::StreamExt::skip_while) but exits + /// early if an error occurs. Because of current HRTB limitations, `Self::Ok` + /// reference can't be captured by the future. When it will be possible, + /// method's signature may be changed. /// /// # Examples /// @@ -517,7 +520,9 @@ pub trait TryStreamExt: TryStream { /// /// Note that this function consumes the stream passed into it and returns a /// wrapped version of it, similar to the existing `filter` methods in - /// the standard library. + /// the standard library. Because of current HRTB limitations, `Self::Ok` + /// reference can't be captured by the future. When it will be possible, + /// method's signature may be changed. /// /// # Examples /// ``` diff --git a/futures/tests/stream.rs b/futures/tests/stream.rs index fd6a8b6da7..54f49c668d 100644 --- a/futures/tests/stream.rs +++ b/futures/tests/stream.rs @@ -20,9 +20,9 @@ fn scan() { futures::executor::block_on(async { assert_eq!( stream::iter(vec![1u8, 2, 3, 4, 6, 8, 2]) - .scan(1, |acc, e| { - *acc += 1; - futures::future::ready(if e < *acc { Some(e) } else { None }) + .scan(1, |state, e| { + *state += 1; + futures::future::ready(if e < *state { Some(e) } else { None }) }) .collect::>() .await, From 7fa1a5087708153a2dcdecfaa880438ad7336818 Mon Sep 17 00:00:00 2001 From: olegnn Date: Thu, 13 Feb 2020 00:50:30 +0300 Subject: [PATCH 2/2] Fixes --- futures-util/src/io/mod.rs | 2 +- futures-util/src/stream/stream/mod.rs | 16 ++++------------ futures-util/src/stream/try_stream/mod.rs | 8 ++------ 3 files changed, 7 insertions(+), 19 deletions(-) diff --git a/futures-util/src/io/mod.rs b/futures-util/src/io/mod.rs index 9f10bce308..43f183f424 100644 --- a/futures-util/src/io/mod.rs +++ b/futures-util/src/io/mod.rs @@ -312,7 +312,7 @@ pub trait AsyncReadExt: AsyncRead { /// use futures::io::{self, AsyncReadExt, Cursor}; /// /// // Note that for `Cursor` the read and write halves share a single - /// // seek position. This may or may not be `true` for other types that + /// // seek position. This may or may not be true for other types that /// // implement both `AsyncRead` and `AsyncWrite`. /// /// let reader = Cursor::new([1, 2, 3, 4]); diff --git a/futures-util/src/stream/stream/mod.rs b/futures-util/src/stream/stream/mod.rs index d1f6b09c5b..4f227326f0 100644 --- a/futures-util/src/stream/stream/mod.rs +++ b/futures-util/src/stream/stream/mod.rs @@ -315,9 +315,7 @@ pub trait StreamExt: Stream { /// /// Note that this function consumes the stream passed into it and returns a /// wrapped version of it, similar to the existing `filter` methods in the - /// standard library. Because of current HRTB limitations, reference to item - /// can't be captured by the future. When it will be possible, method's signature - /// may be changed. + /// standard library. /// /// # Examples /// @@ -551,9 +549,7 @@ pub trait StreamExt: Stream { /// /// Accepts initial state and closure which will be applied to each element /// of the stream until provided closure returns `None`. Once `None` is - /// returned, stream will be terminated. Because of current HRTB limitations, - /// `&mut` state can't be captured by the future. When it will be possible, - /// method's signature may be changed. + /// returned, stream will be terminated. /// /// # Examples /// @@ -587,9 +583,7 @@ pub trait StreamExt: Stream { /// This function, like `Iterator::skip_while`, will skip elements on the /// stream until the predicate `f` resolves to `false`. Once one element /// returns `false`, all future elements will be returned from the underlying - /// stream. Because of current HRTB limitations, reference to item can't be - /// captured by the future. When it will be possible, method's signature may - /// be changed. + /// stream. /// /// # Examples /// @@ -619,9 +613,7 @@ pub trait StreamExt: Stream { /// /// This function, like `Iterator::take_while`, will take elements from the /// stream until the predicate `f` resolves to `false`. Once one element - /// returns `false` it will always return that the stream is done. Because - /// of current HRTB limitations, reference to item can't be captured by - /// the future. When it will be possible, method's signature may be changed. + /// returns `false`, it will always return that the stream is done. /// /// # Examples /// diff --git a/futures-util/src/stream/try_stream/mod.rs b/futures-util/src/stream/try_stream/mod.rs index 06119b1bac..45a57ed7d1 100644 --- a/futures-util/src/stream/try_stream/mod.rs +++ b/futures-util/src/stream/try_stream/mod.rs @@ -387,9 +387,7 @@ pub trait TryStreamExt: TryStream { /// /// This function is similar to /// [`StreamExt::skip_while`](crate::stream::StreamExt::skip_while) but exits - /// early if an error occurs. Because of current HRTB limitations, `Self::Ok` - /// reference can't be captured by the future. When it will be possible, - /// method's signature may be changed. + /// early if an error occurs. /// /// # Examples /// @@ -520,9 +518,7 @@ pub trait TryStreamExt: TryStream { /// /// Note that this function consumes the stream passed into it and returns a /// wrapped version of it, similar to the existing `filter` methods in - /// the standard library. Because of current HRTB limitations, `Self::Ok` - /// reference can't be captured by the future. When it will be possible, - /// method's signature may be changed. + /// the standard library. /// /// # Examples /// ```