Merge pull request #132 from matheus-consoli/update-documentation

Update `Join` documentation

src/future/join/mod.rs

@@ -7,19 +7,58 @@ pub(crate) mod vec;
 /// Wait for all futures to complete.
 ///
 /// Awaits multiple futures simultaneously, returning the output of the futures
-/// once all complete.
+/// in the same container type they were created once all complete.
 pub trait Join {
     /// The resulting output type.
     type Output;
 
-    /// Which kind of future are we turning this into?
+    /// The [`Future`] implementation returned by this method.
     type Future: Future<Output = Self::Output>;
 
     /// Waits for multiple futures to complete.
     ///
-    /// Awaits multiple futures simultaneously, returning the output of the
-    /// futures once all complete.
+    /// Awaits multiple futures simultaneously, returning the output of the futures
+    /// in the same container type they we're created once all complete.
     ///
+    /// # Examples
+    ///
+    /// Awaiting multiple futures of the same type can be done using either a vector
+    /// or an array.
+    /// ```rust
+    /// #  futures::executor::block_on(async {
+    /// use futures_concurrency::prelude::*;
+    ///
+    /// // all futures passed here are of the same type
+    /// let fut1 = core::future::ready(1);
+    /// let fut2 = core::future::ready(2);
+    /// let fut3 = core::future::ready(3);
+    ///
+    /// let outputs = [fut1, fut2, fut3].join().await;
+    /// assert_eq!(outputs, [1, 2, 3]);
+    /// # })
+    /// ```
+    ///
+    /// In practice however, it's common to want to await multiple futures of
+    /// different types. For example if you have two different `async {}` blocks,
+    /// you want to `.await`. To do that, you can call `.join` on tuples of futures.
+    /// ```rust
+    /// #  futures::executor::block_on(async {
+    /// use futures_concurrency::prelude::*;
+    ///
+    /// async fn some_async_fn() -> usize { 3 }
+    ///
+    /// // the futures passed here are of different types
+    /// let fut1 = core::future::ready(1);
+    /// let fut2 = async { 2 };
+    /// let fut3 = some_async_fn();
+    /// //                       ^ NOTE: no `.await` here!
+    ///
+    /// let outputs = (fut1, fut2, fut3).join().await;
+    /// assert_eq!(outputs, (1, 2, 3));
+    /// # })
+    /// ```
+    ///
+    /// <br><br>
     /// This function returns a new future which polls all futures concurrently.
     fn join(self) -> Self::Future;
 }

src/future/join/vec.rs

@@ -10,7 +10,7 @@ use std::vec::Vec;
 
 use pin_project::{pin_project, pinned_drop};
 
-/// A future which waits for two similarly-typed futures to complete.
+/// A future which waits for multiple futures to complete.
 ///
 /// This `struct` is created by the [`join`] method on the [`Join`] trait. See
 /// its documentation for more.

src/lib.rs

@@ -16,13 +16,29 @@
 //!
 //! This library provides the following operations on arrays, vecs, and tuples:
 //!
-//! - [`future::Join`] Wait for all futures to complete.
-//! - [`future::TryJoin`] Wait for all futures to complete successfully, or abort early on error.
-//! - [`future::Race`] Wait for all futures to complete successfully, or abort early on error.
-//! - [`future::RaceOk`] Wait for the first successful future to complete.
-//! - [`stream::Chain`] Takes multiple streams and creates a new stream over all in sequence.
-//! - [`stream::Merge`] Combines multiple streams into a single stream of all their outputs.
-//! - [`stream::Zip`] ‘Zips up’ multiple streams into a single stream of pairs.
+//! - [`future::Join`]: Wait for all futures to complete.
+//! - [`future::TryJoin`]: Wait for all futures to complete successfully, or abort early on error.
+//! - [`future::Race`]: Wait for the first future to complete.
+//! - [`future::RaceOk`]: Wait for the first successful future to complete.
+//! - [`stream::Chain`]: Takes multiple streams and creates a new stream over all in sequence.
+//! - [`stream::Merge`]: Combines multiple streams into a single stream of all their outputs.
+//! - [`stream::Zip`]: ‘Zips up’ multiple streams into a single stream of pairs.
+//!
+//! # Examples
+//!
+//! Concurrently await multiple heterogenous futures:
+//! ```rust
+//! use futures_concurrency::prelude::*;
+//! use futures_lite::future::block_on;
+//! use std::future;
+//!
+//! block_on(async {
+//!     let a = future::ready(1u8);
+//!     let b = future::ready("hello");
+//!     let c = future::ready(3u16);
+//!     assert_eq!((a, b, c).join().await, (1, "hello", 3));
+//! })
+//! ```
 //!
 //! # Limitations
 //!
@@ -41,22 +57,6 @@
 //! `for..await in` loops to be iterated over using `merge` semantics. This would
 //! remove the need to think of "merge" as a verb, and would enable treating
 //! sets of futures concurrently.
-//!
-//! # Examples
-//!
-//! Concurrently await multiple heterogenous futures:
-//! ```rust
-//! use futures_concurrency::prelude::*;
-//! use futures_lite::future::block_on;
-//! use std::future;
-//!
-//! block_on(async {
-//!     let a = future::ready(1u8);
-//!     let b = future::ready("hello");
-//!     let c = future::ready(3u16);
-//!     assert_eq!((a, b, c).join().await, (1, "hello", 3));
-//! })
-//! ```
 
 #![deny(missing_debug_implementations, nonstandard_style)]
 #![warn(missing_docs, unreachable_pub)]
@@ -93,7 +93,8 @@ pub mod array {
     pub use crate::stream::zip::array::Zip;
 }
 
-/// A contiguous growable array type with heap-allocated contents, written `Vec<T>`.
+/// Helper functions and types for contiguous growable array type with heap-allocated contents,
+/// written `Vec<T>`.
 pub mod vec {
     pub use crate::future::join::vec::Join;
     pub use crate::future::race::vec::Race;