@@ -126,7 +126,8 @@ type MonadAsync m = (MonadIO m, MonadBaseControl IO m, MonadThrow m)
126126-- Monoid
127127------------------------------------------------------------------------------
128128
129−-- | '<>' concatenates two 'AsyncT' streams sequentially.
129+-- | '<>' concatenates two 'AsyncT' streams sequentially i.e. the first stream
130+-- is exhausted completely before yielding any element from the second stream.
130131instance Semigroup (AsyncT m a) where
131132 m1 <> m2 = go m1
132133 where
@@ -150,8 +151,9 @@ interleave m1 m2 = AsyncT $ \ctx stp yld -> do
150151
151152infixr 5 <=>
152153
153−-- | Sequential compostion, similar to '<>' except that it interleaves the two
154−-- 'AsyncT' streams fairly.
154+-- | Sequential interleaved composition, similar to '<>' except that it
155+-- fairly interleaves the two 'AsyncT' streams, yielding an element from each
156+-- stream alternately.
155157(<=>) :: AsyncT m a -> AsyncT m a -> AsyncT m a
156158(<=>) = interleave
157159
@@ -198,8 +200,10 @@ bindWith k m f = go m
198200 yield a _ (Just r) = run $ f a `k` (go r)
199201 in g Nothing stp yield
200202
201−-- | '>>=' runs a monadic action for each element in the stream, sequentially,
202−-- in a depth first manner.
203+-- | '>>=' execute a monadic action for each element generated by the 'AsyncT'
204+-- stream, running nested loops sequentially, in a depth first manner i.e. the
205+-- inner loop finishes completely before the next iteration of the outer loop
206+-- can run.
203207instance Monad m => Monad (AsyncT m) where
204208 return = pure
205209
@@ -213,18 +217,20 @@ instance Monad m => Monad (AsyncT m) where
213217-- Alternative ways to bind
214218------------------------------------------------------------------------------
215219
216−-- | Run a monadic action for each element in the stream, sequentially, in a
217−-- breadth first manner i.e. fairly interleaved.
220+-- | Execute a monadic action for each element in the stream, running nested
221+-- loops sequentially, but in a fairly interleaved manner i.e. both inner and
222+-- outer loop yield alternately.
218223(>->) :: AsyncT m a -> (a -> AsyncT m b) -> AsyncT m b
219224(>->) = bindWith (<=>)
220225
221−-- | Run a monadic action for each element in the stream, in parallel, with
222−-- a depth first bias.
226+-- | Execute a monadic action for each element in the stream, running nested
227+-- loops in parallel, but with a depth first preference.
223228(>>|) :: MonadAsync m => AsyncT m a -> (a -> AsyncT m b) -> AsyncT m b
224229(>>|) = bindWith (<|)
225230
226−-- | Run a monadic action for each element in the stream, in parallel, with a
227−-- breadth first bias i.e. fairly interleaved.
231+-- | Execute a monadic action for each element in the stream, running nested
232+-- loops in parallel, but in a fairly interleaved manner i.e. both inner and
233+-- outer loops yield alternately.
228234(>|>) :: MonadAsync m => AsyncT m a -> (a -> AsyncT m b) -> AsyncT m b
229235(>|>) = bindWith (<|>)
230236