@@ -205,8 +205,47 @@ joinStreamVarPar style ss m1 m2 = mkStream $ \st yld sng stp ->
205205consMParallel :: MonadAsync m => m a -> ParallelT m a -> ParallelT m a
206206consMParallel m r = fromStream $ K.yieldM m `parallel` (toStream r)
207207
208−-- | Polymorphic version of the 'Semigroup' operation '<>' of 'ParallelT'
209−-- Merges two streams concurrently.
208+-- | Execute two streams concurrently and merge their outputs. For example, if
209+-- stream @a@ is a serial stream consisting of @a1, a2, a3@ and stream @b@ is a
210+-- serial stream consisting of @b1, b2, b3@ then stream @a `parallel` b@ may
211+-- produce @a1, b1, a2, b2, a3, b3@ or @a1, a2, b1, a3, b2, b3@ or some other
212+-- combination depending on the rate at which the two streams produce elements.
213+-- However, the relative order of outputs from a single stream e.g. @a1, a2,
214+-- a3@ would remain the same in the resulting stream. The effects in the two
215+-- streams may occur concurrently.
216+--
217+-- To run single actions (instead of streams) in parallel wrap them into
218+-- singleton streams. The following trivial example is semantically equivalent
219+-- to running the action @putStrLn "hello"@ in the current thread:
220+--
221+-- >>> S.toList $ S.yieldM (putStrLn "hello") `parallel` S.nil
222+-- > hello
223+-- > [()]
224+--
225+-- Run two actions concurrently:
226+--
227+-- >>> S.toList $ S.yieldM (putStrLn "hello") `parallel` S.yieldM (putStrLn "world")
228+-- > hello
229+-- > world
230+-- > [(),()]
231+--
232+-- Run effects concurrently, disregarding their outputs:
233+--
234+-- >>> S.toList $ S.nilM (putStrLn "hello") `parallel` S.nilM (putStrLn "world")
235+-- > hello
236+-- > world
237+-- > []
238+--
239+-- Run an effectful action, and a pure effect without any output, concurrently:
240+--
241+-- >>> S.toList $ S.yieldM (return 1) `parallel` S.nilM (putStrLn "world")
242+-- world
243+-- [1]
244+--
245+-- Note that 'parallel' is a polymorphic version of the @Semigroup@ operation
246+-- @<>@ of 'ParallelT'.
247+--
248+-- `nilM` is currently @Internal@.
210249--
211250-- @since 0.2.0
212251{-# INLINE parallel #-}