Update FuturesOrdered docs

futures-util/src/stream/futures_ordered.rs

@@ -58,36 +58,39 @@ where
 
 /// An unbounded queue of futures.
 ///
-/// This "combinator" is similar to [`FuturesUnordered`], but it imposes a FIFO order
-/// on top of the set of futures. While futures in the set will race to
+/// This "combinator" is similar to [`FuturesUnordered`], but it imposes a FIFO
+/// order on top of the set of futures. While futures in the set will race to
 /// completion in parallel, results will only be returned in the order their
 /// originating futures were added to the queue.
 ///
 /// Futures are pushed into this queue and their realized values are yielded in
 /// order. This structure is optimized to manage a large number of futures.
-/// Futures managed by `FuturesOrdered` will only be polled when they generate
+/// Futures managed by [`FuturesOrdered`] will only be polled when they generate
 /// notifications. This reduces the required amount of work needed to coordinate
 /// large numbers of futures.
 ///
-/// When a `FuturesOrdered` is first created, it does not contain any futures.
-/// Calling `poll` in this state will result in `Poll::Ready(None))` to be
-/// returned. Futures are submitted to the queue using `push`; however, the
-/// future will **not** be polled at this point. `FuturesOrdered` will only
-/// poll managed futures when `FuturesOrdered::poll` is called. As such, it
-/// is important to call `poll` after pushing new futures.
+/// When a [`FuturesOrdered`] is first created, it does not contain any futures.
+/// Calling [`poll_next`](FuturesOrdered::poll_next) in this state will result
+/// in [`Poll::Ready(None)`](Poll::Ready) to be returned. Futures are submitted
+/// to the queue using [`push_back`](FuturesOrdered::push_back) (or
+/// [`push_front`](FuturesOrdered::push_front)); however, the future will
+/// **not** be polled at this point. [`FuturesOrdered`] will only poll managed
+/// futures when [`FuturesOrdered::poll_next`] is called. As such, it
+/// is important to call [`poll_next`](FuturesOrdered::poll_next) after pushing
+/// new futures.
 ///
-/// If `FuturesOrdered::poll` returns `Poll::Ready(None)` this means that
-/// the queue is currently not managing any futures. A future may be submitted
-/// to the queue at a later time. At that point, a call to
-/// `FuturesOrdered::poll` will either return the future's resolved value
-/// **or** `Poll::Pending` if the future has not yet completed. When
-/// multiple futures are submitted to the queue, `FuturesOrdered::poll` will
-/// return `Poll::Pending` until the first future completes, even if
+/// If [`FuturesOrdered::poll_next`] returns [`Poll::Ready(None)`](Poll::Ready)
+/// this means that the queue is currently not managing any futures. A future
+/// may be submitted to the queue at a later time. At that point, a call to
+/// [`FuturesOrdered::poll_next`] will either return the future's resolved value
+/// **or** [`Poll::Pending`] if the future has not yet completed. When
+/// multiple futures are submitted to the queue, [`FuturesOrdered::poll_next`]
+/// will return [`Poll::Pending`] until the first future completes, even if
 /// some of the later futures have already completed.
 ///
-/// Note that you can create a ready-made `FuturesOrdered` via the
+/// Note that you can create a ready-made [`FuturesOrdered`] via the
 /// [`collect`](Iterator::collect) method, or you can start with an empty queue
-/// with the `FuturesOrdered::new` constructor.
+/// with the [`FuturesOrdered::new`] constructor.
 ///
 /// This type is only available when the `std` or `alloc` feature of this
 /// library is activated, and it is activated by default.
@@ -104,8 +107,9 @@ impl<T: Future> Unpin for FuturesOrdered<T> {}
 impl<Fut: Future> FuturesOrdered<Fut> {
     /// Constructs a new, empty `FuturesOrdered`
     ///
-    /// The returned `FuturesOrdered` does not contain any futures and, in this
-    /// state, `FuturesOrdered::poll_next` will return `Poll::Ready(None)`.
+    /// The returned [`FuturesOrdered`] does not contain any futures and, in
+    /// this state, [`FuturesOrdered::poll_next`] will return
+    /// [`Poll::Ready(None)`](Poll::Ready).
     pub fn new() -> Self {
         Self {
             in_progress_queue: FuturesUnordered::new(),
@@ -132,9 +136,9 @@ impl<Fut: Future> FuturesOrdered<Fut> {
     /// Push a future into the queue.
     ///
     /// This function submits the given future to the internal set for managing.
-    /// This function will not call `poll` on the submitted future. The caller
-    /// must ensure that `FuturesOrdered::poll` is called in order to receive
-    /// task notifications.
+    /// This function will not call [`poll`](Future::poll) on the submitted
+    /// future. The caller must ensure that [`FuturesOrdered::poll_next`] is
+    /// called in order to receive task notifications.
     #[deprecated(note = "use `push_back` instead")]
     pub fn push(&mut self, future: Fut) {
         self.push_back(future);
@@ -143,9 +147,9 @@ impl<Fut: Future> FuturesOrdered<Fut> {
     /// Pushes a future to the back of the queue.
     ///
     /// This function submits the given future to the internal set for managing.
-    /// This function will not call `poll` on the submitted future. The caller
-    /// must ensure that `FuturesOrdered::poll` is called in order to receive
-    /// task notifications.
+    /// This function will not call [`poll`](Future::poll) on the submitted
+    /// future. The caller must ensure that [`FuturesOrdered::poll_next`] is
+    /// called in order to receive task notifications.
     pub fn push_back(&mut self, future: Fut) {
         let wrapped = OrderWrapper { data: future, index: self.next_incoming_index };
         self.next_incoming_index += 1;
@@ -155,10 +159,10 @@ impl<Fut: Future> FuturesOrdered<Fut> {
     /// Pushes a future to the front of the queue.
     ///
     /// This function submits the given future to the internal set for managing.
-    /// This function will not call `poll` on the submitted future. The caller
-    /// must ensure that `FuturesOrdered::poll` is called in order to receive
-    /// task notifications. This future will be the next future to be returned
-    /// complete.
+    /// This function will not call [`poll`](Future::poll) on the submitted
+    /// future. The caller must ensure that [`FuturesOrdered::poll_next`] is
+    /// called in order to receive task notifications. This future will be
+    /// the next future to be returned complete.
     pub fn push_front(&mut self, future: Fut) {
         let wrapped = OrderWrapper { data: future, index: self.next_outgoing_index - 1 };
         self.next_outgoing_index -= 1;