@@ -572,9 +572,9 @@ concatSmapMWith combine f initial =
573-- XXX Implement a StreamD version for fusion.
573-- XXX Implement a StreamD version for fusion.
575−-- | Combine streams in pairs using a binary stream combinator, then combine
575+-- | Combine streams in pairs using a binary combinator, the resulting streams
576−-- the resulting streams in pairs recursively until we get to a single combined
576+-- are then combined again in pairs recursively until we get to a single
577−-- stream.
577+-- combined stream. The composition would thus form a binary tree.
579-- For example, you can sort a stream using merge sort like this:
579-- For example, you can sort a stream using merge sort like this:
@@ -584,6 +584,10 @@ concatSmapMWith combine f initial =
584-- >>> Stream.fold Fold.toList $ Stream.concatPairsWith combine generate s
584-- >>> Stream.fold Fold.toList $ Stream.concatPairsWith combine generate s
585-- [1,2,5,7,9]
585-- [1,2,5,7,9]
587+-- Note that if the stream length is not a power of 2, the binary tree composed
588+-- by concatPairsWith would not be balanced, which may or may not be important
589+-- depending on what you are trying to achieve.
587-- /Caution: the stream of streams must be finite/
591-- /Caution: the stream of streams must be finite/
589-- /Pre-release/
593-- /Pre-release/