Misc docs fixes

Author: olegnn

futures-channel/src/mpsc/mod.rs

@@ -109,7 +109,7 @@ struct BoundedSenderInner<T> {
     // unblocked.
     sender_task: Arc<Mutex<SenderTask>>,
 
-    // 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,15 +189,15 @@ 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,
             _ => false,
         }
     }
 
-    /// 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<T> fmt::Display for TrySendError<T> {
 impl<T: core::any::Any> std::error::Error for TrySendError<T> {}
 
 impl<T> TrySendError<T> {
-    /// 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<T> BoundedSenderInner<T> {
         // 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<T> Receiver<T> {
     /// 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<Option<T>, TryRecvError> {
         match self.next_message() {
             Poll::Ready(msg) => {
@@ -1127,7 +1127,7 @@ impl<T> UnboundedReceiver<T> {
     /// 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<Option<T>, TryRecvError> {
         match self.next_message() {
             Poll::Ready(msg) => {

futures-channel/src/oneshot.rs

@@ -126,7 +126,7 @@ impl<T> Inner<T> {
         }
 
         // 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());

futures-executor/src/unpark_mutex.rs

@@ -108,7 +108,7 @@ impl<D> UnparkMutex<D> {
         self.status.store(POLLING, SeqCst);
     }
 
-    /// Alert the mutex that polling completed with NotReady.
+    /// Alert the mutex that polling completed with `Pending`.
     ///
     /// # Safety
     ///

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]);

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

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
     /// ```

futures/tests/stream.rs

@@ -21,8 +21,8 @@ fn scan() {
         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 })
+                    *state += 1;
+                    futures::future::ready(if e < *state { Some(e) } else { None })
                 })
                 .collect::<Vec<_>>()
                 .await,