Documented futures crate.

Author: horned-sphere

swimos_utilities/swimos_future/src/combinators/mod.rs

@@ -66,6 +66,7 @@ impl<Str: TryStream> Stream for StopAfterError<Str> {
     }
 }
 
+/// A future that will trigger a notification whenever the future it wraps returns [`Poll::Pending`].
 #[pin_project]
 pub struct NotifyOnBlocked<F> {
     #[pin]
@@ -74,6 +75,9 @@ pub struct NotifyOnBlocked<F> {
 }
 
 impl<F> NotifyOnBlocked<F> {
+    /// # Arguments
+    /// * `inner` - The future to wrap.
+    /// * `notify`- This will be notified whenever the wrapped future returns [`Poll::Pending`].
     pub fn new(inner: F, notify: Arc<Notify>) -> NotifyOnBlocked<F> {
         NotifyOnBlocked { inner, notify }
     }

swimos_utilities/swimos_future/src/combinators/race/mod.rs

@@ -7,6 +7,7 @@ use std::future::Future;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
+/// The type returned by the [`race`] function.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 #[derive(Debug)]
 pub struct Race2<L, R> {

swimos_utilities/swimos_future/src/lib.rs

@@ -12,6 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Futures Combinators
+//!
+//! Additional combinators for [`std::future::Future`]s that express transformations that are not
+//! available in the [`futures`] crate.
+
 mod combinators;
 mod retry_strategy;
 mod union;

swimos_utilities/swimos_future/src/retry_strategy.rs

@@ -23,8 +23,8 @@ const DEFAULT_IMMEDIATE_RETRIES: NonZeroUsize = non_zero_usize!(16);
 const DEFAULT_INTERVAL_RETRIES: NonZeroUsize = non_zero_usize!(8);
 const DEFAULT_INTERVAL_DELAY: u64 = 10;
 
-/// The retry strategy that a ['RetryableRequest`] uses to determine when to perform the next
-/// request.
+/// A strategy that determines how many times, and at what interval, a fallible process should be
+/// attempted.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum RetryStrategy {
     /// A retry with a defined delay in between the requests.

swimos_utilities/swimos_future/src/union/mod.rs

@@ -20,6 +20,7 @@ use std::{
 use futures::Future;
 use pin_project::pin_project;
 
+/// Runs any one of three possible types of future, all of which produce the same output type.
 #[derive(Debug, Clone, Copy)]
 #[pin_project(project = Union3Proj)]
 pub enum UnionFuture3<F1, F2, F3> {
@@ -28,6 +29,7 @@ pub enum UnionFuture3<F1, F2, F3> {
     Third(#[pin] F3),
 }
 
+/// Runs any one of four possible types of future, all of which produce the same output type.
 #[derive(Debug, Clone, Copy)]
 #[pin_project(project = Union4Proj)]
 pub enum UnionFuture4<F1, F2, F3, F4> {