@@ -90,7 +90,12 @@ import Prelude hiding (map, repeat, zipWith, errorWithoutStackTrace)
9090zipWithM :: (IsStream t, Monad m) => (a -> b -> m c) -> t m a -> t m b -> t m c
9191zipWithM f m1 m2 = P.fromStreamS $ S.zipWithM f (P.toStreamS m1) (P.toStreamS m2)
9292
93−-- | Zip two streams serially using a pure zipping function.
93+-- | Stream @a@ is evaluated first, followed by stream @b@, the resulting
94+-- elements @a@ and @b@ are then zipped using the supplied zip function and the
95+-- result @c@ is yielded to the consumer.
96+--
97+-- If stream @a@ or stream @b@ ends, the zipped stream ends. If stream @b@ ends
98+-- first, the element @a@ from previous evaluation of stream @a@ is discarded.
9499--
95100-- @
96101-- > S.toList $ S.zipWith (+) (S.fromList [1,2,3]) (S.fromList [4,5,6])
@@ -106,8 +111,7 @@ zipWith f m1 m2 = P.fromStreamS $ S.zipWith f (P.toStreamS m1) (P.toStreamS m2)
106111-- Parallel Zipping
107112------------------------------------------------------------------------------
108113
109−-- | Like 'zipWithM' but zips concurrently i.e. both the streams being zipped
110−-- are generated concurrently.
114+-- | Like 'zipAsyncWith' but with a monadic zipping function.
111115--
112116-- @since 0.4.0
113117{-# INLINE zipAsyncWithM #-}
@@ -117,8 +121,19 @@ zipAsyncWithM f m1 m2 = D.fromStreamD $
117121 D.zipWithM f (Par.mkParallelD $ D.toStreamD m1)
118122 (Par.mkParallelD $ D.toStreamD m2)
119123
124+-- XXX Should we rename this to zipParWith or zipParallelWith? This can happen
125+-- along with the change of behvaior to end the stream concurrently.
126+--
120127-- | Like 'zipWith' but zips concurrently i.e. both the streams being zipped
121−-- are generated concurrently.
128+-- are evaluated concurrently using the 'ParallelT' concurrent evaluation
129+-- style. The maximum number of elements of each stream evaluated in advance
130+-- can be controlled by 'maxBuffer'.
131+--
132+-- The stream ends if stream @a@ or stream @b@ ends. However, if stream @b@
133+-- ends while we are still evaluating stream @a@ and waiting for a result then
134+-- stream will not end until after the evaluation of stream @a@ finishes. This
135+-- behavior can potentially be changed in future to end the stream immediately
136+-- as soon as any of the stream end is detected.
122137--
123138-- @since 0.1.0
124139{-# INLINE zipAsyncWith #-}